codemetrics-ai 0.2.0 → 0.4.0

package/dist/handler-resolution.d.ts

@@ -0,0 +1,26 @@
+import ts from "typescript";
+export declare function unwrapHandler(node: ts.Expression): ts.Expression;
+type Resolution = {
+    body: ts.ConciseBody;
+    resolution: "inline" | "reference";
+} | {
+    reason: string;
+};
+/** Bounded declaration lookup, not a runtime value-flow or mutation proof. */
+export declare class HandlerResolver {
+    private readonly checker;
+    private readonly selected;
+    private readonly written;
+    private readonly identities;
+    constructor(checker: ts.TypeChecker, sources: ts.SourceFile[], root: string, project: string);
+    private recordWrite;
+    identity(body: ts.ConciseBody): {
+        id: string;
+        file: string;
+        project: string;
+        line: number;
+    };
+    resolve(argument: ts.Expression | undefined): Resolution;
+    private resolveReference;
+}
+export {};

package/dist/handler-resolution.js

@@ -0,0 +1,99 @@
+import ts from "typescript";
+import path from "node:path";
+import { hash } from "./evidence.js";
+import { isFunction } from "./function-nodes.js";
+export function unwrapHandler(node) {
+    while (ts.isParenthesizedExpression(node) || ts.isAsExpression(node) || ts.isTypeAssertionExpression(node) ||
+        ts.isNonNullExpression(node) || ts.isSatisfiesExpression(node))
+        node = node.expression;
+    return node;
+}
+/** Bounded declaration lookup, not a runtime value-flow or mutation proof. */
+export class HandlerResolver {
+    checker;
+    selected = new Set();
+    written = new Set();
+    identities = new Map();
+    constructor(checker, sources, root, project) {
+        this.checker = checker;
+        for (const source of sources) {
+            this.selected.add(source);
+            const file = path.relative(root, source.fileName).replaceAll("\\", "/");
+            let functions = 0, catches = 0;
+            const visit = (node) => {
+                if (ts.isTypeNode(node) && !ts.isExpressionWithTypeArguments(node))
+                    return;
+                const body = isFunction(node) ? node.body : ts.isCatchClause(node) ? node.block : undefined;
+                if (body) {
+                    const key = ts.isCatchClause(node) ? `catch:${catches++}` : `function:${functions++}`;
+                    this.identities.set(body, { id: hash(`${project}|${file}|${key}`), file, project,
+                        line: source.getLineAndCharacterOfPosition(body.getStart(source)).line + 1 });
+                }
+                if (ts.isBinaryExpression(node) && node.operatorToken.kind >= ts.SyntaxKind.FirstAssignment &&
+                    node.operatorToken.kind <= ts.SyntaxKind.LastAssignment)
+                    this.recordWrite(node.left);
+                if ((ts.isPrefixUnaryExpression(node) || ts.isPostfixUnaryExpression(node)) &&
+                    [ts.SyntaxKind.PlusPlusToken, ts.SyntaxKind.MinusMinusToken].includes(node.operator))
+                    this.recordWrite(node.operand);
+                if ((ts.isForInStatement(node) || ts.isForOfStatement(node)) && !ts.isVariableDeclarationList(node.initializer))
+                    this.recordWrite(node.initializer);
+                ts.forEachChild(node, visit);
+            };
+            visit(source);
+        }
+    }
+    recordWrite(node) {
+        if (ts.isIdentifier(node)) {
+            const symbol = this.checker.getSymbolAtLocation(node);
+            if (symbol)
+                this.written.add(symbol);
+        }
+        else if (!ts.isPropertyAccessExpression(node) && !ts.isElementAccessExpression(node)) {
+            // Destructuring and parenthesized assignments are conservatively included.
+            ts.forEachChild(node, child => this.recordWrite(child));
+        }
+    }
+    identity(body) { return this.identities.get(body); }
+    resolve(argument) {
+        if (!argument)
+            return { reason: "missingArgument" };
+        const direct = unwrapHandler(argument);
+        if (isFunction(direct) && direct.body)
+            return { body: direct.body, resolution: "inline" };
+        return this.resolveReference(direct, new Set());
+    }
+    resolveReference(node, seen) {
+        node = unwrapHandler(node);
+        if (!ts.isIdentifier(node))
+            return { reason: "unsupportedExpression" };
+        let symbol = this.checker.getSymbolAtLocation(node);
+        if (!symbol)
+            return { reason: "unresolvedSymbol" };
+        if (this.written.has(symbol))
+            return { reason: "reassignedBinding" };
+        if (symbol.flags & ts.SymbolFlags.Alias)
+            symbol = this.checker.getAliasedSymbol(symbol);
+        if (this.written.has(symbol))
+            return { reason: "reassignedBinding" };
+        if (seen.has(symbol) || seen.size >= 32)
+            return { reason: "aliasCycleOrDepth" };
+        seen.add(symbol);
+        const declarations = symbol.declarations ?? [];
+        if (!declarations.length || declarations.some(declaration => !this.selected.has(declaration.getSourceFile())))
+            return { reason: "outsideSelectedSource" };
+        const implementations = declarations.filter(declaration => ts.isFunctionDeclaration(declaration) && declaration.body);
+        if (implementations.length === 1)
+            return { body: implementations[0].body, resolution: "reference" };
+        if (declarations.length !== 1 || !ts.isVariableDeclaration(declarations[0]))
+            return { reason: "unsupportedDeclaration" };
+        const declaration = declarations[0];
+        if (!ts.isVariableDeclarationList(declaration.parent) || !(declaration.parent.flags & ts.NodeFlags.Const))
+            return { reason: "mutableBinding" };
+        if (!declaration.initializer)
+            return { reason: "missingInitializer" };
+        const value = unwrapHandler(declaration.initializer);
+        if (isFunction(value) && value.body)
+            return { body: value.body, resolution: "reference" };
+        return this.resolveReference(value, seen);
+    }
+}

package/dist/metrics.d.ts

@@ -1,5 +1,6 @@
 import ts from "typescript";
 import { type Finding } from "./evidence.js";
+import { type FunctionMeasurement } from "./function-measurements.js";
 export interface Metric {
     project: string;
     file: string;
@@ -18,9 +19,11 @@ export interface Metric {
 export declare function maintainability(volume: number, complexity: number, lines: number): number;
 export declare function analyzeFile(source: ts.SourceFile, checker: ts.TypeChecker, project: string, root: string): {
     metrics: Metric[];
+    functions: FunctionMeasurement[];
     findings: {
         dimension: "codeQuality" | "performanceAsync";
         finding: Finding;
     }[];
     reactSupported: boolean;
+    asyncSupported: boolean;
 };

package/dist/metrics.js

@@ -1,10 +1,10 @@
 import path from "node:path";
 import ts from "typescript";
 import { hash } from "./evidence.js";
-function isFunction(node) {
-    return ts.isFunctionDeclaration(node) || ts.isFunctionExpression(node) || ts.isArrowFunction(node) ||
-        ts.isMethodDeclaration(node) || ts.isConstructorDeclaration(node) || ts.isGetAccessorDeclaration(node) || ts.isSetAccessorDeclaration(node);
-}
+import { isFunction } from "./function-nodes.js";
+import { inspectReactCall } from "./react-probe.js";
+import { inspectAsyncNode, isAsyncFunction, isPromiseConstruction } from "./async-probe.js";
+import { measureFunction } from "./function-measurements.js";
 function nameOf(node, source) {
     if (node.name)
         return node.name.getText(source);
@@ -28,19 +28,24 @@ export function maintainability(volume, complexity, lines) {
 export function analyzeFile(source, checker, project, root) {
     const file = path.relative(root, source.fileName).replaceAll("\\", "/");
     const metrics = [];
+    const functions = [];
     const findings = [];
     const importCount = new Set(source.statements.filter(ts.isImportDeclaration).map(node => node.moduleSpecifier.getText(source))).size;
     const identities = new Map();
-    function emit(category, dimension, node, member, message, observations, confidence = "high") {
+    let asyncSupported = false;
+    function emit(category, dimension, node, member, message, observations, confidence = "high", severity = "warning") {
         const ruleId = `javascript-typescript/${dimension}/${category}`;
         const identity = `${ruleId}|${file}|${project}|${member}`;
         const occurrence = identities.get(identity) ?? 0;
         identities.set(identity, occurrence + 1);
         findings.push({ dimension, finding: { category, ruleId, fingerprint: hash(`${identity}|${occurrence}`),
-                severity: "warning", confidence, file, line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
+                severity, confidence, file, line: source.getLineAndCharacterOfPosition(node.getStart(source)).line + 1,
                 project, member, message, observations } });
     }
     function visit(node, parentName = "") {
+        asyncSupported ||= isAsyncFunction(node) || ts.isAwaitExpression(node) || isPromiseConstruction(node, checker);
+        for (const finding of inspectAsyncNode(node, checker))
+            emit(finding.category, "performanceAsync", node, parentName || "<module>", finding.message, { ...finding.observations, sourceSpanStart: node.getStart(source), sourceSpanLength: node.getWidth(source) }, finding.confidence, finding.severity);
         if (isFunction(node) && node.body) {
             const name = nameOf(node, source);
             const member = parentName ? `${parentName}/${name}` : name;
@@ -57,41 +62,9 @@ export function analyzeFile(source, checker, project, root) {
                 if (ts.isJsxElement(child) || ts.isJsxSelfClosingElement(child) || ts.isJsxFragment(child))
                     hasJsx = true;
                 if (ts.isCallExpression(child)) {
-                    const symbol = checker.getSymbolAtLocation(ts.isPropertyAccessExpression(child.expression) ? child.expression.name : child.expression);
-                    const declarations = symbol?.declarations ?? [];
-                    const reactHook = declarations.some(declaration => {
-                        let cursor = declaration;
-                        while (cursor && !ts.isImportDeclaration(cursor))
-                            cursor = cursor.parent;
-                        return cursor && ts.isStringLiteral(cursor.moduleSpecifier) && cursor.moduleSpecifier.text === "react";
-                    });
-                    const hookName = declarations.find(ts.isImportSpecifier);
-                    const calledName = hookName ? (hookName.propertyName ?? hookName.name).text : ts.isPropertyAccessExpression(child.expression) ? child.expression.name.text : "";
-                    const namespaceSymbol = ts.isPropertyAccessExpression(child.expression) ? checker.getSymbolAtLocation(child.expression.expression) : undefined;
-                    const reactNamespace = namespaceSymbol?.declarations?.some(declaration => {
-                        let cursor = declaration;
-                        while (cursor && !ts.isImportDeclaration(cursor))
-                            cursor = cursor.parent;
-                        return cursor && ts.isStringLiteral(cursor.moduleSpecifier) && cursor.moduleSpecifier.text === "react";
-                    });
-                    if ((reactHook || reactNamespace) && /^use[A-Z]/.test(calledName)) {
-                        let ancestor = child.parent;
-                        while (ancestor && ancestor !== node.body) {
-                            if (ts.isIfStatement(ancestor) || ts.isConditionalExpression(ancestor) || ts.isForStatement(ancestor) || ts.isForOfStatement(ancestor) || ts.isForInStatement(ancestor) || ts.isWhileStatement(ancestor) || ts.isDoStatement(ancestor) ||
-                                ts.isBinaryExpression(ancestor) && [ts.SyntaxKind.AmpersandAmpersandToken, ts.SyntaxKind.BarBarToken, ts.SyntaxKind.QuestionQuestionToken].includes(ancestor.operatorToken.kind)) {
-                                emit("conditionalHook", "performanceAsync", child, member, `${calledName} is called within a conditional or loop.`, { hook: calledName });
-                                break;
-                            }
-                            ancestor = ancestor.parent;
-                        }
-                        if (["useEffect", "useLayoutEffect"].includes(calledName)) {
-                            const callback = child.arguments[0];
-                            if (callback && isFunction(callback) && callback.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AsyncKeyword))
-                                emit("asyncEffectCallback", "performanceAsync", child, member, "An effect callback is async and returns a Promise instead of cleanup or undefined.", { hook: calledName });
-                            if (child.arguments.length < 2)
-                                emit("effectWithoutDependencies", "performanceAsync", child, member, "Effect runs after every render; verify that this is intentional.", { hook: calledName }, "low");
-                        }
-                    }
+                    for (const finding of inspectReactCall(child, node.body, checker))
+                        emit(finding.category, "performanceAsync", child, member, finding.message, { ...finding.observations, sourceSpanStart: child.getStart(source), classification: finding.confidence === "low" ? "reviewLead" : "actionableSignal",
+                            scoreDisposition: finding.confidence === "low" ? "excludedReviewLead" : "scored" }, finding.confidence, finding.confidence === "low" ? "info" : "warning");
                 }
             });
             if (!ts.isBlock(node.body))
@@ -138,16 +111,21 @@ export function analyzeFile(source, checker, project, root) {
                 complexity, sourceLines: Math.max(1, sourceLineSet.size), executableLines, halsteadVolume: volume,
                 maintainabilityIndex: maintainability(volume, complexity, Math.max(1, sourceLineSet.size)), coupling: importCount, inheritance };
             metrics.push(metric);
-            if (complexity > 10)
-                emit("highFunctionComplexity", "codeQuality", node, member, `${member} has cyclomatic complexity ${complexity} (threshold: 10).`, { measured: complexity, threshold: 10, metric: "cyclomaticComplexity", kind });
+            const measurement = measureFunction(node, source, file, project, member);
+            functions.push(measurement);
+            if (measurement.ownComplexity > 10)
+                emit("highFunctionComplexity", "codeQuality", node, member, `${member} has cyclomatic complexity ${measurement.ownComplexity} (threshold: 10).`, { measured: measurement.ownComplexity, threshold: 10, metric: "ownedCyclomaticComplexity", kind, functionId: measurement.id,
+                    complexityBreakdown: measurement.complexityBreakdown });
             ts.forEachChild(node, child => visit(child, member));
             return;
         }
-        if (!ts.isTypeNode(node))
+        // An instantiation expression (factory<T>) is classified as a TypeNode by
+        // TypeScript, but its expression can contain real functions and operations.
+        if (!ts.isTypeNode(node) || ts.isExpressionWithTypeArguments(node))
             ts.forEachChild(node, child => visit(child, parentName));
     }
     visit(source);
     const reactSupported = source.statements.some(statement => ts.isImportDeclaration(statement) && !statement.importClause?.isTypeOnly &&
         ts.isStringLiteral(statement.moduleSpecifier) && statement.moduleSpecifier.text === "react");
-    return { metrics, findings, reactSupported };
+    return { metrics, functions, findings, reactSupported, asyncSupported };
 }

package/dist/module-forwarding.d.ts

@@ -0,0 +1,4 @@
+import ts from "typescript";
+import type { ModuleReference } from "./module-references.js";
+export type DependencyRole = "implementation" | "reExport";
+export declare function dependencyRoles(source: ts.SourceFile, checker: ts.TypeChecker, references: ModuleReference[]): Map<ts.Node, DependencyRole[]>;

package/dist/module-forwarding.js

@@ -0,0 +1,153 @@
+import ts from "typescript";
+function unparenthesized(node) {
+    while (ts.isParenthesizedExpression(node))
+        node = node.expression;
+    return node;
+}
+function staticBase(node) {
+    node = unparenthesized(node);
+    while ((ts.isPropertyAccessExpression(node) && !node.questionDotToken) ||
+        (ts.isElementAccessExpression(node) && !node.questionDotToken && ts.isStringLiteralLike(node.argumentExpression)))
+        node = unparenthesized(node.expression);
+    return node;
+}
+function member(node) {
+    node = unparenthesized(node);
+    if (ts.isPropertyAccessExpression(node) && !node.questionDotToken)
+        return { owner: node.expression, name: node.name.text };
+    if (ts.isElementAccessExpression(node) && !node.questionDotToken && ts.isStringLiteralLike(node.argumentExpression))
+        return { owner: node.expression, name: node.argumentExpression.text };
+    return undefined;
+}
+function nodeName(node, name, checker) {
+    node = unparenthesized(node);
+    if (!ts.isIdentifier(node) || node.text !== name)
+        return false;
+    // In JS, getSymbolAtLocation can return the synthetic exports symbol even
+    // for a shadowed parameter. Ask for the lexical value/alias symbol instead.
+    const declarations = checker.getSymbolsInScope(node, ts.SymbolFlags.Value | ts.SymbolFlags.Alias)
+        .find(symbol => symbol.name === name)?.declarations;
+    return !declarations?.length || declarations.every(declaration => (ts.isIdentifier(declaration) && ts.isPropertyAccessExpression(declaration.parent) && declaration.parent.expression === declaration) ||
+        (declaration.getSourceFile().isDeclarationFile && declaration.getSourceFile().fileName.replaceAll("\\", "/").includes("/node_modules/@types/node/")));
+}
+function moduleExports(node, checker) {
+    const property = member(node);
+    return !!property && property.name === "exports" && nodeName(property.owner, "module", checker);
+}
+function exportTarget(node, checker) {
+    if (moduleExports(node, checker))
+        return true;
+    const property = member(node);
+    return !!property && (nodeName(property.owner, "exports", checker) || moduleExports(property.owner, checker));
+}
+function bindingNames(reference) {
+    const node = reference.node;
+    if (ts.isImportDeclaration(node)) {
+        const clause = node.importClause, bindings = clause?.namedBindings;
+        return [...(clause?.name ? [clause.name] : []), ...(bindings ? ts.isNamespaceImport(bindings) ? [bindings.name] :
+                bindings.elements.filter(element => !element.isTypeOnly).map(element => element.name) : [])];
+    }
+    if (ts.isImportEqualsDeclaration(node))
+        return [node.name];
+    if (reference.form === "require") {
+        let expression = node;
+        while (ts.isParenthesizedExpression(expression.parent))
+            expression = expression.parent;
+        const parent = expression.parent;
+        if (ts.isVariableDeclaration(parent) && parent.initializer === expression && ts.isIdentifier(parent.name))
+            return [parent.name];
+    }
+    return [];
+}
+function assignmentRoot(node) {
+    const parent = node.parent;
+    if (ts.isParenthesizedExpression(parent) || ts.isArrayLiteralExpression(parent) || ts.isObjectLiteralExpression(parent) ||
+        ts.isShorthandPropertyAssignment(parent) || ts.isSpreadElement(parent) || ts.isSpreadAssignment(parent) ||
+        (ts.isPropertyAssignment(parent) && parent.initializer === node))
+        return assignmentRoot(parent);
+    return node;
+}
+// One source walk tracks explicit forwarding and other uses of the same local
+// binding. This is symbol-based syntax evidence, not alias/dataflow analysis.
+export function dependencyRoles(source, checker, references) {
+    const bindings = new Map();
+    const declared = new Set(), forwardedNodes = new Set();
+    const perReference = new Map();
+    const directCalls = new Set(references.filter(reference => reference.form === "require").map(reference => reference.node));
+    for (const reference of references) {
+        const uses = [];
+        if (reference.usage !== "typeOnly")
+            for (const name of bindingNames(reference)) {
+                const symbol = checker.getSymbolAtLocation(name);
+                if (!symbol)
+                    continue;
+                const use = { forwarded: false, local: false, mutated: false };
+                bindings.set(symbol, use);
+                uses.push(use);
+                declared.add(name);
+            }
+        perReference.set(reference, uses);
+    }
+    function forward(expression, symbol) {
+        const base = staticBase(expression);
+        const use = bindings.get(symbol ?? (ts.isIdentifier(base) ? checker.getSymbolAtLocation(base) : undefined));
+        if (use) {
+            use.forwarded = true;
+            forwardedNodes.add(base);
+        }
+        else if (directCalls.has(base))
+            forwardedNodes.add(base);
+    }
+    function local(node, symbol = checker.getSymbolAtLocation(node)) {
+        const use = symbol && bindings.get(symbol);
+        if (!use || declared.has(node) || forwardedNodes.has(node))
+            return;
+        use.local = true;
+        const expression = assignmentRoot(node);
+        const parent = expression.parent;
+        if ((ts.isBinaryExpression(parent) && parent.left === expression &&
+            parent.operatorToken.kind >= ts.SyntaxKind.FirstAssignment && parent.operatorToken.kind <= ts.SyntaxKind.LastAssignment) ||
+            (ts.isVariableDeclaration(parent) && parent.name === expression && !!parent.initializer) ||
+            (ts.isBindingElement(parent) && parent.name === expression) ||
+            ((ts.isForOfStatement(parent) || ts.isForInStatement(parent)) && parent.initializer === expression) ||
+            ((ts.isPrefixUnaryExpression(parent) || ts.isPostfixUnaryExpression(parent)) &&
+                (parent.operator === ts.SyntaxKind.PlusPlusToken || parent.operator === ts.SyntaxKind.MinusMinusToken)))
+            use.mutated = true;
+    }
+    function visit(node) {
+        if (ts.isImportDeclaration(node) || ts.isImportEqualsDeclaration(node))
+            return;
+        if (ts.isExportDeclaration(node)) {
+            if (!node.moduleSpecifier && !node.isTypeOnly && node.exportClause && ts.isNamedExports(node.exportClause))
+                for (const element of node.exportClause.elements)
+                    if (!element.isTypeOnly)
+                        forward(element.propertyName ?? element.name, checker.getExportSpecifierLocalTargetSymbol(element));
+            return;
+        }
+        if (ts.isExportAssignment(node))
+            forward(node.expression);
+        if (ts.isBinaryExpression(node) && node.operatorToken.kind === ts.SyntaxKind.EqualsToken && exportTarget(node.left, checker)) {
+            forward(node.right);
+            visit(node.right);
+            return;
+        }
+        if (ts.isShorthandPropertyAssignment(node))
+            local(node.name, checker.getShorthandAssignmentValueSymbol(node));
+        else if (ts.isIdentifier(node))
+            local(node);
+        ts.forEachChild(node, visit);
+    }
+    visit(source);
+    return new Map(references.map(reference => {
+        const uses = perReference.get(reference);
+        const roles = [];
+        if (reference.usage !== "typeOnly") {
+            const reExport = reference.form === "reExport" || forwardedNodes.has(reference.node) || uses.some(use => use.forwarded && !use.mutated);
+            if (!reExport || uses.some(use => use.local || !use.forwarded || use.mutated))
+                roles.push("implementation");
+            if (reExport)
+                roles.push("reExport");
+        }
+        return [reference.node, roles];
+    }));
+}

package/dist/module-graph.d.ts

@@ -0,0 +1,34 @@
+import ts from "typescript";
+import type { PackageInput } from "./discovery.js";
+import { type Dimension } from "./evidence.js";
+import { type ModuleReference } from "./module-references.js";
+import { type DependencyRole } from "./module-forwarding.js";
+type Resolution = "internal" | "external" | "builtin" | "outOfScope" | "unavailableSource" | "unresolved" | "dynamic";
+export interface DependencyObservation {
+    from: string;
+    project: string;
+    line: number;
+    sourceSpanStart: number;
+    form: ModuleReference["form"];
+    usage: ModuleReference["usage"];
+    specifier: string | null;
+    roles: DependencyRole[];
+    resolution: Resolution;
+    via: string;
+    target?: string;
+    targetFile?: string;
+    declarationTarget?: boolean;
+}
+export declare class ModuleGraphCollector {
+    private readonly root;
+    private readonly packages;
+    private readonly nodes;
+    private readonly dependencies;
+    private readonly scanned;
+    constructor(root: string, packages: PackageInput[]);
+    private relative;
+    forPackage(pkg: PackageInput, program: ts.Program): (source: ts.SourceFile) => void;
+    private resolveObservation;
+    finish(incompleteSource: boolean): Dimension;
+}
+export {};

package/dist/module-graph.js

@@ -0,0 +1,122 @@
+import path from "node:path";
+import { isBuiltin } from "node:module";
+import ts from "typescript";
+import { hash } from "./evidence.js";
+import { moduleReferences } from "./module-references.js";
+import { canonicalFile, moduleResolver } from "./module-resolution.js";
+import { moduleTopology } from "./module-topology.js";
+import { dependencyRoles } from "./module-forwarding.js";
+function reExportOnly(source) {
+    return source.statements.some(statement => ts.isExportDeclaration(statement) && !!statement.moduleSpecifier) &&
+        source.statements.every(statement => ts.isImportDeclaration(statement) || (ts.isExportDeclaration(statement) && !!statement.moduleSpecifier) ||
+            ts.isInterfaceDeclaration(statement) || ts.isTypeAliasDeclaration(statement) || ts.isEmptyStatement(statement) ||
+            (ts.isExpressionStatement(statement) && ts.isStringLiteral(statement.expression)));
+}
+export class ModuleGraphCollector {
+    root;
+    packages;
+    nodes = new Map();
+    dependencies = [];
+    scanned = new Set();
+    constructor(root, packages) {
+        this.root = root;
+        this.packages = packages;
+        for (const pkg of packages)
+            for (const file of pkg.files) {
+                const key = canonicalFile(file);
+                if (!this.nodes.has(key))
+                    this.nodes.set(key, { id: this.relative(file), project: pkg.name, analyzed: false, reExportOnly: false });
+            }
+    }
+    relative(file) { return path.relative(this.root, file).replaceAll("\\", "/"); }
+    forPackage(pkg, program) {
+        const resolve = moduleResolver(pkg, this.packages, program);
+        return (source) => {
+            const key = canonicalFile(source.fileName), node = this.nodes.get(key);
+            if (this.scanned.has(key))
+                return;
+            this.scanned.add(key);
+            node.analyzed = true;
+            node.reExportOnly = reExportOnly(source);
+            const references = moduleReferences(source, program.getTypeChecker());
+            const roles = dependencyRoles(source, program.getTypeChecker(), references);
+            for (const reference of references) {
+                const start = reference.node.getStart(source);
+                const observation = { from: node.id, project: node.project,
+                    line: source.getLineAndCharacterOfPosition(start).line + 1, sourceSpanStart: start,
+                    form: reference.form, usage: reference.usage, roles: roles.get(reference.node), specifier: reference.literal?.text ?? null,
+                    resolution: "dynamic", via: "nonLiteralSpecifier" };
+                if (reference.literal)
+                    this.resolveObservation(observation, source, reference.literal, resolve);
+                this.dependencies.push(observation);
+            }
+        };
+    }
+    resolveObservation(observation, source, literal, resolve) {
+        if (isBuiltin(literal.text)) {
+            observation.resolution = "builtin";
+            observation.via = "nodeBuiltin";
+            observation.target = literal.text.startsWith("node:") ? literal.text : `node:${literal.text}`;
+            return;
+        }
+        const { resolved, via } = resolve(source, literal);
+        observation.via = via;
+        if (!resolved) {
+            observation.resolution = "unresolved";
+            return;
+        }
+        const file = canonicalFile(resolved.resolvedFileName);
+        const target = this.nodes.get(file);
+        observation.declarationTarget = /\.d\.[cm]?ts$/i.test(file);
+        observation.targetFile = target?.id ?? this.relative(ts.sys.realpath?.(resolved.resolvedFileName) ?? resolved.resolvedFileName);
+        if (target) {
+            observation.resolution = "internal";
+            observation.target = target.id;
+        }
+        else
+            observation.resolution = file.includes("/node_modules/") ? "external" : "outOfScope";
+    }
+    finish(incompleteSource) {
+        const nodes = [...this.nodes.values()].sort((a, b) => a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+        const byId = new Map(nodes.map(node => [node.id, node]));
+        const dependencies = this.dependencies.map(item => item.resolution === "internal" && !byId.get(item.target).analyzed ?
+            { ...item, resolution: "unavailableSource" } : item)
+            .sort((a, b) => a.from < b.from ? -1 : a.from > b.from ? 1 : a.sourceSpanStart - b.sourceSpanStart);
+        const topology = moduleTopology(nodes.map(node => node.id), dependencies);
+        const degrees = new Map(topology.modules.map(node => [node.id, node]));
+        const counts = Object.fromEntries(['internal', 'external', 'builtin', 'outOfScope', 'unavailableSource', 'unresolved', 'dynamic']
+            .map(resolution => [resolution, dependencies.filter(item => item.resolution === resolution).length]));
+        const literalOccurrences = dependencies.length - counts.dynamic;
+        const gaps = incompleteSource || this.scanned.size < nodes.length || counts.unresolved + counts.dynamic + counts.outOfScope + counts.unavailableSource > 0;
+        const cycles = topology.cycles.map(modules => ({ id: hash(modules.join("\n")), modules }));
+        const findings = cycles.map(cycle => ({
+            ruleId: "javascript-typescript/architecture/moduleDependencyCycle", category: "moduleDependencyCycle",
+            fingerprint: hash(`javascript-typescript/architecture/moduleDependencyCycle|${cycle.modules.join("|")}`),
+            severity: "info", confidence: "high", file: cycle.modules[0], project: byId.get(cycle.modules[0]).project,
+            message: `${cycle.modules.length} module(s) form a cyclic value-dependency group; review loading behavior and intent.`,
+            observations: { modules: cycle.modules, classification: "reviewLead", scoreDisposition: "excludedUncalibrated",
+                countingUnit: "stronglyConnectedComponent", executionOrderEstablished: false }
+        }));
+        return { status: incompleteSource ? "failed" : "skipped", basis: incompleteSource ?
+                "Incomplete source analysis; module graph is diagnostic only." : "Module dependency evidence collected; architecture scoring is not calibrated.",
+            findings, scope: { id: "javascript-typescript/architecture/module-graph-v1", coverage: "partial",
+                includes: ["source-module-references", "explicit-type-only-dependencies", "internal-value-cycles", "internal-value-fan-in-out"],
+                excludes: ["architecture-score", "runtime-loading-order", "comprehensive-dynamic-resolution", "cohesion", "solid-compliance"] },
+            dependencyGraph: { version: 1, graphKind: "source-value-dependencies", coverage: {
+                    status: gaps ? "gaps" : "observedDependenciesResolved", selectedModules: nodes.length, analyzedModules: this.scanned.size,
+                    dependencyOccurrences: dependencies.length, literalOccurrences, resolvedLiteralOccurrences: literalOccurrences - counts.unresolved,
+                    literalResolutionPercent: literalOccurrences ? 100 * (literalOccurrences - counts.unresolved) / literalOccurrences : null,
+                    occurrencesByResolution: counts, explicitTypeOnlyOccurrences: dependencies.filter(item => item.usage === "typeOnly").length
+                },
+                resolutionEnvironment: { typescriptVersion: ts.version, nodeVersion: process.versions.node },
+                limitations: ["Value/mixed references are source syntax, not proof of emitted runtime imports.",
+                    "Graph scope contains selected source modules only; external and excluded targets are not traversed.",
+                    "Literal calls contribute dependency edges without establishing when or whether they execute.",
+                    "Require aliases, custom loaders, evaluated strings and bundler-specific resolution are not inferred.",
+                    "TypeScript resolution may select declarations; declarationTarget identifies these observations.",
+                    "Ranked fan-in/out lists are observations, not calibrated defects or score deductions."],
+                nodes: nodes.map(node => ({ ...node, ...degrees.get(node.id) })), dependencies, cycles,
+                dependencyViews: topology.dependencyViews,
+                highestFanOut: topology.highestFanOut, highestFanIn: topology.highestFanIn } };
+    }
+}

package/dist/module-references.d.ts

@@ -0,0 +1,8 @@
+import ts from "typescript";
+export interface ModuleReference {
+    node: ts.Node;
+    literal?: ts.StringLiteralLike;
+    form: "import" | "reExport" | "importEquals" | "importType" | "require" | "dynamicImport";
+    usage: "value" | "typeOnly" | "mixed";
+}
+export declare function moduleReferences(source: ts.SourceFile, checker: ts.TypeChecker): ModuleReference[];

package/dist/module-references.js

@@ -0,0 +1,51 @@
+import ts from "typescript";
+function bindingUsage(typeOnly, elements, hasDefault = false) {
+    if (typeOnly)
+        return "typeOnly";
+    const typed = elements?.filter(element => element.isTypeOnly).length ?? 0;
+    if (typed && typed === elements.length && !hasDefault)
+        return "typeOnly";
+    return typed ? "mixed" : "value";
+}
+function ambientNodeName(node, checker) {
+    const declarations = checker.getSymbolAtLocation(node)?.declarations;
+    return !declarations?.length || declarations.every(declaration => declaration.getSourceFile().isDeclarationFile &&
+        declaration.getSourceFile().fileName.replaceAll("\\", "/").includes("/node_modules/@types/node/"));
+}
+function isRequire(node, checker) {
+    if (ts.isIdentifier(node))
+        return node.text === "require" && ambientNodeName(node, checker);
+    return ts.isPropertyAccessExpression(node) && node.name.text === "require" && ts.isIdentifier(node.expression) &&
+        node.expression.text === "module" && ambientNodeName(node.expression, checker);
+}
+export function moduleReferences(source, checker) {
+    const references = [];
+    function add(node, expression, form, usage) {
+        references.push({ node, literal: expression && ts.isStringLiteralLike(expression) ? expression : undefined, form, usage });
+    }
+    function visit(node) {
+        if (ts.isImportDeclaration(node)) {
+            const clause = node.importClause;
+            const bindings = clause?.namedBindings;
+            add(node, node.moduleSpecifier, "import", bindingUsage(clause?.isTypeOnly ?? false, bindings && ts.isNamedImports(bindings) ? bindings.elements : undefined, !!clause?.name));
+        }
+        else if (ts.isExportDeclaration(node) && node.moduleSpecifier) {
+            add(node, node.moduleSpecifier, "reExport", bindingUsage(node.isTypeOnly, node.exportClause && ts.isNamedExports(node.exportClause) ? node.exportClause.elements : undefined));
+        }
+        else if (ts.isImportEqualsDeclaration(node) && ts.isExternalModuleReference(node.moduleReference)) {
+            add(node, node.moduleReference.expression, "importEquals", node.isTypeOnly ? "typeOnly" : "value");
+        }
+        else if (ts.isImportTypeNode(node) && ts.isLiteralTypeNode(node.argument)) {
+            add(node, node.argument.literal, "importType", "typeOnly");
+        }
+        else if (ts.isCallExpression(node)) {
+            if (node.expression.kind === ts.SyntaxKind.ImportKeyword)
+                add(node, node.arguments[0], "dynamicImport", "value");
+            else if (isRequire(node.expression, checker))
+                add(node, node.arguments[0], "require", "value");
+        }
+        ts.forEachChild(node, visit);
+    }
+    visit(source);
+    return references;
+}

package/dist/module-resolution.d.ts

@@ -0,0 +1,10 @@
+import ts from "typescript";
+import type { PackageInput } from "./discovery.js";
+export declare const canonicalFile: (file: string) => string;
+export declare function moduleResolver(pkg: PackageInput, packages: PackageInput[], program: ts.Program): (source: ts.SourceFile, literal: ts.StringLiteralLike) => {
+    resolved: ts.ResolvedModuleFull;
+    via: "typescript";
+} | {
+    resolved: ts.ResolvedModuleFull | undefined;
+    via: "unresolved" | "workspaceManifest";
+};