codemetrics-ai 0.2.0 → 0.4.0

package/dist/module-resolution.js

@@ -0,0 +1,76 @@
+import path from "node:path";
+import ts from "typescript";
+export const canonicalFile = (file) => {
+    const resolved = path.resolve(ts.sys.realpath?.(file) ?? file).replaceAll("\\", "/");
+    return ts.sys.useCaseSensitiveFileNames ? resolved : resolved.toLowerCase();
+};
+// A failed installed-package lookup can mean an intentionally private subpath
+// or missing build output. A same-named workspace is not a substitute version.
+function hasInstalledPackage(specifier, importer) {
+    if (specifier.startsWith(".") || path.isAbsolute(specifier))
+        return false;
+    const parts = specifier.split("/");
+    const name = parts.slice(0, specifier.startsWith("@") ? 2 : 1).join("/");
+    for (let directory = path.dirname(importer);; directory = path.dirname(directory)) {
+        if (ts.sys.directoryExists(path.join(directory, "node_modules", name)))
+            return true;
+        if (path.dirname(directory) === directory)
+            return false;
+    }
+}
+// A read-only virtual node_modules view lets TypeScript interpret workspace
+// manifests/exports without installing packages or guessing source entry points.
+function workspaceHost(packages) {
+    const names = new Map();
+    const ambiguous = new Set();
+    for (const pkg of packages) {
+        if (names.has(pkg.name))
+            ambiguous.add(pkg.name);
+        else
+            names.set(pkg.name, pkg.root);
+    }
+    for (const name of ambiguous)
+        names.delete(name);
+    function mapped(file) {
+        const normalized = file.replaceAll("\\", "/");
+        const index = normalized.lastIndexOf("/node_modules/");
+        if (index < 0)
+            return undefined;
+        const tail = normalized.slice(index + 14).split("/");
+        const count = tail[0].startsWith("@") ? 2 : 1;
+        const root = names.get(tail.slice(0, count).join("/"));
+        return root ? path.join(root, ...tail.slice(count)) : undefined;
+    }
+    return {
+        fileExists: file => ts.sys.fileExists(mapped(file) ?? file),
+        readFile: file => ts.sys.readFile(mapped(file) ?? file),
+        directoryExists: directory => {
+            const normalized = directory.replaceAll("\\", "/").replace(/\/$/, "");
+            if (normalized.endsWith("/node_modules"))
+                return names.size > 0;
+            const scope = normalized.match(/\/node_modules\/(@[^/]+)$/)?.[1];
+            if (scope && [...names.keys()].some(name => name.startsWith(scope + "/")))
+                return true;
+            return ts.sys.directoryExists(mapped(directory) ?? directory);
+        },
+        realpath: file => ts.sys.realpath?.(mapped(file) ?? file) ?? mapped(file) ?? file,
+        getCurrentDirectory: ts.sys.getCurrentDirectory,
+    };
+}
+export function moduleResolver(pkg, packages, program) {
+    const options = pkg.selection === "default-source-scan" ? { ...pkg.options, moduleResolution: ts.ModuleResolutionKind.Node10 } : pkg.options;
+    const canonical = (file) => ts.sys.useCaseSensitiveFileNames ? file : file.toLowerCase();
+    const cache = ts.createModuleResolutionCache(pkg.root, canonical, options);
+    const workspaceCache = ts.createModuleResolutionCache(pkg.root, canonical, options);
+    const host = workspaceHost(packages);
+    return (source, literal) => {
+        const mode = program.getModeForUsageLocation(source, literal);
+        const ordinary = ts.resolveModuleName(literal.text, source.fileName, options, ts.sys, cache, undefined, mode).resolvedModule;
+        if (ordinary)
+            return { resolved: ordinary, via: "typescript" };
+        if (hasInstalledPackage(literal.text, source.fileName))
+            return { resolved: undefined, via: "unresolved" };
+        const workspace = ts.resolveModuleName(literal.text, source.fileName, options, host, workspaceCache, undefined, mode).resolvedModule;
+        return { resolved: workspace, via: workspace ? "workspaceManifest" : "unresolved" };
+    };
+}

package/dist/module-topology.d.ts

@@ -0,0 +1,72 @@
+export declare function cyclicComponents(graph: Map<string, Set<string>>): string[][];
+interface DependencyEdge {
+    from: string;
+    target?: string;
+    usage: string;
+    resolution: string;
+    form: string;
+    roles: string[];
+}
+export declare function moduleTopology(ids: string[], edges: DependencyEdge[]): {
+    cycles: string[][];
+    dependencyViews: {
+        version: number;
+        classification: string;
+        implementation: {
+            modules: {
+                id: string;
+                internalValueFanOut: number;
+                internalValueFanIn: number;
+            }[];
+            internalValueEdgeCount: number;
+            highestFanOut: {
+                id: string;
+                internalValueFanOut: number;
+                internalValueFanIn: number;
+            }[];
+            highestFanIn: {
+                id: string;
+                internalValueFanOut: number;
+                internalValueFanIn: number;
+            }[];
+            basis: string;
+        };
+        reExports: {
+            modules: {
+                id: string;
+                internalValueFanOut: number;
+                internalValueFanIn: number;
+            }[];
+            internalValueEdgeCount: number;
+            highestFanOut: {
+                id: string;
+                internalValueFanOut: number;
+                internalValueFanIn: number;
+            }[];
+            highestFanIn: {
+                id: string;
+                internalValueFanOut: number;
+                internalValueFanIn: number;
+            }[];
+            basis: string;
+        };
+        totalInternalValueEdgeCount: number;
+        sharedInternalValueEdgeCount: number;
+    };
+    modules: {
+        id: string;
+        internalValueFanOut: number;
+        internalValueFanIn: number;
+    }[];
+    highestFanOut: {
+        id: string;
+        internalValueFanOut: number;
+        internalValueFanIn: number;
+    }[];
+    highestFanIn: {
+        id: string;
+        internalValueFanOut: number;
+        internalValueFanIn: number;
+    }[];
+};
+export {};

package/dist/module-topology.js

@@ -0,0 +1,72 @@
+// Iterative SCC traversal avoids stack overflow on long import chains and emits
+// one cyclic component, not an exponential list of individual cycle paths.
+export function cyclicComponents(graph) {
+    const visited = new Set(), order = [];
+    for (const root of graph.keys()) {
+        const stack = [[root, false]];
+        while (stack.length) {
+            const [node, finishing] = stack.pop();
+            if (finishing) {
+                order.push(node);
+                continue;
+            }
+            if (visited.has(node))
+                continue;
+            visited.add(node);
+            stack.push([node, true]);
+            for (const target of graph.get(node) ?? [])
+                if (!visited.has(target))
+                    stack.push([target, false]);
+        }
+    }
+    const reverse = new Map([...graph.keys()].map(node => [node, new Set()]));
+    for (const [node, targets] of graph)
+        for (const target of targets)
+            reverse.get(target).add(node);
+    visited.clear();
+    const components = [];
+    for (const root of order.reverse()) {
+        if (visited.has(root))
+            continue;
+        const component = [], stack = [root];
+        visited.add(root);
+        while (stack.length) {
+            const node = stack.pop();
+            component.push(node);
+            for (const target of reverse.get(node) ?? [])
+                if (!visited.has(target)) {
+                    visited.add(target);
+                    stack.push(target);
+                }
+        }
+        if (component.length > 1 || graph.get(root)?.has(root))
+            components.push(component.sort());
+    }
+    return components.sort((a, b) => a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0);
+}
+function referenceView(ids, edges) {
+    const graph = new Map(ids.map(id => [id, new Set()]));
+    const incoming = new Map(ids.map(id => [id, new Set()]));
+    for (const edge of edges)
+        if (edge.resolution === "internal" && edge.usage !== "typeOnly" && edge.target) {
+            graph.get(edge.from).add(edge.target);
+            incoming.get(edge.target).add(edge.from);
+        }
+    const modules = ids.map(id => ({ id, internalValueFanOut: graph.get(id).size, internalValueFanIn: incoming.get(id).size }));
+    const rank = (key) => modules.filter(item => item[key] > 0)
+        .sort((a, b) => b[key] - a[key] || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0)).slice(0, 10);
+    return { graph, modules, internalValueEdgeCount: modules.reduce((sum, node) => sum + node.internalValueFanOut, 0),
+        highestFanOut: rank("internalValueFanOut"), highestFanIn: rank("internalValueFanIn") };
+}
+export function moduleTopology(ids, edges) {
+    const { graph, internalValueEdgeCount, ...overall } = referenceView(ids, edges);
+    const { graph: _imports, ...implementation } = referenceView(ids, edges.filter(edge => edge.roles.includes("implementation")));
+    const { graph: _exports, ...reExports } = referenceView(ids, edges.filter(edge => edge.roles.includes("reExport")));
+    return { ...overall, cycles: cyclicComponents(graph), dependencyViews: {
+            version: 2, classification: "explicit-forwarding-v2",
+            implementation: { basis: "Imports/loads with local uses or no recognized forwarding; unsupported alias flow remains here.", ...implementation },
+            reExports: { basis: "Direct re-exports and explicit forwarding through an unmodified local import/require binding or direct require call.", ...reExports },
+            totalInternalValueEdgeCount: internalValueEdgeCount,
+            sharedInternalValueEdgeCount: implementation.internalValueEdgeCount + reExports.internalValueEdgeCount - internalValueEdgeCount
+        } };
+}

package/dist/react-probe.d.ts

@@ -0,0 +1,6 @@
+import ts from "typescript";
+import type { Finding } from "./evidence.js";
+type ReactObservation = Pick<Finding, "category" | "message" | "observations" | "confidence">;
+export declare function importedHookName(call: ts.CallExpression, checker: ts.TypeChecker): string | undefined;
+export declare function inspectReactCall(call: ts.CallExpression, body: ts.ConciseBody, checker: ts.TypeChecker): ReactObservation[];
+export {};

package/dist/react-probe.js

@@ -0,0 +1,60 @@
+import ts from "typescript";
+import { isFunction } from "./function-nodes.js";
+function isReactImport(declaration) {
+    if (ts.isImportSpecifier(declaration) && declaration.isTypeOnly)
+        return false;
+    let cursor = declaration;
+    while (cursor && !ts.isImportDeclaration(cursor))
+        cursor = cursor.parent;
+    return !!cursor && !cursor.importClause?.isTypeOnly && ts.isStringLiteral(cursor.moduleSpecifier) && cursor.moduleSpecifier.text === "react";
+}
+export function importedHookName(call, checker) {
+    const symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(call.expression) ? call.expression.name : call.expression);
+    const declarations = symbol?.declarations ?? [];
+    const reactHook = declarations.some(isReactImport);
+    const hookName = declarations.find(ts.isImportSpecifier);
+    const calledName = hookName ? (hookName.propertyName ?? hookName.name).text : ts.isPropertyAccessExpression(call.expression) ? call.expression.name.text : "";
+    const namespaceSymbol = ts.isPropertyAccessExpression(call.expression) ? checker.getSymbolAtLocation(call.expression.expression) : undefined;
+    const reactNamespace = namespaceSymbol?.declarations?.some(isReactImport);
+    return (reactHook || reactNamespace) && /^use[A-Z]/.test(calledName) ? calledName : undefined;
+}
+function isConditionalOrLoop(node, child) {
+    if (ts.isIfStatement(node))
+        return child !== node.expression;
+    if (ts.isConditionalExpression(node))
+        return child !== node.condition;
+    if (ts.isBinaryExpression(node))
+        return child === node.right &&
+            [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(node.operatorToken.kind);
+    if (ts.isForStatement(node))
+        return child !== node.initializer;
+    if (ts.isForOfStatement(node) || ts.isForInStatement(node))
+        return child !== node.expression;
+    return ts.isWhileStatement(node) || ts.isDoStatement(node);
+}
+// The metric visitor supplies only calls owned by the current function. Keeping
+// traversal and identity there preserves nested-function boundaries and ordering.
+export function inspectReactCall(call, body, checker) {
+    const hook = importedHookName(call, checker);
+    if (!hook)
+        return [];
+    const findings = [];
+    let ancestor = call.parent;
+    let child = call;
+    while (ancestor && ancestor !== body) {
+        if (isConditionalOrLoop(ancestor, child)) {
+            findings.push({ category: "conditionalHook", message: `${hook} is called within a conditional or loop.`, observations: { hook }, confidence: "high" });
+            break;
+        }
+        child = ancestor;
+        ancestor = ancestor.parent;
+    }
+    if (["useEffect", "useLayoutEffect"].includes(hook)) {
+        const callback = call.arguments[0];
+        if (callback && isFunction(callback) && callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword))
+            findings.push({ category: "asyncEffectCallback", message: "An effect callback is async and returns a Promise instead of cleanup or undefined.", observations: { hook }, confidence: "high" });
+        if (call.arguments.length < 2)
+            findings.push({ category: "effectWithoutDependencies", message: "Effect runs after every render; verify that this is intentional.", observations: { hook }, confidence: "low" });
+    }
+    return findings;
+}

package/dist/score-arithmetic.d.ts

@@ -0,0 +1,12 @@
+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;

package/dist/score-arithmetic.js

@@ -0,0 +1,40 @@
+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/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.4.0",
   "description": "Deterministic code metrics and scorecard evidence for JavaScript, TypeScript, and React projects",
   "license": "MIT",
   "type": "module",
@@ -15,8 +15,9 @@
   "scripts": {
     "build": "tsc -p tsconfig.json && node scripts/copy-schema.mjs",
     "prepack": "npm run build",
-    "test": "npm run build && vitest run",
-    "test:package": "node scripts/package-smoke.mjs"
+    "test": "npm run build && vitest run --maxWorkers=2",
+    "test:package": "node scripts/package-smoke.mjs",
+    "test:architecture": "npm run build && node scripts/architecture-corpus.mjs"
   },
   "engines": {
     "node": ">=20"