codemetrics-ai 0.3.0 → 0.5.0

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";
+};

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 {};