code-report

Generate beautiful PDF code-quality reports from your CI analysis results.

Plug it after your existing test / lint / audit jobs and get a polished, multi-module, theme-aware PDF that you can hand to clients or executives. No new analyzers to configure — code-report only consumes the files your current tools already produce.

Your CI (jest, eslint, audit, jacoco, …) → JSON / XML files → code-report → PDF

Highlights

• Multi-stack — Jest, JaCoCo, Cobertura, JUnit, LCOV, ESLint, Biome, Checkstyle, SonarQube, npm-audit, OWASP DC, Trivy, Snyk, license-checker, CycloneDX, SPDX.
• Multi-module — one PDF, one global synthesis, one annex per module.
• Themed — 6 built-in themes (executive, midnight, vivid, terracotta, stark, neon) + colour overrides + custom fonts.
• Trends — code-report fetch-history pulls past report.json from GitLab/GitHub artefacts, sparklines render automatically. No external storage required. See docs/trends.md.
• CI-native — Docker image + ready-to-include GitLab CI template + GitHub Actions workflow example. Same CLI everywhere.
• Reproducible — pure function of its input files; same inputs, same PDF.
• AI-grade — structured playbook (AGENTS.md) so coding assistants can integrate it into a project autonomously.

Quick start (Docker)

docker run --rm -v "$PWD:/data" \
  registry.gitlab.com/ftprod1/ft-code-report-builder:latest \
  --config /data/code-report.config.json \
  --output /data/report.pdf

Quick start (Node)

npm install -D @ftprod/code-report
npx code-report --config code-report.config.json --output report.pdf

Quick start (GitLab CI)

include:
  - remote: 'https://gitlab.com/ftprod1/ft-code-report-builder/-/raw/v1/ci-templates/code-report.gitlab-ci.yml'

code-report:
  extends: .code-report
  needs: [analyze]

Quick start (GitHub Actions)

- name: Generate quality report
  run: |
    docker run --rm -v "$GITHUB_WORKSPACE:/data" \
      registry.gitlab.com/ftprod1/ft-code-report-builder:v1 \
      --config /data/code-report.config.json \
      --output /data/report.pdf
- uses: actions/upload-artifact@v4
  with: { name: code-report, path: report.pdf }

Full workflow: .github/workflows/code-report.yml.example. See docs/github-actions.md for releases / pages / monorepo patterns.

Minimal config

{
  "$schema": "https://gitlab.com/ftprod1/ft-code-report-builder/-/raw/main/config.schema.json",
  "projectName": "My Project",
  "clientName": "Acme Corp",
  "modules": [
    {
      "name": "backend",
      "version": "2.4.1",
      "tests":    [{ "type": "jest-coverage",  "path": "./coverage/coverage-summary.json" }],
      "lint":     [{ "type": "eslint",         "path": "./eslint-report.json" }],
      "security": [{ "type": "npm-audit",      "path": "./audit.json" }],
      "bom":      [{ "type": "license-checker","path": "./licenses.json" }]
    }
  ]
}

Full reference: docs/configuration.md. GitLab CI: docs/gitlab-ci.md — GitHub Actions: docs/github-actions.md — Distribution patterns (Releases / Pages / S3 / Slack): docs/distribute.md.

Examples

Drop-in starter kits for the most common stacks:

| Folder | Stack | |-------------------------------------------|-------------------| | examples/node-simple/ | Single Node app | | examples/node-monorepo/ | Node monorepo | | examples/java-maven/ | Java / Maven | | examples/python/ | Python (pytest) |

Each folder contains a ready code-report.config.json and .gitlab-ci.yml.

For AI coding assistants

If you're an AI agent integrating code-report into a target project, read AGENTS.md — it contains a structured playbook with stack-detection rules, parser-mapping tables, a validation procedure, and a list of common pitfalls. Humans should stick to this README.

CLI

code-report [options]

Options:
  -c, --config <path>      Path to config file        (default: code-report.config.json)
  -o, --output <path>      Output PDF path            (default: code-report.pdf)
  --json-output <path>     Also export normalized JSON report (used for trends on next run)
  --validate               Validate config and check referenced files exist, then exit
  -V, --version            Show version
  -h, --help               Show help

--validate is safe to run as a CI lint step — it never spawns Chromium and exits non-zero only on blocking issues. Missing history files (previousReports) are reported as warnings, not errors.

Supported analyzers

| Section | Type | Tool / source | |----------|--------------------------|------------------------------------------| | Tests | jest-coverage | jest --coverage --coverageReporters=json-summary | | Tests | jacoco | Maven / Gradle JaCoCo plugin | | Tests | cobertura | Cobertura, pytest-cov, Go coverage | | Tests | junit | JUnit, pytest, vitest, mocha | | Tests | lcov | lcov, nyc, c8 | | Lint | eslint | eslint --format json | | Lint | biome | biome check --reporter=json | | Lint | checkstyle | Checkstyle, ktlint, detekt | | Lint | sonar | SonarQube API /api/issues/search | | Security | npm-audit | npm audit --json / pnpm audit | | Security | owasp-dependency-check | OWASP Dependency-Check | | Security | trivy | trivy fs --format json | | Security | snyk | snyk test --json | | BOM | license-checker | license-checker --json | | BOM | cyclonedx | cdxgen, syft | | BOM | spdx | syft, cdxgen --spec spdx |

Themes

| Theme | Look & feel | |--------------|--------------------------------------------------------| | executive | Light corporate, sober blue / violet | | midnight | Dark premium, deep navy | | vivid | Dark bold, indigo → pink gradients | | terracotta | Warm light, serif typography | | stark | Brutalist, WCAG AAA, square corners | | neon | Synthwave, monospace, cyan / pink glow |

Override any colour:

{ "theme": "executive", "colors": { "accent": "#FF6B00" } }

Development

pnpm install
pnpm dlx playwright install chromium   # one-time — Playwright needs it at runtime
pnpm typecheck
pnpm test
pnpm build
node dist/index.js --config fixtures/code-report.config.json --output out.pdf

The Docker image ships Chromium pre-installed, so users consuming code-report via Docker (the recommended path) never need this step.

See CONTRIBUTING.md for workflow and conventions, and docs/publishing.md for the release process.

License

MIT © Guillaume Pouleri / FTPROD