codemetrics-ai 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,8 @@
 # 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.
+Deterministic source analysis for JavaScript, TypeScript, JSX and TSX. Version 0.3.0 implements source metrics and React hook/effect checks and emits schema-v3 evidence, including executed scoring decisions. Scores are **uncalibrated across ecosystems**; compare them only with compatible runs of this analyzer.
+
+Each scored dimension includes `scoringDecision`: policy inputs, the selected threshold/condition, other matching conditions, and finding attribution. These are aggregate policy decisions, not independent deductions. See [the decision contract](../../shared/scorecard-schema/scoring-decisions.md). Existing 0.2.0 scores and thresholds are unchanged.
 
 ```sh
 npx codemetrics-ai --project package.json

package/dist/analyzer.js

@@ -3,6 +3,7 @@ import { discover } from "./discovery.js";
 import { analyzeFile } from "./metrics.js";
 import { hash, invocationIds, scored, skippedDimensions } from "./evidence.js";
 import { metricsCsvHeader } from "./scorecard-contract.js";
+import { firstMatch, thresholdDecision } from "./scoring-decision.js";
 export function analyze(options, version) {
     const identity = invocationIds(options.runId, options.auditId);
     const discovery = discover(options.project, options.tsconfig);
@@ -38,15 +39,18 @@ export function analyze(options, version) {
         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;
+        const quality = thresholdDecision("javascript-typescript/codeQuality/v1", maximum, [5, 10, 20, 40], false, [...new Set(collected.filter(item => item.dimension === "codeQuality").map(item => item.finding.category))]);
         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] });
+        dimensions.maintainability = scored(thresholdDecision("javascript-typescript/maintainability/v1", median, [85, 65, 40, 20], true), `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" });
+            dimensions.performanceAsync = scored(firstMatch("javascript-typescript/performanceAsync/react-hooks/v1", { actionableFindings: actionable.length, advisoryFindings: performance.length - actionable.length }, [
+                { id: "actionableHooks", condition: "actionableFindings > 0", matched: actionable.length > 0, score: 6, categories: [...new Set(actionable.map(f => f.category))] },
+                { id: "noActionableHooks", condition: "otherwise", matched: true, score: 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" }, finding => finding.confidence !== "low");
     }
     if (diagnostics.length)
         for (const key of ["codeQuality", "maintainability", "performanceAsync"])

package/dist/evidence-tools.js

@@ -19,6 +19,26 @@ export function validateEvidence(value) {
     const ids = findings(evidence).map(finding => finding.fingerprint);
     if (new Set(ids).size !== ids.length)
         throw new Error("Duplicate finding fingerprints.");
+    for (const dimension of Object.values(evidence.dimensions)) {
+        const decision = dimension.scoringDecision;
+        if (!decision)
+            continue; // Older schema-v3 producers remain supported.
+        if (decision.finalScore !== dimension.score)
+            throw new Error("Scoring decision differs from dimension score.");
+        const steps = (items) => items.flatMap(step => [step, ...steps(step.decision?.steps ?? [])]);
+        const stepIds = steps(decision.steps).map(step => step.id);
+        if (new Set(stepIds).size !== stepIds.length)
+            throw new Error("Duplicate scoring step identifiers.");
+        const effectIds = decision.findingEffects.map(effect => effect.fingerprint);
+        if (new Set(effectIds).size !== effectIds.length || effectIds.length !== dimension.findings.length)
+            throw new Error("Scoring effects must identify each finding exactly once.");
+        for (const effect of decision.findingEffects) {
+            if (!dimension.findings.some(finding => finding.fingerprint === effect.fingerprint && finding.category === effect.category))
+                throw new Error("Scoring effect references an unknown finding.");
+            if (effect.stepIds.some(id => !stepIds.includes(id)))
+                throw new Error("Scoring effect references an unknown step.");
+        }
+    }
 }
 export function readEvidence(file) {
     const value = JSON.parse(fs.readFileSync(file, "utf8"));

package/dist/evidence.d.ts

@@ -1,4 +1,5 @@
 import { type DimensionKey } from "./scorecard-contract.js";
+import { type ScoringDecision } from "./scoring-decision.js";
 export declare const hash: (text: string) => string;
 export declare function invocationIds(runId?: string, auditId?: string): {
     runId: string;
@@ -20,6 +21,7 @@ export interface Finding {
     observations: Record<string, unknown>;
 }
 export interface Dimension {
+    scoringDecision?: ScoringDecision;
     scope?: {
         id: string;
         coverage: "partial" | "unsupported";
@@ -81,4 +83,4 @@ export interface Evidence {
     };
 }
 export declare function skippedDimensions(): Record<DimensionKey, Dimension>;
-export declare function scored(score: number, basis: string, findings: Finding[], observations: Record<string, unknown>): Dimension;
+export declare function scored(decision: ScoringDecision, basis: string, findings: Finding[], observations: Record<string, unknown>, eligible?: (finding: Finding) => boolean): Dimension;

package/dist/evidence.js

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from "node:crypto";
 import { dimensionKeys } from "./scorecard-contract.js";
+import { attachFindings } from "./scoring-decision.js";
 export const hash = (text) => createHash("sha256").update(text).digest("hex");
 export function invocationIds(runId = randomUUID(), auditId = runId) {
     for (const [name, value] of Object.entries({ runId, auditId }))
@@ -13,8 +14,10 @@ export function skippedDimensions() {
             scope: { id: `javascript-typescript/${key}/unsupported`, coverage: "unsupported", includes: [], excludes: [key] }
         }]));
 }
-export function scored(score, basis, findings, observations) {
-    return { status: "scored", score, basis, findings: findings.sort((a, b) => a.fingerprint.localeCompare(b.fingerprint, "en")),
+export function scored(decision, basis, findings, observations, eligible) {
+    const score = decision.finalScore;
+    attachFindings(decision, findings, eligible);
+    return { status: "scored", score, basis, scoringDecision: decision, findings: findings.sort((a, b) => a.fingerprint.localeCompare(b.fingerprint, "en")),
         scoring: { algorithm: "dimension-policy", finalScore: score, aggregateScoreLoss: 10 - score,
             contributionMode: "aggregate; findings are not independent deductions", observations } };
 }

package/dist/evidence.schema.v3.json

@@ -347,6 +347,9 @@
               }
             }
           }
+        },
+        "scoringDecision": {
+          "$ref": "#/$defs/scoringDecision"
         }
       },
       "additionalProperties": true,
@@ -367,8 +370,17 @@
       },
       "else": {
         "not": {
-          "required": [
-            "score"
+          "anyOf": [
+            {
+              "required": [
+                "score"
+              ]
+            },
+            {
+              "required": [
+                "scoringDecision"
+              ]
+            }
           ]
         }
       }
@@ -439,6 +451,163 @@
           "type": "object"
         }
       }
+    },
+    "scoringDecision": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "version",
+        "policy",
+        "operation",
+        "finalScore",
+        "inputs",
+        "steps",
+        "findingEffects"
+      ],
+      "properties": {
+        "version": {
+          "const": 1
+        },
+        "policy": {
+          "type": "string",
+          "minLength": 1
+        },
+        "operation": {
+          "enum": [
+            "firstMatch",
+            "minimum",
+            "mean",
+            "deductions"
+          ]
+        },
+        "finalScore": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 10
+        },
+        "inputs": {
+          "type": "object"
+        },
+        "steps": {
+          "type": "array",
+          "minItems": 1,
+          "items": {
+            "$ref": "#/$defs/scoringStep"
+          }
+        },
+        "findingEffects": {
+          "type": "array",
+          "items": {
+            "$ref": "#/$defs/findingScoreEffect"
+          }
+        }
+      }
+    },
+    "scoringStep": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "id",
+        "kind",
+        "score",
+        "disposition",
+        "inputs",
+        "findingCategories"
+      ],
+      "properties": {
+        "id": {
+          "type": "string",
+          "minLength": 1
+        },
+        "kind": {
+          "enum": [
+            "rule",
+            "component",
+            "cap"
+          ]
+        },
+        "score": {
+          "type": "number",
+          "minimum": 0,
+          "maximum": 10
+        },
+        "condition": {
+          "type": [
+            "string",
+            "null"
+          ]
+        },
+        "matched": {
+          "type": [
+            "boolean",
+            "null"
+          ]
+        },
+        "disposition": {
+          "enum": [
+            "selected",
+            "shadowed",
+            "notMatched",
+            "contributing",
+            "notLimiting",
+            "applied"
+          ]
+        },
+        "inputs": {
+          "type": "object"
+        },
+        "findingCategories": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        },
+        "decision": {
+          "anyOf": [
+            {
+              "$ref": "#/$defs/scoringDecision"
+            },
+            {
+              "type": "null"
+            }
+          ]
+        }
+      }
+    },
+    "findingScoreEffect": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "fingerprint",
+        "category",
+        "effect",
+        "stepIds"
+      ],
+      "properties": {
+        "fingerprint": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{64}$"
+        },
+        "category": {
+          "type": "string",
+          "minLength": 1
+        },
+        "effect": {
+          "enum": [
+            "policyInput",
+            "excluded",
+            "noAdditionalReduction"
+          ]
+        },
+        "stepIds": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "minLength": 1
+          }
+        }
+      }
     }
   }
 }

package/dist/scoring-decision.d.ts

@@ -0,0 +1,35 @@
+import type { Finding } from "./evidence.js";
+export interface ScoringStep {
+    id: string;
+    kind: "rule" | "component" | "cap";
+    score: number;
+    condition?: string | null;
+    matched?: boolean | null;
+    disposition: "selected" | "shadowed" | "notMatched" | "contributing" | "notLimiting" | "applied";
+    inputs: Record<string, unknown>;
+    findingCategories: string[];
+    decision?: ScoringDecision | null;
+}
+export interface ScoringDecision {
+    version: 1;
+    policy: string;
+    operation: "firstMatch" | "minimum" | "mean" | "deductions";
+    finalScore: number;
+    inputs: Record<string, unknown>;
+    steps: ScoringStep[];
+    findingEffects: {
+        fingerprint: string;
+        category: string;
+        effect: "policyInput" | "excluded" | "noAdditionalReduction";
+        stepIds: string[];
+    }[];
+}
+export declare function firstMatch(policy: string, inputs: Record<string, unknown>, rules: {
+    id: string;
+    condition: string;
+    matched: boolean;
+    score: number;
+    categories?: string[];
+}[]): ScoringDecision;
+export declare function thresholdDecision(policy: string, measured: number, thresholds: number[], descending: boolean, categories?: string[]): ScoringDecision;
+export declare function attachFindings(decision: ScoringDecision, findings: Finding[], eligible?: (finding: Finding) => boolean): void;

package/dist/scoring-decision.js

@@ -0,0 +1,24 @@
+export function firstMatch(policy, inputs, rules) {
+    const selected = rules.findIndex(rule => rule.matched);
+    if (selected < 0)
+        throw new Error("Scoring ladder requires a matching default.");
+    return { version: 1, policy, operation: "firstMatch", finalScore: rules[selected].score, inputs, findingEffects: [],
+        steps: rules.map((rule, index) => ({ id: rule.id, kind: "rule", condition: rule.condition, matched: rule.matched, score: rule.score,
+            disposition: index === selected ? "selected" : rule.matched ? "shadowed" : "notMatched", inputs: {}, findingCategories: rule.categories ?? [] })) };
+}
+export function thresholdDecision(policy, measured, thresholds, descending, categories = []) {
+    return firstMatch(policy, { measured, thresholds }, [
+        ...thresholds.map((threshold, index) => ({ id: `band${index}`, condition: `measured ${descending ? ">=" : "<="} threshold[${index}]`,
+            matched: descending ? measured >= threshold : measured <= threshold, score: 10 - index * 2, categories })),
+        { id: "otherwise", condition: "otherwise", matched: true, score: 2, categories }
+    ]);
+}
+export function attachFindings(decision, findings, eligible = () => true) {
+    decision.findingEffects = findings.map(finding => {
+        const steps = decision.steps.filter(step => step.findingCategories.includes(finding.category));
+        const excluded = String(finding.observations.scoreDisposition ?? "").startsWith("excluded");
+        return { fingerprint: finding.fingerprint, category: finding.category,
+            effect: excluded ? "excluded" : eligible(finding) && steps.some(step => step.disposition === "selected") ? "policyInput" : "noAdditionalReduction",
+            stepIds: steps.map(step => step.id).sort() };
+    }).sort((a, b) => a.fingerprint.localeCompare(b.fingerprint, "en"));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemetrics-ai",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Deterministic code metrics and scorecard evidence for JavaScript, TypeScript, and React projects",
   "license": "MIT",
   "type": "module",