1.2.0: feed measured coverage to the fallow-health report (#12)

## Summary

`report --coverage <path>` (or `report.coverage` in `.code-quality.yml`;
the flag wins) gives Fallow an Istanbul `coverage-final.json` so the
advisory CRAP values use measured coverage instead of the 0 % estimate.
The blocking gate does not change.

- `src/report/coverage.ts`: repository-relative path validation,
directory form, `realpath` containment, regular file + 256 MiB cap,
Istanbul shape check (`path`/`s`/`f`/`fnMap`), `--coverage-root` derived
by scoring ancestor prefixes over the sampled keys (order independent,
longest prefix wins ties).
- fallow-health: `--coverage`/`--coverage-root`, exit 2 accepted only
with coverage, `coverage:` errors get an Istanbul hint, the coverage
directory is excluded from Fallow scans unless it overlaps a configured
path (then only the file is excluded).
- Unmatched coverage paths → one notice, CRAP stays estimated, exit 0.
Missing / malformed / raw V8 input → exit 1 before any tool runs.
- `quality.yml`: opt-in `report` and `coverage-artifact` inputs;
`Validate coverage artifact` before `Check`; `Download coverage`,
`Report`, `Upload quality reports` gated on step outcomes.
- `report.coverage` is kept out of `configHash`; `check` untouched.
- `scripts/integration.ts`: `ts-project report --coverage` row against a
committed Istanbul fixture asserting `istanbul_files_matched >= 1`.
- Docs: README report paragraph, config row, workflow inputs and
"Coverage for CRAP" (same-job and artifact patterns), quality-gate.md.
Version 1.2.0.

## Test plan

- [x] tsc, oxlint, vitest (59 files / 532 tests), build, actionlint,
dogfood `check` PASS
- [x] `node scripts/integration.ts` against the branch image: 14/14 rows
ok including `report --coverage`
- [x] launcher + branch image on a fixture copy: matched 1/1 with a
`/home/runner/work/...` prefix, dir-form via config,
absolute/missing/raw-V8 → exit 1, unmatched → notice + exit 0
- [ ] after merge: push `v1.2.0`, approve the staged npm version

Author: Cenadros

.github/workflows/quality.yml

@@ -19,6 +19,14 @@ on:
         description: Consumer working directory inside /work
         type: string
         default: "."
+      report:
+        description: Run code-quality report after check and upload artifacts/quality
+        type: boolean
+        default: false
+      coverage-artifact:
+        description: Artifact holding coverage/coverage-final.json for the fallow-health report
+        type: string
+        default: ""
 
 permissions:
   contents: read
@@ -52,11 +60,51 @@ jobs:
             echo "Invalid checks input: only lowercase check ids separated by spaces are allowed" >&2
             exit 1
           fi
+      - name: Validate coverage artifact
+        id: validate-coverage
+        if: ${{ inputs.report && inputs.coverage-artifact != '' }}
+        env:
+          CODE_QUALITY_COVERAGE_ARTIFACT: ${{ inputs.coverage-artifact }}
+        shell: bash
+        run: |
+          if ! printf '%s' "$CODE_QUALITY_COVERAGE_ARTIFACT" | grep -Eq '^[A-Za-z0-9._-]+$'; then
+            echo "Invalid coverage artifact input" >&2
+            exit 1
+          fi
       - name: Check
+        id: check
         working-directory: ${{ inputs.working-directory }}
         env:
           CODE_QUALITY_CHECKS: ${{ inputs.checks }}
         shell: bash
         run: |
           read -ra CHECKS <<< "$CODE_QUALITY_CHECKS"
           code-quality check "${CHECKS[@]}"
+      - name: Download coverage
+        id: download-coverage
+        if: ${{ inputs.report && inputs.coverage-artifact != '' && !cancelled() && steps.validate-coverage.outcome == 'success' }}
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
+        with:
+          name: ${{ inputs.coverage-artifact }}
+          path: ${{ inputs.working-directory }}/coverage
+      - name: Report
+        id: report
+        if: ${{ inputs.report && !cancelled() && steps.check.outcome != 'skipped' && steps.validate-coverage.outcome != 'failure' && (inputs.coverage-artifact == '' || steps.download-coverage.outcome == 'success') }}
+        working-directory: ${{ inputs.working-directory }}
+        env:
+          CODE_QUALITY_COVERAGE_ARTIFACT: ${{ inputs.coverage-artifact }}
+        shell: bash
+        run: |
+          if [[ -n "$CODE_QUALITY_COVERAGE_ARTIFACT" ]]; then
+            code-quality report --coverage coverage/coverage-final.json
+          else
+            code-quality report
+          fi
+      - name: Upload quality reports
+        if: ${{ inputs.report && !cancelled() && steps.report.outcome != 'skipped' }}
+        uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
+        with:
+          name: quality-reports
+          path: ${{ inputs.working-directory }}/artifacts/quality
+          if-no-files-found: warn
+          retention-days: 14

README.md

@@ -120,19 +120,24 @@ The caller can provide the supported inputs. For example, this selects checks, i
 | `checks` | string | empty | Space-separated lowercase check IDs; empty runs all detected checks |
 | `setup` | string | empty | Consumer shell command run before checking |
 | `working-directory` | string | `.` | Consumer working directory inside `/work` |
+| `report` | boolean | `false` | Run the advisory report after the check and upload `artifacts/quality` |
+| `coverage-artifact` | string | empty | Artifact containing `coverage/coverage-final.json` for Fallow health |
 
 ```yaml
 jobs:
   quality:
+    needs: test
     uses: Runroom/code-quality/.github/workflows/quality.yml@v1
     with:
       checks: "complexity duplication unused"
       setup: composer install --no-interaction
       image-tag: v1
       working-directory: "."
+      report: true
+      coverage-artifact: test-coverage
 ```
 
-The reusable job checks out the full history, runs the optional setup command, and invokes plain `code-quality check`. Failing findings produce GitHub annotations, and the job summary is written to `GITHUB_STEP_SUMMARY`. It never passes `--update` or `--initialize`, so CI never writes baselines. Knip and the PHP unused checks need installed dependencies before they run: use `setup: pnpm install --frozen-lockfile` for pnpm, `setup: npm ci` for npm, or `setup: composer install` for Composer. The first two create `node_modules/` for Knip; Composer creates `vendor/` for the PHP unused checks.
+The reusable job checks out the full history, runs the optional setup command, and invokes plain `code-quality check`. With `report` enabled, it also downloads the coverage artifact, runs `code-quality report`, and uploads `artifacts/quality` as the `quality-reports` artifact. Failing findings produce GitHub annotations, and the job summary is written to `GITHUB_STEP_SUMMARY`. It never passes `--update` or `--initialize`, so CI never writes baselines. Knip and the PHP unused checks need installed dependencies before they run: use `setup: pnpm install --frozen-lockfile` for pnpm, `setup: npm ci` for npm, or `setup: composer install` for Composer. The first two create `node_modules/` for Knip; Composer creates `vendor/` for the PHP unused checks.
 
 ## Check selection
 
@@ -165,7 +170,7 @@ Initialize a check once with `check --initialize` after reviewing its current fi
 A realistic output block is:
 
 ```text
- code-quality 1.1.7 · ts, python · 5 checks
+ code-quality 1.2.0 · ts, python · 5 checks
 
  ✔ ts-complexity      oxlint 1.82.0  280 findings
  ✖ ts-cognitive       fallow 3.23.0  18 findings · 2 new
@@ -187,6 +192,8 @@ A realistic output block is:
 
 `check`, `baseline`, and `init` accept `--artifacts <dir>` to retain raw tool output plus `stdout.log` and `stderr.log` per adapter. Without it, adapter output stays in a temporary directory and no adapter artifacts or logs are written by default. `report --output <dir>` selects the advisory report directory and defaults to `artifacts/quality/`.
 
+`report --coverage <path>` gives Fallow an Istanbul `coverage-final.json` map, or a directory containing that file, so its advisory CRAP values use measured coverage. The repository-relative `report.coverage` configuration key does the same and requires code-quality 1.2.0 or newer; an explicit flag wins. Coverage paths that match no repository file produce a notice and CRAP stays estimated; missing or malformed coverage files still fail. The coverage file's directory is excluded from Fallow scans unless it overlaps a configured source path, in which case only the coverage file is excluded.
+
 In GitHub Actions, each regression also emits a `::error file=…` annotation. The current Markdown summary is appended to `GITHUB_STEP_SUMMARY` when that environment variable is available.
 
 ## Configuration reference
@@ -205,6 +212,7 @@ In GitHub Actions, each regression also emits a `::error file=…` annotation. T
 | `architecture.ts.rulesFile` | repository-relative file path | `.dependency-cruiser.cjs` when it exists; otherwise skipped |
 | `architecture.php.rulesFile` | repository-relative file path | `deptrac.yaml` when it exists; otherwise skipped |
 | `architecture.python.rulesFile` | repository-relative file path | `.importlinter` when it exists; otherwise skipped |
+| `report.coverage` | repository-relative Istanbul map or directory | Unset; requires code-quality 1.2.0 or newer |
 
 An explicitly configured architecture file that is missing is an error. Consumer exclusions apply to applicable checks, while tests remain excluded from duplication regardless of the consumer paths.
 
@@ -232,6 +240,17 @@ exclude:
 
 The Drupal profile discovers custom modules, themes, and profiles and prints a `Notice:` describing the applied defaults. Normal applicable complexity, cognitive-complexity, duplication, and architecture checks run for the detected custom-code languages; PHP `composer-unused` and `composer-require-checker` run with installed Composer dependencies, while PHPStan dead-code analysis is skipped because consumer PHPStan extensions are incompatible with the image.
 
+### Coverage for CRAP
+
+When tests and the report run in the same job, configure Vitest's `json` coverage reporter (with either the V8 or Istanbul provider), then run:
+
+```sh
+vitest run --coverage
+npx @runroom/code-quality report --coverage coverage/coverage-final.json
+```
+
+With the reusable workflow, have the tests job upload the `coverage/` directory as an artifact named `test-coverage`. The quality job must declare `needs: test`, then set `report: true` and `coverage-artifact: test-coverage` as shown above. Raw V8 output is not supported; the input must be the Istanbul map written by the Vitest or Jest JSON reporter.
+
 ## Version pinning
 
 Pin npm consumers to the major launcher version with `npx @runroom/code-quality@1`. Pin Docker consumers to the major image tag `ghcr.io/runroom/code-quality:v1` and the reusable workflow reference `Runroom/code-quality/.github/workflows/quality.yml@v1`. The image carries the exact v1 tool matrix documented in [quality-gate.md](docs/quality-gate.md#v1-tool-pins); the workflow accepts only an `image-tag`, while the registry and repository remain fixed.

docs/quality-gate.md

@@ -165,6 +165,8 @@ Some supported tree-sitter grammars reject otherwise valid newer syntax. When th
 
 `report` is advisory: it retains full Fallow health and semantic-duplication output, complexipy JSON, and jscpd HTML for investigation. Advisory similarity and health reports do not alter the exact jscpd or complexity baselines and do not turn a report-only measurement into an accepted regression.
 
+Coverage-backed CRAP remains advisory only and never changes the blocking quality gate.
+
 ### Output
 
 `check` prints one line per failing finding as `file:line:col  rule  message  [new]`, `[worsened P → V]`, or `[stale: was P]`; duplication uses `a:start-end ↔ b:start-end`. `check --all` also prints every current finding with `[baselined]`.

launcher/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runroom/code-quality",
-  "version": "1.1.7",
+  "version": "1.2.0",
   "description": "Runroom incremental quality gate — runs the pinned ghcr.io/runroom/code-quality image",
   "type": "module",
   "scripts": {

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@runroom/code-quality",
-  "version": "1.1.7",
+  "version": "1.2.0",
   "private": true,
   "type": "module",
   "engines": { "node": ">=24" },

scripts/integration.ts

@@ -7,6 +7,7 @@ import {
   existsSync,
   mkdirSync,
   mkdtempSync,
+  readFileSync,
   readdirSync,
   rmSync,
   writeFileSync,
@@ -75,6 +76,7 @@ export interface ResultRow {
   expectedExitCode: number;
   stderr: string;
   expectedStderr?: string;
+  evidenceOk?: boolean;
 }
 
 interface DockerResult {
@@ -242,7 +244,8 @@ function resultRow(
 
 function rowIsOk(row: ResultRow): boolean {
   return row.exitCode === row.expectedExitCode &&
-    (row.expectedStderr === undefined || row.stderr.includes(row.expectedStderr));
+    (row.expectedStderr === undefined || row.stderr.includes(row.expectedStderr)) &&
+    row.evidenceOk !== false;
 }
 
 export function formatResultRow(row: ResultRow): string {
@@ -300,6 +303,29 @@ function fixtureReportRow(repositoryRoot: string, image: string, fixture: string
   }
 }
 
+function fixtureCoverageReportRow(repositoryRoot: string, image: string): ResultRow {
+  const root = temporaryFixture(repositoryRoot, "ts-project");
+  try {
+    const coverageDirectory = join(root, "coverage");
+    mkdirSync(coverageDirectory, { recursive: true });
+    copyFileSync(
+      join(repositoryRoot, "tests/fixtures/istanbul/ts-project.coverage-final.json"),
+      join(coverageDirectory, "coverage-final.json"),
+    );
+    const result = runDocker(image, ["report", "--coverage", "coverage/coverage-final.json"], root);
+    const report = JSON.parse(readFileSync(
+      join(root, "artifacts/quality/fallow-health/fallow-health.json"),
+      "utf8",
+    )) as { summary?: { istanbul_files_matched?: number } };
+    return {
+      ...resultRow("ts-project report --coverage", result, 0),
+      evidenceOk: (report.summary?.istanbul_files_matched ?? 0) >= 1,
+    };
+  } finally {
+    rmSync(root, { recursive: true, force: true });
+  }
+}
+
 function mutationRow(repositoryRoot: string, image: string, mutation: Mutation): ResultRow {
   const root = temporaryFixture(repositoryRoot, mutation.fixture);
   try {
@@ -316,6 +342,7 @@ function integrationRows(repositoryRoot: string, image: string): ResultRow[] {
   installMissingFixtureDependencies(repositoryRoot, image);
   for (const fixture of FIXTURES) rows.push(fixtureCheckRow(repositoryRoot, image, fixture));
   for (const fixture of REPORT_FIXTURES) rows.push(fixtureReportRow(repositoryRoot, image, fixture));
+  rows.push(fixtureCoverageReportRow(repositoryRoot, image));
   for (const mutation of MUTATIONS) rows.push(mutationRow(repositoryRoot, image, mutation));
   return rows;
 }

src/checks/ts/fallow.ts

@@ -29,9 +29,9 @@ export const fallowErrorSchema = z.looseObject({
   message: z.string(),
 });
 
-export function fallowConfig(ctx: CheckContext): string {
+export function fallowConfig(ctx: CheckContext, extraIgnorePatterns: readonly string[] = []): string {
   return JSON.stringify({
-    ignorePatterns: [...excludeGlobs(ctx.config, true), "artifacts/**"],
+    ignorePatterns: [...excludeGlobs(ctx.config, true), "artifacts/**", ...extraIgnorePatterns],
     health: { maxCyclomatic: POLICY.complexity, maxCognitive: POLICY.cognitive },
     duplicates: POLICY.advisoryDuplication,
   }, null, 2);

src/cli/commands/report.ts

@@ -5,6 +5,7 @@ import type { CliDeps } from "../deps.ts";
 
 interface ReportOptions {
   output?: string | undefined;
+  coverage?: string | undefined;
 }
 
 const DEFAULT_OUTPUT = "artifacts/quality";
@@ -13,5 +14,6 @@ export function reportCommand(deps: CliDeps, options: ReportOptions = {}): Promi
   return runReports({
     ...deps,
     output: resolve(deps.cwd, options.output ?? DEFAULT_OUTPUT),
+    coverage: options.coverage,
   });
 }

src/cli/program.ts

@@ -28,6 +28,7 @@ interface GateFlags {
 
 interface ReportFlags {
   output?: string;
+  coverage?: string;
 }
 
 const PROGRAM_STATES = new WeakMap<Command, ProgramState>();
@@ -103,6 +104,7 @@ function registerCommands(program: Command, deps: CliDeps, state: ProgramState):
   program.command("report")
     .description("Generate advisory reports")
     .option("--output <dir>", "report output directory")
+    .option("--coverage <path>", "Istanbul coverage map (coverage-final.json) or its directory")
     .action(async (flags: ReportFlags) => {
       state.exitCode = await reportCommand(deps, flags);
     });

src/cli/version.ts

@@ -1 +1 @@
-export const CLI_VERSION = "1.1.7";
+export const CLI_VERSION = "1.2.0";