@component-compass/reference-graph 0.0.0-pr-114-393daf6-20260518195554

package/dist/builder.d.ts

@@ -0,0 +1,40 @@
+import type { ResolveImport } from "@component-compass/plugin-core";
+import type { BindingDecl, ExportRecord, Graph, ImportRecord, Reference, ScopeId } from "./index.js";
+export interface FileBuilder {
+    pushScope(): ScopeId;
+    popScope(): void;
+    currentScope(): ScopeId;
+    addImport(record: Omit<ImportRecord, "scope"> & {
+        scope?: ScopeId;
+    }): void;
+    addDeclaration(decl: Omit<BindingDecl, "scope"> & {
+        scope?: ScopeId;
+    }): void;
+    addExport(record: ExportRecord): void;
+    addJsxUsage(usage: {
+        ref: Omit<Reference, "scope"> & {
+            scope?: ScopeId;
+        };
+        loc: {
+            line: number;
+            column: number;
+        };
+        props: unknown[];
+    }): void;
+    /** Wire the owner of the last-emitted JsxUsage. */
+    setOwner(ownerSymbolRef: Reference | null): void;
+}
+export interface GraphBuilder {
+    beginFile(filePath: string): FileBuilder;
+    build(): Graph;
+}
+export type CreateGraphBuilderOptions = {
+    moduleResolver: ResolveImport;
+    /**
+     * Optional absolute repo root. When provided, the built Graph gains a
+     * `resolveToGraphKey` helper that normalises absolute paths returned by
+     * `moduleResolver` into repo-relative POSIX keys matching `Graph.files`.
+     */
+    repoRoot?: string;
+};
+export declare function createGraphBuilder(opts: CreateGraphBuilderOptions): GraphBuilder;

package/dist/builder.js

@@ -0,0 +1,80 @@
+// API surface validated against two emitters (paper-sketch + implementation):
+//   - parser-react: full implementation (Phase 6)
+//   - parser-vue: paper sketch (Task 0.2, see plan doc)
+// Members not justified by either should not be added speculatively.
+import { isAbsolute, relative } from "node:path";
+import { MODULE_SCOPE } from "./index.js";
+export function createGraphBuilder(opts) {
+    const files = new Map();
+    return {
+        beginFile(filePath) {
+            const scopes = new Map([[MODULE_SCOPE, { parent: null }]]);
+            const declarations = new Map();
+            const imports = [];
+            const exports = [];
+            const jsxUsages = [];
+            const ownership = [];
+            const scopeStack = [MODULE_SCOPE];
+            let nextScopeId = 1;
+            const fg = { filePath, scopes, declarations, imports, exports, jsxUsages, ownership };
+            files.set(filePath, fg);
+            return {
+                pushScope() {
+                    const id = nextScopeId++;
+                    scopes.set(id, { parent: scopeStack[scopeStack.length - 1] ?? null });
+                    scopeStack.push(id);
+                    return id;
+                },
+                popScope() {
+                    if (scopeStack.length <= 1)
+                        throw new Error("popScope at module-scope root");
+                    scopeStack.pop();
+                },
+                currentScope() {
+                    return scopeStack[scopeStack.length - 1] ?? MODULE_SCOPE;
+                },
+                addImport(record) {
+                    const scope = record.scope ?? scopeStack[scopeStack.length - 1] ?? MODULE_SCOPE;
+                    imports.push({ ...record, scope });
+                },
+                addDeclaration(decl) {
+                    const scope = decl.scope ?? scopeStack[scopeStack.length - 1] ?? MODULE_SCOPE;
+                    declarations.set(`${scope}::${decl.symbol}`, { ...decl, scope });
+                },
+                addExport(record) {
+                    exports.push(record);
+                },
+                addJsxUsage(usage) {
+                    const scope = usage.ref.scope ?? scopeStack[scopeStack.length - 1] ?? MODULE_SCOPE;
+                    jsxUsages.push({
+                        ref: { ...usage.ref, scope },
+                        loc: usage.loc,
+                        props: usage.props,
+                    });
+                    ownership.push({ usageIdx: jsxUsages.length - 1, ownerSymbolRef: null });
+                },
+                setOwner(ownerSymbolRef) {
+                    if (ownership.length === 0)
+                        return;
+                    const last = ownership[ownership.length - 1];
+                    if (last)
+                        last.ownerSymbolRef = ownerSymbolRef;
+                },
+            };
+        },
+        build() {
+            if (opts.repoRoot) {
+                const repoRoot = opts.repoRoot;
+                const resolveToGraphKey = (absPath) => {
+                    if (!isAbsolute(absPath))
+                        return null;
+                    const rel = relative(repoRoot, absPath).replace(/\\/g, "/");
+                    return files.has(rel) ? rel : null;
+                };
+                return { files, moduleResolver: opts.moduleResolver, resolveToGraphKey };
+            }
+            return { files, moduleResolver: opts.moduleResolver };
+        },
+    };
+}
+//# sourceMappingURL=builder.js.map

package/dist/builder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"builder.js","sourceRoot":"","sources":["../src/builder.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,kDAAkD;AAClD,wDAAwD;AACxD,qEAAqE;AAErE,OAAO,EAAE,UAAU,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAYjD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAiC1C,MAAM,UAAU,kBAAkB,CAAC,IAA+B;IAChE,MAAM,KAAK,GAAG,IAAI,GAAG,EAAqB,CAAC;IAE3C,OAAO;QACL,SAAS,CAAC,QAAgB;YACxB,MAAM,MAAM,GAAG,IAAI,GAAG,CAAsC,CAAC,CAAC,YAAY,EAAE,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC;YAChG,MAAM,YAAY,GAAG,IAAI,GAAG,EAAuB,CAAC;YACpD,MAAM,OAAO,GAAmB,EAAE,CAAC;YACnC,MAAM,OAAO,GAAmB,EAAE,CAAC;YACnC,MAAM,SAAS,GAAe,EAAE,CAAC;YACjC,MAAM,SAAS,GAAkE,EAAE,CAAC;YAEpF,MAAM,UAAU,GAAc,CAAC,YAAY,CAAC,CAAC;YAC7C,IAAI,WAAW,GAAY,CAAC,CAAC;YAE7B,MAAM,EAAE,GAAc,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,SAAS,EAAE,CAAC;YACjG,KAAK,CAAC,GAAG,CAAC,QAAQ,EAAE,EAAE,CAAC,CAAC;YAExB,OAAO;gBACL,SAAS;oBACP,MAAM,EAAE,GAAG,WAAW,EAAE,CAAC;oBACzB,MAAM,CAAC,GAAG,CAAC,EAAE,EAAE,EAAE,MAAM,EAAE,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;oBACtE,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;oBACpB,OAAO,EAAE,CAAC;gBACZ,CAAC;gBACD,QAAQ;oBACN,IAAI,UAAU,CAAC,MAAM,IAAI,CAAC;wBAAE,MAAM,IAAI,KAAK,CAAC,+BAA+B,CAAC,CAAC;oBAC7E,UAAU,CAAC,GAAG,EAAE,CAAC;gBACnB,CAAC;gBACD,YAAY;oBACV,OAAO,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,YAAY,CAAC;gBAC3D,CAAC;gBACD,SAAS,CAAC,MAAM;oBACd,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,IAAI,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,YAAY,CAAC;oBAChF,OAAO,CAAC,IAAI,CAAC,EAAE,GAAG,MAAM,EAAE,KAAK,EAAE,CAAC,CAAC;gBACrC,CAAC;gBACD,cAAc,CAAC,IAAI;oBACjB,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,YAAY,CAAC;oBAC9E,YAAY,CAAC,GAAG,CAAC,GAAG,KAAK,KAAK,IAAI,CAAC,MAAM,EAAE,EAAE,EAAE,GAAG,IAAI,EAAE,KAAK,EAAE,CAAC,CAAC;gBACnE,CAAC;gBACD,SAAS,CAAC,MAAM;oBACd,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBACvB,CAAC;gBACD,WAAW,CAAC,KAAK;oBACf,MAAM,KAAK,GAAG,KAAK,CAAC,GAAG,CAAC,KAAK,IAAI,UAAU,CAAC,UAAU,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,YAAY,CAAC;oBACnF,SAAS,CAAC,IAAI,CAAC;wBACb,GAAG,EAAE,EAAE,GAAG,KAAK,CAAC,GAAG,EAAE,KAAK,EAAE;wBAC5B,GAAG,EAAE,KAAK,CAAC,GAAG;wBACd,KAAK,EAAE,KAAK,CAAC,KAAK;qBACnB,CAAC,CAAC;oBACH,SAAS,CAAC,IAAI,CAAC,EAAE,QAAQ,EAAE,SAAS,CAAC,MAAM,GAAG,CAAC,EAAE,cAAc,EAAE,IAAI,EAAE,CAAC,CAAC;gBAC3E,CAAC;gBACD,QAAQ,CAAC,cAAc;oBACrB,IAAI,SAAS,CAAC,MAAM,KAAK,CAAC;wBAAE,OAAO;oBACnC,MAAM,IAAI,GAAG,SAAS,CAAC,SAAS,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;oBAC7C,IAAI,IAAI;wBAAE,IAAI,CAAC,cAAc,GAAG,cAAc,CAAC;gBACjD,CAAC;aACF,CAAC;QACJ,CAAC;QACD,KAAK;YACH,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClB,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,CAAC;gBAC/B,MAAM,iBAAiB,GAAG,CAAC,OAAe,EAAiB,EAAE;oBAC3D,IAAI,CAAC,UAAU,CAAC,OAAO,CAAC;wBAAE,OAAO,IAAI,CAAC;oBACtC,MAAM,GAAG,GAAG,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC;oBAC5D,OAAO,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;gBACrC,CAAC,CAAC;gBACF,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,iBAAiB,EAAE,CAAC;YAC3E,CAAC;YACD,OAAO,EAAE,KAAK,EAAE,cAAc,EAAE,IAAI,CAAC,cAAc,EAAE,CAAC;QACxD,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/engine/argument-map.d.ts

@@ -0,0 +1,14 @@
+import type { InferredType, Reference } from "../index.js";
+/**
+ * Argument map: substitution table for ParameterOf nodes.
+ *
+ * When `resolveType` walks `ReturnTypeOf(callee, args)`, it binds `args` to
+ * the callee function's parameters. Any `ParameterOf(fn, i)` encountered
+ * during resolution of the function's return type substitutes via this map.
+ */
+export interface ArgumentMap {
+    bind(fn: Reference, args: InferredType[]): void;
+    unbind(fn: Reference): void;
+    lookup(fn: Reference, index: number): InferredType | undefined;
+}
+export declare function createArgumentMap(): ArgumentMap;

package/dist/engine/argument-map.js

@@ -0,0 +1,30 @@
+function refKey(ref) {
+    return `${ref.symbol}::${ref.scope}`;
+}
+export function createArgumentMap() {
+    const stack = [];
+    return {
+        bind(fn, args) {
+            stack.push({ key: refKey(fn), args });
+        },
+        unbind(fn) {
+            const key = refKey(fn);
+            for (let i = stack.length - 1; i >= 0; i--) {
+                if (stack[i]?.key === key) {
+                    stack.splice(i, 1);
+                    return;
+                }
+            }
+        },
+        lookup(fn, index) {
+            const key = refKey(fn);
+            for (let i = stack.length - 1; i >= 0; i--) {
+                const frame = stack[i];
+                if (frame?.key === key)
+                    return frame.args[index];
+            }
+            return undefined;
+        },
+    };
+}
+//# sourceMappingURL=argument-map.js.map

package/dist/engine/argument-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argument-map.js","sourceRoot":"","sources":["../../src/engine/argument-map.ts"],"names":[],"mappings":"AAeA,SAAS,MAAM,CAAC,GAAc;IAC5B,OAAO,GAAG,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,KAAK,EAAE,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,MAAM,KAAK,GAAiD,EAAE,CAAC;IAC/D,OAAO;QACL,IAAI,CAAC,EAAE,EAAE,IAAI;YACX,KAAK,CAAC,IAAI,CAAC,EAAE,GAAG,EAAE,MAAM,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QACxC,CAAC;QACD,MAAM,CAAC,EAAE;YACP,MAAM,GAAG,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;YACvB,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC3C,IAAI,KAAK,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,GAAG,EAAE,CAAC;oBAC1B,KAAK,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;oBACnB,OAAO;gBACT,CAAC;YACH,CAAC;QACH,CAAC;QACD,MAAM,CAAC,EAAE,EAAE,KAAK;YACd,MAAM,GAAG,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;YACvB,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;gBAC3C,MAAM,KAAK,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC;gBACvB,IAAI,KAAK,EAAE,GAAG,KAAK,GAAG;oBAAE,OAAO,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;YACnD,CAAC;YACD,OAAO,SAAS,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/engine/cycle-detection.d.ts

@@ -0,0 +1,10 @@
+/** Max barrel-walk depth, matches LazyResolver's MAX_REEXPORT_HOPS budget. */
+export declare const MAX_REFERENCE_DEPTH = 32;
+export type CycleGuard = {
+    visited: Set<string>;
+    depth: number;
+    /** Cheap key: file + symbol identity for cycle detection. */
+    push(file: string, symbol: string): "ok" | "cycle" | "too-deep";
+    pop(file: string, symbol: string): void;
+};
+export declare function createCycleGuard(): CycleGuard;

package/dist/engine/cycle-detection.js

@@ -0,0 +1,25 @@
+/** Max barrel-walk depth, matches LazyResolver's MAX_REEXPORT_HOPS budget. */
+export const MAX_REFERENCE_DEPTH = 32;
+export function createCycleGuard() {
+    const visited = new Set();
+    let depth = 0;
+    return {
+        visited,
+        get depth() { return depth; },
+        push(file, symbol) {
+            const key = `${file}::${symbol}`;
+            if (visited.has(key))
+                return "cycle";
+            if (depth >= MAX_REFERENCE_DEPTH)
+                return "too-deep";
+            visited.add(key);
+            depth++;
+            return "ok";
+        },
+        pop(file, symbol) {
+            visited.delete(`${file}::${symbol}`);
+            depth--;
+        },
+    };
+}
+//# sourceMappingURL=cycle-detection.js.map

package/dist/engine/cycle-detection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cycle-detection.js","sourceRoot":"","sources":["../../src/engine/cycle-detection.ts"],"names":[],"mappings":"AAAA,8EAA8E;AAC9E,MAAM,CAAC,MAAM,mBAAmB,GAAG,EAAE,CAAC;AAUtC,MAAM,UAAU,gBAAgB;IAC9B,MAAM,OAAO,GAAG,IAAI,GAAG,EAAU,CAAC;IAClC,IAAI,KAAK,GAAG,CAAC,CAAC;IACd,OAAO;QACL,OAAO;QACP,IAAI,KAAK,KAAK,OAAO,KAAK,CAAC,CAAC,CAAC;QAC7B,IAAI,CAAC,IAAI,EAAE,MAAM;YACf,MAAM,GAAG,GAAG,GAAG,IAAI,KAAK,MAAM,EAAE,CAAC;YACjC,IAAI,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC;gBAAE,OAAO,OAAO,CAAC;YACrC,IAAI,KAAK,IAAI,mBAAmB;gBAAE,OAAO,UAAU,CAAC;YACpD,OAAO,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;YACjB,KAAK,EAAE,CAAC;YACR,OAAO,IAAI,CAAC;QACd,CAAC;QACD,GAAG,CAAC,IAAI,EAAE,MAAM;YACd,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,KAAK,MAAM,EAAE,CAAC,CAAC;YACrC,KAAK,EAAE,CAAC;QACV,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/engine/index.d.ts

@@ -0,0 +1,43 @@
+import type { Graph } from "../index.js";
+import type { OccurrenceVia, ComponentId } from "@component-compass/plugin-core";
+/** Full occurrence shape produced by the engine.
+ *
+ *  `rawComponentId` carries the structured `ComponentId` (same type as in
+ *  plugin-core scan-types) so scan.ts can pass it through
+ *  `computeStableIdFromComponentId` (cli/src/identity.ts) and produce the
+ *  final short-hash string that lands on `OutputOccurrence.componentId`. The
+ *  engine stays self-contained and avoids duplicating the sha1 logic.
+ *
+ *  `occurrenceId` is a provisional hash keyed on `serialiseComponentId(...)` +
+ *  location; scan.ts re-derives it after hashing.
+ */
+export type EngineOccurrence = {
+    /** Raw structured component identity (pre-hash). Scan.ts converts to string. */
+    rawComponentId: ComponentId;
+    filePath: string;
+    line: number;
+    column: number;
+    /** Outermost access pattern (alias for viaChain[0]). */
+    via: OccurrenceVia;
+    /** Full provenance chain, outermost-first. Single-element for direct imports. */
+    viaChain: OccurrenceVia[];
+    props: Record<string, unknown>;
+    /** Provisional stable id (keyed on serialised componentId + location).
+     *  Scan.ts re-derives using the final hashed componentId string. */
+    occurrenceId: string;
+    /** Composition depth — 0 for now; deferred to a follow-up task. */
+    depth: number;
+    /** Declaration position for local-scope identities. */
+    definition?: {
+        line: number;
+        column: number;
+    };
+    /** Raw owner component identity (pre-hash). Scan.ts converts to ownerComponentId string. */
+    rawOwnerComponentId?: ComponentId;
+    /** Stable id of enclosing component definition. Absent when deferred. */
+    ownerComponentId?: string;
+};
+export type ResolvedGraph = {
+    occurrences: EngineOccurrence[];
+};
+export declare function resolve(graph: Graph): ResolvedGraph;

package/dist/engine/index.js

@@ -0,0 +1,241 @@
+import { MODULE_SCOPE } from "../index.js";
+import { computeOccurrenceId, serialiseComponentId } from "@component-compass/plugin-core";
+import { createArgumentMap } from "./argument-map.js";
+import { resolveReference } from "./resolve-reference.js";
+import { resolveType } from "./resolve-type.js";
+/** Extract the npm package name from a module specifier.
+ *  - `react`               → `react`
+ *  - `@org/pkg`            → `@org/pkg`
+ *  - `@org/pkg/sub/path`   → `@org/pkg`
+ *  - `./foo` / `../bar`    → null  (relative — local file, skip)
+ *  - `/abs/path`           → null  (absolute — local file, skip)
+ */
+function packageNameFromSpecifier(specifier) {
+    if (specifier.startsWith(".") || specifier.startsWith("/"))
+        return null;
+    const parts = specifier.split("/");
+    if (parts[0]?.startsWith("@")) {
+        if (parts.length < 2)
+            return null;
+        return `${parts[0]}/${parts[1]}`;
+    }
+    return parts[0] ?? null;
+}
+export function resolve(graph) {
+    const occurrences = [];
+    const argMap = createArgumentMap();
+    for (const [filePath, fileGraph] of graph.files) {
+        for (let usageIdx = 0; usageIdx < fileGraph.jsxUsages.length; usageIdx++) {
+            const usage = fileGraph.jsxUsages[usageIdx];
+            if (!usage)
+                continue;
+            // Resolve owner symbol ref for this usage (for composition attribution).
+            const ownerRef = fileGraph.ownership[usageIdx]?.ownerSymbolRef ?? null;
+            // Find the import record that introduced the root symbol at module scope.
+            // We check usage.ref.symbol (the root binding name), not member-chain
+            // segments, because ImportRecord.local binds the top-level name.
+            const matchedImport = fileGraph.imports.find((i) => i.local === usage.ref.symbol);
+            if (!matchedImport) {
+                // Symbol is locally declared (no import) — emit local identity.
+                const decl = findLocalDeclaration(fileGraph, usage.ref);
+                if (!decl)
+                    continue;
+                // Resolve to check JSX type.
+                const refType = resolveReference(graph, fileGraph, usage.ref);
+                const terminals = resolveType(graph, fileGraph, refType, argMap);
+                if (!terminals.some((t) => t.kind === "JSX"))
+                    continue;
+                const rawOwnerComponentId = ownerRef
+                    ? makeLocalComponentId(fileGraph.filePath, ownerRef.symbol)
+                    : undefined;
+                pushLocalOccurrence(occurrences, filePath, usage, decl, rawOwnerComponentId);
+                continue;
+            }
+            const packageName = packageNameFromSpecifier(matchedImport.specifier);
+            if (!packageName) {
+                // Relative / absolute specifier — always a local file reference.
+                // Resolve the target path; normalize absolute → graph-relative if possible.
+                const resolvedAbsTarget = graph.moduleResolver(filePath, matchedImport.specifier);
+                if (!resolvedAbsTarget)
+                    continue;
+                const resolvedTarget = graph.resolveToGraphKey
+                    ? (graph.resolveToGraphKey(resolvedAbsTarget) ?? resolvedAbsTarget)
+                    : resolvedAbsTarget;
+                // Resolve the type to confirm it's a JSX component. Cross-file resolution
+                // works when resolveToGraphKey is present (graph keys are repo-relative).
+                const refType = resolveReference(graph, fileGraph, usage.ref);
+                const terminals = resolveType(graph, fileGraph, refType, argMap);
+                const jsxTerminals = terminals.filter((t) => t.kind === "JSX");
+                if (jsxTerminals.length === 0)
+                    continue;
+                // Determine the actual export name used in the target file.
+                // When the target is in the graph, look up the export record to find
+                // the local symbol name (e.g. "Button" rather than "default").
+                // This ensures the componentId hash matches the local-index seed.
+                const targetGraph = graph.files.get(resolvedTarget);
+                let exportName = matchedImport.imported;
+                if (targetGraph && matchedImport.imported === "default") {
+                    const defaultExp = targetGraph.exports.find((e) => e.kind === "default");
+                    if (defaultExp && "local" in defaultExp) {
+                        exportName = defaultExp.local;
+                    }
+                }
+                else if (targetGraph) {
+                    // Named import: find the local name for the exported binding.
+                    const namedExp = targetGraph.exports.find((e) => e.kind === "named" && "exportedAs" in e && e.exportedAs === matchedImport.imported && "local" in e);
+                    if (namedExp && "local" in namedExp) {
+                        exportName = namedExp.local;
+                    }
+                }
+                const rawOwnerComponentId = ownerRef
+                    ? makeLocalComponentId(fileGraph.filePath, ownerRef.symbol)
+                    : undefined;
+                const via = {
+                    kind: "direct-import",
+                    specifier: matchedImport.specifier,
+                    import: matchedImport.imported,
+                };
+                const rawComponentId = {
+                    kind: "react-component",
+                    export: exportName,
+                    source: { type: "local", filePath: resolvedTarget },
+                };
+                const provisionalId = serialiseComponentId(rawComponentId);
+                const occurrenceId = computeOccurrenceId(provisionalId, filePath, usage.loc.line, usage.loc.column);
+                occurrences.push({
+                    rawComponentId,
+                    filePath,
+                    line: usage.loc.line,
+                    column: usage.loc.column,
+                    via,
+                    viaChain: [via],
+                    props: {},
+                    occurrenceId,
+                    depth: 0,
+                    ...(rawOwnerComponentId !== undefined ? { rawOwnerComponentId } : {}),
+                });
+                continue;
+            }
+            // Check whether the import resolves to a local file that IS in the graph.
+            // If it does, resolve properly to avoid false positives (e.g. importing a
+            // utility function that happens to be named with a capital letter from a
+            // workspace sibling). For imports whose target is outside the graph
+            // (external packages in node_modules), trust the JSX call site directly.
+            const resolvedAbsTarget = graph.moduleResolver(filePath, matchedImport.specifier);
+            // Normalize absolute path → repo-relative graph key when possible.
+            const resolvedNormTarget = resolvedAbsTarget !== null && graph.resolveToGraphKey
+                ? (graph.resolveToGraphKey(resolvedAbsTarget) ?? resolvedAbsTarget)
+                : resolvedAbsTarget;
+            const targetInGraph = resolvedNormTarget !== null && graph.files.has(resolvedNormTarget);
+            const rawOwnerComponentId = ownerRef
+                ? makeLocalComponentId(fileGraph.filePath, ownerRef.symbol)
+                : undefined;
+            if (targetInGraph) {
+                // Target file is in graph — resolve to check JSX type, and fan out
+                // per JSX terminal (handles dynamic-map fanout within workspace siblings).
+                const refType = resolveReference(graph, fileGraph, usage.ref);
+                const terminals = resolveType(graph, fileGraph, refType, argMap);
+                const jsxTerminals = terminals.filter((t) => t.kind === "JSX");
+                if (jsxTerminals.length === 0)
+                    continue;
+                for (const _terminal of jsxTerminals) {
+                    pushOccurrence(occurrences, filePath, usage, matchedImport, packageName, rawOwnerComponentId);
+                }
+            }
+            else {
+                // Target not in graph (external package or unresolvable specifier).
+                // Trust the JSX call site — emit one occurrence.
+                pushOccurrence(occurrences, filePath, usage, matchedImport, packageName, rawOwnerComponentId);
+            }
+        }
+    }
+    return { occurrences };
+}
+/**
+ * Walk the scope chain for `ref.symbol` in `fileGraph.declarations` and
+ * return the first matching BindingDecl, or null if not found.
+ */
+function findLocalDeclaration(fileGraph, ref) {
+    let scope = ref.scope;
+    while (true) {
+        const decl = fileGraph.declarations.get(`${scope}::${ref.symbol}`);
+        if (decl)
+            return decl;
+        if (scope === MODULE_SCOPE)
+            return null;
+        const parent = fileGraph.scopes.get(scope)?.parent;
+        if (parent === null || parent === undefined)
+            return null;
+        scope = parent;
+    }
+}
+/**
+ * Build a local-scope ComponentId for a symbol declared in `filePath`.
+ * Used for both the occurrence's own identity and for owner attribution.
+ */
+function makeLocalComponentId(filePath, symbol) {
+    return {
+        kind: "react-component",
+        export: symbol,
+        source: { type: "local", filePath },
+    };
+}
+function pushOccurrence(occurrences, filePath, usage, matchedImport, packageName, rawOwnerComponentId) {
+    const rawComponentId = {
+        kind: "react-component",
+        export: matchedImport.imported,
+        source: {
+            type: "external",
+            package: packageName,
+            // modulePath: proper resolution via graph.moduleResolver deferred
+        },
+    };
+    const via = {
+        kind: "direct-import",
+        specifier: matchedImport.specifier,
+        import: matchedImport.imported,
+    };
+    // Provisional occurrenceId keyed on the serialised (human-readable) form.
+    // Scan.ts re-derives the final occurrenceId using the hashed componentId.
+    const provisionalId = serialiseComponentId(rawComponentId);
+    const occurrenceId = computeOccurrenceId(provisionalId, filePath, usage.loc.line, usage.loc.column);
+    occurrences.push({
+        rawComponentId,
+        filePath,
+        line: usage.loc.line,
+        column: usage.loc.column,
+        via,
+        viaChain: [via],
+        props: {},
+        occurrenceId,
+        depth: 0,
+        ...(rawOwnerComponentId !== undefined ? { rawOwnerComponentId } : {}),
+    });
+}
+/**
+ * Push a local-scope occurrence for a symbol declared in the same file (no import).
+ */
+function pushLocalOccurrence(occurrences, filePath, usage, decl, rawOwnerComponentId) {
+    const rawComponentId = {
+        kind: "react-component",
+        export: usage.ref.symbol,
+        source: { type: "local", filePath },
+    };
+    const via = { kind: "local-component" };
+    const provisionalId = serialiseComponentId(rawComponentId);
+    const occurrenceId = computeOccurrenceId(provisionalId, filePath, usage.loc.line, usage.loc.column);
+    occurrences.push({
+        rawComponentId,
+        filePath,
+        line: usage.loc.line,
+        column: usage.loc.column,
+        via,
+        viaChain: [via],
+        props: {},
+        occurrenceId,
+        depth: 0,
+        definition: { line: decl.loc.line, column: decl.loc.column },
+        ...(rawOwnerComponentId !== undefined ? { rawOwnerComponentId } : {}),
+    });
+}
+//# sourceMappingURL=index.js.map

package/dist/engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/engine/index.ts"],"names":[],"mappings":"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"}

package/dist/engine/resolve-reference.d.ts

@@ -0,0 +1,9 @@
+import type { FileGraph, Graph, InferredType, Reference } from "../index.js";
+import { type CycleGuard } from "./cycle-detection.js";
+/**
+ * Resolve a Reference to an InferredType by walking the scope chain in
+ * its FileGraph, falling through to imports at module scope, and following
+ * cross-file resolution through exports. Returns InferredType::Unknown for
+ * unresolved symbols and cycles.
+ */
+export declare function resolveReference(graph: Graph, fileGraph: FileGraph, ref: Reference, guard?: CycleGuard): InferredType;

package/dist/engine/resolve-reference.js

@@ -0,0 +1,125 @@
+import { MODULE_SCOPE } from "../index.js";
+import { createCycleGuard } from "./cycle-detection.js";
+/**
+ * Resolve a Reference to an InferredType by walking the scope chain in
+ * its FileGraph, falling through to imports at module scope, and following
+ * cross-file resolution through exports. Returns InferredType::Unknown for
+ * unresolved symbols and cycles.
+ */
+export function resolveReference(graph, fileGraph, ref, guard = createCycleGuard()) {
+    // Walk up the scope chain.
+    let scope = ref.scope;
+    while (true) {
+        const decl = fileGraph.declarations.get(`${scope}::${ref.symbol}`);
+        if (decl) {
+            // Apply member chain via MemberOf wrap.
+            return wrapWithMemberChain(decl.value, ref.memberChain);
+        }
+        if (scope === MODULE_SCOPE)
+            break;
+        const parent = fileGraph.scopes.get(scope)?.parent;
+        if (parent === null || parent === undefined)
+            break;
+        scope = parent;
+    }
+    // At module scope — check imports.
+    const imp = fileGraph.imports.find((i) => i.local === ref.symbol);
+    if (!imp)
+        return { kind: "Unknown" };
+    const resolvedFile = graph.moduleResolver(fileGraph.filePath, imp.specifier);
+    if (!resolvedFile)
+        return { kind: "Unknown" };
+    // Normalize the resolved path to the graph key format (repo-relative POSIX).
+    // `moduleResolver` may return absolute paths; `resolveToGraphKey` maps them
+    // to relative keys matching `graph.files`.
+    const targetFile = graph.resolveToGraphKey
+        ? (graph.resolveToGraphKey(resolvedFile) ?? resolvedFile)
+        : resolvedFile;
+    const targetGraph = graph.files.get(targetFile);
+    if (!targetGraph)
+        return { kind: "Unknown" };
+    // Look up the export with the imported name in the target file.
+    const exp = findExport(targetGraph.exports, imp.imported);
+    if (!exp)
+        return { kind: "Unknown" };
+    return resolveExport(graph, targetGraph, exp, ref.memberChain, guard);
+}
+function findExport(exports, imported) {
+    for (const exp of exports) {
+        if (exp.kind === "named" && exp.exportedAs === imported)
+            return exp;
+        if (exp.kind === "default" && imported === "default")
+            return exp;
+    }
+    // Star re-exports — fall through to first match (simplified for v1).
+    return null;
+}
+function resolveExport(graph, fileGraph, exp, memberChain, guard) {
+    if (exp.kind === "named" && "local" in exp) {
+        const guardResult = guard.push(fileGraph.filePath, exp.local);
+        if (guardResult !== "ok")
+            return { kind: "Unknown" };
+        try {
+            const localRef = {
+                symbol: exp.local,
+                scope: MODULE_SCOPE,
+                memberChain,
+                loc: { line: 0, column: 0 },
+            };
+            return resolveReference(graph, fileGraph, localRef, guard);
+        }
+        finally {
+            guard.pop(fileGraph.filePath, exp.local);
+        }
+    }
+    if (exp.kind === "named" && "from" in exp) {
+        // Re-export: resolve to the source module's binding.
+        const resolvedFrom = graph.moduleResolver(fileGraph.filePath, exp.from);
+        if (!resolvedFrom)
+            return { kind: "Unknown" };
+        const targetFile = graph.resolveToGraphKey
+            ? (graph.resolveToGraphKey(resolvedFrom) ?? resolvedFrom)
+            : resolvedFrom;
+        const targetGraph = graph.files.get(targetFile);
+        if (!targetGraph)
+            return { kind: "Unknown" };
+        const innerExp = findExport(targetGraph.exports, exp.fromImported);
+        if (!innerExp)
+            return { kind: "Unknown" };
+        const guardResult = guard.push(fileGraph.filePath, exp.exportedAs);
+        if (guardResult !== "ok")
+            return { kind: "Unknown" };
+        try {
+            return resolveExport(graph, targetGraph, innerExp, memberChain, guard);
+        }
+        finally {
+            guard.pop(fileGraph.filePath, exp.exportedAs);
+        }
+    }
+    if (exp.kind === "default" && "local" in exp) {
+        const guardResult = guard.push(fileGraph.filePath, exp.local);
+        if (guardResult !== "ok")
+            return { kind: "Unknown" };
+        try {
+            const localRef = {
+                symbol: exp.local,
+                scope: MODULE_SCOPE,
+                memberChain,
+                loc: { line: 0, column: 0 },
+            };
+            return resolveReference(graph, fileGraph, localRef, guard);
+        }
+        finally {
+            guard.pop(fileGraph.filePath, exp.local);
+        }
+    }
+    return { kind: "Unknown" };
+}
+function wrapWithMemberChain(t, chain) {
+    let result = t;
+    for (const member of chain) {
+        result = { kind: "MemberOf", obj: result, member };
+    }
+    return result;
+}
+//# sourceMappingURL=resolve-reference.js.map

package/dist/engine/resolve-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-reference.js","sourceRoot":"","sources":["../../src/engine/resolve-reference.ts"],"names":[],"mappings":"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"}

package/dist/engine/resolve-type.d.ts

@@ -0,0 +1,11 @@
+import type { FileGraph, Graph, InferredType } from "../index.js";
+import type { ArgumentMap } from "./argument-map.js";
+import { type CycleGuard } from "./cycle-detection.js";
+/** Sentinel for dynamic member access (`obj[expr]` where expr isn't a literal). */
+export declare const DYNAMIC_MEMBER_KEY = "";
+/**
+ * Walk an InferredType to its terminal types (JSX, Str, Unknown, or
+ * concrete TypeOf/ParameterOf leaves that can't be reduced further).
+ * Returns one or more results — multi-result for Union and fanout cases.
+ */
+export declare function resolveType(graph: Graph, fileGraph: FileGraph, type: InferredType, argMap: ArgumentMap, guard?: CycleGuard): InferredType[];

package/dist/engine/resolve-type.js

@@ -0,0 +1,154 @@
+import { resolveReference } from "./resolve-reference.js";
+import { createCycleGuard } from "./cycle-detection.js";
+/** Sentinel for dynamic member access (`obj[expr]` where expr isn't a literal). */
+export const DYNAMIC_MEMBER_KEY = "";
+/**
+ * Walk an InferredType to its terminal types (JSX, Str, Unknown, or
+ * concrete TypeOf/ParameterOf leaves that can't be reduced further).
+ * Returns one or more results — multi-result for Union and fanout cases.
+ */
+export function resolveType(graph, fileGraph, type, argMap, guard = createCycleGuard()) {
+    switch (type.kind) {
+        case "JSX":
+        case "Str":
+        case "Unknown":
+            return [type];
+        case "TypeOf": {
+            const resolved = resolveReference(graph, fileGraph, type.ref, guard);
+            return resolveType(graph, fileGraph, resolved, argMap, guard);
+        }
+        case "Function":
+            return type.returns.flatMap((r) => resolveType(graph, fileGraph, r, argMap, guard));
+        case "ReturnTypeOf": {
+            // Resolve the callee to its bare Function node(s) without expanding
+            // their returns — if we went through resolveType the Function case would
+            // prematurely walk returns before args are bound.
+            // Each entry carries a bindingRef: the Reference that ParameterOf nodes
+            // inside the function use as their fn key. For a TypeOf callee this is
+            // the callee ref; for a nested ReturnTypeOf chain it's propagated up.
+            const calleeFns = resolveToFunctions(graph, fileGraph, type.callee, argMap, guard);
+            const results = [];
+            for (const { fn, bindingRef } of calleeFns) {
+                if (fn.kind !== "Function") {
+                    results.push({ kind: "Unknown" });
+                    continue;
+                }
+                if (bindingRef)
+                    argMap.bind(bindingRef, type.args);
+                try {
+                    for (const ret of fn.returns) {
+                        results.push(...resolveType(graph, fileGraph, ret, argMap, guard));
+                    }
+                }
+                finally {
+                    if (bindingRef)
+                        argMap.unbind(bindingRef);
+                }
+            }
+            return results;
+        }
+        case "ParameterOf": {
+            const subbed = argMap.lookup(type.fn, type.index);
+            if (!subbed)
+                return [{ kind: "Unknown" }];
+            return resolveType(graph, fileGraph, subbed, argMap, guard);
+        }
+        case "MemberOf": {
+            const objTypes = resolveType(graph, fileGraph, type.obj, argMap, guard);
+            const results = [];
+            for (const obj of objTypes) {
+                if (obj.kind === "Object") {
+                    if (type.member === DYNAMIC_MEMBER_KEY) {
+                        for (const v of Object.values(obj.props)) {
+                            results.push(...resolveType(graph, fileGraph, v, argMap, guard));
+                        }
+                    }
+                    else {
+                        const v = obj.props[type.member];
+                        if (v)
+                            results.push(...resolveType(graph, fileGraph, v, argMap, guard));
+                        else
+                            results.push({ kind: "Unknown" });
+                    }
+                }
+                else if (obj.kind === "Array") {
+                    for (const el of obj.elements) {
+                        results.push(...resolveType(graph, fileGraph, el, argMap, guard));
+                    }
+                }
+                else {
+                    results.push({ kind: "Unknown" });
+                }
+            }
+            return results;
+        }
+        case "Union":
+            return type.types.flatMap((t) => resolveType(graph, fileGraph, t, argMap, guard));
+        case "Object":
+        case "Array":
+            return [type];
+    }
+}
+/**
+ * Resolve a type down to its bare Function node(s) without expanding their
+ * returns[]. Used by ReturnTypeOf so that args can be bound before the
+ * function body is walked.
+ *
+ * Each entry carries a `bindingRef` — the Reference that `ParameterOf` nodes
+ * inside the function use as their `fn` key. For `TypeOf` callees this is the
+ * referenced symbol; for nested `ReturnTypeOf` chains it is propagated from
+ * the innermost `TypeOf` that started the chain, because `ParameterOf` nodes
+ * are authored with that outer ref (e.g. `id()(Foo)` where the inner
+ * function's body has `ParameterOf(idRef, 0)` and the outer invocation
+ * supplies `Foo`).
+ *
+ * Follows: TypeOf (via resolveReference), Union fanout, and nested
+ * ReturnTypeOf chains. Returns `{fn: Unknown}` when the chain doesn't bottom
+ * out at Function.
+ */
+function resolveToFunctions(graph, fileGraph, type, argMap, guard) {
+    switch (type.kind) {
+        case "Function":
+            return [{ fn: type, bindingRef: null }];
+        case "TypeOf": {
+            const resolved = resolveReference(graph, fileGraph, type.ref, guard);
+            // Carry the TypeOf ref through so the caller can bind args to it.
+            const inner = resolveToFunctions(graph, fileGraph, resolved, argMap, guard);
+            return inner.map((e) => ({ fn: e.fn, bindingRef: e.bindingRef ?? type.ref }));
+        }
+        case "Union":
+            return type.types.flatMap((t) => resolveToFunctions(graph, fileGraph, t, argMap, guard));
+        case "ReturnTypeOf": {
+            // Recursively resolve the inner callee to Function entries, then walk
+            // each function's returns to find Functions one level deeper.
+            const innerFns = resolveToFunctions(graph, fileGraph, type.callee, argMap, guard);
+            const results = [];
+            for (const { fn, bindingRef } of innerFns) {
+                if (fn.kind !== "Function") {
+                    results.push({ fn: { kind: "Unknown" }, bindingRef: null });
+                    continue;
+                }
+                if (bindingRef)
+                    argMap.bind(bindingRef, type.args);
+                try {
+                    for (const ret of fn.returns) {
+                        const deeper = resolveToFunctions(graph, fileGraph, ret, argMap, guard);
+                        // Propagate bindingRef so the outer call can bind to the same ref.
+                        results.push(...deeper.map((e) => ({
+                            fn: e.fn,
+                            bindingRef: e.bindingRef ?? bindingRef,
+                        })));
+                    }
+                }
+                finally {
+                    if (bindingRef)
+                        argMap.unbind(bindingRef);
+                }
+            }
+            return results;
+        }
+        default:
+            return [{ fn: { kind: "Unknown" }, bindingRef: null }];
+    }
+}
+//# sourceMappingURL=resolve-type.js.map

package/dist/engine/resolve-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resolve-type.js","sourceRoot":"","sources":["../../src/engine/resolve-type.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export type { Reference, ScopeId } from "./types/reference.js";
+export { MODULE_SCOPE } from "./types/reference.js";
+export type { InferredType } from "./types/inferred-type.js";
+export type { BindingDecl, ExportRecord, FileGraph, Graph, ImportRecord, JsxUsage, } from "./types/file-graph.js";
+export { createGraphBuilder } from "./builder.js";
+export type { GraphBuilder, FileBuilder, CreateGraphBuilderOptions } from "./builder.js";
+export { resolveType, DYNAMIC_MEMBER_KEY } from "./engine/resolve-type.js";
+export { createArgumentMap } from "./engine/argument-map.js";
+export type { ArgumentMap } from "./engine/argument-map.js";
+export { resolve } from "./engine/index.js";
+export type { ResolvedGraph, EngineOccurrence } from "./engine/index.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+// Public API surface for @component-compass/reference-graph.
+// Types and builders re-exported below as they're implemented.
+export { MODULE_SCOPE } from "./types/reference.js";
+export { createGraphBuilder } from "./builder.js";
+export { resolveType, DYNAMIC_MEMBER_KEY } from "./engine/resolve-type.js";
+export { createArgumentMap } from "./engine/argument-map.js";
+export { resolve } from "./engine/index.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,6DAA6D;AAC7D,+DAA+D;AAG/D,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AAWpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC;AAGlD,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,MAAM,0BAA0B,CAAC;AAC3E,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAG7D,OAAO,EAAE,OAAO,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/types/file-graph.d.ts

@@ -0,0 +1,81 @@
+import type { ResolveImport } from "@component-compass/plugin-core";
+import type { InferredType } from "./inferred-type.js";
+import type { Reference, ScopeId } from "./reference.js";
+/** A binding declared in a file (variable, function, class, import alias). */
+export type BindingDecl = {
+    scope: ScopeId;
+    symbol: string;
+    value: InferredType;
+    loc: {
+        line: number;
+        column: number;
+    };
+    isExported: boolean;
+    /** When `export { local as exported }`, the public name differs from the local. */
+    exportedAs?: string;
+};
+export type ImportRecord = {
+    specifier: string;
+    /** `"default"` | exported name | `"*"` (namespace). */
+    imported: string;
+    local: string;
+    scope: ScopeId;
+    loc: {
+        line: number;
+        column: number;
+    };
+};
+export type ExportRecord = {
+    kind: "named";
+    exportedAs: string;
+    local: string;
+} | {
+    kind: "named";
+    exportedAs: string;
+    from: string;
+    fromImported: string;
+} | {
+    kind: "star";
+    from: string;
+} | {
+    kind: "default";
+    local: string;
+};
+/** A JSX element opening — becomes one or more Occurrences post-resolution. */
+export type JsxUsage = {
+    ref: Reference;
+    loc: {
+        line: number;
+        column: number;
+    };
+    /** Per-occurrence prop usage; existing PropUsage shape from plugin-core. */
+    props: unknown[];
+};
+export type FileGraph = {
+    /** Repo-relative POSIX path. */
+    filePath: string;
+    scopes: Map<ScopeId, {
+        parent: ScopeId | null;
+    }>;
+    /** Keyed by `${scopeId}::${symbol}` for O(1) scope-aware lookup. */
+    declarations: Map<string, BindingDecl>;
+    imports: ImportRecord[];
+    exports: ExportRecord[];
+    jsxUsages: JsxUsage[];
+    /** Per-JSX-usage owner attribution. usageIdx aligns with jsxUsages[i]. */
+    ownership: Array<{
+        usageIdx: number;
+        ownerSymbolRef: Reference | null;
+    }>;
+};
+export type Graph = {
+    files: Map<string, FileGraph>;
+    moduleResolver: ResolveImport;
+    /**
+     * Optional function that normalises an absolute path returned by
+     * `moduleResolver` into the repo-relative POSIX key used by `files`.
+     * When provided, enables cross-file resolution for relative-specifier
+     * imports where `moduleResolver` returns absolute paths.
+     */
+    resolveToGraphKey?: (absPath: string) => string | null;
+};

package/dist/types/file-graph.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=file-graph.js.map

package/dist/types/file-graph.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-graph.js","sourceRoot":"","sources":["../../src/types/file-graph.ts"],"names":[],"mappings":""}

package/dist/types/inferred-type.d.ts

@@ -0,0 +1,44 @@
+import type { Reference } from "./reference.js";
+/**
+ * Typed value-flow algebra. Every binding's value is described by an
+ * InferredType expression. The resolution engine walks these expressions
+ * across module boundaries, threading concrete component identities
+ * through arbitrary call chains.
+ *
+ * 11 variants — adapted from Omlet's analyzer. See spec §5.
+ */
+export type InferredType = {
+    kind: "TypeOf";
+    ref: Reference;
+} | {
+    kind: "Function";
+    returns: InferredType[];
+} | {
+    kind: "ReturnTypeOf";
+    callee: InferredType;
+    args: InferredType[];
+} | {
+    kind: "ParameterOf";
+    fn: Reference;
+    index: number;
+} | {
+    kind: "MemberOf";
+    obj: InferredType;
+    member: string;
+} | {
+    kind: "Union";
+    types: InferredType[];
+} | {
+    kind: "Object";
+    props: Record<string, InferredType>;
+} | {
+    kind: "Array";
+    elements: InferredType[];
+} | {
+    kind: "JSX";
+} | {
+    kind: "Str";
+    value: string;
+} | {
+    kind: "Unknown";
+};

package/dist/types/inferred-type.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=inferred-type.js.map

package/dist/types/inferred-type.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inferred-type.js","sourceRoot":"","sources":["../../src/types/inferred-type.ts"],"names":[],"mappings":""}

package/dist/types/reference.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A scope id is opaque per-FileGraph. Sequential ints assigned by
+ * GraphBuilder.pushScope(); module scope is always 0.
+ */
+export type ScopeId = number;
+export declare const MODULE_SCOPE: ScopeId;
+/**
+ * A Reference is what a parser emits when it sees an identifier in code.
+ * Captures the identifier as written, the scope it resolves in, and any
+ * member access chain (`<Foo.Bar.Baz />` produces memberChain ["Bar", "Baz"]).
+ */
+export type Reference = {
+    symbol: string;
+    scope: ScopeId;
+    memberChain: string[];
+    loc: {
+        line: number;
+        column: number;
+    };
+};

package/dist/types/reference.js

@@ -0,0 +1,2 @@
+export const MODULE_SCOPE = 0;
+//# sourceMappingURL=reference.js.map

package/dist/types/reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reference.js","sourceRoot":"","sources":["../../src/types/reference.ts"],"names":[],"mappings":"AAMA,MAAM,CAAC,MAAM,YAAY,GAAY,CAAC,CAAC"}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@component-compass/reference-graph",
+  "version": "0.0.0-pr-114-393daf6-20260518195554",
+  "description": "Project-wide reference graph + cross-module resolution engine for component-compass parsers.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit",
+    "lint": "biome lint src tests",
+    "clean": "rm -rf dist .turbo"
+  },
+  "dependencies": {
+    "@component-compass/plugin-core": "workspace:^"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "typescript": "^5.9.0",
+    "vitest": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}