codemetrics-ai 0.5.0 → 0.6.0-preview.1

package/dist/python-async-usage.js

@@ -0,0 +1,143 @@
+import { isDeepStrictEqual } from "node:util";
+import { fingerprint } from "./python-error-context.js";
+export const asyncUsagePolicy = "python/async-owned-calls-review-v1";
+const blocking = ["os.system", "subprocess.call", "subprocess.check_call", "subprocess.check_output", "subprocess.run", "time.sleep", "urllib.request.urlopen"];
+const offload = ["anyio.to_thread.run_sync", "asyncio.to_thread", "starlette.concurrency.run_in_threadpool"];
+const wrapper = "asgiref.sync.sync_to_async";
+const unresolved = ["dynamic-callee-expression", "comprehension-local-binding", "reflective-or-cross-scope-binding", "non-import-or-ambiguous-binding", "import-not-before-use", "imported-module-attribute-write", "no-lexical-import"];
+const expressionKinds = ["BoolOp", "NamedExpr", "BinOp", "UnaryOp", "Lambda", "IfExp", "Dict", "Set", "ListComp", "SetComp", "DictComp", "GeneratorExp", "Await", "Yield", "YieldFrom", "Compare", "Call", "FormattedValue", "JoinedStr", "Constant", "Attribute", "Subscript", "Name", "List", "Tuple"];
+function requireValue(condition, message) {
+    if (!condition)
+        throw new Error(`Invalid Python async evidence: ${message}.`);
+}
+function keys(value, names) {
+    requireValue(value !== null && typeof value === "object" && !Array.isArray(value), "object required");
+    requireValue(isDeepStrictEqual(Object.keys(value).sort(), names.sort()), "unexpected or missing fields");
+}
+const integer = (value) => Number.isSafeInteger(value) && value >= 0;
+const nonempty = (value) => typeof value === "string" && value.trim().length > 0;
+const pathSyntax = (value) => nonempty(value) && value.split(".").every(part => part.trim() === part && part.length > 0 && !/[\s()\[\]]/u.test(part));
+const histogram = (items) => Object.fromEntries([...new Set(items)].sort().map(key => [key, items.filter(value => value === key).length]));
+function binding(value, wrapped = false) {
+    keys(value, ["syntax", "target", "status", "reason"]);
+    requireValue(value.syntax === null || pathSyntax(value.syntax), "invalid callee spelling");
+    if (value.status === "import-matched") {
+        requireValue(pathSyntax(value.target) && value.syntax !== null, "matched import must have a target and spelling");
+        requireValue(value.reason === (wrapped ? "immediate-import-matched-wrapper-syntax" : "import-spelling-only"), "invalid match reason");
+    }
+    else {
+        requireValue(!wrapped && value.status === "unresolved" && value.target === null && unresolved.includes(value.reason), "invalid unresolved binding");
+        requireValue((value.syntax === null) === (value.reason === "dynamic-callee-expression"), "binding syntax/reason mismatch");
+    }
+}
+function callback(value) {
+    requireValue(value !== null, "helper callback evidence required");
+    if (value.kind === "unresolved-argument-layout") {
+        keys(value, ["kind", "binding"]);
+        requireValue(value.binding === null, "unresolved arguments cannot resolve a callback");
+        return;
+    }
+    keys(value, ["kind", "binding", "evaluation"]);
+    requireValue(expressionKinds.includes(value.kind) && value.binding !== null, "invalid callback expression");
+    binding(value.binding);
+    requireValue(value.evaluation === (value.kind === "Call" ? "eager-call-expression" : "callback-expression-only"), "callback evaluation mismatch");
+    requireValue((value.binding.syntax !== null) === ["Name", "Attribute"].includes(value.kind) ||
+        value.kind === "Attribute" && value.binding.syntax === null, "callback spelling/kind mismatch");
+}
+function counts(rows) {
+    const eligible = rows.filter(row => row.status === "observed");
+    const calls = eligible.flatMap(row => row.measurement.calls);
+    const direct = calls.filter(call => call.executionContext === "async-body");
+    return { selectedFunctions: rows.length, asyncFunctions: eligible.length, excludedSynchronousFunctions: rows.length - eligible.length,
+        availability: eligible.length ? "available" : "unavailable", asyncBodyCallExpressions: eligible.length ? direct.length : null,
+        asyncBodyCallCategories: eligible.length ? histogram(direct.map(call => call.category)) : null,
+        deferredGeneratorCallExpressions: eligible.length ? calls.length - direct.length : null,
+        functionsWithBlockingCandidates: eligible.length ? eligible.filter(row => row.measurement.calls.some(call => call.category === "blocking-call-candidate" && call.executionContext === "async-body")).length : null };
+}
+function callEvidence(call, row, used) {
+    keys(call, ["id", "line", "column", "endLine", "endColumn", "executionContext", "category", "binding", "directlyAwaited", "callback", "disposition"]);
+    requireValue([call.line, call.column, call.endLine, call.endColumn].every(integer) && call.line >= row.line && call.endLine <= row.endLine &&
+        (call.endLine > call.line || call.endLine === call.line && call.endColumn > call.column), "invalid call extent");
+    const location = { line: call.line, column: call.column, endLine: call.endLine, endColumn: call.endColumn };
+    requireValue(call.id === fingerprint([row.id, location]) && !used.has(call.id), "call identity mismatch or duplicate");
+    used.add(call.id);
+    requireValue(["async-body", "deferred-generator-body"].includes(call.executionContext) && typeof call.directlyAwaited === "boolean" && call.disposition === "review-only", "call context/disposition mismatch");
+    const wrapped = call.category === "offload-wrapped-invocation";
+    binding(call.binding, wrapped);
+    const target = call.binding.target;
+    const category = target === null ? "unresolved-call" : blocking.includes(target) ? "blocking-call-candidate" :
+        offload.includes(target) ? "offload-call" : target === wrapper ? (wrapped ? "offload-wrapped-invocation" : "offload-wrapper-construction") : "other-import-call";
+    requireValue(call.category === category, "call category does not match the catalogue");
+    if (call.category.startsWith("offload-")) {
+        requireValue(call.callback !== null, "helper callback required");
+        callback(call.callback);
+        if (wrapped) {
+            requireValue(call.callback.kind !== "unresolved-argument-layout", "wrapped invocation requires a direct positional callback");
+            requireValue(row.measurement.calls.some(inner => inner.category === "offload-wrapper-construction" &&
+                inner.line === call.line && inner.column === call.column &&
+                (inner.endLine < call.endLine || inner.endLine === call.endLine && inner.endColumn < call.endColumn) &&
+                inner.executionContext === call.executionContext && !inner.directlyAwaited && isDeepStrictEqual(inner.callback, call.callback)), "missing immediate wrapper construction");
+        }
+    }
+    else
+        requireValue(call.callback === null, "non-helper cannot claim an offloaded callback");
+}
+/** Validate identity, catalogue coherence and accounting, not runtime resolution or independent AST semantics. */
+export function validateAsyncUsage(value, facts, subject, ids, decomposition) {
+    keys(value, ["schemaVersion", "artifactKind", "producer", "generatedAtUtc", "runId", "auditId", "policy", "configuration", "configurationFingerprint", "subject", "sourceFactsProducer", "sourceFactsPolicy", "selection", "status", "diagnostics", "scope", "functions", "summary"]);
+    const report = value;
+    requireValue(report.schemaVersion === 1 && report.artifactKind === "experimental-python-async-usage-review" && report.policy === asyncUsagePolicy &&
+        isDeepStrictEqual(report.producer, { name: "codemetrics-ai/python-async-usage", version: "0.1.0-experimental" }), "unsupported producer/policy");
+    requireValue(report.runId === ids.runId && report.auditId === ids.auditId, "stale invocation identities");
+    const target = subject.entryPoint.replaceAll("\\", "/").endsWith("/pyproject.toml") ? subject.root : subject.entryPoint;
+    requireValue(isDeepStrictEqual(report.subject, { root: subject.root, entryPoint: target }) && isDeepStrictEqual(report.selection, facts.selection) &&
+        isDeepStrictEqual(report.sourceFactsProducer, facts.producer) && report.sourceFactsPolicy === facts.measurementPolicy, "source provenance mismatch");
+    const configuration = { policy: asyncUsagePolicy, selectionFingerprint: facts.selection.configurationFingerprint, parserVersion: facts.producer.parserVersion,
+        maxOwners: 100000, maxCalls: 100000, blockingCatalogue: blocking, offloadCatalogue: offload, wrapperCatalogue: [wrapper] };
+    requireValue(isDeepStrictEqual(report.configuration, configuration) && report.configurationFingerprint === fingerprint(configuration), "configuration mismatch");
+    requireValue(nonempty(report.scope) && typeof report.generatedAtUtc === "string" && Number.isFinite(Date.parse(report.generatedAtUtc)), "missing scope/time");
+    requireValue(Array.isArray(report.functions) && Array.isArray(report.diagnostics), "collections required");
+    for (const item of report.diagnostics) {
+        keys(item, item.file === undefined ? ["code", "message"] : ["code", "message", "file"]);
+        requireValue(nonempty(item.code) && typeof item.message === "string" && (item.file === undefined || typeof item.file === "string"), "invalid diagnostic");
+    }
+    if (report.status === "incomplete") {
+        requireValue(report.diagnostics.length > 0 && report.functions.length === 0 && report.summary === null, "incomplete review must withhold rows");
+        return;
+    }
+    requireValue(report.status === "complete" && facts.status === "complete" && !report.diagnostics.length && report.functions.length <= 100000, "status/owner budget mismatch");
+    const owners = new Map(facts.functions.map(row => [row.id, row]));
+    const bodies = new Map(decomposition.functions.map(row => [row.id, row]));
+    const files = new Map(facts.selection.files.map(row => [row.file, row]));
+    const used = new Set(), calls = new Set();
+    for (const row of report.functions) {
+        keys(row, ["id", "file", "member", "line", "population", "sourceSha256", "endLine", "functionKind", "disposition", "status", "reason", "measurement"]);
+        const owner = owners.get(row.id), body = bodies.get(row.id);
+        requireValue(owner && !used.has(row.id), "unknown or repeated owner");
+        used.add(row.id);
+        requireValue(row.file === owner.file && row.member === owner.member && row.line === owner.line && row.population === owner.population &&
+            row.sourceSha256 === files.get(row.file)?.contentSha256 && integer(row.endLine) && row.endLine >= row.line && row.disposition === "review-only", "owner location/source mismatch");
+        if (decomposition.status === "complete")
+            requireValue(body && row.functionKind === body.functionKind && row.endLine === body.endLine, "owner differs from decomposition");
+        if (["FunctionDef", "Lambda"].includes(row.functionKind)) {
+            requireValue(row.status === "excluded" && row.reason === "synchronous-owner" && row.measurement === null, "synchronous owner must be excluded");
+            continue;
+        }
+        requireValue(row.functionKind === "AsyncFunctionDef" && row.status === "observed" && row.reason === null, "async owner required");
+        keys(row.measurement, ["kind", "awaitExpressions", "calls"]);
+        const measurement = row.measurement;
+        requireValue(["coroutine", "async-generator"].includes(measurement.kind) && Array.isArray(measurement.calls), "invalid async measurement");
+        requireValue(measurement.awaitExpressions !== null && typeof measurement.awaitExpressions === "object" && !Array.isArray(measurement.awaitExpressions), "await histogram required");
+        for (const [key, count] of Object.entries(measurement.awaitExpressions))
+            requireValue(["async-body", "deferred-generator-body"].includes(key) && integer(count) && count > 0, "invalid await count");
+        for (const call of measurement.calls)
+            callEvidence(call, row, calls);
+        for (const context of ["async-body", "deferred-generator-body"])
+            requireValue(measurement.calls.filter(call => call.executionContext === context && call.directlyAwaited).length <= (measurement.awaitExpressions[context] ?? 0), "direct-await accounting mismatch");
+        requireValue(calls.size <= 100000, "call budget exceeded");
+    }
+    requireValue(used.size === owners.size, "missing selected owners");
+    const expected = { ...counts(report.functions), populations: Object.fromEntries([...new Set(report.functions.map(row => row.population))].sort()
+            .map(population => [population, counts(report.functions.filter(row => row.population === population))])) };
+    requireValue(isDeepStrictEqual(report.summary, expected), "summary accounting mismatch");
+}

package/dist/python-cli.d.ts

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

package/dist/python-cli.js

@@ -0,0 +1,53 @@
+#!/usr/bin/env node
+import fs from "node:fs";
+import path from "node:path";
+import { parseArgs } from "node:util";
+import { analyzePython } from "./python-analyzer.js";
+import { pythonVersion } from "./python-evidence.js";
+import { validateEvidence } from "./evidence-tools.js";
+try {
+    const { values } = parseArgs({ options: {
+            project: { type: "string" }, python: { type: "string" }, "scorecard-output": { type: "string" },
+            "run-id": { type: "string" }, "audit-id": { type: "string" },
+            "coverage-json": { type: "string" }, "collection-manifest": { type: "string" },
+            include: { type: "string", multiple: true }, exclude: { type: "string", multiple: true },
+            "test-path": { type: "string", multiple: true }, "production-path": { type: "string", multiple: true },
+            "include-tests": { type: "boolean" }, "include-generated": { type: "boolean" }, "include-support": { type: "boolean" },
+            help: { type: "boolean", short: "h" }, version: { type: "boolean" }
+        } });
+    if (values.help)
+        console.log([
+            "codemetrics-python — Python 3.12 Method Complexity scoring and unscored decomposition, duplication, and coverage evidence (Node 20+)",
+            "--project <directory|pyproject.toml|file.py> --scorecard-output <new-evidence.json>",
+            "--python <absolute Python 3.12 interpreter path> (default: py -3.12 on Windows; python3 elsewhere)",
+            "--include <pattern> --exclude <pattern> --test-path <pattern> --production-path <pattern> (repeatable)",
+            "--include-tests --include-generated --include-support --run-id <uuid> --audit-id <uuid>",
+            "--coverage-json <coverage.py JSON> --collection-manifest <optional collection receipt>",
+            "Coverage/CRAP is unscored. Missing coverage stays unavailable; unbound imports stay conditional. Provenance mismatches fail.",
+            "Emits evidence v3 with one scored dimension for nonempty production implementations. Other dimensions are unavailable. No CSV.",
+            "Matching supported policies and selections can compare Method Complexity scores through codemetrics-evidence. Exact whole-body duplication is review-only, with a five-statement minimum. Zero matches does not prove no duplication.",
+            "Target code is parsed, never installed or executed. Exit 0: complete (possibly empty); 2: invalid/incomplete."
+        ].join("\n"));
+    else if (values.version)
+        console.log(pythonVersion);
+    else {
+        if (!values.project || !values["scorecard-output"])
+            throw new Error("--project and --scorecard-output are required.");
+        const output = path.resolve(values["scorecard-output"]);
+        if (path.extname(output) !== ".json" || fs.existsSync(output))
+            throw new Error("Evidence output must be a new .json file; existing files are never overwritten.");
+        const evidence = analyzePython({ project: values.project, python: values.python, runId: values["run-id"], auditId: values["audit-id"],
+            coverageJson: values["coverage-json"], collectionManifest: values["collection-manifest"],
+            include: values.include, exclude: values.exclude, testPath: values["test-path"], productionPath: values["production-path"],
+            includeTests: values["include-tests"], includeGenerated: values["include-generated"], includeSupport: values["include-support"] });
+        validateEvidence(evidence);
+        fs.mkdirSync(path.dirname(output), { recursive: true });
+        fs.writeFileSync(output, JSON.stringify(evidence, null, 2) + "\n", { flag: "wx" });
+        console.log(`Python ${evidence.analysis.status}; ${evidence.population.members} implementation bodies. Evidence: ${output}`);
+        process.exitCode = evidence.analysis.status === "complete" ? 0 : 2;
+    }
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 2;
+}

package/dist/python-collect-cli.d.ts

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

package/dist/python-collect-cli.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { spawnSync } from "node:child_process";
+// Explicit opt-in test execution; never called by the scorecard analyzer.
+try {
+    const args = process.argv.slice(2);
+    const separator = args.indexOf("--");
+    const options = separator < 0 ? args : args.slice(0, separator);
+    const index = options.indexOf("--python");
+    const supplied = index >= 0 ? options[index + 1] : undefined;
+    if (supplied && !path.isAbsolute(supplied))
+        throw new Error("--python must be an absolute Python 3.12 interpreter path.");
+    if (!supplied && !options.includes("--help") && !options.includes("-h"))
+        throw new Error("Explicit collection executes tests. Supply --python with an environment containing coverage.py and the project's test dependencies.");
+    const script = fileURLToPath(new URL("./python/coverage_collect.py", import.meta.url));
+    const bootstrap = "import runpy,sys; from pathlib import Path; script=sys.argv[1]; sys.path.insert(0,str(Path(script).parent)); sys.argv=sys.argv[1:]; runpy.run_path(script,run_name='__main__')";
+    const command = supplied ?? (process.platform === "win32" ? "py" : "python3");
+    const result = spawnSync(command, [...(!supplied && process.platform === "win32" ? ["-3.12"] : []),
+        "-I", "-S", "-B", "-c", bootstrap, script, ...args], { stdio: "inherit", windowsHide: true });
+    if (result.error)
+        throw result.error;
+    process.exitCode = result.status === 0 ? 0 : 2;
+}
+catch (error) {
+    console.error(error instanceof Error ? error.message : error);
+    process.exitCode = 2;
+}

package/dist/python-complexity.d.ts

@@ -0,0 +1,18 @@
+import type { SourceFacts } from "#source-facts/contract.mjs";
+import { type Dimension } from "./evidence.js";
+export declare const pythonComplexityPolicy = "python/method-complexity-worst-40-remainder-60/v1";
+export declare const pythonCalibration = "baseline";
+/** Score each selected production implementation once; other populations remain review evidence. */
+export declare function methodComplexity(facts: SourceFacts | null): {
+    status: string;
+    scoringPolicy: string;
+    measurementPolicy: string;
+    comparableAcrossLanguages: boolean;
+    selectedFunctions: number | null;
+    eligibleFunctions: number | null;
+    excludedPopulations: {
+        [k: string]: number;
+    } | null;
+    population: import("#source-facts/population.mjs").PopulationResult | null;
+};
+export declare function scoreMethodComplexity(dimension: Dimension, facts: SourceFacts | null, complete: boolean): Dimension;

package/dist/python-complexity.js

@@ -0,0 +1,36 @@
+import { aggregatePopulation, complexityAnchors } from "#source-facts/population.mjs";
+import { scored } from "./evidence.js";
+import { firstMatch } from "./scoring-decision.js";
+export const pythonComplexityPolicy = "python/method-complexity-worst-40-remainder-60/v1";
+export const pythonCalibration = "baseline";
+/** Score each selected production implementation once; other populations remain review evidence. */
+export function methodComplexity(facts) {
+    const available = facts?.status === "complete" && facts.capabilities.functionComplexity === "available";
+    const selected = available ? facts.functions : [];
+    const eligible = selected.filter(item => item.population === "production");
+    const population = available ? aggregatePopulation(eligible.map(item => ({ id: item.id, value: item.complexity.value })), complexityAnchors, true, 1) : null;
+    return { status: population ? "scored" : "unavailable", scoringPolicy: pythonComplexityPolicy,
+        measurementPolicy: "python/owned-function-complexity-v2", comparableAcrossLanguages: false,
+        selectedFunctions: available ? selected.length : null, eligibleFunctions: available ? eligible.length : null,
+        excludedPopulations: available ? Object.fromEntries(["test", "support", "generated"].map(kind => [kind, selected.filter(item => item.population === kind).length])) : null,
+        population };
+}
+export function scoreMethodComplexity(dimension, facts, complete) {
+    const details = methodComplexity(complete ? facts : null);
+    const { experimentalPreview: _preview, ...base } = dimension;
+    const findings = base.findings.map(finding => finding.category === "methodComplexityReview" ? { ...finding,
+        observations: { ...finding.observations, scoringDisposition: finding.observations.population === "production" ? "aggregate-policy-input" : "unscored" }
+    } : finding);
+    const scope = { id: pythonComplexityPolicy, coverage: "partial",
+        includes: ["selected-production-function-complexity"],
+        excludes: ["test-support-generated-scoring", "decomposition-scoring", "duplication-scoring", "coverage-crap-scoring", "runtime-performance", "semantic-validation"] };
+    if (!details.population)
+        return { ...base, scope, findings, methodComplexity: details,
+            basis: complete ? "Method Complexity unavailable: no selected production implementations. Other measurements are unscored review evidence." : base.basis };
+    const decision = firstMatch(pythonComplexityPolicy, { measurementPolicy: facts.measurementPolicy,
+        eligibleFunctions: details.eligibleFunctions, excludedPopulations: details.excludedPopulations,
+        anchors: complexityAnchors, weighting: "one-worst-40-percent/remainder-mean-60-percent; singleton-100-percent", rounding: "decimal-half-up-one-place" }, [{ id: "methodComplexity", condition: "nonempty selected production implementation population", matched: true,
+            score: details.population.score, categories: ["methodComplexityReview"] }]);
+    return { ...base, ...scored(decision, "Method Complexity of selected production implementations. Decomposition, duplication and coverage/CRAP are unscored review evidence.", findings, { population: details.population }, finding => finding.category === "methodComplexityReview" && finding.observations.population === "production"),
+        scope, methodComplexity: details };
+}

package/dist/python-coverage.d.ts

@@ -0,0 +1,63 @@
+import type { SourceFacts } from "#source-facts/contract.mjs";
+import { type Evidence } from "./evidence.js";
+type ObjectValue = Record<string, unknown>;
+interface CoverageRow {
+    id: string;
+    file: string;
+    member: string;
+    line: number;
+    endLine: number;
+    population: string;
+    sourceSha256: string;
+    complexity: number;
+    coverage: {
+        status: string;
+        reason?: string;
+        basis?: string;
+        coveredLines?: number;
+        executableLines?: number;
+        executedLines?: number[];
+        missingLines?: number[];
+        excludedLines?: number[];
+        fraction?: number;
+    };
+    crapEstimate: {
+        value: number;
+        disposition: string;
+        basis: string;
+        formula: string;
+    } | null;
+}
+export interface PythonCoverage {
+    schemaVersion: number;
+    artifactKind: string;
+    producer: {
+        name: string;
+        version: string;
+    };
+    generatedAtUtc: string;
+    runId: string;
+    auditId: string;
+    status: string;
+    policy: string;
+    configuration: ObjectValue;
+    configurationFingerprint: string;
+    subject: {
+        root: string;
+        entryPoint: string;
+    };
+    sourceFactsProducer: SourceFacts["producer"];
+    selection: SourceFacts["selection"];
+    coverageInput: ObjectValue | null;
+    collectionProvenance: ObjectValue | null;
+    diagnostics: SourceFacts["diagnostics"];
+    scope: string;
+    functions: CoverageRow[];
+    summary: ObjectValue | null;
+}
+/** Offline integrity checks; this does not rerun tests or authenticate unsigned receipts. */
+export declare function validateCoverage(value: unknown, facts: SourceFacts, subject: Evidence["subject"], ids: {
+    runId: string;
+    auditId: string;
+}): asserts value is PythonCoverage;
+export {};

package/dist/python-coverage.js

@@ -0,0 +1,173 @@
+import { isDeepStrictEqual } from "node:util";
+import { hash } from "./evidence.js";
+const policy = "python/coveragepy-line-crap-review-v1";
+const formula = "CC^2 * (1 - coveredLines / executableLines)^3 + CC";
+function requireValue(value, message) {
+    if (!value)
+        throw new Error(`Invalid Python coverage evidence: ${message}.`);
+}
+function object(value) {
+    requireValue(value !== null && typeof value === "object" && !Array.isArray(value), "expected object");
+}
+function keys(value, fields) {
+    object(value);
+    requireValue(isDeepStrictEqual(Object.keys(value).sort(), [...fields].sort()), "unexpected or missing fields");
+}
+const text = (value) => typeof value === "string" && value.length > 0;
+const hex = (value) => typeof value === "string" && /^[a-f0-9]{64}$/.test(value);
+const integer = (value) => Number.isSafeInteger(value) && value >= 0;
+const timestamp = (value) => text(value) && Number.isFinite(Date.parse(value));
+const uuid = (value) => typeof value === "string" && /^[a-f0-9]{8}(-[a-f0-9]{4}){3}-[a-f0-9]{12}$/i.test(value);
+const relative = (value) => text(value) && !value.includes("\\") && !value.includes(":") && !value.startsWith("/") && value.split("/").every(part => part && part !== "." && part !== "..");
+function sameRoot(value, expected) {
+    if (!text(value))
+        return false;
+    const normalize = (name) => {
+        const result = name.replaceAll("\\", "/").replace(/\/$/, "");
+        return /^[a-z]:\//i.test(result) ? result.toLowerCase() : result;
+    };
+    return normalize(value) === normalize(expected);
+}
+/** Python's sorted, ASCII JSON convention used for source snapshot digests. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(",")}]`;
+    if (value !== null && typeof value === "object")
+        return `{${Object.entries(value).sort(([a], [b]) => a < b ? -1 : a > b ? 1 : 0)
+            .map(([key, item]) => `${canonical(key)}:${canonical(item)}`).join(",")}}`;
+    return JSON.stringify(value).replace(/[\u007f-\uffff]/g, char => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function collection(value, input, facts, subject) {
+    keys(value, ["path", "sha256", "collectionId", "policy", "startedAtUtc", "finishedAtUtc", "sourceBinding", "freshness", "command", "receipt", "limitations"]);
+    const bound = value;
+    requireValue(input && text(bound.path) && hex(bound.sha256) && uuid(bound.collectionId) && bound.policy === "python/coverage-collection-v1" &&
+        bound.sourceBinding === "matched-pre-post-snapshots" && bound.freshness === "source-matched" && text(bound.limitations), "invalid collection binding");
+    keys(bound.receipt, ["schemaVersion", "policy", "collectionId", "startedAtUtc", "finishedAtUtc", "root", "status", "configuration", "sourceSelection",
+        "beforeSourceSha256", "afterSourceSha256", "sourceFactsPolicy", "sourceFactsProducer", "reportSha256", "command", "runtime", "testExitCode", "diagnostics"]);
+    const receipt = bound.receipt;
+    requireValue(receipt.schemaVersion === 1 && receipt.status === "complete" && receipt.testExitCode === 0 &&
+        sameRoot(receipt.root, subject.root) && receipt.reportSha256 === input.sha256 && input.branchDataPresent === true &&
+        isDeepStrictEqual(receipt.diagnostics, []), "failed or mismatched collection receipt");
+    for (const key of ["policy", "collectionId", "startedAtUtc", "finishedAtUtc", "command"])
+        requireValue(isDeepStrictEqual(bound[key], receipt[key]), "collection summary disagrees with receipt");
+    requireValue(timestamp(receipt.startedAtUtc) && timestamp(receipt.finishedAtUtc) &&
+        /(?:Z|[+-]\d\d:\d\d)$/.test(receipt.startedAtUtc) && /(?:Z|[+-]\d\d:\d\d)$/.test(receipt.finishedAtUtc) &&
+        Date.parse(receipt.finishedAtUtc) >= Date.parse(receipt.startedAtUtc), "invalid collection times");
+    requireValue(Array.isArray(receipt.command) && receipt.command.length > 0 && receipt.command.every(text), "missing collection command");
+    requireValue(isDeepStrictEqual(receipt.configuration, { branch: true, configFile: false, processScope: "single-process", freshBytecodeCache: true }), "collection configuration mismatch");
+    keys(receipt.runtime, ["coverageVersion", "pythonVersion", "testExitCode"]);
+    const runtime = receipt.runtime;
+    requireValue(runtime.coverageVersion === input.version && text(runtime.pythonVersion) && /^3\.12\./.test(runtime.pythonVersion) && runtime.testExitCode === 0, "collection runtime mismatch");
+    const selected = facts.selection;
+    const snapshot = { policy: selected.policy, configurationFingerprint: selected.configurationFingerprint, options: selected.options,
+        files: selected.files.filter(row => row.disposition === "analyzed"), excludedFunctions: selected.excludedFunctions };
+    const digest = hash(canonical(snapshot));
+    requireValue(receipt.beforeSourceSha256 === digest && receipt.afterSourceSha256 === digest && isDeepStrictEqual(receipt.sourceSelection, snapshot) &&
+        receipt.sourceFactsPolicy === facts.measurementPolicy && isDeepStrictEqual(receipt.sourceFactsProducer, facts.producer), "collection source snapshot mismatch");
+}
+function inputs(report, facts, subject) {
+    const input = report.coverageInput;
+    if (input !== null) {
+        keys(input, ["path", "sha256", "producer", "version", "format", "reportedAt", "branchDataPresent", "sourceBinding", "freshness"]);
+        requireValue(text(input.path) && hex(input.sha256) && input.producer === "coverage.py" && text(input.version) &&
+            [2, 3].includes(input.format) && typeof input.reportedAt === "string" && typeof input.branchDataPresent === "boolean", "invalid coverage input");
+        // Failed reviews may retain verified receipt diagnostics, but never promote input status.
+        const bound = report.status === "complete" && report.collectionProvenance !== null;
+        requireValue(input.sourceBinding === (bound ? "matched-pre-post-snapshots" : "unverified") &&
+            input.freshness === (bound ? "source-matched" : "unverified"), "unjustified coverage freshness");
+    }
+    if (report.collectionProvenance !== null)
+        collection(report.collectionProvenance, input, facts, subject);
+}
+function lines(value, row) {
+    requireValue(Array.isArray(value) && value.every((line, index) => integer(line) && line > row.line && line <= row.endLine &&
+        (index === 0 || line > value[index - 1])), "invalid body line attribution");
+}
+function observations(row, input, bound) {
+    const coverage = row.coverage;
+    if (coverage.status === "unavailable") {
+        keys(coverage, ["status", "reason", ...(coverage.excludedLines === undefined ? [] : ["excludedLines"])]);
+        requireValue(row.crapEstimate === null && (input === null ? coverage.reason === "coverage-not-supplied" :
+            ["lambda-line-attribution", "body-shares-definition-line", "body-shares-docstring-line", "nested-definition", "no-reportable-body-lines", "file-not-in-report"].includes(coverage.reason)), "invalid unavailable reason");
+        if (coverage.excludedLines !== undefined) {
+            lines(coverage.excludedLines, row);
+            requireValue(coverage.reason === "no-reportable-body-lines", "unexpected excluded lines");
+        }
+        return;
+    }
+    keys(coverage, ["status", "basis", "coveredLines", "executableLines", "executedLines", "missingLines", "excludedLines", "fraction"]);
+    requireValue(input !== null && coverage.status === (bound ? "reported-source-matched" : "reported-unverified") && coverage.basis === "executable-line", "unjustified coverage status");
+    lines(coverage.executedLines, row);
+    lines(coverage.missingLines, row);
+    lines(coverage.excludedLines, row);
+    const all = [...coverage.executedLines, ...coverage.missingLines, ...coverage.excludedLines];
+    const covered = coverage.executedLines.length, total = covered + coverage.missingLines.length;
+    requireValue(new Set(all).size === all.length && total > 0 && coverage.coveredLines === covered && coverage.executableLines === total &&
+        coverage.fraction === covered / total, "invalid coverage arithmetic");
+    keys(row.crapEstimate, ["value", "disposition", "basis", "formula"]);
+    const estimate = row.crapEstimate;
+    const expected = row.complexity ** 2 * ((total - covered) / total) ** 3 + row.complexity;
+    requireValue(Number.isFinite(estimate.value) && Math.abs(estimate.value - expected) <= 1e-12 * Math.max(1, expected) &&
+        estimate.disposition === (bound ? "review-only" : "conditional-review-only") && estimate.basis === "line-coverage-proxy" && estimate.formula === formula, "invalid CRAP estimate");
+}
+/** Offline integrity checks; this does not rerun tests or authenticate unsigned receipts. */
+export function validateCoverage(value, facts, subject, ids) {
+    keys(value, ["schemaVersion", "artifactKind", "producer", "generatedAtUtc", "runId", "auditId", "policy", "configuration", "configurationFingerprint", "status",
+        "subject", "sourceFactsProducer", "selection", "coverageInput", "collectionProvenance", "diagnostics", "scope", "functions", "summary"]);
+    const report = value;
+    requireValue(report.schemaVersion === 2 && report.artifactKind === "experimental-python-coverage-review" && report.policy === policy &&
+        isDeepStrictEqual(report.producer, { name: "codemetrics-ai/python-coverage-review", version: "0.3.0-experimental" }), "unsupported coverage producer or policy");
+    requireValue(report.runId === ids.runId && report.auditId === ids.auditId, "stale coverage identities");
+    const target = subject.entryPoint.replaceAll("\\", "/").endsWith("/pyproject.toml") ? subject.root : subject.entryPoint;
+    requireValue(isDeepStrictEqual(report.subject, { root: subject.root, entryPoint: target }) && isDeepStrictEqual(report.selection, facts.selection) &&
+        isDeepStrictEqual(report.sourceFactsProducer, facts.producer), "source selection/provenance mismatch");
+    const configuration = { policy, selectionFingerprint: facts.selection.configurationFingerprint, complexityPolicy: facts.measurementPolicy,
+        parserVersion: facts.producer.parserVersion, maxReportBytes: 33554432, maxOwners: 100000 };
+    requireValue(isDeepStrictEqual(report.configuration, configuration) && report.configurationFingerprint === hash(canonical(configuration)), "configuration mismatch");
+    requireValue(timestamp(report.generatedAtUtc) && text(report.scope) && Array.isArray(report.diagnostics) && Array.isArray(report.functions), "missing report metadata");
+    for (const item of report.diagnostics) {
+        keys(item, ["code", "message", ...(item.file === undefined ? [] : ["file"])]);
+        requireValue(text(item.code) && typeof item.message === "string" && (item.file === undefined || text(item.file)), "invalid diagnostic");
+    }
+    inputs(report, facts, subject);
+    if (report.status === "incomplete") {
+        requireValue(report.functions.length === 0 && report.summary === null && report.diagnostics.length > 0, "incomplete review must withhold estimates");
+        return;
+    }
+    requireValue(report.status === "complete" && facts.status === "complete" && report.diagnostics.length === 0, "status mismatch");
+    const owners = new Map(facts.functions.map(row => [row.id, row])), used = new Set(), usedLines = new Set();
+    const files = new Map(facts.selection.files.map(row => [row.file, row]));
+    const reasons = {};
+    let estimates = 0;
+    for (const row of report.functions) {
+        keys(row, ["id", "file", "member", "line", "population", "endLine", "complexity", "coverage", "crapEstimate", "sourceSha256"]);
+        const owner = owners.get(row.id);
+        requireValue(owner && !used.has(row.id) && row.file === owner.file && row.member === owner.member && row.line === owner.line &&
+            row.population === owner.population && row.complexity === owner.complexity?.value && row.sourceSha256 === files.get(row.file)?.contentSha256 &&
+            integer(row.endLine) && row.endLine >= row.line, "unknown, repeated, or mismatched function");
+        used.add(row.id);
+        object(row.coverage);
+        observations(row, report.coverageInput, report.collectionProvenance !== null);
+        if (row.crapEstimate === null)
+            reasons[row.coverage.reason] = (reasons[row.coverage.reason] ?? 0) + 1;
+        else {
+            estimates++;
+            for (const line of [...row.coverage.executedLines, ...row.coverage.missingLines]) {
+                const key = `${row.file}:${line}`;
+                requireValue(!usedLines.has(key), "coverage line credited to multiple owners");
+                usedLines.add(key);
+            }
+        }
+    }
+    requireValue(used.size === owners.size, "incomplete function population");
+    keys(report.summary, ["selectedFunctions", "conditionalEstimates", "sourceBoundEstimates", "unavailableFunctions", "unavailableReasons", "matchedFiles", "unmatchedReportFiles"]);
+    const summary = report.summary;
+    requireValue(summary.selectedFunctions === owners.size && summary.conditionalEstimates === (report.collectionProvenance ? 0 : estimates) &&
+        summary.sourceBoundEstimates === (report.collectionProvenance ? estimates : 0) && summary.unavailableFunctions === owners.size - estimates &&
+        isDeepStrictEqual(summary.unavailableReasons, reasons), "summary accounting mismatch");
+    requireValue(integer(summary.matchedFiles) && summary.matchedFiles <= facts.selection.files.filter(file => file.disposition === "analyzed").length &&
+        Array.isArray(summary.unmatchedReportFiles) && summary.unmatchedReportFiles.every(file => relative(file) && files.get(file)?.disposition !== "analyzed") &&
+        new Set(summary.unmatchedReportFiles).size === summary.unmatchedReportFiles.length, "invalid file accounting");
+    if (report.coverageInput === null)
+        requireValue(summary.matchedFiles === 0 && summary.unmatchedReportFiles.length === 0, "missing coverage cannot contain file observations");
+}

package/dist/python-decomposition.d.ts

@@ -0,0 +1,56 @@
+import type { SourceFacts } from "#source-facts/contract.mjs";
+import { type Evidence } from "./evidence.js";
+export declare const decompositionPolicy = "python/owned-statements-block-nesting-v1";
+interface Measurement {
+    ownedStatements: number;
+    maxBlockNesting: number;
+    statementKinds: Record<string, number>;
+    excludedSyntax: Record<string, number>;
+}
+interface Owner {
+    id: string;
+    file: string;
+    member: string;
+    line: number;
+    endLine: number;
+    population: string;
+    sourceSha256: string;
+    functionKind: string;
+    complexity: number;
+    disposition: string;
+    status: string;
+    measurement: Measurement | null;
+    reason?: string;
+}
+export interface PythonDecomposition {
+    schemaVersion: number;
+    artifactKind: string;
+    producer: {
+        name: string;
+        version: string;
+    };
+    generatedAtUtc: string;
+    runId: string;
+    auditId: string;
+    status: string;
+    policy: string;
+    configuration: Record<string, string | number>;
+    configurationFingerprint: string;
+    subject: {
+        root: string;
+        entryPoint: string;
+    };
+    sourceFactsProducer: SourceFacts["producer"];
+    sourceFactsPolicy: string;
+    selection: SourceFacts["selection"];
+    scope: string;
+    diagnostics: SourceFacts["diagnostics"];
+    functions: Owner[];
+    summary: unknown;
+}
+/** Validate provenance and internal accounting; AST measurements remain the producer's observations. */
+export declare function validateDecomposition(value: unknown, facts: SourceFacts, subject: Evidence["subject"], ids: {
+    runId: string;
+    auditId: string;
+}): asserts value is PythonDecomposition;
+export {};