codemetrics-ai 0.4.0 → 0.6.0-preview.1

package/dist/python-evidence.js

@@ -0,0 +1,255 @@
+import { validateAsyncHelpers, validateAsyncScoring, scorePythonAsync } from "./python-async-scoring.js";
+import { validateAsyncAdapters } from "./python-async-adapters.js";
+import { validateAsyncContext } from "./python-async-context.js";
+import { validateAsyncUsage, asyncUsagePolicy } from "./python-async-usage.js";
+import { isDeepStrictEqual } from "node:util";
+import { complexityPopulation } from "#source-facts/population.mjs";
+import { validateSourceFacts } from "#source-facts/contract.mjs";
+import { dimensionKeys } from "./scorecard-contract.js";
+import { hash } from "./evidence.js";
+import { duplicationFindings, validateDuplication } from "./python-duplication.js";
+import { validateCoverage } from "./python-coverage.js";
+import { validateDecomposition } from "./python-decomposition.js";
+import { validateErrorHandling, errorHandlingPolicy } from "./python-error-handling.js";
+import { validateErrorContext } from "./python-error-context.js";
+import { validateOperations } from "./python-error-operations.js";
+import { validateTransfers } from "./python-error-transfers.js";
+import { scoreMethodComplexity, pythonCalibration } from "./python-complexity.js";
+export const pythonVersion = "0.15.0";
+export const pythonRuleset = "python-2026-10-28-async-scoring-v1";
+const currentProfile = { version: pythonVersion, ruleset: pythonRuleset, decomposition: true, scored: true, errorHandling: true, context: true, transfers: true, operations: true, asyncUsage: true, asyncContext: true, asyncAdapters: true, asyncScoring: true };
+const adapterProfile = { ...currentProfile, version: "0.14.0", ruleset: "python-2026-10-24-async-adapters-review-v1", asyncScoring: false };
+const asyncContextProfile = { ...adapterProfile, version: "0.13.0", ruleset: "python-2026-10-18-async-context-review-v1", asyncAdapters: false, asyncScoring: false };
+const asyncProfile = { ...asyncContextProfile, version: "0.12.0", ruleset: "python-2026-10-16-async-usage-review-v1", asyncContext: false, asyncAdapters: false, asyncScoring: false };
+const operationProfile = { version: "0.11.0", ruleset: "python-2026-10-15-exception-operations-review-v1", decomposition: true, scored: true, errorHandling: true, context: true, transfers: true, operations: true, asyncUsage: false, asyncContext: false, asyncAdapters: false, asyncScoring: false };
+const transferProfile = { version: "0.10.0", ruleset: "python-2026-10-15-exception-transfers-review-v1", decomposition: true, scored: true, errorHandling: true, context: true, transfers: true, operations: false, asyncUsage: false, asyncContext: false, asyncAdapters: false, asyncScoring: false };
+const contextProfile = { version: "0.9.0", ruleset: "python-2026-10-15-exception-context-review-v1", decomposition: true, scored: true, errorHandling: true, context: true, transfers: false, operations: false, asyncUsage: false, asyncContext: false, asyncAdapters: false, asyncScoring: false };
+const handlerProfile = { version: "0.8.0", ruleset: "python-2026-10-15-error-handling-review-v1", decomposition: true, scored: true, errorHandling: true, context: false, transfers: false, operations: false, asyncUsage: false, asyncContext: false, asyncAdapters: false, asyncScoring: false };
+const complexityProfile = { version: "0.7.0", ruleset: "python-2026-10-13-method-complexity-v1", decomposition: true, scored: true, errorHandling: false, context: false, transfers: false, operations: false, asyncUsage: false, asyncContext: false, asyncAdapters: false, asyncScoring: false };
+const decompositionProfile = { version: "0.6.0-experimental", ruleset: "python-2026-10-13-decomposition-preview", decomposition: true, scored: false, errorHandling: false, context: false, transfers: false, operations: false, asyncUsage: false, asyncContext: false, asyncAdapters: false, asyncScoring: false };
+const coverageProfile = { version: "0.5.0-experimental", ruleset: "python-2026-10-12-coverage-preview", decomposition: false, scored: false, errorHandling: false, context: false, transfers: false, operations: false, asyncUsage: false, asyncContext: false, asyncAdapters: false, asyncScoring: false };
+const previewPolicy = "experimental/shared-complexity-worst-40-remainder-60/v1";
+function complexityDetails(facts) {
+    const population = facts ? complexityPopulation(facts) : null;
+    return { status: population ? "experimental-preview" : "unavailable", scoringPolicy: previewPolicy,
+        comparableAcrossLanguages: false, population };
+}
+function reviewFindings(facts) {
+    if (facts?.status !== "complete")
+        return [];
+    return facts.functions.filter(item => item.complexity && item.complexity.value >= 10).map(item => ({
+        category: "methodComplexityReview", ruleId: "python/method-complexity/review-v1",
+        fingerprint: hash(`${facts.measurementPolicy}:${item.id}`), severity: "info", confidence: "high",
+        file: item.file, line: item.line, member: item.member,
+        message: `Measured CC ${item.complexity.value}; inspect control flow and required behavior before recommending decomposition.`,
+        observations: { functionId: item.id, complexity: item.complexity, population: item.population,
+            measurementPolicy: facts.measurementPolicy, reviewThreshold: 10, scoringDisposition: "unscored" }
+    }));
+}
+function measurements(facts) {
+    const files = facts?.selection?.files ?? [];
+    return { filters: { totalUnits: files.length, analyzedUnits: files.filter(item => item.disposition === "analyzed").length,
+            skipped: files.filter(item => item.disposition === "excluded").map(item => ({ name: item.file, reason: item.reason })) },
+        population: { types: 0, members: facts?.functions.length ?? 0 } };
+}
+export function pythonEvidence(facts, subject, ids, error, duplication = null, coverage = null, decomposition = null, errorHandling = null, context = null, transfers = null, operations = null, asyncReview = null, asyncContext = null, asyncAdapters = null, asyncHelpers = null, asyncScoring = null) {
+    return buildEvidence(currentProfile, facts, subject, ids, error, duplication, coverage, decomposition, errorHandling, context, transfers, operations, asyncReview, asyncContext, asyncAdapters, asyncHelpers, asyncScoring);
+}
+function buildEvidence(profile, facts, subject, ids, error, duplication, coverage, decomposition, errorHandling, context, transfers, operations, asyncReview, asyncContext, asyncAdapters, asyncHelpers, asyncScoring) {
+    if (facts)
+        validateSourceFacts(facts);
+    if (facts && duplication)
+        validateDuplication(duplication, facts, subject, ids);
+    if (facts && coverage)
+        validateCoverage(coverage, facts, subject, ids);
+    if (facts && decomposition)
+        validateDecomposition(decomposition, facts, subject, ids);
+    if (facts && errorHandling)
+        validateErrorHandling(errorHandling, facts, subject, ids);
+    if (context && errorHandling)
+        validateErrorContext(context, errorHandling);
+    if (transfers && context)
+        validateTransfers(transfers, context);
+    if (operations && transfers)
+        validateOperations(operations, transfers);
+    if (asyncReview && facts && decomposition)
+        validateAsyncUsage(asyncReview, facts, subject, ids, decomposition);
+    if (asyncContext && asyncReview)
+        validateAsyncContext(asyncContext, asyncReview);
+    if (asyncAdapters && asyncReview && asyncContext)
+        validateAsyncAdapters(asyncAdapters, asyncReview, asyncContext);
+    if (asyncHelpers && asyncReview && asyncContext && asyncAdapters)
+        validateAsyncHelpers(asyncHelpers, asyncReview, asyncContext, asyncAdapters);
+    if (asyncScoring && asyncHelpers && asyncReview)
+        validateAsyncScoring(asyncScoring, asyncHelpers, asyncReview);
+    const complete = facts?.status === "complete" && duplication?.status === "complete" && coverage?.status === "complete" && (!profile.decomposition || decomposition?.status === "complete") && (!profile.errorHandling || errorHandling?.status === "complete") && (!profile.context || context?.status === "complete") && (!profile.transfers || transfers?.status === "complete") && (!profile.operations || operations?.status === "complete") && (!profile.asyncUsage || asyncReview?.status === "complete") && (!profile.asyncContext || asyncContext?.status === "complete") && (!profile.asyncAdapters || asyncAdapters?.status === "complete") && (!profile.asyncScoring || asyncHelpers?.status === "complete" && asyncScoring?.status === "complete") && !error;
+    const dimensions = Object.fromEntries(dimensionKeys.map(key => [key, {
+            status: "skipped", basis: profile.scored ? "Not measured by this Python analyzer." : "Not measured by the experimental Python analyzer.", findings: [],
+            scope: { id: `python/${key}/unsupported`, coverage: "unsupported", includes: [], excludes: [key] }
+        }]));
+    dimensions.codeQuality = {
+        status: complete ? "skipped" : "failed",
+        basis: complete ? profile.decomposition
+            ? "Complexity, owned statements, block nesting, duplication and optional coverage/CRAP review evidence; all unscored. Missing coverage and lambda decomposition are unavailable."
+            : "Complexity, duplication and optional coverage/CRAP review evidence; all unscored. Complexity preview is experimental. Missing coverage is unavailable."
+            : "Python analysis incomplete; partial measurements are diagnostic only.",
+        scope: { id: "python/owned-function-complexity-v2", coverage: "partial", includes: ["selected-function-complexity", "exact-function-body-duplication", "optional-line-coverage-crap-review", ...(profile.decomposition ? ["owned-function-statements", "function-block-nesting"] : [])],
+            excludes: ["calibrated-dimension-score", ...(profile.decomposition ? [] : ["decomposition"]), "runtime-performance", "semantic-validation"] },
+        findings: complete ? [...reviewFindings(facts), ...duplicationFindings(duplication)] : [],
+        duplication, coverageReview: coverage, ...(profile.decomposition ? { decomposition } : {}),
+        sourceFacts: facts, experimentalPreview: complete ? complexityDetails(facts) : complexityDetails(null),
+        populationNotes: "Units are observed Python files; members are selected implementation bodies. Types are not measured (the required types field is a placeholder zero). Pruned directories do not enumerate unseen files."
+    };
+    if (profile.scored)
+        dimensions.codeQuality = scoreMethodComplexity(dimensions.codeQuality, facts, complete);
+    if (profile.errorHandling)
+        dimensions.errorHandling = {
+            status: complete ? "skipped" : "failed", basis: complete
+                ? "Exception-handler syntax and local documentation are review evidence only; no handling-quality score."
+                : "Python analysis incomplete; handler observations are diagnostic only.",
+            scope: { id: errorHandlingPolicy, coverage: "partial", includes: ["selected-exception-suites", "module-and-class-body-handlers", "local-no-op-documentation", ...(profile.context ? ["bounded-lexical-context", "conservative-handler-patterns"] : []), ...(profile.transfers ? ["owned-raise-cause-syntax", "conservative-raise-patterns"] : []), ...(profile.operations ? ["owned-call-return-syntax", "unresolved-suite-inventory"] : [])],
+                excludes: ["calibrated-dimension-score", "resolved-exception-types", "business-correctness", "context-manager-suppression", "path-completeness"] },
+            findings: [], review: errorHandling, ...(profile.context ? { contextReview: context } : {}), ...(profile.transfers ? { transferReview: transfers } : {}), ...(profile.operations ? { operationReview: operations } : {})
+        };
+    if (profile.asyncUsage)
+        dimensions.performanceAsync = {
+            status: complete ? "skipped" : "failed", basis: complete
+                ? "Async-owned calls, import-matched blocking candidates, and thread-helper syntax are unscored review evidence. Unresolved calls are not clean-async evidence."
+                : "Python analysis incomplete; async observations are diagnostic only.",
+            scope: { id: asyncUsagePolicy, coverage: "partial", includes: ["selected-async-bodies", "import-spelling-matches", "thread-helper-syntax", "separate-deferred-generator-observations", ...(profile.asyncContext ? ["unresolved-call-shape-inventory", "bounded-local-source-links", "stored-wrapper-syntax-links"] : []), ...(profile.asyncAdapters ? ["partial-construction-context", "bounded-partial-references", "sync-to-async-decorator-links"] : [])],
+                excludes: ["calibrated-dimension-score", "synchronous-owners", "runtime-performance", "resolved-receiver-types", "offloading-success", "complete-blocking-detection"] },
+            findings: [], review: asyncReview, ...(profile.asyncContext ? { contextReview: asyncContext } : {}), ...(profile.asyncAdapters ? { adapterReview: asyncAdapters } : {}), ...(profile.asyncScoring ? { helperReview: asyncHelpers, asyncScoring } : {})
+        };
+    if (profile.asyncScoring)
+        dimensions.performanceAsync = scorePythonAsync(dimensions.performanceAsync, asyncScoring, complete);
+    return { schemaVersion: 3, generatedAtUtc: new Date().toISOString(),
+        tool: { name: "CodeMetrics.AI.Python", version: profile.version, ecosystem: "python" }, subject,
+        ...measurements(facts), dimensions,
+        analysis: { ...ids, status: complete ? "complete" : "incomplete", ruleset: profile.ruleset, calibration: profile.scored ? pythonCalibration : "uncalibrated",
+            configurationFingerprint: hash(JSON.stringify([profile.ruleset, facts?.producer, facts?.measurementPolicy, facts?.selection?.configurationFingerprint, duplication?.configurationFingerprint, coverage?.configurationFingerprint, ...(profile.decomposition ? [decomposition?.configurationFingerprint] : []), ...(profile.errorHandling ? [errorHandling?.configurationFingerprint] : []), ...(profile.context ? [context?.configurationFingerprint] : []), ...(profile.transfers ? [transfers?.configurationFingerprint] : []), ...(profile.operations ? [operations?.configurationFingerprint] : []), ...(profile.asyncUsage ? [asyncReview?.configurationFingerprint] : []), ...(profile.asyncContext ? [asyncContext?.configurationFingerprint] : []), ...(profile.asyncAdapters ? [asyncAdapters?.configurationFingerprint] : []), ...(profile.asyncScoring ? [asyncHelpers?.configurationFingerprint, asyncScoring?.configurationFingerprint] : [])])),
+            diagnostics: [...(facts?.diagnostics ?? []).map(item => ({ kind: item.code, message: item.message, ...(item.file ? { project: item.file } : {}) })),
+                ...(duplication?.diagnostics ?? []).filter(item => !facts?.diagnostics.some(other => isDeepStrictEqual(item, other)))
+                    .map(item => ({ kind: item.code, message: item.message, ...(item.file ? { project: item.file } : {}) })),
+                ...(coverage?.diagnostics ?? []).filter(item => !facts?.diagnostics.some(other => isDeepStrictEqual(item, other)))
+                    .map(item => ({ kind: item.code, message: item.message, ...(item.file ? { project: item.file } : {}) })),
+                ...(decomposition?.diagnostics ?? []).filter(item => !facts?.diagnostics.some(other => isDeepStrictEqual(item, other)))
+                    .map(item => ({ kind: item.code, message: item.message, ...(item.file ? { project: item.file } : {}) })),
+                ...(errorHandling?.diagnostics ?? []).filter(item => !facts?.diagnostics.some(other => isDeepStrictEqual(item, other)))
+                    .map(item => ({ kind: item.code, message: item.message, ...(item.file ? { project: item.file } : {}) })),
+                ...(context?.diagnostics ?? []).filter(item => !facts?.diagnostics.some(other => isDeepStrictEqual(item, other)))
+                    .map(item => ({ kind: item.code, message: item.message, ...(item.file ? { project: item.file } : {}) })),
+                ...(transfers?.diagnostics ?? []).filter(item => !facts?.diagnostics.some(other => isDeepStrictEqual(item, other)))
+                    .map(item => ({ kind: item.code, message: item.message, ...(item.file ? { project: item.file } : {}) })),
+                ...(operations?.diagnostics ?? []).filter(item => !facts?.diagnostics.some(other => isDeepStrictEqual(item, other)))
+                    .map(item => ({ kind: item.code, message: item.message, ...(item.file ? { project: item.file } : {}) })),
+                ...(asyncReview?.diagnostics ?? []).filter(item => !facts?.diagnostics.some(other => isDeepStrictEqual(item, other)))
+                    .map(item => ({ kind: item.code, message: item.message, ...(item.file ? { project: item.file } : {}) })),
+                ...(asyncContext?.diagnostics ?? []).filter(item => !facts?.diagnostics.some(other => isDeepStrictEqual(item, other)))
+                    .map(item => ({ kind: item.code, message: item.message, ...(item.file ? { project: item.file } : {}) })),
+                ...(asyncAdapters?.diagnostics ?? []).map(item => ({ kind: item.code, message: item.message })),
+                ...(asyncHelpers?.diagnostics ?? []).map(item => ({ kind: item.code, message: item.message })),
+                ...(asyncScoring?.diagnostics ?? []).map(item => ({ kind: item.code, message: item.message })),
+                ...(error ? [{ kind: "pythonExecution", message: error }] : [])], suppressions: [] }
+    };
+}
+/** Validate supported scoring and historical review contracts within the shared v3 envelope. */
+export function validatePythonEvidence(evidence) {
+    if (evidence.tool.ecosystem !== "python")
+        return;
+    const profile = [currentProfile, adapterProfile, asyncContextProfile, asyncProfile, operationProfile, transferProfile, contextProfile, handlerProfile, complexityProfile, decompositionProfile, coverageProfile].find(item => item.ruleset === evidence.analysis.ruleset);
+    if (!profile) {
+        if ([pythonVersion, adapterProfile.version, asyncContextProfile.version, asyncProfile.version, operationProfile.version, transferProfile.version, contextProfile.version, handlerProfile.version, complexityProfile.version, decompositionProfile.version, coverageProfile.version].includes(evidence.tool.version) || evidence.dimensions.codeQuality.coverageReview !== undefined || evidence.dimensions.codeQuality.decomposition !== undefined ||
+            evidence.dimensions.performanceAsync.helperReview !== undefined || evidence.dimensions.performanceAsync.asyncScoring !== undefined || evidence.dimensions.performanceAsync.adapterReview !== undefined || evidence.dimensions.performanceAsync.contextReview !== undefined || evidence.dimensions.performanceAsync.review !== undefined || evidence.dimensions.errorHandling.operationReview !== undefined || evidence.dimensions.errorHandling.transferReview !== undefined || evidence.dimensions.errorHandling.contextReview !== undefined || evidence.dimensions.errorHandling.review !== undefined || evidence.dimensions.codeQuality.methodComplexity !== undefined || Object.values(evidence.dimensions).some(item => item.status === "scored"))
+            throw new Error("Python review evidence requires its recorded supported ruleset.");
+        return; // Historical producers without these extensions retain their original contract.
+    }
+    if (!profile.asyncScoring && (Object.hasOwn(evidence.dimensions.performanceAsync, "helperReview") || Object.hasOwn(evidence.dimensions.performanceAsync, "asyncScoring")))
+        throw new Error("Historical Python evidence cannot contain async scoring measurements.");
+    if (!profile.asyncAdapters && Object.hasOwn(evidence.dimensions.performanceAsync, "adapterReview"))
+        throw new Error("Historical Python evidence cannot contain callback adapter measurements.");
+    if (!profile.asyncContext && Object.hasOwn(evidence.dimensions.performanceAsync, "contextReview"))
+        throw new Error("Historical Python evidence cannot contain async context measurements.");
+    if (!profile.asyncUsage && Object.hasOwn(evidence.dimensions.performanceAsync, "review"))
+        throw new Error("Historical Python evidence cannot contain async measurements.");
+    if (!profile.operations && Object.hasOwn(evidence.dimensions.errorHandling, "operationReview"))
+        throw new Error("Historical Python evidence cannot contain call/return measurements.");
+    if (!profile.transfers && Object.hasOwn(evidence.dimensions.errorHandling, "transferReview"))
+        throw new Error("Historical Python evidence cannot contain raise/chaining measurements.");
+    if (!profile.context && Object.hasOwn(evidence.dimensions.errorHandling, "contextReview"))
+        throw new Error("Historical Python evidence cannot contain exception context measurements.");
+    if (!profile.errorHandling && Object.hasOwn(evidence.dimensions.errorHandling, "review"))
+        throw new Error("Historical Python evidence cannot contain handler measurements.");
+    if (!profile.decomposition && Object.hasOwn(evidence.dimensions.codeQuality, "decomposition"))
+        throw new Error("Historical Python coverage evidence cannot contain decomposition measurements.");
+    if (!evidence.analysis.runId || !evidence.analysis.auditId || evidence.analysis.calibration !== (profile.scored ? pythonCalibration : "uncalibrated") ||
+        evidence.tool.version !== profile.version || evidence.tool.name !== "CodeMetrics.AI.Python")
+        throw new Error("Python evidence requires invocation IDs and matching versioned provenance.");
+    if (Object.entries(evidence.dimensions).some(([key, item]) => item.status === "scored" && (!profile.scored || key !== "codeQuality" && !(profile.asyncScoring && key === "performanceAsync"))))
+        throw new Error("Only supported Python Method Complexity and Async/Blocking Usage can be scored.");
+    const facts = evidence.dimensions.codeQuality.sourceFacts;
+    const duplication = evidence.dimensions.codeQuality.duplication;
+    const coverage = evidence.dimensions.codeQuality.coverageReview;
+    const decomposition = profile.decomposition ? evidence.dimensions.codeQuality.decomposition : null;
+    const errorHandling = profile.errorHandling ? evidence.dimensions.errorHandling.review : null;
+    const context = profile.context ? evidence.dimensions.errorHandling.contextReview : null;
+    const transfers = profile.transfers ? evidence.dimensions.errorHandling.transferReview : null;
+    const operations = profile.operations ? evidence.dimensions.errorHandling.operationReview : null;
+    const asyncReview = profile.asyncUsage ? evidence.dimensions.performanceAsync.review : null;
+    if (facts === null && (duplication !== null || coverage !== null || decomposition !== null || errorHandling !== null || context !== null || transfers !== null || operations !== null || asyncReview !== null))
+        throw new Error("Python measurements require source facts.");
+    const asyncAdapters = profile.asyncAdapters ? evidence.dimensions.performanceAsync.adapterReview : null;
+    const asyncContext = profile.asyncContext ? evidence.dimensions.performanceAsync.contextReview : null;
+    const asyncHelpers = profile.asyncScoring ? evidence.dimensions.performanceAsync.helperReview : null;
+    const asyncScoring = profile.asyncScoring ? evidence.dimensions.performanceAsync.asyncScoring : null;
+    if (facts === null && (asyncHelpers !== null || asyncScoring !== null))
+        throw new Error("Python async scoring requires source facts.");
+    if (facts === null && (asyncContext !== null || asyncAdapters !== null))
+        throw new Error("Python async context and adapters require source facts.");
+    if (facts !== null) {
+        validateSourceFacts(facts);
+        if (facts.language !== "python" || facts.schemaVersion !== 2 || facts.producer.version !== "0.4.0-experimental" ||
+            facts.producer.name !== "codemetrics-ai/python-source-facts" || facts.producer.parser !== "python-ast" ||
+            facts.measurementPolicy !== "python/owned-function-complexity-v2" || facts.selection?.policy !== "python/source-selection-v1" ||
+            (facts.status === "complete" && !/^3\.12\./.test(facts.producer.parserVersion)))
+            throw new Error("Unexpected Python source-facts producer or version.");
+        validateDuplication(duplication, facts, evidence.subject, { runId: evidence.analysis.runId, auditId: evidence.analysis.auditId });
+        validateCoverage(coverage, facts, evidence.subject, { runId: evidence.analysis.runId, auditId: evidence.analysis.auditId });
+        if (profile.decomposition)
+            validateDecomposition(decomposition, facts, evidence.subject, { runId: evidence.analysis.runId, auditId: evidence.analysis.auditId });
+        if (profile.errorHandling)
+            validateErrorHandling(errorHandling, facts, evidence.subject, { runId: evidence.analysis.runId, auditId: evidence.analysis.auditId });
+        if (profile.context)
+            validateErrorContext(context, errorHandling);
+        if (profile.transfers)
+            validateTransfers(transfers, context);
+        if (profile.operations)
+            validateOperations(operations, transfers);
+        if (profile.asyncUsage)
+            validateAsyncUsage(asyncReview, facts, evidence.subject, { runId: evidence.analysis.runId, auditId: evidence.analysis.auditId }, decomposition);
+        if (profile.asyncContext)
+            validateAsyncContext(asyncContext, asyncReview);
+        if (profile.asyncAdapters)
+            validateAsyncAdapters(asyncAdapters, asyncReview, asyncContext);
+        if (profile.asyncScoring) {
+            validateAsyncHelpers(asyncHelpers, asyncReview, asyncContext, asyncAdapters);
+            validateAsyncScoring(asyncScoring, asyncHelpers, asyncReview);
+        }
+    }
+    if (evidence.analysis.status === "complete" && (facts?.status !== "complete" || duplication?.status !== "complete" || coverage?.status !== "complete" || (profile.decomposition && decomposition?.status !== "complete") || (profile.errorHandling && errorHandling?.status !== "complete") || (profile.context && context?.status !== "complete") || (profile.transfers && transfers?.status !== "complete") || (profile.operations && operations?.status !== "complete") || (profile.asyncUsage && asyncReview?.status !== "complete") || (profile.asyncContext && asyncContext?.status !== "complete") || (profile.asyncAdapters && asyncAdapters?.status !== "complete") || (profile.asyncScoring && (asyncHelpers?.status !== "complete" || asyncScoring?.status !== "complete"))))
+        throw new Error("Complete Python evidence requires complete measurements.");
+    if (evidence.analysis.status === "incomplete" && facts?.status === "complete" && duplication?.status === "complete" && coverage?.status === "complete" && (!profile.decomposition || decomposition?.status === "complete") && (!profile.errorHandling || errorHandling?.status === "complete") && (!profile.context || context?.status === "complete") && (!profile.transfers || transfers?.status === "complete") && (!profile.operations || operations?.status === "complete") && (!profile.asyncUsage || asyncReview?.status === "complete") && (!profile.asyncContext || asyncContext?.status === "complete") && (!profile.asyncAdapters || asyncAdapters?.status === "complete") && (!profile.asyncScoring || asyncHelpers?.status === "complete" && asyncScoring?.status === "complete"))
+        throw new Error("Incomplete Python evidence must identify an incomplete measurement.");
+    if (evidence.analysis.status === "incomplete" && !evidence.analysis.diagnostics.length)
+        throw new Error("Incomplete Python evidence requires diagnostics.");
+    const expected = buildEvidence(profile, facts, evidence.subject, { runId: evidence.analysis.runId, auditId: evidence.analysis.auditId }, evidence.analysis.status === "incomplete" ? "Validation placeholder" : undefined, duplication, coverage, decomposition, errorHandling, context, transfers, operations, asyncReview, asyncContext, asyncAdapters, asyncHelpers, asyncScoring);
+    for (const key of ["filters", "population", "dimensions"])
+        if (!isDeepStrictEqual(evidence[key], expected[key]))
+            throw new Error(`Python ${key} do not match measured facts and experimental policy.`);
+    if (evidence.analysis.configurationFingerprint !== expected.analysis.configurationFingerprint)
+        throw new Error("Python configuration fingerprint does not match source facts.");
+}
+/** Historical previews and unavailable populations cannot participate in score comparisons. */
+export function supportsPythonComparison(evidence) {
+    return [currentProfile, adapterProfile, asyncContextProfile, asyncProfile, operationProfile, transferProfile, contextProfile, handlerProfile, complexityProfile].some(profile => evidence.tool.version === profile.version && evidence.analysis.ruleset === profile.ruleset) &&
+        evidence.analysis.calibration === pythonCalibration && evidence.dimensions.codeQuality.status === "scored";
+}

package/dist/score-arithmetic.d.ts

@@ -1,12 +1 @@
-export interface Fraction {
-    numerator: bigint;
-    denominator: bigint;
-}
-export declare function fraction(numerator: bigint, denominator?: bigint): Fraction;
-export declare function decimal(value: number): Fraction;
-export declare const add: (a: Fraction, b: Fraction) => Fraction;
-export declare const multiply: (a: Fraction, b: Fraction) => Fraction;
-export declare const subtract: (a: Fraction, b: Fraction) => Fraction;
-export declare const numeric: (a: Fraction) => number;
-export declare function roundScore(a: Fraction): number;
-export declare function interpolate(value: number, anchors: readonly (readonly [number, number])[]): Fraction;
+export * from "#source-facts/arithmetic.mjs";

package/dist/score-arithmetic.js

@@ -1,40 +1 @@
-export function fraction(numerator, denominator = 1n) {
-    if (denominator <= 0n)
-        throw new Error("Positive denominator required.");
-    let a = numerator < 0n ? -numerator : numerator, b = denominator;
-    while (b) {
-        const remainder = a % b;
-        a = b;
-        b = remainder;
-    }
-    return { numerator: numerator / a, denominator: denominator / a };
-}
-export function decimal(value) {
-    if (!Number.isFinite(value))
-        throw new Error("Finite score measurement required.");
-    const [mantissa, exponent = "0"] = String(value).toLowerCase().split("e");
-    const places = (mantissa.split(".")[1] ?? "").length - Number(exponent);
-    const numerator = BigInt(mantissa.replace(".", ""));
-    return places >= 0 ? fraction(numerator, 10n ** BigInt(places)) : fraction(numerator * 10n ** BigInt(-places));
-}
-export const add = (a, b) => fraction(a.numerator * b.denominator + b.numerator * a.denominator, a.denominator * b.denominator);
-export const multiply = (a, b) => fraction(a.numerator * b.numerator, a.denominator * b.denominator);
-export const subtract = (a, b) => add(a, { ...b, numerator: -b.numerator });
-export const numeric = (a) => Number(a.numerator) / Number(a.denominator);
-export function roundScore(a) {
-    if (a.numerator < 0n)
-        throw new Error("Score must be nonnegative.");
-    return Number((a.numerator * 20n + a.denominator) / (2n * a.denominator)) / 10;
-}
-export function interpolate(value, anchors) {
-    if (!Number.isFinite(value))
-        throw new Error("Finite score measurement required.");
-    if (value <= anchors[0][0])
-        return decimal(anchors[0][1]);
-    for (let index = 1; index < anchors.length; index++) {
-        const [x, y] = anchors[index], [previousX, previousY] = anchors[index - 1];
-        if (value <= x)
-            return add(decimal(previousY), multiply(subtract(decimal(value), decimal(previousX)), fraction(BigInt(y - previousY), BigInt(x - previousX))));
-    }
-    return decimal(anchors[anchors.length - 1][1]);
-}
+export * from "#source-facts/arithmetic.mjs";

package/dist/shared-source-facts/arithmetic.d.mts

@@ -0,0 +1,9 @@
+export interface Fraction { numerator: bigint; denominator: bigint; }
+export function fraction(numerator: bigint, denominator?: bigint): Fraction;
+export function decimal(value: number): Fraction;
+export function add(a: Fraction, b: Fraction): Fraction;
+export function multiply(a: Fraction, b: Fraction): Fraction;
+export function subtract(a: Fraction, b: Fraction): Fraction;
+export function numeric(a: Fraction): number;
+export function roundScore(a: Fraction): number;
+export function interpolate(value: number, anchors: readonly (readonly [number, number])[]): Fraction;

package/dist/shared-source-facts/arithmetic.mjs

@@ -0,0 +1,32 @@
+// Decimal inputs retain their measurement precision; subsequent arithmetic is exact.
+export function fraction(numerator, denominator = 1n) {
+  if (denominator <= 0n) throw new Error('Positive denominator required.');
+  let a = numerator < 0n ? -numerator : numerator, b = denominator;
+  while (b) { const remainder = a % b; a = b; b = remainder; }
+  return { numerator: numerator / a, denominator: denominator / a };
+}
+export function decimal(value) {
+  if (!Number.isFinite(value)) throw new Error('Finite score measurement required.');
+  const [mantissa, exponent = '0'] = String(value).toLowerCase().split('e');
+  const places = (mantissa.split('.')[1] ?? '').length - Number(exponent);
+  const numerator = BigInt(mantissa.replace('.', ''));
+  return places >= 0 ? fraction(numerator, 10n ** BigInt(places)) : fraction(numerator * 10n ** BigInt(-places));
+}
+export const add = (a, b) => fraction(a.numerator * b.denominator + b.numerator * a.denominator, a.denominator * b.denominator);
+export const multiply = (a, b) => fraction(a.numerator * b.numerator, a.denominator * b.denominator);
+export const subtract = (a, b) => add(a, { ...b, numerator: -b.numerator });
+export const numeric = a => Number(a.numerator) / Number(a.denominator);
+export function roundScore(a) {
+  if (a.numerator < 0n) throw new Error('Score must be nonnegative.');
+  return Number((a.numerator * 20n + a.denominator) / (2n * a.denominator)) / 10;
+}
+export function interpolate(value, anchors) {
+  if (!Number.isFinite(value)) throw new Error('Finite score measurement required.');
+  if (value <= anchors[0][0]) return decimal(anchors[0][1]);
+  for (let index = 1; index < anchors.length; index++) {
+    const [x, y] = anchors[index], [previousX, previousY] = anchors[index - 1];
+    if (value <= x) return add(decimal(previousY), multiply(subtract(decimal(value), decimal(previousX)),
+      fraction(BigInt(y - previousY), BigInt(x - previousX))));
+  }
+  return decimal(anchors[anchors.length - 1][1]);
+}

package/dist/shared-source-facts/contract.d.mts

@@ -0,0 +1,35 @@
+/** Internal adapter contract, deliberately separate from scorecard evidence v3. */
+export interface SourceFacts {
+  schemaVersion: 1 | 2;
+  language: string;
+  producer: { name: string; version: string; parser: string; parserVersion: string };
+  measurementPolicy: string;
+  status: 'complete' | 'incomplete';
+  capabilities: { functionComplexity: 'available' | 'unsupported'; coverage: 'unsupported'; maintainability: 'unsupported' };
+  scope: { description: string; excludes: string[] };
+  diagnostics: { code: string; message: string; file?: string }[];
+  functions: FunctionFact[];
+  /** Required for v2; forbidden for v1. */
+  selection?: SelectionInventory;
+}
+export interface FunctionFact {
+  id: string;
+  file: string;
+  member: string;
+  line: number;
+  /** Required for v2 facts. V1 facts retain the producing analyzer's selection. */
+  population?: 'production' | 'test' | 'support' | 'generated';
+  /** Each body owns its decisions; nested function/class bodies are separate. */
+  ownership: 'exclusive-function-body';
+  complexity: { value: number; baseline: 1; decisions: Record<string, number> | null } | null;
+}
+export interface SelectionInventory {
+  policy: string; configurationFingerprint: string;
+  options: { include: string[]; exclude: string[]; testPaths: string[]; productionPaths: string[];
+    includeTests: boolean; includeGenerated: boolean; includeSupport: boolean };
+  files: { file: string; category: 'production' | 'test' | 'support' | 'generated' | 'declaration';
+    disposition: 'analyzed' | 'excluded' | 'failed'; reason: string; contentSha256: string | null }[];
+  prunedDirectories: { path: string; reason: string }[];
+  excludedFunctions: { id: string; file: string; member: string; line: number; reason: string }[];
+}
+export function validateSourceFacts(value: unknown): asserts value is SourceFacts;

package/dist/shared-source-facts/contract.mjs

@@ -0,0 +1,95 @@
+// Validate at the producer/consumer boundary. Unknown data must never imply a pass.
+function requireValue(ok, message) {
+  if (!ok) throw new Error(`Invalid source facts: ${message}`);
+}
+const object = value => value !== null && typeof value === 'object' && !Array.isArray(value);
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const count = value => Number.isSafeInteger(value) && value >= 0;
+function keys(value, allowed, label) {
+  requireValue(object(value), `${label} must be an object`);
+  requireValue(Object.keys(value).every(key => allowed.includes(key)), `${label} has unknown fields`);
+}
+export function validateSourceFacts(value) {
+  const v2 = value?.schemaVersion === 2;
+  keys(value, ['schemaVersion', 'language', 'producer', 'measurementPolicy', 'status', 'capabilities', 'scope', 'diagnostics', 'functions', ...(v2 ? ['selection'] : [])], 'document');
+  requireValue(value.schemaVersion === 1 || v2, 'unsupported schemaVersion');
+  requireValue(text(value.language) && text(value.measurementPolicy), 'language and measurementPolicy required');
+  keys(value.producer, ['name', 'version', 'parser', 'parserVersion'], 'producer');
+  requireValue(['name', 'version', 'parser', 'parserVersion'].every(key => text(value.producer[key])), 'producer provenance required');
+  requireValue(['complete', 'incomplete'].includes(value.status), 'invalid status');
+  keys(value.capabilities, ['functionComplexity', 'coverage', 'maintainability'], 'capabilities');
+  requireValue(['available', 'unsupported'].includes(value.capabilities.functionComplexity), 'invalid complexity capability');
+  requireValue(value.capabilities.coverage === 'unsupported' && value.capabilities.maintainability === 'unsupported', 'this contract only exchanges complexity');
+  keys(value.scope, ['description', 'excludes'], 'scope');
+  requireValue(text(value.scope.description) && Array.isArray(value.scope.excludes) && value.scope.excludes.every(text), 'invalid scope');
+  requireValue(Array.isArray(value.diagnostics), 'diagnostics must be an array');
+  for (const diagnostic of value.diagnostics) {
+    keys(diagnostic, ['code', 'message', 'file'], 'diagnostic');
+    requireValue(text(diagnostic.code) && text(diagnostic.message) && (diagnostic.file === undefined || text(diagnostic.file)), 'invalid diagnostic');
+  }
+  requireValue(value.status !== 'incomplete' || value.diagnostics.length > 0, 'incomplete analysis needs a diagnostic');
+  requireValue(value.status !== 'complete' || value.diagnostics.length === 0, 'complete analysis cannot contain failure diagnostics');
+  requireValue(Array.isArray(value.functions), 'functions must be an array');
+  const ids = new Set();
+  for (const item of value.functions) {
+    keys(item, ['id', 'file', 'member', 'line', 'ownership', 'complexity', ...(v2 ? ['population'] : [])], 'function');
+    requireValue(text(item.id) && !ids.has(item.id), 'function IDs must be nonempty and unique');
+    ids.add(item.id);
+    requireValue(text(item.file) && text(item.member) && count(item.line) && item.line > 0, 'function source location required');
+    requireValue(item.ownership === 'exclusive-function-body', 'unsupported ownership policy');
+    if (v2) requireValue(['production', 'test', 'support', 'generated'].includes(item.population), 'invalid function population');
+    if (value.capabilities.functionComplexity === 'unsupported') {
+      requireValue(item.complexity === null, 'unsupported complexity must be null');
+      continue;
+    }
+    keys(item.complexity, ['value', 'baseline', 'decisions'], 'complexity');
+    requireValue(count(item.complexity.value) && item.complexity.value >= 1 && item.complexity.baseline === 1, 'invalid complexity value/baseline');
+    const decisions = item.complexity.decisions;
+    requireValue(decisions === null || object(decisions), 'decisions must be counts or null');
+    if (decisions !== null) {
+      requireValue(Object.entries(decisions).every(([key, n]) => text(key) && count(n)), 'invalid decision counts');
+      requireValue(1 + Object.values(decisions).reduce((a, b) => a + b, 0) === item.complexity.value, 'decision counts disagree with complexity');
+    }
+  }
+  if (v2) validateSelection(value, ids);
+}
+
+function validateSelection(document, ids) {
+  const value = document.selection;
+  const digest = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+  keys(value, ['policy', 'configurationFingerprint', 'options', 'files', 'prunedDirectories', 'excludedFunctions'], 'selection');
+  requireValue(text(value.policy) && digest(value.configurationFingerprint), 'selection provenance required');
+  const lists = ['include', 'exclude', 'testPaths', 'productionPaths'];
+  const flags = ['includeTests', 'includeGenerated', 'includeSupport'];
+  keys(value.options, [...lists, ...flags], 'selection options');
+  requireValue(lists.every(key => Array.isArray(value.options[key]) && value.options[key].every(text)) &&
+    flags.every(key => typeof value.options[key] === 'boolean'), 'invalid selection options');
+  requireValue(Array.isArray(value.files) && Array.isArray(value.prunedDirectories) && Array.isArray(value.excludedFunctions), 'selection inventories required');
+  const files = new Map();
+  for (const item of value.files) {
+    keys(item, ['file', 'category', 'disposition', 'reason', 'contentSha256'], 'selected file');
+    requireValue(text(item.file) && !files.has(item.file) && text(item.reason), 'unique files and reasons required');
+    requireValue(['production', 'test', 'support', 'generated', 'declaration'].includes(item.category) &&
+      ['analyzed', 'excluded', 'failed'].includes(item.disposition), 'invalid file classification');
+    requireValue(item.contentSha256 === null || digest(item.contentSha256), 'invalid source digest');
+    requireValue(item.disposition !== 'analyzed' || (digest(item.contentSha256) && item.category !== 'declaration'), 'analyzed implementation source required');
+    const flag = { test: 'includeTests', support: 'includeSupport', generated: 'includeGenerated' }[item.category];
+    requireValue(item.disposition !== 'analyzed' || !flag || value.options[flag], 'population was not enabled by selection options');
+    requireValue(item.disposition !== 'failed' || document.status === 'incomplete', 'failed files require incomplete analysis');
+    files.set(item.file, item);
+  }
+  for (const item of value.prunedDirectories) {
+    keys(item, ['path', 'reason'], 'pruned directory');
+    requireValue(text(item.path) && text(item.reason), 'pruned directory provenance required');
+  }
+  for (const item of document.functions) {
+    const file = files.get(item.file);
+    requireValue(file?.disposition === 'analyzed' && file.category === item.population, 'function does not belong to its analyzed population');
+  }
+  for (const item of value.excludedFunctions) {
+    keys(item, ['id', 'file', 'member', 'line', 'reason'], 'excluded function');
+    requireValue(text(item.id) && !ids.has(item.id) && text(item.member) && count(item.line) && item.line > 0 && text(item.reason), 'invalid or duplicate excluded function');
+    requireValue(files.get(item.file)?.disposition === 'analyzed', 'excluded declaration needs an analyzed file');
+    ids.add(item.id);
+  }
+}

package/dist/shared-source-facts/population.d.mts

@@ -0,0 +1,12 @@
+import type { SourceFacts } from './contract.mjs';
+export const complexityAnchors: readonly (readonly [number, number])[];
+export interface Contribution {
+  id: string; group: 'weakest' | 'remainder'; individualScore: number;
+  weightNumerator: number; weightDenominator: number; weightedScoreLoss: number;
+}
+export interface PopulationResult {
+  weakCount: number; restCount: number; contributions: Contribution[];
+  losses: Record<string, number>; unroundedScore: number; score: number;
+}
+export function aggregatePopulation(measurements: {id: string; value: number}[], anchors: readonly (readonly [number, number])[], higherIsWorse: boolean, weakCount: number): PopulationResult | null;
+export function complexityPopulation(facts: SourceFacts): PopulationResult | null;

package/dist/shared-source-facts/population.mjs

@@ -0,0 +1,41 @@
+import { add, decimal, fraction, interpolate, multiply, numeric, roundScore, subtract } from './arithmetic.mjs';
+import { validateSourceFacts } from './contract.mjs';
+
+export const complexityAnchors = Object.freeze([[3, 10], [5, 8], [10, 6], [20, 4], [40, 0]].map(Object.freeze));
+
+/** Shared policy mechanics; selecting/calibrating a language policy remains explicit. */
+export function aggregatePopulation(measurements, anchors, higherIsWorse, weakCount) {
+  if (!measurements.length) return null;
+  if (!Number.isSafeInteger(weakCount) || weakCount < 1 || weakCount > measurements.length) throw new Error('Invalid weakest population size.');
+  if (!Array.isArray(anchors) || anchors.length < 2 || anchors.some(([x, y], i) => !Number.isSafeInteger(x) ||
+      !Number.isSafeInteger(y) || y < 0 || y > 10 || (i > 0 && x <= anchors[i - 1][0]))) throw new Error('Invalid score anchors.');
+  const ids = new Set();
+  for (const item of measurements) {
+    if (!item.id || ids.has(item.id) || !Number.isFinite(item.value)) throw new Error('Unique IDs and finite measurements required.');
+    ids.add(item.id);
+  }
+  const ordered = measurements.map(item => ({ item, score: interpolate(item.value, anchors) }))
+    .sort((a, b) => (higherIsWorse ? b.item.value - a.item.value : a.item.value - b.item.value) ||
+      (a.item.id < b.item.id ? -1 : a.item.id > b.item.id ? 1 : 0));
+  const restCount = ordered.length - weakCount;
+  const weakWeight = restCount ? fraction(2n, 5n * BigInt(weakCount)) : fraction(1n, BigInt(weakCount));
+  const restWeight = restCount ? fraction(3n, 5n * BigInt(restCount)) : decimal(0);
+  const losses = { weakest: decimal(0), remainder: decimal(0) };
+  const contributions = ordered.map(({ item, score }, index) => {
+    const group = index < weakCount ? 'weakest' : 'remainder';
+    const weight = index < weakCount ? weakWeight : restWeight;
+    const weightedLoss = multiply(subtract(decimal(10), score), weight);
+    losses[group] = add(losses[group], weightedLoss);
+    return { id: item.id, group, individualScore: numeric(score), weightNumerator: Number(weight.numerator),
+      weightDenominator: Number(weight.denominator), weightedScoreLoss: numeric(weightedLoss) };
+  });
+  const total = subtract(decimal(10), add(losses.weakest, losses.remainder));
+  return { weakCount, restCount, contributions, losses: { weakest: numeric(losses.weakest), remainder: numeric(losses.remainder) },
+    unroundedScore: numeric(total), score: roundScore(total) };
+}
+
+export function complexityPopulation(facts) {
+  validateSourceFacts(facts);
+  if (facts.status !== 'complete' || facts.capabilities.functionComplexity !== 'available') return null;
+  return aggregatePopulation(facts.functions.map(item => ({ id: item.id, value: item.complexity.value })), complexityAnchors, true, 1);
+}

package/dist/source-facts.d.ts

@@ -0,0 +1,4 @@
+import type { FunctionMeasurement } from './function-measurements.js';
+import type { SourceFacts } from '#source-facts/contract.mjs';
+/** Adapt the existing selected population; this does not rediscover or remeasure files. */
+export declare function functionSourceFacts(functions: FunctionMeasurement[]): SourceFacts;

package/dist/source-facts.js

@@ -0,0 +1,16 @@
+import ts from 'typescript';
+/** Adapt the existing selected population; this does not rediscover or remeasure files. */
+export function functionSourceFacts(functions) {
+    return {
+        schemaVersion: 1, language: 'javascript-typescript',
+        producer: { name: 'codemetrics-ai/function-adapter', version: '1', parser: 'typescript', parserVersion: ts.version },
+        measurementPolicy: 'owned-function-body-v2-type-erasure', status: 'complete',
+        capabilities: { functionComplexity: 'available', coverage: 'unsupported', maintainability: 'unsupported' },
+        scope: { description: 'Existing selected implemented-function population supplied by the JS/TS analyzer.',
+            excludes: ['nested-function-and-class-bodies', 'type-only-syntax', 'parameter-initializers', 'module-and-field-initializers'] },
+        diagnostics: [],
+        functions: functions.map(item => ({ id: item.id, file: item.file, member: item.member, line: item.line,
+            ownership: 'exclusive-function-body', complexity: { value: item.ownComplexity, baseline: 1,
+                decisions: item.complexityBreakdown ? { ...item.complexityBreakdown.counts } : null } }))
+    };
+}