@component-compass/reference-graph 0.1.17 → 0.1.18

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

@@ -11,4 +11,8 @@ export interface ArgumentMap {
     unbind(fn: Reference): void;
     lookup(fn: Reference, index: number): InferredType | undefined;
 }
+/** Key an ArgumentMap frame by. Exported so wrapper-folding's structural
+ *  pass-through check compares `ParameterOf.fn` against a callee's
+ *  `bindingRef` exactly the way `lookup` would. */
+export declare function argumentRefKey(ref: Reference): string;
 export declare function createArgumentMap(): ArgumentMap;

package/dist/engine/argument-map.js

@@ -1,14 +1,17 @@
-function refKey(ref) {
+/** Key an ArgumentMap frame by. Exported so wrapper-folding's structural
+ *  pass-through check compares `ParameterOf.fn` against a callee's
+ *  `bindingRef` exactly the way `lookup` would. */
+export function argumentRefKey(ref) {
     return `${ref.symbol}::${ref.scope}`;
 }
 export function createArgumentMap() {
     const stack = [];
     return {
         bind(fn, args) {
-            stack.push({ key: refKey(fn), args });
+            stack.push({ key: argumentRefKey(fn), args });
         },
         unbind(fn) {
-            const key = refKey(fn);
+            const key = argumentRefKey(fn);
             for (let i = stack.length - 1; i >= 0; i--) {
                 if (stack[i]?.key === key) {
                     stack.splice(i, 1);
@@ -17,7 +20,7 @@ export function createArgumentMap() {
             }
         },
         lookup(fn, index) {
-            const key = refKey(fn);
+            const key = argumentRefKey(fn);
             for (let i = stack.length - 1; i >= 0; i--) {
                 const frame = stack[i];
                 if (frame?.key === key)

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

@@ -1 +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"}
+{"version":3,"file":"argument-map.js","sourceRoot":"","sources":["../../src/engine/argument-map.ts"],"names":[],"mappings":"AAeA;;mDAEmD;AACnD,MAAM,UAAU,cAAc,CAAC,GAAc;IAC3C,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,cAAc,CAAC,EAAE,CAAC,EAAE,IAAI,EAAE,CAAC,CAAC;QAChD,CAAC;QACD,MAAM,CAAC,EAAE;YACP,MAAM,GAAG,GAAG,cAAc,CAAC,EAAE,CAAC,CAAC;YAC/B,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,cAAc,CAAC,EAAE,CAAC,CAAC;YAC/B,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/assert-never.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Exhaustiveness guard for every `switch (type.kind)` over `InferredType`
+ * (spec D7). Reaching it is a type error at compile time — adding a kind to
+ * the IR must fail to build in every interpreter — and a loud error at
+ * runtime for the one way TypeScript can be bypassed (a cast).
+ */
+export declare function assertNever(x: never): never;

package/dist/engine/assert-never.js

@@ -0,0 +1,10 @@
+/**
+ * Exhaustiveness guard for every `switch (type.kind)` over `InferredType`
+ * (spec D7). Reaching it is a type error at compile time — adding a kind to
+ * the IR must fail to build in every interpreter — and a loud error at
+ * runtime for the one way TypeScript can be bypassed (a cast).
+ */
+export function assertNever(x) {
+    throw new Error(`Unhandled InferredType kind: ${JSON.stringify(x)}`);
+}
+//# sourceMappingURL=assert-never.js.map

package/dist/engine/assert-never.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"assert-never.js","sourceRoot":"","sources":["../../src/engine/assert-never.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH,MAAM,UAAU,WAAW,CAAC,CAAQ;IAClC,MAAM,IAAI,KAAK,CAAC,gCAAgC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;AACvE,CAAC"}

package/dist/engine/component-shape.d.ts

@@ -0,0 +1,38 @@
+import type { FileGraph, Graph, InferredType } from "../index.js";
+import { type ArgumentMap } from "./argument-map.js";
+import { type CycleGuard } from "./cycle-detection.js";
+/**
+ * THE component-shape predicate (spec D2, D7, D9). Reduces an InferredType
+ * to what its VALUE is:
+ *
+ *   "jsx"        — a JSX value (`const br = <br/>`, or what calling a
+ *                  component yields). Not a component.
+ *   "component"  — a function whose returns are DIRECTLY JSX, or a call that
+ *                  evaluates to one.
+ *   "unresolved" — bottoms out at an import the graph cannot see with nothing
+ *                  component-shaped in hand (D7).
+ *   "other"      — anything else: factories, data, hooks, strings.
+ *
+ * The non-recursion into nested Function returns is load-bearing: a Function
+ * whose return is itself a Function evaluates that return to "component",
+ * not "jsx", so the outer function is "other" — a factory. That single rule
+ * separates `createField` from its products and is why `hasJsx`'s recursive
+ * arm was deleted (D11). Do not add a second implementation anywhere; every
+ * caller — registry membership, owner classification, occurrence admission —
+ * calls this one. Named in docs/CONTEXT.md ("Component-shape seam").
+ */
+export type ValueKind = "jsx" | "component" | "unresolved" | "other";
+export declare function evalKind(type: InferredType, graph: Graph, fileGraph: FileGraph, argMap?: ArgumentMap, guard?: CycleGuard): ValueKind;
+export declare function isComponentShaped(type: InferredType, graph: Graph, fileGraph: FileGraph): boolean;
+/** A TypeOf (possibly under a ReturnTypeOf chain, or a MemberOf access on
+ *  one — `Sentry.withProfiler`) that names an import the graph cannot
+ *  resolve — the shape the opaque-HOC fold synthesises identity from (#274).
+ *  Unwrapping MemberOf.obj is what lets Ruling 16(ii)'s render-callback
+ *  narrowing correctly except FOR an import-backed namespace member call.
+ *
+ *  Exported (ruling 19): `wrapper-folding.ts`'s opaque-callee identity-fold
+ *  step shares this EXACT predicate for its parallel "is this a data-method
+ *  render call, not a wrapper" decision — never re-derive it there. Takes
+ *  plain params (not this module's private `Ctx`) so a caller outside this
+ *  file doesn't need to construct one. */
+export declare function isImportBackedLeaf(t: InferredType, graph: Graph, fileGraph: FileGraph, guard: CycleGuard): boolean;

package/dist/engine/component-shape.js

@@ -0,0 +1,177 @@
+import { createArgumentMap } from "./argument-map.js";
+import { createCycleGuard } from "./cycle-detection.js";
+import { fileGraphForRef, resolveReference } from "./resolve-reference.js";
+import { resolveToFunctions, resolveType, DYNAMIC_MEMBER_KEY } from "./resolve-type.js";
+import { assertNever } from "./assert-never.js";
+export function evalKind(type, graph, fileGraph, argMap = createArgumentMap(), guard = createCycleGuard()) {
+    return evalInner(type, { graph, fileGraph, argMap, guard });
+}
+export function isComponentShaped(type, graph, fileGraph) {
+    return evalKind(type, graph, fileGraph) === "component";
+}
+/** Priority merge for fan-out shapes: jsx > component > unresolved > other. */
+function merge(kinds) {
+    if (kinds.includes("jsx"))
+        return "jsx";
+    if (kinds.includes("component"))
+        return "component";
+    if (kinds.includes("unresolved"))
+        return "unresolved";
+    return "other";
+}
+function evalInner(t, ctx) {
+    if (ctx.guard.pushNode(t) === "cycle")
+        return "other";
+    try {
+        switch (t.kind) {
+            case "JSX":
+                return "jsx";
+            case "Function":
+                return t.returns.some((r) => evalInner(r, ctx) === "jsx") ? "component" : "other";
+            case "Union":
+                return merge(t.types.map((u) => evalInner(u, ctx)));
+            case "ParameterOf": {
+                const bound = ctx.argMap.lookup(t.fn, t.index);
+                return bound ? evalInner(bound, ctx) : "other";
+            }
+            case "TypeOf": {
+                const resolved = resolveReference(ctx.graph, ctx.fileGraph, t.ref, ctx.guard);
+                if (resolved.kind === "Unknown")
+                    return isImportBacked(t, ctx.graph, ctx.fileGraph) ? "unresolved" : "other";
+                return evalInner(resolved, ctx);
+            }
+            case "MemberOf": {
+                const objs = resolveType(ctx.graph, ctx.fileGraph, t.obj, ctx.argMap, ctx.guard);
+                const kinds = [];
+                for (const { type: obj } of objs) {
+                    if (obj.kind !== "Object")
+                        continue;
+                    // Ruling 16(iii): a dynamic-key access (`BannerComponent[type]`)
+                    // could select any prop at runtime — merge the shape of every
+                    // prop the object carries, the same "any branch could be it"
+                    // treatment Union already gets.
+                    if (t.member === DYNAMIC_MEMBER_KEY) {
+                        for (const prop of Object.values(obj.props))
+                            kinds.push(evalInner(prop, ctx));
+                        continue;
+                    }
+                    const prop = obj.props[t.member];
+                    if (prop)
+                        kinds.push(evalInner(prop, ctx));
+                }
+                return kinds.length === 0 ? "other" : merge(kinds);
+            }
+            case "ReturnTypeOf":
+                return evalCall(t, ctx);
+            case "Str":
+            case "Object":
+            case "Array":
+            case "Unknown":
+            case "DynamicImport":
+                // A literal array of JSX elements is deliberately "other", the same
+                // treatment a Function returning Object-containing-JSX gets ("data
+                // factory"): helper-callers.ts's helper/component split (D11) depends
+                // on a Function returning Array<JSX> classifying as a helper, not a
+                // component, so its callers attribute correctly via helper-call
+                // chains instead of it becoming a standalone identity. Ruling 16's
+                // ".map(render)" and dynamic-member patterns don't need this arm —
+                // both resolve to "jsx" through evalCall's opaque-MemberOf-callee
+                // rule and the MemberOf DYNAMIC_MEMBER_KEY merge instead.
+                return "other";
+            default:
+                return assertNever(t);
+        }
+    }
+    finally {
+        ctx.guard.popNode(t);
+    }
+}
+function evalCall(t, ctx) {
+    // `lazy(() => import('./x'))` and friends: the engine's lazy-import rule
+    // owns identity; for shape purposes the call is a component.
+    if (t.args.some(containsDynamicImport))
+        return "component";
+    const fns = resolveToFunctions(ctx.graph, ctx.fileGraph, t.callee, ctx.argMap, ctx.guard);
+    const resolvable = [];
+    for (const f of fns) {
+        if (f.fn.kind === "Function")
+            resolvable.push(f);
+    }
+    if (resolvable.length === 0) {
+        // Opaque callee (D9 arm 3 / D7): component iff some argument is
+        // component-shaped or an import-backed leaf the engine will fold to.
+        const carries = t.args.some((a) => evalInner(a, ctx) === "component" || isImportBackedLeaf(a, ctx.graph, ctx.fileGraph, ctx.guard));
+        if (!carries)
+            return "unresolved";
+        // Ruling 16(ii): a method call on non-import-backed data — a parameter,
+        // a local array/object literal, a hook result, a global like
+        // `Object.keys(x)` — with a component-shaped argument is a *render
+        // callback* (`items.map(({...}) => <Button/>)`), not a wrapper that
+        // takes a component as a prop: the call's OUTPUT is rendered JSX, not a
+        // component. An import-backed callee (the actual unresolvable-HOC case
+        // D9 arm 3 exists for) keeps "component". Ruling 19: wrapper-folding.ts's
+        // opaque step shares this exact condition (isImportBackedLeaf, exported
+        // below) for the parallel identity-folding decision — don't re-derive it.
+        if (t.callee.kind === "MemberOf" && !isImportBackedLeaf(t.callee, ctx.graph, ctx.fileGraph, ctx.guard))
+            return "jsx";
+        return "component";
+    }
+    const kinds = [];
+    for (const { fn, bindingRef } of resolvable) {
+        if (fn.kind !== "Function")
+            continue;
+        if (bindingRef)
+            ctx.argMap.bind(bindingRef, t.args);
+        try {
+            for (const ret of fn.returns)
+                kinds.push(evalInner(ret, ctx));
+        }
+        finally {
+            if (bindingRef)
+                ctx.argMap.unbind(bindingRef);
+        }
+    }
+    return merge(kinds);
+}
+function isImportBacked(t, graph, fileGraph) {
+    return fileGraphForRef(graph, t.ref, fileGraph).importsByLocal.has(t.ref.symbol);
+}
+/** A TypeOf (possibly under a ReturnTypeOf chain, or a MemberOf access on
+ *  one — `Sentry.withProfiler`) that names an import the graph cannot
+ *  resolve — the shape the opaque-HOC fold synthesises identity from (#274).
+ *  Unwrapping MemberOf.obj is what lets Ruling 16(ii)'s render-callback
+ *  narrowing correctly except FOR an import-backed namespace member call.
+ *
+ *  Exported (ruling 19): `wrapper-folding.ts`'s opaque-callee identity-fold
+ *  step shares this EXACT predicate for its parallel "is this a data-method
+ *  render call, not a wrapper" decision — never re-derive it there. Takes
+ *  plain params (not this module's private `Ctx`) so a caller outside this
+ *  file doesn't need to construct one. */
+export function isImportBackedLeaf(t, graph, fileGraph, guard) {
+    let cur = t;
+    while (cur.kind === "ReturnTypeOf" || cur.kind === "MemberOf") {
+        cur = cur.kind === "ReturnTypeOf" ? cur.callee : cur.obj;
+    }
+    if (cur.kind !== "TypeOf")
+        return false;
+    if (!isImportBacked(cur, graph, fileGraph))
+        return false;
+    return resolveReference(graph, fileGraph, cur.ref, guard).kind === "Unknown";
+}
+function containsDynamicImport(t) {
+    switch (t.kind) {
+        case "DynamicImport":
+            return true;
+        case "Function":
+            return t.returns.some(containsDynamicImport);
+        case "ReturnTypeOf":
+            return containsDynamicImport(t.callee) || t.args.some(containsDynamicImport);
+        case "MemberOf":
+            return containsDynamicImport(t.obj);
+        case "Union":
+            return t.types.some(containsDynamicImport);
+        default:
+            return false;
+    }
+}
+//# sourceMappingURL=component-shape.js.map

package/dist/engine/component-shape.js.map

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

package/dist/engine/helper-callers.d.ts

@@ -1,33 +1,21 @@
-import type { BindingDecl, Graph, InferredType } from "../index.js";
-import { type CycleGuard } from "./cycle-detection.js";
-export type Classification = "component" | "helper" | "unknown";
+import type { BindingDecl, FileGraph, Graph, Reference } from "../index.js";
 /**
- * Structural component-vs-helper classification. Mirrors Omlet's `is_component`
- * at `cli/crates/core/src/analyzer/mod.rs:1498`. A Function is a component iff
- * any of its return types satisfies `hasJsx` — i.e. returns JSX directly or
- * through `Union`/`ReturnTypeOf`. Non-Function values get `unknown` so the
- * caller preserves today's behavior (no helper reassignment).
- *
- * NOTE: an `originFile` argument is required when the decl's value contains
- * cross-module type refs (TypeOf / ReturnTypeOf with refs), so that
- * `resolveReference` knows which FileGraph to look up scope chains against.
+ * Walk the scope chain for `ref.symbol` in `fileGraph.declarations` and
+ * return the first matching BindingDecl, or null if not found. THE
+ * scope-chain walk (I4) — `registry.ts`'s `resolveUsageTarget` calls this
+ * seam instead of re-deriving it.
  */
-export declare function classifyDeclaration(decl: BindingDecl, graph: Graph, originFile?: string): Classification;
+export declare function findLocalDeclaration(fileGraph: FileGraph, ref: Reference): BindingDecl | null;
+export type Classification = "component" | "helper" | "unknown";
 /**
- * Strict JSX-bearing predicate. Mirrors Omlet's `has_jsx` at
- * `cli/crates/core/src/analyzer/mod.rs:1478`.
- *
- *   JSX                                          → true
- *   Union<...JSX...>                             → true (any branch)
- *   ReturnTypeOf<componentCallable>              → true
- *   MemberOf<obj, member> where resolved has JSX → true (recursive)
- *   TypeOf<ref> where resolved value has JSX     → true (recursive, cross-file)
- *   Object / Array / Str / Unknown / etc.        → false
- *
- * The `Object{cta: JSX}` and `Array<{x: JSX}>` cases deliberately return false
- * — that's what classifies data factories and JSX-in-container hooks as helpers.
+ * Component-vs-helper classification for owner attribution. Delegates to
+ * THE component-shape predicate (`evalKind`, spec D11) — this file no longer
+ * carries its own JSX-bearing walk. A Function or call that is not
+ * component-shaped is a "helper" (JSX inside it fans out to its callers);
+ * plain values stay "unknown" so `resolveOwnerChain` treats them as it
+ * always has.
  */
-export declare function hasJsx(t: InferredType, graph: Graph, originFile: string | undefined, guard: CycleGuard): boolean;
+export declare function classifyDeclaration(decl: BindingDecl, graph: Graph, originFile?: string): Classification;
 export type SymbolKey = {
     file: string;
     symbol: string;
@@ -42,8 +30,10 @@ export type ClassifiedHelperIndex = HelperCallerIndex & {
  * Three-phase build of the helper → component-callers reverse index plus
  * per-decl classification cache.
  *
- * Phase 1 (collect) walks every module-scope `Function`-valued BindingDecl
- * across the graph, collecting caller-side references from three sources:
+ * Phase 1 (collect) walks every module-scope `Function`- or
+ * `ReturnTypeOf`-valued BindingDecl across the graph (the latter is a
+ * factory's product, spec D13), collecting caller-side references from
+ * three sources:
  *
  *   1. `TypeOf` refs inside the decl's return-type expressions
  *      (`decl.value.returns`) — captures `() => helper()` shapes where the
@@ -61,7 +51,7 @@ export type ClassifiedHelperIndex = HelperCallerIndex & {
  *      (the dominant React call shape) never appear as called by anyone.
  *
  * Phase 2 (classify) runs structural classification on every module-scope
- * Function decl, with a reclassification gate: a decl classified as
+ * Function- or ReturnTypeOf-valued decl, with a reclassification gate: a decl classified as
  * `"component"` but consumed only as a value (never JSX) is reclassified
  * as `"helper"`.
  *
@@ -74,3 +64,15 @@ export type ClassifiedHelperIndex = HelperCallerIndex & {
  * resolution uses the existing module resolver — no new IO.
  */
 export declare function buildHelperCallers(graph: Graph): ClassifiedHelperIndex;
+/**
+ * Resolve a Reference to the BindingDecl it ultimately points at, crossing
+ * files via imports + the module resolver. Returns `{file, decl}` keyed by
+ * the target file (not the import-bearing file) so caller-set membership
+ * dedupes across multiple import paths.
+ *
+ * Returns null for unresolved or external refs.
+ */
+export declare function resolveRefToDecl(ref: Reference, callerFile: string, callerGraph: FileGraph, graph: Graph): {
+    file: string;
+    decl: BindingDecl;
+} | null;

package/dist/engine/helper-callers.js

@@ -1,82 +1,68 @@
 import { MODULE_SCOPE } from "../index.js";
-import { resolveReference } from "./resolve-reference.js";
-import { createCycleGuard } from "./cycle-detection.js";
+import { evalKind } from "./component-shape.js";
 import { followReExportChain } from "./re-export-chain.js";
 /**
- * Structural component-vs-helper classification. Mirrors Omlet's `is_component`
- * at `cli/crates/core/src/analyzer/mod.rs:1498`. A Function is a component iff
- * any of its return types satisfies `hasJsx` — i.e. returns JSX directly or
- * through `Union`/`ReturnTypeOf`. Non-Function values get `unknown` so the
- * caller preserves today's behavior (no helper reassignment).
- *
- * NOTE: an `originFile` argument is required when the decl's value contains
- * cross-module type refs (TypeOf / ReturnTypeOf with refs), so that
- * `resolveReference` knows which FileGraph to look up scope chains against.
+ * Walk the scope chain for `ref.symbol` in `fileGraph.declarations` and
+ * return the first matching BindingDecl, or null if not found. THE
+ * scope-chain walk (I4) — `registry.ts`'s `resolveUsageTarget` calls this
+ * seam instead of re-deriving it.
  */
-export function classifyDeclaration(decl, graph, originFile) {
-    if (decl.value.kind !== "Function")
-        return "unknown";
-    const guard = createCycleGuard();
-    for (const t of decl.value.returns) {
-        if (hasJsx(t, graph, originFile, guard))
-            return "component";
+export 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;
     }
-    return "helper";
 }
 /**
- * Strict JSX-bearing predicate. Mirrors Omlet's `has_jsx` at
- * `cli/crates/core/src/analyzer/mod.rs:1478`.
- *
- *   JSX                                          → true
- *   Union<...JSX...>                             → true (any branch)
- *   ReturnTypeOf<componentCallable>              → true
- *   MemberOf<obj, member> where resolved has JSX → true (recursive)
- *   TypeOf<ref> where resolved value has JSX     → true (recursive, cross-file)
- *   Object / Array / Str / Unknown / etc.        → false
- *
- * The `Object{cta: JSX}` and `Array<{x: JSX}>` cases deliberately return false
- * — that's what classifies data factories and JSX-in-container hooks as helpers.
+ * Component-vs-helper classification for owner attribution. Delegates to
+ * THE component-shape predicate (`evalKind`, spec D11) — this file no longer
+ * carries its own JSX-bearing walk. A Function or call that is not
+ * component-shaped is a "helper" (JSX inside it fans out to its callers);
+ * plain values stay "unknown" so `resolveOwnerChain` treats them as it
+ * always has.
  */
-export function hasJsx(t, graph, originFile, guard) {
-    switch (t.kind) {
-        case "JSX":
-            return true;
-        case "Union":
-            return t.types.some((u) => hasJsx(u, graph, originFile, guard));
-        case "ReturnTypeOf":
-            return hasJsx(t.callee, graph, originFile, guard);
-        case "Function":
-            return t.returns.some((r) => hasJsx(r, graph, originFile, guard));
-        case "TypeOf": {
-            const effectiveFile = t.ref.originFile ?? originFile;
-            if (!effectiveFile)
-                return false;
-            const file = graph.files.get(effectiveFile);
-            if (!file)
-                return false;
-            const gr = guard.push(effectiveFile, t.ref.symbol);
-            if (gr !== "ok")
-                return false;
-            try {
-                const resolved = resolveReference(graph, file, t.ref, guard);
-                return hasJsx(resolved, graph, effectiveFile, guard);
-            }
-            finally {
-                guard.pop(effectiveFile, t.ref.symbol);
-            }
-        }
-        case "MemberOf":
-            return hasJsx(t.obj, graph, originFile, guard);
-        default:
-            return false;
-    }
+export function classifyDeclaration(decl, graph, originFile) {
+    const fileGraph = (originFile !== undefined ? graph.files.get(originFile) : undefined) ?? syntheticFileGraph(originFile);
+    const kind = evalKind(decl.value, graph, fileGraph);
+    if (kind === "component")
+        return "component";
+    if (decl.value.kind === "Function" || decl.value.kind === "ReturnTypeOf")
+        return "helper";
+    return "unknown";
+}
+/** Tests call `classifyDeclaration(decl, graph)` with no file; give the
+ *  evaluator an empty FileGraph to resolve against. */
+function syntheticFileGraph(filePath) {
+    return {
+        filePath: filePath ?? "",
+        dialect: "react",
+        scopes: new Map([[MODULE_SCOPE, { parent: null }]]),
+        declarations: new Map(),
+        imports: [],
+        importsByLocal: new Map(),
+        exports: [],
+        jsxUsages: [],
+        tagUsages: [],
+        ownership: [],
+        bodyCalls: [],
+    };
 }
 /**
  * Three-phase build of the helper → component-callers reverse index plus
  * per-decl classification cache.
  *
- * Phase 1 (collect) walks every module-scope `Function`-valued BindingDecl
- * across the graph, collecting caller-side references from three sources:
+ * Phase 1 (collect) walks every module-scope `Function`- or
+ * `ReturnTypeOf`-valued BindingDecl across the graph (the latter is a
+ * factory's product, spec D13), collecting caller-side references from
+ * three sources:
  *
  *   1. `TypeOf` refs inside the decl's return-type expressions
  *      (`decl.value.returns`) — captures `() => helper()` shapes where the
@@ -94,7 +80,7 @@ export function hasJsx(t, graph, originFile, guard) {
  *      (the dominant React call shape) never appear as called by anyone.
  *
  * Phase 2 (classify) runs structural classification on every module-scope
- * Function decl, with a reclassification gate: a decl classified as
+ * Function- or ReturnTypeOf-valued decl, with a reclassification gate: a decl classified as
  * `"component"` but consumed only as a value (never JSX) is reclassified
  * as `"helper"`.
  *
@@ -131,11 +117,27 @@ export function buildHelperCallers(graph) {
         for (const decl of fileGraph.declarations.values()) {
             if (decl.scope !== MODULE_SCOPE)
                 continue;
-            if (decl.value.kind !== "Function")
-                continue;
             const refs = [];
-            for (const r of decl.value.returns)
-                collectRefsInType(r, refs);
+            if (decl.value.kind === "Function") {
+                for (const r of decl.value.returns)
+                    collectRefsInType(r, refs);
+            }
+            else if (decl.value.kind === "ReturnTypeOf") {
+                // A factory's product (`const Foo = withLoading(FooView)`) is a
+                // caller of the factory (spec D13), so JSX inside the factory's body
+                // fans out to each product. Only the CALLEE chain contributes — an
+                // argument is the thing being wrapped, not a value the product
+                // consumes, and must not feed the reclassification gate. Restricted
+                // to `ReturnTypeOf` specifically: D13 is about the PRODUCT OF A
+                // CALL. A bare alias (`const Item = RadioArea`, `TypeOf`) or a
+                // member alias (`const Root = Primitive.Root`, `MemberOf`) is not a
+                // call — running `collectCalleeRefs` on those would index the alias
+                // as a caller of what it aliases, flip the aliased declaration's
+                // classification to "helper" via the reclassification rule, and
+                // fan its JSX out to the alias instead of leaving it owned by the
+                // original declaration (found via the cal.diy real-consumer diff).
+                collectCalleeRefs(decl.value, refs);
+            }
             for (const bc of fileGraph.bodyCalls) {
                 if (bc.ownerSymbol === decl.symbol)
                     refs.push(bc.callee);
@@ -183,8 +185,7 @@ export function buildHelperCallers(graph) {
         }
     }
     // ── Phase 2: classify ───────────────────────────────────────────────────
-    // Structural classification, then reclassification gate. (The gate kicks
-    // in at task 3; today it's a no-op because we already cache the result.)
+    // Structural classification, then reclassification gate.
     function classifyKey(file, decl) {
         const key = `${file}::${decl.symbol}`;
         const hit = classificationCache.get(key);
@@ -199,14 +200,15 @@ export function buildHelperCallers(graph) {
         classificationCache.set(key, result);
         return result;
     }
-    // Walk every module-scope Function-valued decl so its classification lands
-    // in the cache before resolveOwnerChain runs. Non-Function decls classify
-    // lazily via the same path.
+    // Walk every module-scope Function- or ReturnTypeOf-valued decl so its
+    // classification lands in the cache before resolveOwnerChain runs (a
+    // factory's product is ReturnTypeOf-valued — spec D13). Other decls
+    // classify lazily via the same path.
     for (const [file, fileGraph] of graph.files) {
         for (const decl of fileGraph.declarations.values()) {
             if (decl.scope !== MODULE_SCOPE)
                 continue;
-            if (decl.value.kind !== "Function")
+            if (decl.value.kind !== "Function" && decl.value.kind !== "ReturnTypeOf")
                 continue;
             classifyKey(file, decl);
         }
@@ -249,6 +251,24 @@ export function buildHelperCallers(graph) {
         },
     };
 }
+/** Walk only the callee side of a value: `ReturnTypeOf.callee` chains and
+ *  `MemberOf.obj`, collecting the `TypeOf` refs that name what is being
+ *  called. Arguments are deliberately skipped (see Pass A). */
+function collectCalleeRefs(t, out) {
+    switch (t.kind) {
+        case "ReturnTypeOf":
+            collectCalleeRefs(t.callee, out);
+            return;
+        case "MemberOf":
+            collectCalleeRefs(t.obj, out);
+            return;
+        case "TypeOf":
+            out.push(t.ref);
+            return;
+        default:
+            return;
+    }
+}
 /** Walk an InferredType, collecting every `TypeOf` ref found at any depth. */
 function collectRefsInType(t, out) {
     switch (t.kind) {
@@ -295,7 +315,7 @@ function collectRefsInType(t, out) {
  *
  * Returns null for unresolved or external refs.
  */
-function resolveRefToDecl(ref, callerFile, callerGraph, graph) {
+export function resolveRefToDecl(ref, callerFile, callerGraph, graph) {
     // 1. Try the local declaration first.
     const localKey = `${MODULE_SCOPE}::${ref.symbol}`;
     const localDecl = callerGraph.declarations.get(localKey);