codemetrics-ai 0.2.0

package/dist/evidence-tools.d.ts

@@ -0,0 +1,85 @@
+import type { Evidence, Finding } from "./evidence.js";
+export declare function validateEvidence(value: unknown): asserts value is Evidence;
+export declare function readEvidence(file: string): Evidence;
+export declare function findings(evidence: Evidence): Finding[];
+export declare function compare(current: Evidence, baseline: Evidence, allowIncompatible?: boolean): {
+    compatible: boolean;
+    reasons: string[];
+    currentRun: {
+        runId: string | null;
+        auditId: string | null;
+    };
+    baselineRun: {
+        runId: string | null;
+        auditId: string | null;
+    };
+    new: Finding[];
+    resolved: Finding[];
+    changed: Finding[];
+    severityIncreases: Finding[];
+    unchanged: Finding[];
+    dimensions: {
+        [k: string]: {
+            before: number | null;
+            after: number | null;
+            delta: number | null;
+        };
+    };
+};
+export declare function gate(comparison: ReturnType<typeof compare>, severity?: string, maxScoreDrop?: number): boolean;
+export declare function sarif(evidence: Evidence): {
+    $schema: string;
+    version: string;
+    runs: {
+        properties: {
+            runId: string | null;
+            auditId: string | null;
+        };
+        tool: {
+            driver: {
+                name: string;
+                version: string;
+                rules: {
+                    id: string;
+                    shortDescription: {
+                        text: string;
+                    };
+                    help: {
+                        text: string;
+                    };
+                }[];
+            };
+        };
+        invocations: {
+            workingDirectory: {
+                uri: string;
+            };
+            executionSuccessful: boolean;
+        }[];
+        results: {
+            locations?: {
+                physicalLocation: {
+                    region?: {
+                        startLine: number;
+                    } | undefined;
+                    artifactLocation: {
+                        uri: string;
+                    };
+                };
+            }[] | undefined;
+            ruleId: string;
+            ruleIndex: number;
+            level: string;
+            message: {
+                text: string;
+            };
+            partialFingerprints: {
+                "codemetrics/v1": string;
+            };
+            properties: {
+                confidence: "high" | "medium" | "low";
+                observations: Record<string, unknown>;
+            };
+        }[];
+    }[];
+};

package/dist/evidence-tools.js

@@ -0,0 +1,103 @@
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+import { dimensionKeys } from "./scorecard-contract.js";
+const ajv = new Ajv2020({ allErrors: true, strict: false });
+addFormats(ajv);
+let validator;
+export function validateEvidence(value) {
+    if (value?.schemaVersion !== 3)
+        throw new Error("Schema-v3 evidence is required. Re-run the analyzer; v2 lacks comparison provenance.");
+    validator ??= ajv.compile(JSON.parse(fs.readFileSync(new URL("./evidence.schema.v3.json", import.meta.url), "utf8")));
+    if (!validator(value))
+        throw new Error("Invalid evidence: " + ajv.errorsText(validator.errors));
+    const evidence = value;
+    if (evidence.filters.analyzedUnits > evidence.filters.totalUnits)
+        throw new Error("Analyzed units exceed total units.");
+    const ids = findings(evidence).map(finding => finding.fingerprint);
+    if (new Set(ids).size !== ids.length)
+        throw new Error("Duplicate finding fingerprints.");
+}
+export function readEvidence(file) {
+    const value = JSON.parse(fs.readFileSync(file, "utf8"));
+    validateEvidence(value);
+    return value;
+}
+export function findings(evidence) { return dimensionKeys.flatMap(key => evidence.dimensions[key].findings); }
+const ranks = { info: 0, warning: 1, error: 2 };
+function entryPoint(evidence) {
+    const root = evidence.subject.root.replaceAll("\\", "/").replace(/\/$/, "") + "/";
+    const entry = evidence.subject.entryPoint.replaceAll("\\", "/");
+    return entry.startsWith(root) ? entry.slice(root.length) : entry;
+}
+export function compare(current, baseline, allowIncompatible = false) {
+    const reasons = [];
+    for (const key of ["ecosystem", "version", "name"])
+        if (current.tool[key] !== baseline.tool[key])
+            reasons.push("tool." + key + " differs");
+    for (const key of ["ruleset", "configurationFingerprint"])
+        if (current.analysis[key] !== baseline.analysis[key])
+            reasons.push("analysis." + key + " differs");
+    for (const key of ["name", "variant"])
+        if (current.subject[key] !== baseline.subject[key])
+            reasons.push("subject." + key + " differs");
+    if (entryPoint(current) !== entryPoint(baseline))
+        reasons.push("subject.entryPoint differs");
+    if (current.analysis.status !== "complete" || baseline.analysis.status !== "complete")
+        reasons.push("Analysis is incomplete");
+    if (dimensionKeys.some(key => current.dimensions[key].status === "failed" || baseline.dimensions[key].status === "failed"))
+        reasons.push("A dimension failed");
+    if (dimensionKeys.some(key => current.dimensions[key].status !== baseline.dimensions[key].status))
+        reasons.push("Dimension availability differs");
+    const scopeIdentity = (scope) => scope === undefined ? "unknown" :
+        JSON.stringify([scope.id, scope.coverage, [...scope.includes].sort(), [...scope.excludes].sort()]);
+    if (dimensionKeys.some(key => scopeIdentity(current.dimensions[key].scope) !== scopeIdentity(baseline.dimensions[key].scope)))
+        reasons.push("Dimension scope differs");
+    if (reasons.length && !allowIncompatible)
+        throw new Error("Incompatible baseline: " + reasons.join("; "));
+    const before = new Map(findings(baseline).map(finding => [finding.fingerprint, finding]));
+    const after = new Map(findings(current).map(finding => [finding.fingerprint, finding]));
+    const changed = findings(current).filter(finding => before.has(finding.fingerprint) &&
+        (before.get(finding.fingerprint).severity !== finding.severity || before.get(finding.fingerprint).confidence !== finding.confidence));
+    return { compatible: reasons.length === 0, reasons,
+        currentRun: { runId: current.analysis.runId ?? null, auditId: current.analysis.auditId ?? null },
+        baselineRun: { runId: baseline.analysis.runId ?? null, auditId: baseline.analysis.auditId ?? null },
+        new: findings(current).filter(finding => !before.has(finding.fingerprint)),
+        resolved: findings(baseline).filter(finding => !after.has(finding.fingerprint)), changed,
+        severityIncreases: changed.filter(finding => ranks[finding.severity] > ranks[before.get(finding.fingerprint).severity]),
+        unchanged: findings(current).filter(finding => before.has(finding.fingerprint) && !changed.includes(finding)),
+        dimensions: Object.fromEntries(dimensionKeys.map(key => [key, { before: baseline.dimensions[key].score ?? null,
+                after: current.dimensions[key].score ?? null,
+                delta: reasons.length || current.dimensions[key].score === undefined || baseline.dimensions[key].score === undefined ? null :
+                    current.dimensions[key].score - baseline.dimensions[key].score }])) };
+}
+export function gate(comparison, severity, maxScoreDrop) {
+    if (!comparison.compatible)
+        throw new Error("Cannot apply quality gates to incompatible evidence.");
+    if (severity !== undefined && !(severity in ranks))
+        throw new Error("--fail-on-new must be info, warning, or error.");
+    if (maxScoreDrop !== undefined && (!Number.isFinite(maxScoreDrop) || maxScoreDrop < 0))
+        throw new Error("--max-score-drop must be a nonnegative number.");
+    return (severity !== undefined && [...comparison.new, ...comparison.severityIncreases].some(finding => ranks[finding.severity] >= ranks[severity])) ||
+        (maxScoreDrop !== undefined && Object.values(comparison.dimensions).some(dimension => dimension.delta !== null && dimension.delta < -maxScoreDrop));
+}
+export function sarif(evidence) {
+    const all = findings(evidence);
+    const ids = [...new Set(all.map(finding => finding.ruleId))].sort();
+    return { $schema: "https://json.schemastore.org/sarif-2.1.0.json", version: "2.1.0",
+        runs: [{ properties: { runId: evidence.analysis.runId ?? null, auditId: evidence.analysis.auditId ?? null },
+                tool: { driver: { name: evidence.tool.name, version: evidence.tool.version,
+                        rules: ids.map(id => ({ id, shortDescription: { text: id.split("/").at(-1) },
+                            help: { text: "Review observations and source context. Scores use aggregate dimension policies; findings are not independent deductions." } })) } },
+                invocations: [{ workingDirectory: { uri: pathToFileURL(evidence.subject.root + path.sep).href },
+                        executionSuccessful: evidence.analysis.status === "complete" && !dimensionKeys.some(key => evidence.dimensions[key].status === "failed") }],
+                results: all.map(finding => ({ ruleId: finding.ruleId, ruleIndex: ids.indexOf(finding.ruleId),
+                    level: finding.severity === "info" ? "note" : finding.severity, message: { text: finding.message },
+                    partialFingerprints: { "codemetrics/v1": finding.fingerprint }, properties: { confidence: finding.confidence, observations: finding.observations },
+                    ...(finding.file && !finding.file.startsWith("../") && !/^(?:[A-Za-z]:|\/)/.test(finding.file) ? {
+                        locations: [{ physicalLocation: { artifactLocation: { uri: finding.file.split("/").map(encodeURIComponent).join("/") },
+                                    ...(finding.line && finding.line > 0 ? { region: { startLine: finding.line } } : {}) } }]
+                    } : {}) })) }] };
+}

package/dist/evidence.d.ts

@@ -0,0 +1,84 @@
+import { type DimensionKey } from "./scorecard-contract.js";
+export declare const hash: (text: string) => string;
+export declare function invocationIds(runId?: string, auditId?: string): {
+    runId: string;
+    auditId: string;
+};
+export interface Finding {
+    category: string;
+    ruleId: string;
+    fingerprint: string;
+    severity: "info" | "warning" | "error";
+    confidence: "high" | "medium" | "low";
+    message: string;
+    file?: string;
+    line?: number;
+    project?: string;
+    type?: string;
+    member?: string;
+    package?: string;
+    observations: Record<string, unknown>;
+}
+export interface Dimension {
+    scope?: {
+        id: string;
+        coverage: "partial" | "unsupported";
+        includes: string[];
+        excludes: string[];
+    };
+    status: "scored" | "skipped" | "failed";
+    score?: number;
+    basis: string;
+    findings: Finding[];
+    [key: string]: unknown;
+}
+export interface Evidence {
+    schemaVersion: number;
+    generatedAtUtc: string;
+    tool: {
+        name: string;
+        version: string;
+        ecosystem: string;
+    };
+    subject: {
+        root: string;
+        entryPoint: string;
+        name?: string;
+        variant?: string;
+    };
+    filters: {
+        totalUnits: number;
+        analyzedUnits: number;
+        skipped: {
+            name: string;
+            reason: string;
+        }[];
+    };
+    population: {
+        types: number;
+        members: number;
+    };
+    dimensions: Record<DimensionKey, Dimension>;
+    analysis: {
+        runId?: string;
+        auditId?: string;
+        status: "complete" | "incomplete";
+        ruleset: string;
+        calibration: string;
+        configurationFingerprint: string;
+        diagnostics: {
+            kind: string;
+            message: string;
+            project?: string;
+        }[];
+        suppressions: {
+            file: string;
+            line: number;
+            categories: string[];
+            reason?: string;
+            status: string;
+        }[];
+    };
+}
+export declare function skippedDimensions(): Record<DimensionKey, Dimension>;
+export declare function scored(score: number, basis: string, findings: Finding[], observations: Record<string, unknown>): Dimension;

package/dist/evidence.js

@@ -0,0 +1,20 @@
+import { createHash, randomUUID } from "node:crypto";
+import { dimensionKeys } from "./scorecard-contract.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 }))
+        if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i.test(value))
+            throw new Error(`${name} must be a UUID.`);
+    return { runId: runId.toLowerCase(), auditId: auditId.toLowerCase() };
+}
+export function skippedDimensions() {
+    return Object.fromEntries(dimensionKeys.map(key => [key, {
+            status: "skipped", basis: "Not implemented by this analyzer version.", findings: [],
+            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")),
+        scoring: { algorithm: "dimension-policy", finalScore: score, aggregateScoreLoss: 10 - score,
+            contributionMode: "aggregate; findings are not independent deductions", observations } };
+}

package/dist/evidence.schema.v2.json

@@ -0,0 +1,127 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/sean-m-cooper/CodeMetrics.AI/shared/scorecard-schema/evidence.schema.v2.json",
+  "title": "CodeMetrics.AI Evidence v2",
+  "type": "object",
+  "required": ["schemaVersion", "generatedAtUtc", "tool", "subject", "filters", "population", "dimensions"],
+  "additionalProperties": false,
+  "properties": {
+    "schemaVersion": { "const": 2 },
+    "generatedAtUtc": { "type": "string", "format": "date-time" },
+    "tool": {
+      "type": "object",
+      "required": ["name", "version", "ecosystem"],
+      "additionalProperties": false,
+      "properties": {
+        "name": { "type": "string", "minLength": 1 },
+        "version": { "type": "string", "minLength": 1 },
+        "ecosystem": { "enum": ["dotnet", "javascript-typescript", "python", "rust"] }
+      }
+    },
+    "subject": {
+      "type": "object",
+      "required": ["root", "entryPoint"],
+      "additionalProperties": false,
+      "properties": {
+        "root": { "type": "string", "minLength": 1 },
+        "entryPoint": { "type": "string", "minLength": 1 },
+        "name": { "type": "string" },
+        "variant": { "type": "string" }
+      }
+    },
+    "filters": {
+      "type": "object",
+      "required": ["totalUnits", "analyzedUnits", "skipped"],
+      "additionalProperties": false,
+      "properties": {
+        "totalUnits": { "type": "integer", "minimum": 0 },
+        "analyzedUnits": { "type": "integer", "minimum": 0 },
+        "skipped": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "required": ["name", "reason"],
+            "additionalProperties": false,
+            "properties": {
+              "name": { "type": "string", "minLength": 1 },
+              "reason": { "type": "string", "minLength": 1 }
+            }
+          }
+        }
+      }
+    },
+    "population": {
+      "type": "object",
+      "required": ["types", "members"],
+      "additionalProperties": false,
+      "properties": {
+        "types": { "type": "integer", "minimum": 0 },
+        "members": { "type": "integer", "minimum": 0 }
+      }
+    },
+    "dimensions": {
+      "type": "object",
+      "required": [
+        "codeQuality",
+        "maintainability",
+        "errorHandling",
+        "performanceAsync",
+        "security",
+        "testing",
+        "documentation",
+        "dependencyManagement",
+        "architecture"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "codeQuality": { "$ref": "#/$defs/dimensionResult" },
+        "maintainability": { "$ref": "#/$defs/dimensionResult" },
+        "errorHandling": { "$ref": "#/$defs/dimensionResult" },
+        "performanceAsync": { "$ref": "#/$defs/dimensionResult" },
+        "security": { "$ref": "#/$defs/dimensionResult" },
+        "testing": { "$ref": "#/$defs/dimensionResult" },
+        "documentation": { "$ref": "#/$defs/dimensionResult" },
+        "dependencyManagement": { "$ref": "#/$defs/dimensionResult" },
+        "architecture": { "$ref": "#/$defs/dimensionResult" }
+      }
+    }
+  },
+  "$defs": {
+    "dimensionResult": {
+      "type": "object",
+      "required": ["status", "basis", "findings"],
+      "properties": {
+        "status": { "enum": ["scored", "skipped", "failed"] },
+        "score": { "type": "number", "minimum": 0, "maximum": 10 },
+        "basis": { "type": "string", "minLength": 1 },
+        "findings": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/finding" }
+        }
+      },
+      "additionalProperties": true,
+      "if": {
+        "properties": { "status": { "const": "scored" } },
+        "required": ["status"]
+      },
+      "then": { "required": ["score"] }
+    },
+    "finding": {
+      "type": "object",
+      "required": ["category", "severity", "message"],
+      "additionalProperties": false,
+      "properties": {
+        "category": { "type": "string", "minLength": 1 },
+        "severity": { "enum": ["info", "warning", "error"] },
+        "file": { "type": "string" },
+        "line": { "type": "integer", "minimum": 0 },
+        "project": { "type": "string" },
+        "type": { "type": "string" },
+        "member": { "type": "string" },
+        "package": { "type": "string" },
+        "confidence": { "enum": ["high", "medium", "low"] },
+        "message": { "type": "string", "minLength": 1 }
+      }
+    }
+  }
+}