codemetrics-ai 0.2.0

package/README.md

@@ -0,0 +1,70 @@
+# codemetrics-ai
+
+Deterministic source analysis for JavaScript, TypeScript, JSX and TSX. Version 0.2.0 implements source metrics and React hook/effect checks and emits schema-v3 evidence. Scores are **uncalibrated across ecosystems**; compare them only with compatible runs of this analyzer.
+
+```sh
+npx codemetrics-ai --project package.json
+npx codemetrics-ai --project package.json --tsconfig tsconfig.json
+npx codemetrics-ai --output results/metrics.csv --scorecard-output results/evidence.json
+```
+
+Default output paths are `.scorecard/javascript-typescript/metrics.csv` and `.scorecard/javascript-typescript/evidence.json`, relative to the current directory. Node 20 or later is required. The TypeScript compiler API is a pinned runtime dependency, so an installed package can analyze source without a development checkout.
+
+## Implemented scope
+
+| Dimension | Implementation |
+|---|---|
+| codeQuality | Maximum member cyclomatic complexity and findings above 10 |
+| maintainability | Median member maintainability index |
+| performanceAsync | Imported React hooks inside conditionals/loops, async effect callbacks, and advisory effects without dependency arrays |
+| Other dimensions | Explicitly skipped |
+
+React checks run only when a source file imports React. Aliased named imports and namespace imports are recognized; local functions shadowing imports are excluded. Missing dependency arrays are advisory because running after every render can be intentional. The implementation does not claim exhaustive Rules of Hooks, dependency-array correctness, or general concurrency analysis. Source syntax errors make the run incomplete and source dimensions unscored. Semantic type errors are outside this AST-focused version's completeness check.
+
+## Discovery
+
+The CLI discovers files from each package's tsconfig when present, otherwise scans source extensions. Positive npm workspace globs (including object-form `workspaces.packages`) are supported. Each child package owns its files and exclusions; the root cannot re-include a child's excluded files. External tsconfig references are not recursively analyzed as separate packages: include them in the workspace manifest. Explicit missing manifests/configs and unsupported negative workspace patterns are errors.
+
+Build output, node_modules, metadata, declarations, test/fixture directories, `.test`/`.spec` source, conventional generated filenames, and `@generated`/`<auto-generated` headers are excluded. Discovery does not follow directory symlinks. Skipped candidate files appear in filters; pruned directories are not counted as candidate files.
+
+## Metric policy
+
+A member is a function with a body: declarations, expressions, arrows, methods, constructors and accessors. Nested functions are separate members and do not inflate their parent's complexity. Named JSX-producing PascalCase functions are components; `useX` functions are hooks. Types group class members or standalone functions and their callbacks within a module. TypeScript interfaces, type aliases and overload signatures without bodies are not runtime members.
+
+Cyclomatic complexity starts at 1 per member and adds 1 for `if`, loops, `catch`, non-default switch cases, ternaries, `&&`, `||` and `??`. JSX markup itself contributes no decisions; expressions inside JSX do. Type-only conditions contribute none. Source lines count distinct lines with non-brace/non-semicolon tokens owned by the member, excluding nested functions and type nodes. Executable counts count owned statements (excluding blocks/empty statements), with one for expression-bodied functions.
+
+Halstead volume is `N * log2(n)`: token count times vocabulary size. Identifiers/literals are operands; other runtime tokens are operators. Nested function and type tokens are excluded. MI is rounded to the nearest integer using:
+
+```text
+max(0, (171 - 5.2*ln(max(V,1)) - 0.23*CC - 16.2*ln(max(LOC,1))) * 100/171)
+```
+
+For hand-checking, V=64, CC=4, LOC=10 produces MI=65. Quality scores use maximum CC thresholds 5/10/20/40 for scores 10/8/6/4 (otherwise 2). Maintainability scores use median MI thresholds 85/65/40/20 for 10/8/6/4 (otherwise 2). These policies are provisional, not a claim of parity with .NET score ladders.
+
+CSV preserves the shared header. Namespace is the repository-relative module path; Project is the package name. Coupling currently counts distinct imported module specifiers per file, and is repeated on its member/type rows; it is not .NET class-coupling parity. Inheritance follows compiler-resolved class base types. Type rows sum owned member complexity/lines and average member MI; these are documented JS/TS aggregates, not Visual Studio type metrics.
+
+## Baselines and SARIF
+
+```sh
+npx codemetrics-ai --baseline quality-baselines/javascript-typescript.json \
+  --comparison-output results/comparison.json --fail-on-new warning \
+  --max-score-drop 0 --sarif results/analysis.sarif
+
+# Works with either .NET or JS/TS evidence:
+npx --package codemetrics-ai codemetrics-evidence --input results/evidence.json \
+  --baseline quality-baselines/javascript-typescript.json --output results/comparison.json
+```
+
+Exit codes: 0 success, 1 requested quality gate failed, 2 invalid input or incomplete/incompatible evidence. Without gate flags, findings do not fail an otherwise complete analysis. See [evidence workflows](../../docs/evidence-workflows.md) and [v3 migration](../../shared/scorecard-schema/migration-v3.md).
+
+## Development
+
+```sh
+npm ci
+npm test
+npm run test:package
+```
+
+Tests include parser/React/workspace fixtures, formula assertions, schema validation, comparison compatibility, gate behavior, and compiled CLI execution. The package smoke test packs and installs the package with production dependencies in an isolated directory and exercises analysis, comparison and SARIF. The shared corpus adds pinned accuracy and score-distribution checks.
+
+The packaged `codemetrics-evidence --inspect-output <path>` command reads v2/v3 and validates optional expected provenance; historical v2 cannot be compared, gated or exported as SARIF. Structured dimension scope identifies implemented coverage, including React-hook-only performance checks. See [consumer integration](../../docs/evidence-workflows.md#skill-and-other-evidence-consumers).

package/dist/analyzer.d.ts

@@ -0,0 +1,13 @@
+import { type Metric } from "./metrics.js";
+import { type Evidence } from "./evidence.js";
+export declare function analyze(options: {
+    project?: string;
+    tsconfig?: string;
+    runId?: string;
+    auditId?: string;
+}, version: string): {
+    evidence: Evidence;
+    metrics: Metric[];
+    csv: string;
+    inputs: string[];
+};

package/dist/analyzer.js

@@ -0,0 +1,102 @@
+import ts from "typescript";
+import { discover } from "./discovery.js";
+import { analyzeFile } from "./metrics.js";
+import { hash, invocationIds, scored, skippedDimensions } from "./evidence.js";
+import { metricsCsvHeader } from "./scorecard-contract.js";
+export function analyze(options, version) {
+    const identity = invocationIds(options.runId, options.auditId);
+    const discovery = discover(options.project, options.tsconfig);
+    const dimensions = skippedDimensions();
+    const diagnostics = [];
+    const metrics = [];
+    const collected = [];
+    let analyzedFiles = 0;
+    let reactSupported = false;
+    for (const pkg of discovery.packages) {
+        const program = ts.createProgram(pkg.files, { ...pkg.options, noEmit: true });
+        const checker = program.getTypeChecker();
+        for (const filename of pkg.files) {
+            const source = program.getSourceFile(filename);
+            if (!source) {
+                diagnostics.push({ kind: "sourceUnavailable", message: filename, project: pkg.name });
+                continue;
+            }
+            const errors = program.getSyntacticDiagnostics(source);
+            if (errors.length) {
+                diagnostics.push(...errors.map(error => ({ kind: "parseError", message: `${filename}: ${ts.flattenDiagnosticMessageText(error.messageText, " ")}`, project: pkg.name })));
+                continue;
+            }
+            analyzedFiles++;
+            const result = analyzeFile(source, checker, pkg.name, discovery.repositoryRoot);
+            reactSupported ||= result.reactSupported;
+            metrics.push(...result.metrics);
+            collected.push(...result.findings);
+        }
+    }
+    metrics.sort((a, b) => a.file < b.file ? -1 : a.file > b.file ? 1 : a.line - b.line);
+    if (analyzedFiles === 0)
+        diagnostics.push({ kind: "emptyPopulation", message: "No production source files were analyzed." });
+    if (metrics.length) {
+        const maximum = Math.max(...metrics.map(metric => metric.complexity));
+        const quality = maximum <= 5 ? 10 : maximum <= 10 ? 8 : maximum <= 20 ? 6 : maximum <= 40 ? 4 : 2;
+        dimensions.codeQuality = scored(quality, `Maximum member cyclomatic complexity=${maximum}; uncalibrated JS/TS policy.`, collected.filter(item => item.dimension === "codeQuality").map(item => item.finding), { maxMemberComplexity: maximum, thresholds: [5, 10, 20, 40] });
+        const values = metrics.map(metric => metric.maintainabilityIndex).sort((a, b) => a - b);
+        const median = (values[Math.floor((values.length - 1) / 2)] + values[Math.ceil((values.length - 1) / 2)]) / 2;
+        dimensions.maintainability = scored(median >= 85 ? 10 : median >= 65 ? 8 : median >= 40 ? 6 : median >= 20 ? 4 : 2, `Median member maintainability index=${median}; uncalibrated JS/TS policy.`, [], { median, thresholds: [85, 65, 40, 20] });
+        const performance = collected.filter(item => item.dimension === "performanceAsync").map(item => item.finding);
+        const actionable = performance.filter(finding => finding.confidence !== "low");
+        if (reactSupported)
+            dimensions.performanceAsync = scored(actionable.length ? 6 : 10, "Limited scope: React hook placement and effect callbacks. General async and concurrency analysis is not implemented.", performance, { actionableFindings: actionable.length, advisoryFindings: performance.length - actionable.length, scope: "react-hooks" });
+    }
+    if (diagnostics.length)
+        for (const key of ["codeQuality", "maintainability", "performanceAsync"])
+            dimensions[key] = { status: "failed", basis: "Incomplete source analysis; partial findings are unscored.", findings: dimensions[key].findings };
+    for (const [key, includes, excludes] of [
+        ["codeQuality", ["maximum-member-cyclomatic-complexity"], ["design-quality", "runtime-behavior"]],
+        ["maintainability", ["median-member-maintainability-index"], ["change-cost", "comprehensive-human-review"]],
+        ["performanceAsync", ["react-hook-placement", "react-effect-callbacks"], ["general-async", "concurrency", "runtime-performance"]]
+    ])
+        dimensions[key].scope = { id: `javascript-typescript/${key}/v1`, coverage: "partial", includes: [...includes], excludes: [...excludes] };
+    const evidence = {
+        schemaVersion: 3, generatedAtUtc: new Date().toISOString(), tool: { name: "codemetrics-ai", version, ecosystem: "javascript-typescript" },
+        subject: { root: discovery.repositoryRoot, entryPoint: discovery.entryPoint, name: discovery.name, variant: "source" },
+        filters: { totalUnits: discovery.packages.reduce((sum, pkg) => sum + pkg.files.length, 0) + discovery.skipped.length,
+            analyzedUnits: analyzedFiles, skipped: discovery.skipped },
+        population: { types: new Set(metrics.map(metric => `${metric.project}|${metric.file}|${metric.type}`)).size, members: metrics.length },
+        dimensions, analysis: { ...identity, status: diagnostics.length ? "incomplete" : "complete", ruleset: "javascript-typescript-2026-09-05",
+            calibration: "uncalibrated", configurationFingerprint: hash(JSON.stringify(canonicalConfiguration(discovery.packages.map(pkg => ({ name: pkg.name,
+                options: pkg.options, selection: pkg.selection })), discovery.repositoryRoot))), diagnostics, suppressions: [] }
+    };
+    return { evidence, metrics, csv: toCsv(metrics), inputs: discovery.packages.flatMap(pkg => [pkg.entryPoint, ...pkg.files]) };
+}
+function canonicalConfiguration(value, root) {
+    if (typeof value === "string")
+        return value.replaceAll("\\", "/").replace(root.replaceAll("\\", "/") + "/", "<root>/");
+    if (Array.isArray(value))
+        return value.map(item => canonicalConfiguration(item, root));
+    if (value && typeof value === "object")
+        return Object.fromEntries(Object.entries(value).sort(([a], [b]) => a < b ? -1 : 1)
+            .map(([key, item]) => [key, canonicalConfiguration(item, root)]));
+    return value;
+}
+function toCsv(metrics) {
+    const escape = (value) => `"${String(value).replaceAll('"', '""')}"`;
+    const rows = [];
+    const types = new Map();
+    for (const metric of metrics) {
+        const key = `${metric.project}|${metric.file}|${metric.type}`;
+        const group = types.get(key) ?? [];
+        group.push(metric);
+        types.set(key, group);
+    }
+    for (const members of types.values()) {
+        const first = members[0];
+        rows.push(["Type", first.project, first.file, first.type, "", Math.round(members.reduce((sum, m) => sum + m.maintainabilityIndex, 0) / members.length),
+            members.reduce((sum, m) => sum + m.complexity, 0), Math.max(...members.map(m => m.inheritance)), first.coupling,
+            members.reduce((sum, m) => sum + m.sourceLines, 0), members.reduce((sum, m) => sum + m.executableLines, 0)]);
+        for (const member of members)
+            rows.push(["Member", member.project, member.file, member.type, member.member, member.maintainabilityIndex,
+                member.complexity, member.inheritance, member.coupling, member.sourceLines, member.executableLines]);
+    }
+    return metricsCsvHeader + "\n" + rows.map(row => row.map(escape).join(",")).join("\n") + "\n";
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import { parseArgs } from "node:util";
+import { analyze } from "./analyzer.js";
+import { defaultEvidencePath, defaultMetricsPath } from "./scorecard-contract.js";
+import { compare, gate, readEvidence, sarif, validateEvidence } from "./evidence-tools.js";
+import { distinctOutputs, write } from "./io.js";
+try {
+    const { values } = parseArgs({ options: {
+            project: { type: "string" }, tsconfig: { type: "string" }, "run-id": { type: "string" }, "audit-id": { type: "string" }, output: { type: "string", default: defaultMetricsPath },
+            "scorecard-output": { type: "string", default: defaultEvidencePath }, baseline: { type: "string" },
+            "comparison-output": { type: "string" }, sarif: { type: "string" }, "fail-on-new": { type: "string" },
+            "max-score-drop": { type: "string" }, help: { type: "boolean", short: "h" }, version: { type: "boolean" }
+        } });
+    const version = JSON.parse(fs.readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+    if (values.help)
+        console.log([
+            "codemetrics-ai — JavaScript, TypeScript and React source analysis",
+            "--project <package.json> --tsconfig <tsconfig.json>",
+            "--run-id <uuid> --audit-id <uuid> (generated when omitted)",
+            "--output <metrics.csv> --scorecard-output <evidence.json>",
+            "--baseline <evidence.json> --comparison-output <comparison.json>",
+            "--fail-on-new <info|warning|error> --max-score-drop <number> --sarif <results.sarif>",
+            "Scores are uncalibrated across ecosystems. Unsupported dimensions are skipped.",
+            "Exit codes: 0 success, 1 quality gate, 2 invalid input/incomplete analysis."
+        ].join("\n"));
+    else if (values.version)
+        console.log(version);
+    else {
+        if ((values["fail-on-new"] || values["max-score-drop"] || values["comparison-output"]) && !values.baseline)
+            throw new Error("Comparison and quality gates require --baseline.");
+        distinctOutputs([values.project ?? "package.json", values.tsconfig, values.baseline], [values.output, values["scorecard-output"], values["comparison-output"], values.sarif]);
+        const result = analyze({ ...values, runId: values["run-id"], auditId: values["audit-id"] }, version);
+        validateEvidence(result.evidence);
+        distinctOutputs(result.inputs, [values.output, values["scorecard-output"], values["comparison-output"], values.sarif]);
+        const comparison = values.baseline ? compare(result.evidence, readEvidence(values.baseline)) : undefined;
+        const failed = comparison ? gate(comparison, values["fail-on-new"], values["max-score-drop"] === undefined ? undefined : Number(values["max-score-drop"])) : false;
+        write(values.output, result.csv);
+        write(values["scorecard-output"], result.evidence);
+        if (values.sarif)
+            write(values.sarif, sarif(result.evidence));
+        if (values["comparison-output"])
+            write(values["comparison-output"], comparison);
+        console.log("Analyzed " + result.evidence.filters.analyzedUnits + " files; " + result.metrics.length + " members. Evidence: " + values["scorecard-output"]);
+        process.exitCode = result.evidence.analysis.status === "incomplete" ? 2 : failed ? 1 : 0;
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 2;
+}

package/dist/contract-examples/dotnet-evidence.json

@@ -0,0 +1,37 @@
+{
+  "schemaVersion": 2,
+  "generatedAtUtc": "2026-06-10T00:00:00.0000000Z",
+  "tool": {
+    "name": "CodeMetrics.AI",
+    "version": "1.1.0",
+    "ecosystem": "dotnet"
+  },
+  "subject": {
+    "root": "/repo",
+    "entryPoint": "/repo/MyApp.slnx",
+    "name": "MyApp",
+    "variant": "Debug"
+  },
+  "filters": {
+    "totalUnits": 2,
+    "analyzedUnits": 1,
+    "skipped": [
+      { "name": "MyApp.Tests", "reason": "Test project" }
+    ]
+  },
+  "population": {
+    "types": 1,
+    "members": 1
+  },
+  "dimensions": {
+    "codeQuality": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "maintainability": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "errorHandling": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "performanceAsync": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "security": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "testing": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "documentation": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "dependencyManagement": { "status": "skipped", "basis": "Dependency probe skipped.", "findings": [] },
+    "architecture": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] }
+  }
+}

package/dist/contract-examples/javascript-typescript-evidence.json

@@ -0,0 +1,35 @@
+{
+  "schemaVersion": 2,
+  "generatedAtUtc": "2026-06-10T00:00:00.0000000Z",
+  "tool": {
+    "name": "codemetrics-ai",
+    "version": "0.1.0",
+    "ecosystem": "javascript-typescript"
+  },
+  "subject": {
+    "root": "/repo",
+    "entryPoint": "/repo/package.json",
+    "name": "my-app",
+    "variant": "tsconfig.json"
+  },
+  "filters": {
+    "totalUnits": 1,
+    "analyzedUnits": 1,
+    "skipped": []
+  },
+  "population": {
+    "types": 1,
+    "members": 1
+  },
+  "dimensions": {
+    "codeQuality": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "maintainability": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "errorHandling": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "performanceAsync": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "security": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "testing": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "documentation": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] },
+    "dependencyManagement": { "status": "skipped", "basis": "Dependency checks not implemented in scaffold.", "findings": [] },
+    "architecture": { "status": "scored", "score": 10, "basis": "Example.", "findings": [] }
+  }
+}

package/dist/discovery.d.ts

@@ -0,0 +1,24 @@
+import ts from "typescript";
+export declare const excludedDirectories: Set<string>;
+export declare function exclusion(file: string): string | undefined;
+export declare function walk(root: string): string[];
+export interface PackageInput {
+    name: string;
+    root: string;
+    entryPoint: string;
+    files: string[];
+    options: ts.CompilerOptions;
+    selection: unknown;
+}
+export declare function repositoryRoot(root: string): string;
+export declare function discover(project?: string, config?: string): {
+    root: string;
+    repositoryRoot: string;
+    entryPoint: string;
+    name: any;
+    packages: PackageInput[];
+    skipped: {
+        name: string;
+        reason: string;
+    }[];
+};

package/dist/discovery.js

@@ -0,0 +1,101 @@
+import fs from "node:fs";
+import path from "node:path";
+import ts from "typescript";
+export const excludedDirectories = new Set(["node_modules", ".git", ".worktrees", ".scorecard", "dist", "build", ".next", "out", "coverage", "vendor"]);
+const slash = (file) => file.replaceAll("\\", "/");
+export function exclusion(file) {
+    const name = slash(file);
+    if (name.split("/").some(part => excludedDirectories.has(part)))
+        return "Build output, dependencies, or metadata";
+    if (/\.d\.[cm]?ts$/.test(name))
+        return "Type declarations";
+    if (/(^|\/)(__tests__|tests?|fixtures)(\/|$)|\.(test|spec)\.[cm]?[jt]sx?$/.test(name))
+        return "Test or fixture source";
+    if (/(\.generated\.|\.g\.|\.min\.)/.test(name))
+        return "Generated source";
+    return undefined;
+}
+export function walk(root) {
+    const files = [];
+    for (const entry of fs.readdirSync(root, { withFileTypes: true }).sort((a, b) => a.name < b.name ? -1 : 1)) {
+        if (entry.isSymbolicLink())
+            continue;
+        const full = path.join(root, entry.name);
+        if (entry.isDirectory() && !excludedDirectories.has(entry.name))
+            files.push(...walk(full));
+        else if (entry.isFile())
+            files.push(full);
+    }
+    return files;
+}
+export function repositoryRoot(root) {
+    for (let directory = root;; directory = path.dirname(directory)) {
+        if (fs.existsSync(path.join(directory, ".git")))
+            return directory;
+        if (path.dirname(directory) === directory)
+            return root;
+    }
+}
+export function discover(project, config) {
+    const entryPoint = path.resolve(project ?? (config ? path.join(path.dirname(config), "package.json") : "package.json"));
+    if (!fs.existsSync(entryPoint))
+        throw new Error(`Package manifest does not exist: ${entryPoint}`);
+    const root = path.dirname(entryPoint);
+    const manifest = JSON.parse(fs.readFileSync(entryPoint, "utf8"));
+    const workspacePatterns = Array.isArray(manifest.workspaces) ? manifest.workspaces : manifest.workspaces?.packages;
+    const manifests = [entryPoint];
+    if (Array.isArray(workspacePatterns)) {
+        if (!workspacePatterns.every(pattern => typeof pattern === "string" && !pattern.startsWith("!") && !pattern.includes("..")))
+            throw new Error("Workspace patterns must be relative positive globs without '..'.");
+        manifests.push(...ts.sys.readDirectory(root, [".json"], ["**/node_modules/**", "**/.git/**", "**/.worktrees/**"], workspacePatterns.map(pattern => `${pattern.replace(/\/$/, "")}/package.json`)));
+    }
+    const packages = [];
+    const skipped = [];
+    const owned = new Set();
+    // Children own their files before the workspace root is scanned.
+    const manifestPaths = [...new Set(manifests.map(file => path.resolve(file)))];
+    for (const manifestPath of manifestPaths.sort((a, b) => b.length - a.length || a.localeCompare(b, "en"))) {
+        const packageRoot = path.dirname(manifestPath);
+        const data = JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+        const configPath = config && manifestPath === entryPoint ? path.resolve(config) : path.join(packageRoot, "tsconfig.json");
+        if (config && manifestPath === entryPoint && !fs.existsSync(configPath))
+            throw new Error(`tsconfig does not exist: ${configPath}`);
+        let files;
+        let selection = "default-source-scan";
+        let options = { allowJs: true, jsx: ts.JsxEmit.Preserve, target: ts.ScriptTarget.Latest, noEmit: true };
+        if (fs.existsSync(configPath)) {
+            const read = ts.readConfigFile(configPath, ts.sys.readFile);
+            if (read.error)
+                throw new Error(ts.flattenDiagnosticMessageText(read.error.messageText, "\n"));
+            const parsed = ts.parseJsonConfigFileContent(read.config, ts.sys, path.dirname(configPath), { noEmit: true }, configPath);
+            const errors = parsed.errors.filter(error => error.code !== 18003);
+            if (errors.length)
+                throw new Error(errors.map(error => ts.flattenDiagnosticMessageText(error.messageText, "\n")).join("\n"));
+            files = parsed.fileNames;
+            options = parsed.options;
+            selection = { include: parsed.raw.include, exclude: parsed.raw.exclude, files: parsed.raw.files, references: parsed.raw.references };
+        }
+        else
+            files = walk(packageRoot).filter(file => /\.[cm]?[jt]sx?$/.test(file));
+        const accepted = [];
+        for (const file of files.map(file => path.resolve(file)).sort()) {
+            if (manifestPaths.some(other => other !== manifestPath && path.dirname(other).startsWith(packageRoot + path.sep) && file.startsWith(path.dirname(other) + path.sep)))
+                continue;
+            const relative = slash(path.relative(root, file));
+            if (owned.has(file))
+                continue;
+            owned.add(file);
+            const reason = relative.startsWith("../") ? "Outside repository" : exclusion(relative);
+            if (reason) {
+                skipped.push({ name: relative, reason });
+                continue;
+            }
+            if (/^\s*(?:\/\/|\/\*)[^\n]*(?:@generated|<auto-generated)/im.test(fs.readFileSync(file, "utf8")))
+                skipped.push({ name: relative, reason: "Generated source marker" });
+            else
+                accepted.push(file);
+        }
+        packages.push({ name: data.name ?? path.basename(packageRoot), root: packageRoot, entryPoint: manifestPath, files: accepted, options, selection });
+    }
+    return { root, repositoryRoot: repositoryRoot(root), entryPoint, name: manifest.name ?? path.basename(root), packages, skipped };
+}

package/dist/evidence-cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/evidence-cli.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import { compare, gate, readEvidence, sarif } from "./evidence-tools.js";
+import { distinctOutputs, write } from "./io.js";
+import { inspectEvidence } from "./evidence-reader.js";
+try {
+    const { values } = parseArgs({ options: { input: { type: "string" }, baseline: { type: "string" }, output: { type: "string" },
+            sarif: { type: "string" }, "allow-incompatible": { type: "boolean" }, "fail-on-new": { type: "string" },
+            "max-score-drop": { type: "string" }, "inspect-output": { type: "string" },
+            "expected-ecosystem": { type: "string" }, "expected-version": { type: "string" }, "expected-run-id": { type: "string" }, "expected-audit-id": { type: "string" },
+            "expected-entry-point": { type: "string" }, "expected-variant": { type: "string" }, "expected-root": { type: "string" },
+            help: { type: "boolean", short: "h" } } });
+    if (values.help)
+        console.log([
+            "codemetrics-evidence — validate v2/v3, compare and export v3 evidence from any ecosystem",
+            "--input <evidence.json> [--baseline <baseline.json> --output <comparison.json>]",
+            "--sarif <results.sarif> --fail-on-new <info|warning|error> --max-score-drop <number>",
+            "--inspect-output <inspection.json> reads v2/v3 without upgrading historical evidence.",
+            "--expected-ecosystem <id> --expected-version <version> --expected-entry-point <path> --expected-variant <variant> --expected-root <path>",
+            "--expected-run-id <uuid> --expected-audit-id <uuid> reject findings from another invocation, including files with missing IDs.",
+            "--allow-incompatible permits exploratory comparison with null score deltas; gates remain disabled.",
+            "Exit codes: 0 success, 1 quality gate, 2 invalid/incompatible/incomplete evidence."
+        ].join("\n"));
+    else {
+        if (!values.input)
+            throw new Error("--input is required.");
+        distinctOutputs([values.input, values.baseline], [values.output, values.sarif, values["inspect-output"]]);
+        const inspection = inspectEvidence(values.input, { ecosystem: values["expected-ecosystem"], version: values["expected-version"],
+            entryPoint: values["expected-entry-point"], variant: values["expected-variant"], root: values["expected-root"],
+            runId: values["expected-run-id"], auditId: values["expected-audit-id"] });
+        if (values["inspect-output"])
+            write(values["inspect-output"], inspection);
+        if (inspection.evidence.schemaVersion === 2) {
+            if (values.baseline || values.output || values.sarif || values["fail-on-new"] !== undefined || values["max-score-drop"] !== undefined)
+                throw new Error("V2 is compatibility-only: comparison, gates and SARIF require v3. Re-run the pinned analyzer.");
+            console.log("V2 evidence is valid; completeness, scope and comparison provenance are unknown.");
+            process.exitCode = inspection.usable ? 0 : 2;
+        }
+        else {
+            const current = readEvidence(values.input);
+            if (!values.baseline && (values.output || values["fail-on-new"] || values["max-score-drop"]))
+                throw new Error("Comparison and quality gates require --baseline.");
+            let failed = false;
+            if (values.baseline) {
+                const result = compare(current, readEvidence(values.baseline), values["allow-incompatible"]);
+                if (values["fail-on-new"] !== undefined || values["max-score-drop"] !== undefined)
+                    failed = gate(result, values["fail-on-new"], values["max-score-drop"] === undefined ? undefined : Number(values["max-score-drop"]));
+                if (values.output)
+                    write(values.output, result);
+                else
+                    console.log(JSON.stringify(result, null, 2));
+            }
+            if (values.sarif)
+                write(values.sarif, sarif(current));
+            process.exitCode = current.analysis.status !== "complete" || Object.values(current.dimensions).some(d => d.status === "failed") ? 2 : failed ? 1 : 0;
+            if (!values.baseline)
+                console.log("Evidence is valid.");
+        }
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 2;
+}

package/dist/evidence-reader.d.ts

@@ -0,0 +1,27 @@
+import type { Evidence, Dimension, Finding } from "./evidence.js";
+import type { DimensionKey } from "./scorecard-contract.js";
+export type LegacyEvidence = Omit<Evidence, "analysis" | "dimensions"> & {
+    dimensions: Record<DimensionKey, Omit<Dimension, "findings"> & {
+        findings: Omit<Finding, "ruleId" | "fingerprint" | "confidence" | "observations">[];
+    }>;
+};
+/** Read historical evidence without fabricating v3 metadata or enabling comparisons. */
+export declare function readCompatibleEvidence(file: string): Evidence | LegacyEvidence;
+export declare function inspectEvidence(file: string, expected?: {
+    ecosystem?: string;
+    version?: string;
+    entryPoint?: string;
+    variant?: string;
+    root?: string;
+    runId?: string;
+    auditId?: string;
+}): {
+    evidence: Evidence | LegacyEvidence;
+    compatibility: {
+        mode: string;
+        comparisonAvailable: boolean;
+        analysisStatus: string;
+        scopeAvailable: boolean;
+    };
+    usable: boolean;
+};

package/dist/evidence-reader.js

@@ -0,0 +1,53 @@
+import fs from "node:fs";
+import path from "node:path";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { validateEvidence } from "./evidence-tools.js";
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+addFormats(ajv);
+let legacyValidator;
+/** Read historical evidence without fabricating v3 metadata or enabling comparisons. */
+export function readCompatibleEvidence(file) {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    if (value?.schemaVersion === 3)
+        validateEvidence(value);
+    else if (value?.schemaVersion === 2) {
+        legacyValidator ??= ajv.compile(JSON.parse(fs.readFileSync(new URL("./evidence.schema.v2.json", import.meta.url), "utf8")));
+        if (!legacyValidator(value))
+            throw new Error("Invalid v2 evidence: " + ajv.errorsText(legacyValidator.errors));
+        if (value.filters.analyzedUnits > value.filters.totalUnits)
+            throw new Error("Analyzed units exceed total units.");
+    }
+    else
+        throw new Error("Unsupported evidence schema; supported versions are 2 and 3.");
+    return value;
+}
+export function inspectEvidence(file, expected = {}) {
+    const evidence = readCompatibleEvidence(file);
+    for (const key of ["runId", "auditId"])
+        if (expected[key] !== undefined && evidence.analysis?.[key]?.toLowerCase() !== expected[key]?.toLowerCase())
+            throw new Error(`Stale or unrelated evidence: analysis.${key} does not match this invocation.`);
+    for (const key of ["ecosystem", "version"])
+        if (expected[key] !== undefined && evidence.tool[key] !== expected[key])
+            throw new Error(`Provenance mismatch: tool.${key}`);
+    if (expected.variant !== undefined && evidence.subject.variant !== expected.variant)
+        throw new Error("Provenance mismatch: subject.variant");
+    const normalize = (value) => {
+        const absolute = path.resolve(value);
+        // Native resolution handles Windows 8.3 names as well as junctions/symlinks.
+        // Historical paths may no longer exist; retain lexical matching for those.
+        const resolved = fs.existsSync(absolute) ? fs.realpathSync.native(absolute) : absolute;
+        return process.platform === "win32" ? resolved.toLowerCase() : resolved;
+    };
+    if (expected.root !== undefined && normalize(evidence.subject.root) !== normalize(expected.root))
+        throw new Error("Provenance mismatch: subject.root");
+    if (expected.entryPoint !== undefined && normalize(path.resolve(evidence.subject.root, evidence.subject.entryPoint)) !== normalize(expected.entryPoint))
+        throw new Error("Provenance mismatch: subject.entryPoint");
+    const legacy = evidence.schemaVersion === 2;
+    const failed = Object.values(evidence.dimensions).some(dimension => dimension.status === "failed");
+    const incomplete = !legacy && evidence.analysis.status !== "complete";
+    return { evidence, compatibility: { mode: legacy ? "legacy" : "native", comparisonAvailable: !legacy && !failed && !incomplete,
+            analysisStatus: legacy ? "unknown" : evidence.analysis.status,
+            scopeAvailable: !legacy && Object.values(evidence.dimensions).every(dimension => dimension.scope !== undefined) },
+        usable: !failed && !incomplete };
+}