@component-compass/reference-graph 0.1.24 → 0.1.25

package/dist/engine/index.js

@@ -8,16 +8,16 @@ import { followReExportChain } from "./re-export-chain.js";
 import { buildHelperCallers, findLocalDeclaration } from "./helper-callers.js";
 import { resolveOwnerChain } from "./owner-resolution.js";
 import { createCycleGuard } from "./cycle-detection.js";
-import { unparsedMemberDefinition, effectiveExportName, residualMemberChain, compoundExportName } from "./member-identity.js";
-import { buildComponentRegistry, excludeFoldedHolders, excludeHostElementNames, entryKey } from "./registry.js";
+import { unparsedMemberDefinition, effectiveExportName, residualMemberChain, compoundExportName, memberOfObjectPath } from "./member-identity.js";
+import { buildComponentRegistry, excludeFoldedHolders, excludeHostElementNames, entryKey, findDeclaration } from "./registry.js";
 import { hasOnlyHostElementNames, isHostElementName, HOOK_NAME } from "./host-element.js";
 import { firstDynamicImport } from "./component-shape.js";
-import { creditedTerminals, renderOutcome } from "./denotation.js";
+import { creditedTerminals, isCallable, renderOutcome } from "./denotation.js";
 /**
- * JSX treats a bare, lowercase-initial element name as a host element
- * (`div`, `svg`, `web-button`) — it never names a binding, so it is not an
- * unresolved reference. A member chain (`motion.div`) or a capitalised name
- * is a component reference and IS reported when unbound.
+ * A bare, lowercase-initial element name (`div`, `svg`, `web-button`). On a
+ * React tag it is the host element: the tag is never evaluated, credited or
+ * reported. A member chain (`motion.div`) or a capitalised name is a
+ * component reference.
  */
 function isHostElementRoot(ref) {
     return ref.memberChain.length === 0 && isHostElementName(ref.symbol);
@@ -25,42 +25,41 @@ function isHostElementRoot(ref) {
 export function resolve(graph, opts) {
     const occurrences = [];
     const argMap = createArgumentMap();
-    // The registry is the one judge of component-ness: owner
-    // classification asks it (through the host-element narrowing, so a
-    // lowercase member is a helper for ownership while the base registry still
-    // gates the argument-site holder loop below).
-    const registry = buildComponentRegistry(graph);
+    // The walk reads no registry, owner or helper index, so every JSX tag is
+    // evaluated once here, before the registry; the registry reads the
+    // declarations the tags landed on as functions, and the render loop below
+    // reads the result.
+    const tagEvaluations = new Map();
+    for (const [filePath, fileGraph] of graph.files) {
+        tagEvaluations.set(filePath, fileGraph.jsxUsages.map((usage) => evaluateJsxUsage(graph, filePath, fileGraph, usage, argMap)));
+    }
+    // The registry is the one judge of component-ness: every declaration a
+    // tag landed on as a function is a member. Owner classification asks it
+    // (through the host-element narrowing, so a lowercase member is a helper
+    // for ownership while the base registry still gates the argument-site
+    // holder loop below).
+    const registry = buildComponentRegistry(graph, taggedDeclarations(graph, tagEvaluations));
     const helperIndex = buildHelperCallers(graph, excludeHostElementNames(registry, graph));
-    // THE admission rule (shape-only). A local
-    // react-component identity must be component-shaped; consumption is the
-    // usage itself (a JSX usage that resolves to a local declaration IS that
-    // declaration's consumption — the engine's own alias/union/dynamic-map/
-    // re-export/wrapper-fold resolution already did that work, so admission
-    // never re-derives it). Everything the registry does not type (externals,
-    // custom elements, vue-dialect declarations, workspace-member definitions
-    // outside the graph) is admitted — except a non-code file, which is never a
-    // component.
-    //
-    // A workspace-member path outside the graph (the bounded
-    // resolver pins it but never parses it — a lazy `import("./PhoneInput")`
-    // whose target file wasn't walked) is rejected only when its path HAS an
-    // extension that is provably not code (`hero.png`, `.SVG`). An
-    // extensionless path (`./PhoneInput` resolved without a suffix — the
-    // resolver's own concern, not this rule's) is admitted: it's far more
-    // likely an unwalked source file than a non-code asset, and this rule has
-    // no way to tell without walking it.
+    // THE admission rule: a local react-component identity pinned to a
+    // workspace-member path outside the graph (the bounded resolver pins it but
+    // never parses it — a lazy `import("./PhoneInput")` whose target file wasn't
+    // walked) is rejected when that path HAS an extension that is provably not
+    // code (`hero.png`, `.SVG`). An extensionless path (`./PhoneInput` resolved
+    // without a suffix — the resolver's own concern, not this rule's) is
+    // admitted: it's far more likely an unwalked source file than a non-code
+    // asset, and this rule has no way to tell without walking it. Every other
+    // identity is admitted: the evaluator decides at the tag, and argument
+    // sites and non-`callable` local tag credits ask the registry's component
+    // judge (`registryHolds`).
     const CODE_EXT = /\.(?:[cm]?[jt]sx?|vue)$/i;
     const HAS_EXT = /\.[^./\\]+$/;
     const admit = (id) => {
         if (id.kind !== "react-component" || id.source.type !== "local")
             return true;
         const { filePath } = id.source;
-        const declaring = graph.files.get(filePath);
-        if (declaring === undefined)
-            return !HAS_EXT.test(filePath) || CODE_EXT.test(filePath);
-        if (declaring.dialect === "vue")
+        if (graph.files.has(filePath))
             return true;
-        return registry.isComponentShaped(filePath, id.export);
+        return !HAS_EXT.test(filePath) || CODE_EXT.test(filePath);
     };
     // Parallel sidecar holding the per-file usage index, kind, and (pre-resolved)
     // parent-usage index for each emitted occurrence. Used in pass 2 to resolve
@@ -77,10 +76,12 @@ export function resolve(graph, opts) {
     // emit so helper-call fanout (multiple occurrences per usage) carries
     // identical composition metadata across the fan.
     //
-    // Dedup: resolveType's `Function` case flatMaps every `return`, so a
-    // referenced component whose body has N `return <JSX>` branches yields N
-    // folded terminals that all collapse to one identity — emitting N records
-    // sharing an `occurrenceId` (componentId + file + line + column + owner).
+    // Dedup: one evaluation can credit several terminals naming the same
+    // identity — a function walked as a value (an argument, a factory product
+    // the algebra flattens) yields one per `return <JSX>` branch, and a
+    // same-identity fan-out at a tag (`flag ? Card : Card`) one per branch —
+    // emitting N records sharing an `occurrenceId` (componentId + file + line +
+    // column + owner).
     // Collapsing is scoped to THIS usage's slice, so genuinely-distinct
     // cross-usage repeats that share an occurrenceId (e.g. a prop-forward
     // of one `const x = <Y/>` literal into two sibling call sites) are separate
@@ -89,7 +90,7 @@ export function resolve(graph, opts) {
     // `composition` sidecar isn't populated for this slice until the stamp loop
     // below, so the compaction only touches `occurrences`.
     // THE per-slice compaction seam (admission + dedup). Every emission
-    // path — a usage's slice via `stampComposition`, a holder's argument-site
+    // path — a usage's slice via `stampComposition`, each argument-site loop's
     // slice below — routes through it; never re-derive admission or dedup at a
     // push site.
     const compactSlice = (lengthBefore) => {
@@ -121,174 +122,21 @@ export function resolve(graph, opts) {
         }
         return occurrences.length - lengthBefore;
     };
-    const pushJsxUsageOccurrences = (filePath, fileGraph, usage, ownership) => {
-        // Resolve owner symbol ref for this usage (for composition attribution).
-        const ownerRef = ownership?.ownerSymbolRef ?? null;
-        const viaOverride = ownership?.viaOverride;
-        // 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.importsByLocal.get(usage.ref.symbol);
-        if (!matchedImport) {
-            // Symbol is locally declared (no import) — emit local identity.
-            const decl = findLocalDeclaration(fileGraph, usage.ref);
-            if (!decl)
-                return { kind: "unbound" };
-            return {
-                kind: "evaluated",
-                ...pushLocalOccurrence(occurrences, filePath, usage, decl, graph, fileGraph, argMap, ownerRef, helperIndex, opts, viaOverride),
-            };
-        }
-        const packageName = packageNameFromSpecifier(matchedImport.specifier);
-        // Resolve namespace-import members to their export name once, up front —
-        // every export-name / re-export lookup below keys on this, not the raw
-        // `imported`. `via.import` keeps the raw `imported` (provenance).
-        const effectiveImported = effectiveExportName(matchedImport.imported, usage.ref.memberChain);
-        // Lookups below key on `effectiveImported` (the ROOT); the
-        // identity stamped on a fallback is the root plus the residual chain.
-        // A member the walker resolves to its own declaration never reaches a
-        // fallback, so this only names members with no declaration of their own.
-        const residual = residualMemberChain(matchedImport.imported, usage.ref.memberChain);
-        const holderDefinition = (file, exportName) => {
-            if (residual.length === 0)
-                return undefined;
-            const loc = graph.files.get(file)?.declarations.get(`${MODULE_SCOPE}::${exportName}`)?.loc;
-            return loc === undefined ? undefined : { line: loc.line, column: loc.column };
-        };
-        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)
-                return { kind: "import-failed", specifier: matchedImport.specifier };
-            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 evaluation = walkWithFolding(graph, fileGraph, refType, argMap);
-            const jsxTerminals = creditedTerminals(evaluation);
-            if (jsxTerminals.length === 0)
-                return { kind: "evaluated", evaluation, value: refType };
-            // Determine the canonical source file + local export name. When the
-            // target is a re-export barrel (`export { X } from './source'`),
-            // follow the chain to the actual definition file so JSX edges
-            // attribute to the source rather than the barrel. Without
-            // this, two consumers importing the same component through different
-            // re-export paths fragment across phantom identities.
-            const chained = followReExportChain(graph, resolvedTarget, effectiveImported);
-            const canonicalFile = chained?.file ?? resolvedTarget;
-            let exportName = chained?.localExport ?? effectiveImported;
-            // When the re-export chain didn't follow (no chain present), still
-            // look up the local export name at the resolved target to match the
-            // local-index seed's hash convention.
-            if (!chained) {
-                const targetGraph = graph.files.get(resolvedTarget);
-                if (targetGraph && effectiveImported === "default") {
-                    const defaultExp = targetGraph.exports.find((e) => e.kind === "default");
-                    if (defaultExp && "local" in defaultExp) {
-                        exportName = defaultExp.local;
-                    }
-                }
-                else if (targetGraph) {
-                    const namedExp = targetGraph.exports.find((e) => e.kind === "named" && "exportedAs" in e && e.exportedAs === effectiveImported && "local" in e);
-                    if (namedExp && "local" in namedExp) {
-                        exportName = namedExp.local;
-                    }
-                }
-            }
-            const outerVia = viaOverride ?? {
-                kind: "direct-import",
-                specifier: matchedImport.specifier,
-                import: matchedImport.imported,
-            };
-            const fallbackComponentId = {
-                kind: componentKindFor(fileGraph.dialect),
-                export: compoundExportName(exportName, residual),
-                source: { type: "local", filePath: canonicalFile },
-            };
-            const site = usageSite(filePath, usage);
-            const owners = usageOwners(graph, helperIndex, ownerRef, viaOverride, fileGraph.filePath);
-            const definition = holderDefinition(canonicalFile, exportName);
-            for (const ft of jsxTerminals) {
-                const rawComponentId = componentIdFromIdentity(ft.identity, fallbackComponentId, fileGraph.dialect, {
-                    filePath,
-                    resolveExternalLeaf: opts?.resolveExternalLeaf,
-                });
-                emitOccurrence(occurrences, site, rawComponentId, owners, viaOverride !== undefined ? [viaOverride] : [outerVia, ...ft.viaTrail], ft.identity === null ? definition : undefined);
-            }
-            return { kind: "evaluated", evaluation, value: refType };
-        }
-        // 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);
-        if (targetInGraph) {
-            // Target file is in graph — workspace sibling. Resolve to check
-            // JSX type, fan out per terminal. The fallback identity is local so
-            // null-identity terminals still attribute to the sibling file rather
-            // than a phantom external stub. Terminal identities from deriveIdentity
-            // are already local when applicable (workspaceSiblingIdentity fires).
-            const refType = resolveReference(graph, fileGraph, usage.ref);
-            const evaluation = walkWithFolding(graph, fileGraph, refType, argMap);
-            const jsxTerminals = creditedTerminals(evaluation);
-            if (jsxTerminals.length === 0)
-                return { kind: "evaluated", evaluation, value: refType };
-            const siblingFallback = workspaceSiblingFallback(graph, resolvedNormTarget, matchedImport, effectiveImported, fileGraph.dialect);
-            const localFallback = siblingFallback !== undefined && siblingFallback.kind !== "custom-element"
-                ? { ...siblingFallback, export: compoundExportName(siblingFallback.export, residual) }
-                : siblingFallback;
-            const definition = siblingFallback !== undefined && siblingFallback.kind !== "custom-element" && siblingFallback.source.type === "local"
-                ? holderDefinition(siblingFallback.source.filePath, siblingFallback.export)
-                : undefined;
-            for (const ft of jsxTerminals) {
-                pushOccurrence(occurrences, filePath, usage, matchedImport, compoundExportName(effectiveImported, residual), packageName, graph, fileGraph, ft, ownerRef, helperIndex, opts, localFallback, viaOverride, ft.identity === null ? definition : undefined);
-            }
-            return { kind: "evaluated", evaluation, value: refType };
-        }
-        // Target not in graph. Workspace membership: a
-        // resolved target owned by a workspace member is first-party — emit
-        // LOCAL, pinned to the definition file (bounded re-export resolution)
-        // so identity is scope-invariant between whole-repo and single-app
-        // scans. Otherwise: external, trusting the JSX call site (external
-        // package or unresolvable specifier — identity null →
-        // matchedImport-based componentId). See `unparsedMemberDefinition`.
-        const member = resolvedAbsTarget !== null
-            ? unparsedMemberDefinition(graph, resolvedAbsTarget, effectiveImported)
-            : null;
-        const sentinelFt = { denotation: { kind: "foreign" }, viaTrail: [], identity: null };
-        if (member !== null) {
-            const localFallback = {
-                kind: componentKindFor(fileGraph.dialect),
-                export: compoundExportName(member.exportName, residual),
-                source: { type: "local", filePath: member.absFile },
-            };
-            pushOccurrence(occurrences, filePath, usage, matchedImport, compoundExportName(effectiveImported, residual), packageName, graph, fileGraph, sentinelFt, ownerRef, helperIndex, opts, localFallback, viaOverride);
-        }
-        else {
-            pushOccurrence(occurrences, filePath, usage, matchedImport, compoundExportName(effectiveImported, residual), packageName, graph, fileGraph, sentinelFt, ownerRef, helperIndex, opts, undefined, viaOverride);
-        }
-        return { kind: "evaluated", evaluation: [sentinelFt], value: null };
-    };
     for (const [filePath, fileGraph] of graph.files) {
+        const evaluations = tagEvaluations.get(filePath) ?? [];
         for (let usageIdx = 0; usageIdx < fileGraph.jsxUsages.length; usageIdx++) {
             const usage = fileGraph.jsxUsages[usageIdx];
-            if (!usage)
+            const evaluated = evaluations[usageIdx];
+            if (!usage || !evaluated)
                 continue;
             const ownership = fileGraph.ownership[usageIdx];
             const lengthBefore = occurrences.length;
-            const outcome = pushJsxUsageOccurrences(filePath, fileGraph, usage, ownership);
+            if (evaluated.kind === "evaluated") {
+                emitTagCredits(occurrences, graph, filePath, fileGraph, usage, ownership, evaluated.credits, helperIndex, registry, opts);
+            }
             const admitted = stampComposition(lengthBefore, "jsx", usageIdx, ownership?.depth ?? 0, ownership?.parentUsageIdx);
             if (admitted === 0)
-                reportDroppedRender(opts, filePath, fileGraph.dialect, usage, outcome);
+                reportDroppedRender(opts, filePath, fileGraph.dialect, usage, evaluated);
         }
         // Tag-usage resolution (Vue auto-imports, Lit tag-only references, HTML).
         for (let i = 0; i < fileGraph.tagUsages.length; i++) {
@@ -377,7 +225,7 @@ export function resolve(graph, opts) {
             if (foldedAway !== null)
                 folded.set(entryKey(filePath, decl.symbol), foldedAway);
             const lengthBefore = occurrences.length;
-            pushArgumentSiteOccurrences(occurrences, filePath, decl, decl.value, holderJsx, graph, fileGraph, argMap, opts);
+            pushArgumentSiteOccurrences(occurrences, filePath, decl, decl.value, holderJsx, graph, fileGraph, argMap, registry, opts);
             compactSlice(lengthBefore);
         }
     }
@@ -411,7 +259,7 @@ export function resolve(graph, opts) {
             };
             const owners = () => chainOwners(graph, helperIndex, ownerRef);
             const lengthBefore = occurrences.length;
-            pushCallArgumentOccurrences(occurrences, filePath, call, owners, graph, fileGraph, argMap, opts);
+            pushCallArgumentOccurrences(occurrences, filePath, call, owners, graph, fileGraph, argMap, registry, opts);
             compactSlice(lengthBefore);
         }
     }
@@ -685,47 +533,297 @@ function usageOwners(graph, helperIndex, ownerRef, viaOverride, fallbackFile) {
     }
     return chainOwners(graph, helperIndex, ownerRef);
 }
-function pushOccurrence(occurrences, filePath, usage, matchedImport, 
-/** Export name for the fallback identity — the root export resolved via
- *  `effectiveExportName` joined with the residual member chain via
- *  `compoundExportName`. Distinct from `matchedImport.imported`,
- *  which stays raw for `via` provenance. */
-effectiveImported, packageName, graph, fileGraph, ft, ownerRef, helperIndex, opts, fallbackOverride, viaOverride, definition) {
-    const fallback = fallbackOverride ?? {
-        kind: componentKindFor(fileGraph.dialect),
-        export: effectiveImported,
-        source: externalSource(packageName, matchedImport.specifier),
+/** A compound name (`NS.Member`) names a member of an object literal: the
+ *  holder's value, followed down `path` (`memberOfObjectPath`), is an `Object`
+ *  at every step and has the member. An empty path names the holder itself. */
+function namesObjectMember(holder, path) {
+    return path.length === 0 || memberOfObjectPath(holder, path) !== undefined;
+}
+/**
+ * Evaluate one JSX usage's tag and name each credited terminal's fallback
+ * identity, chain head and `definition`. A bare lowercase React tag is
+ * `host-element` and is not evaluated; a Vue usage's reference names a
+ * binding, so the rule does not apply to it. Every walk here is in tag
+ * position. A same-file symbol walks its declaration, or the member its member
+ * chain names; an undeclared one is `unbound`. A relative import walks the
+ * reference and falls back to the definition file behind any re-export chain;
+ * one that does not resolve is `import-failed`. A package import whose target
+ * is in the graph (a workspace sibling) walks the reference and falls back to
+ * the sibling, else the external package. A package import whose target is
+ * outside the graph is not walked: it credits a `foreign` sentinel that falls
+ * back to the workspace member's definition, else the external package. A
+ * terminal with no identity of its own is credited under a compound fallback
+ * on a local or in-graph holder only when that holder names an object member
+ * there (`namesObjectMember`).
+ */
+function evaluateJsxUsage(graph, filePath, fileGraph, usage, argMap) {
+    if (fileGraph.dialect === "react" && isHostElementRoot(usage.ref))
+        return { kind: "host-element" };
+    // 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.importsByLocal.get(usage.ref.symbol);
+    if (!matchedImport) {
+        // Symbol is locally declared (no import) — local identity.
+        const decl = findLocalDeclaration(fileGraph, usage.ref);
+        if (!decl)
+            return { kind: "unbound" };
+        // A member access on a same-file binding (`<LocalNS.Leaf/>`) walks the
+        // MEMBER, not the whole object — `resolveReference` applies the usage's
+        // member chain exactly as the import path already gets it (the same
+        // static-MemberOf arm). A bare reference is unchanged:
+        // `decl.value` is what `resolveReference` returns for an empty chain.
+        const value = usage.ref.memberChain.length > 0 ? resolveReference(graph, fileGraph, usage.ref) : decl.value;
+        const evaluation = walkWithFolding(graph, fileGraph, value, argMap, createCycleGuard(), undefined, "tag");
+        const fallback = {
+            kind: componentKindFor(fileGraph.dialect),
+            export: compoundExportName(usage.ref.symbol, usage.ref.memberChain),
+            source: { type: "local", filePath },
+        };
+        const definition = { line: decl.loc.line, column: decl.loc.column };
+        const outerVia = { kind: "local-component" };
+        const rendered = usage.ref.memberChain.length === 0 ? { declaration: decl } : {};
+        const named = namesObjectMember(decl.value, usage.ref.memberChain);
+        const credits = creditedTerminals(evaluation).filter((t) => t.identity !== null || named).map((terminal) => ({
+            terminal,
+            fallback,
+            outerVia,
+            ...(terminal.identity === null ? { definition, ...rendered } : {}),
+        }));
+        return { kind: "evaluated", evaluation, value, credits };
+    }
+    const packageName = packageNameFromSpecifier(matchedImport.specifier);
+    // Resolve namespace-import members to their export name once, up front —
+    // every export-name / re-export lookup below keys on this, not the raw
+    // `imported`. `via.import` keeps the raw `imported` (provenance).
+    const effectiveImported = effectiveExportName(matchedImport.imported, usage.ref.memberChain);
+    // Lookups below key on `effectiveImported` (the ROOT); the
+    // identity stamped on a fallback is the root plus the residual chain.
+    // A member the walker resolves to its own declaration never reaches a
+    // fallback, so this only names members with no declaration of their own.
+    const residual = residualMemberChain(matchedImport.imported, usage.ref.memberChain);
+    const holderDecl = (file, exportName) => {
+        const holderFile = graph.files.get(file);
+        return holderFile === undefined ? undefined : findDeclaration(holderFile, exportName);
     };
-    const rawComponentId = componentIdFromIdentity(ft.identity, fallback, fileGraph.dialect, {
-        filePath,
-        fallbackSpecifier: matchedImport.specifier,
-        resolveExternalLeaf: opts?.resolveExternalLeaf,
-    });
-    const outerVia = viaOverride ?? {
+    const holderDefinition = (file, exportName) => {
+        if (residual.length === 0)
+            return undefined;
+        const loc = holderDecl(file, exportName)?.loc;
+        return loc === undefined ? undefined : { line: loc.line, column: loc.column };
+    };
+    const namesHolderMember = (file, exportName) => namesObjectMember(holderDecl(file, exportName)?.value, residual);
+    const outerVia = {
         kind: "direct-import",
         specifier: matchedImport.specifier,
         import: matchedImport.imported,
     };
-    emitOccurrence(occurrences, usageSite(filePath, usage), rawComponentId, usageOwners(graph, helperIndex, ownerRef, viaOverride, filePath), viaOverride !== undefined ? [viaOverride] : [outerVia, ...ft.viaTrail], definition);
+    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)
+            return { kind: "import-failed", specifier: matchedImport.specifier };
+        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 evaluation = walkWithFolding(graph, fileGraph, refType, argMap, createCycleGuard(), undefined, "tag");
+        const jsxTerminals = creditedTerminals(evaluation);
+        if (jsxTerminals.length === 0)
+            return { kind: "evaluated", evaluation, value: refType, credits: [] };
+        // Determine the canonical source file + local export name. When the
+        // target is a re-export barrel (`export { X } from './source'`),
+        // follow the chain to the actual definition file so JSX edges
+        // attribute to the source rather than the barrel. Without
+        // this, two consumers importing the same component through different
+        // re-export paths fragment across phantom identities.
+        const chained = followReExportChain(graph, resolvedTarget, effectiveImported);
+        const canonicalFile = chained?.file ?? resolvedTarget;
+        let exportName = chained?.localExport ?? effectiveImported;
+        // When the re-export chain didn't follow (no chain present), still
+        // look up the local export name at the resolved target to match the
+        // local-index seed's hash convention.
+        if (!chained) {
+            const targetGraph = graph.files.get(resolvedTarget);
+            if (targetGraph && effectiveImported === "default") {
+                const defaultExp = targetGraph.exports.find((e) => e.kind === "default");
+                if (defaultExp && "local" in defaultExp) {
+                    exportName = defaultExp.local;
+                }
+            }
+            else if (targetGraph) {
+                const namedExp = targetGraph.exports.find((e) => e.kind === "named" && "exportedAs" in e && e.exportedAs === effectiveImported && "local" in e);
+                if (namedExp && "local" in namedExp) {
+                    exportName = namedExp.local;
+                }
+            }
+        }
+        const fallback = {
+            kind: componentKindFor(fileGraph.dialect),
+            export: compoundExportName(exportName, residual),
+            source: { type: "local", filePath: canonicalFile },
+        };
+        const definition = holderDefinition(canonicalFile, exportName);
+        const named = namesHolderMember(canonicalFile, exportName);
+        const credits = jsxTerminals.filter((t) => t.identity !== null || named).map((terminal) => ({
+            terminal,
+            fallback,
+            outerVia,
+            ...(terminal.identity === null && definition !== undefined ? { definition } : {}),
+        }));
+        return { kind: "evaluated", evaluation, value: refType, credits };
+    }
+    const externalFallback = {
+        kind: componentKindFor(fileGraph.dialect),
+        export: compoundExportName(effectiveImported, residual),
+        source: externalSource(packageName, matchedImport.specifier),
+    };
+    // 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);
+    if (targetInGraph) {
+        // Target file is in graph — workspace sibling. Resolve to check
+        // JSX type, fan out per terminal. The fallback identity is local so
+        // null-identity terminals still attribute to the sibling file rather
+        // than a phantom external stub. Terminal identities from deriveIdentity
+        // are already local when applicable (workspaceSiblingIdentity fires).
+        const refType = resolveReference(graph, fileGraph, usage.ref);
+        const evaluation = walkWithFolding(graph, fileGraph, refType, argMap, createCycleGuard(), undefined, "tag");
+        const jsxTerminals = creditedTerminals(evaluation);
+        if (jsxTerminals.length === 0)
+            return { kind: "evaluated", evaluation, value: refType, credits: [] };
+        const siblingFallback = workspaceSiblingFallback(graph, resolvedNormTarget, matchedImport, effectiveImported, fileGraph.dialect);
+        const localFallback = siblingFallback !== undefined && siblingFallback.kind !== "custom-element"
+            ? { ...siblingFallback, export: compoundExportName(siblingFallback.export, residual) }
+            : siblingFallback;
+        const localHolder = siblingFallback !== undefined && siblingFallback.kind !== "custom-element" && siblingFallback.source.type === "local"
+            ? { filePath: siblingFallback.source.filePath, exportName: siblingFallback.export }
+            : undefined;
+        const definition = localHolder === undefined ? undefined : holderDefinition(localHolder.filePath, localHolder.exportName);
+        const named = localHolder === undefined || namesHolderMember(localHolder.filePath, localHolder.exportName);
+        const fallback = localFallback ?? externalFallback;
+        const credits = jsxTerminals.filter((t) => t.identity !== null || named).map((terminal) => ({
+            terminal,
+            fallback,
+            fallbackSpecifier: matchedImport.specifier,
+            outerVia,
+            ...(terminal.identity === null && definition !== undefined ? { definition } : {}),
+        }));
+        return { kind: "evaluated", evaluation, value: refType, credits };
+    }
+    // Target not in graph. Workspace membership: a
+    // resolved target owned by a workspace member is first-party — credit
+    // LOCAL, pinned to the definition file (bounded re-export resolution)
+    // so identity is scope-invariant between whole-repo and single-app
+    // scans. Otherwise: external, trusting the JSX call site (external
+    // package or unresolvable specifier — identity null →
+    // matchedImport-based componentId). See `unparsedMemberDefinition`.
+    const member = resolvedAbsTarget !== null
+        ? unparsedMemberDefinition(graph, resolvedAbsTarget, effectiveImported)
+        : null;
+    const sentinel = { denotation: { kind: "foreign" }, viaTrail: [], identity: null };
+    const fallback = member !== null
+        ? {
+            kind: componentKindFor(fileGraph.dialect),
+            export: compoundExportName(member.exportName, residual),
+            source: { type: "local", filePath: member.absFile },
+        }
+        : externalFallback;
+    return {
+        kind: "evaluated",
+        evaluation: [sentinel],
+        value: null,
+        credits: [{ terminal: sentinel, fallback, fallbackSpecifier: matchedImport.specifier, outerVia }],
+    };
+}
+/** The declaration a credit carries: its identity's tag-position stamp, else
+ *  the render site's own binding for a credit with no identity. */
+function carriedDeclaration(credit) {
+    const { identity } = credit.terminal;
+    if (identity === null)
+        return credit.declaration;
+    return identity.kind === "local" ? identity.declaration : undefined;
+}
+/** Every local declaration a tag's walk landed on as a function: the
+ *  terminal's own identity, else the render site's fallback, named exactly as
+ *  the render loop names it, with the declaration the identity's stamp or the
+ *  render site resolved when there is one. */
+function taggedDeclarations(graph, tagEvaluations) {
+    const tagged = [];
+    for (const [filePath, evaluations] of tagEvaluations) {
+        const dialect = dialectForFile(graph, filePath);
+        for (const evaluated of evaluations) {
+            if (evaluated.kind !== "evaluated")
+                continue;
+            for (const credit of evaluated.credits) {
+                if (!isCallable(credit.terminal))
+                    continue;
+                const { identity } = credit.terminal;
+                const id = buildComponentId(identity, credit.fallback, dialect);
+                if (id.kind === "react-component" && id.source.type === "local") {
+                    const declaration = carriedDeclaration(credit);
+                    tagged.push({ filePath: id.source.filePath, exportName: id.export, ...(declaration !== undefined ? { declaration } : {}) });
+                }
+            }
+        }
+    }
+    return tagged;
+}
+/** Push one usage's credited terminals: one occurrence per credit × owner,
+ *  through the external-leaf relabel seam and `emitOccurrence`. A credit that
+ *  is not `callable` is pushed only when `registryHolds` its identity, a
+ *  `callable` one only when `registryTagged` its identity. */
+function emitTagCredits(occurrences, graph, filePath, fileGraph, usage, ownership, credits, helperIndex, registry, opts) {
+    if (credits.length === 0)
+        return;
+    const viaOverride = ownership?.viaOverride;
+    const site = usageSite(filePath, usage);
+    const owners = usageOwners(graph, helperIndex, ownership?.ownerSymbolRef ?? null, viaOverride, filePath);
+    for (const credit of credits) {
+        const rawComponentId = componentIdFromIdentity(credit.terminal.identity, credit.fallback, fileGraph.dialect, {
+            filePath,
+            ...(credit.fallbackSpecifier !== undefined ? { fallbackSpecifier: credit.fallbackSpecifier } : {}),
+            resolveExternalLeaf: opts?.resolveExternalLeaf,
+        });
+        const declaration = carriedDeclaration(credit);
+        const stands = isCallable(credit.terminal)
+            ? registryTagged(registry, graph, rawComponentId, declaration)
+            : registryHolds(registry, graph, rawComponentId, declaration);
+        if (!stands)
+            continue;
+        emitOccurrence(occurrences, site, rawComponentId, owners, viaOverride !== undefined ? [viaOverride] : [credit.outerVia, ...credit.terminal.viaTrail], credit.definition);
+    }
 }
 /**
  * The one reporter for a JSX usage that produced no occurrence. A host-element
- * root reports nothing. A failed import is `unresolved-import`, an unbound root
+ * tag reports nothing. A failed import is `unresolved-import`, an unbound root
  * `unresolved-reference`. A walked value holding an `import()` is
  * `lazy-import-unsupported`, naming the file the `import()` is declared in when
  * that is not the render file; the `import()` in the walked value is checked
  * before the evaluation. Everything the evaluation itself decides
  * is `renderOutcome`'s: a value that is not a component reports nothing, a
  * value supplied elsewhere reports `late-bound-render`, and anything else —
- * including a credit whose occurrences admission rejected (#544: one occurrence
- * or one diagnostic) — reports `unresolved-reference`. A non-react dialect
+ * including a credit the registry's judge, its tagged membership or admission
+ * rejected (#544: one occurrence or one diagnostic) — reports
+ * `unresolved-reference`. A non-react dialect
  * reports only the import codes (#621).
  */
 function reportDroppedRender(opts, filePath, dialect, usage, outcome) {
     const collector = opts?.collector;
     if (collector === undefined)
         return;
-    if (isHostElementRoot(usage.ref))
+    if (outcome.kind === "host-element")
         return;
     const at = { filePath, line: usage.loc.line, column: usage.loc.column };
     const positional = { ...at, symbol: usage.ref.symbol, memberChain: [...usage.ref.memberChain] };
@@ -759,39 +857,6 @@ function reportDroppedRender(opts, filePath, dialect, usage, outcome) {
     }
     collector.emit({ code: decided.code, severity: "info", ...positional });
 }
-/**
- * Push local-scope occurrences for a symbol declared in the same file (no import).
- * Walks the decl's value via walkWithFolding and fans out per JSX terminal.
- */
-function pushLocalOccurrence(occurrences, filePath, usage, decl, graph, fileGraph, argMap, ownerRef, helperIndex, opts, viaOverride) {
-    // A member access on a same-file binding (`<LocalNS.Leaf/>`) walks the
-    // MEMBER, not the whole object — `resolveReference` applies the usage's
-    // member chain exactly as the import path already gets it (the same
-    // static-MemberOf arm). A bare reference is unchanged:
-    // `decl.value` is what `resolveReference` returns for an empty chain.
-    const value = usage.ref.memberChain.length > 0 ? resolveReference(graph, fileGraph, usage.ref) : decl.value;
-    const evaluation = walkWithFolding(graph, fileGraph, value, argMap);
-    const jsxTerminals = creditedTerminals(evaluation);
-    if (jsxTerminals.length === 0)
-        return { evaluation, value };
-    const outerVia = viaOverride ?? { kind: "local-component" };
-    const site = usageSite(filePath, usage);
-    const owners = usageOwners(graph, helperIndex, ownerRef, viaOverride, fileGraph.filePath);
-    const fallback = {
-        kind: componentKindFor(fileGraph.dialect),
-        export: compoundExportName(usage.ref.symbol, usage.ref.memberChain),
-        source: { type: "local", filePath },
-    };
-    const definition = { line: decl.loc.line, column: decl.loc.column };
-    for (const ft of jsxTerminals) {
-        const rawComponentId = componentIdFromIdentity(ft.identity, fallback, fileGraph.dialect, {
-            filePath,
-            resolveExternalLeaf: opts?.resolveExternalLeaf,
-        });
-        emitOccurrence(occurrences, site, rawComponentId, owners, viaOverride !== undefined ? [viaOverride] : [outerVia, ...ft.viaTrail], ft.identity === null ? definition : undefined);
-    }
-    return { evaluation, value };
-}
 /**
  * A holder is folded away iff its fold reaches JSX and EVERY JSX
  * terminal carries an identity — the fold credited someone else for every
@@ -821,7 +886,7 @@ function foldedHolder(holderJsx, filePath) {
  * the same helper `hoc-wrapper` uses. The caller compacts the slice
  * (admission + dedup).
  */
-function pushArgumentSiteOccurrences(occurrences, filePath, holder, call, holderJsx, graph, fileGraph, argMap, opts, depth = 0) {
+function pushArgumentSiteOccurrences(occurrences, filePath, holder, call, holderJsx, graph, fileGraph, argMap, registry, opts, depth = 0) {
     // The holder is its own identity iff its fold reaches JSX and no
     // terminal carries an identity of its own OR a `hoc-wrapper` hop — the hop
     // is the fold's own record that it credited an argument,
@@ -838,7 +903,7 @@ function pushArgumentSiteOccurrences(occurrences, filePath, holder, call, holder
         if (folded?.arg.kind !== "ReturnTypeOf")
             return;
         const innerJsx = creditedTerminals(walkWithFolding(graph, fileGraph, folded.arg, argMap));
-        pushArgumentSiteOccurrences(occurrences, filePath, holder, folded.arg, innerJsx, graph, fileGraph, argMap, opts, depth + 1);
+        pushArgumentSiteOccurrences(occurrences, filePath, holder, folded.arg, innerJsx, graph, fileGraph, argMap, registry, opts, depth + 1);
         return;
     }
     if (shape !== "product")
@@ -857,7 +922,7 @@ function pushArgumentSiteOccurrences(occurrences, filePath, holder, call, holder
     const rawOwnerComponentId = hasOnlyHostElementNames(holder.symbol, fileGraph)
         ? undefined
         : ownerIdFromRef(graph, holderRef, filePath);
-    pushCallArgumentOccurrences(occurrences, filePath, call, () => [{ rawOwnerComponentId, viaPrefix: [] }], graph, fileGraph, argMap, opts, depth);
+    pushCallArgumentOccurrences(occurrences, filePath, call, () => [{ rawOwnerComponentId, viaPrefix: [] }], graph, fileGraph, argMap, registry, opts, depth);
 }
 /** Calls below the outermost one that argument seeding descends through. */
 const MAX_ARGUMENT_CALL_DEPTH = 2;
@@ -876,6 +941,30 @@ function callFoldShape(jsx) {
         return "product";
     return credited === jsx.length ? "wrapper" : null;
 }
+/** A local identity declared in a parsed React-dialect file is a component
+ *  only when the registry's judge says its declaration is one (`declaration`
+ *  when the credit carries it); the declaring file's dialect decides, not the
+ *  identity's kind. Any other identity is not the registry's to judge. */
+function registryHolds(registry, graph, id, declaration) {
+    if (id.kind === "custom-element" || id.source.type !== "local")
+        return true;
+    if (graph.files.get(id.source.filePath)?.dialect !== "react")
+        return true;
+    return registry.isComponent(id.source.filePath, id.export, declaration);
+}
+/** A local, non-compound `react-component` identity declared in a parsed
+ *  React-dialect file is what a `callable` credit names only when tagged
+ *  membership marked a declaration for it (`isTagged`, `declaration` when the
+ *  credit carries it). Any other identity is not the registry's to judge. */
+function registryTagged(registry, graph, id, declaration) {
+    if (id.kind !== "react-component" || id.source.type !== "local")
+        return true;
+    if (graph.files.get(id.source.filePath)?.dialect !== "react")
+        return true;
+    if (parseCompoundExport(id.export).isCompound)
+        return true;
+    return registry.isTagged(id.source.filePath, id.export, declaration);
+}
 /**
  * THE argument-site push seam: one `passed-as-argument` occurrence per
  * (identifier argument that resolves to a component) × (owner). The
@@ -891,7 +980,8 @@ function callFoldShape(jsx) {
  * rendered as a component, whatever it resolves to — an external leaf has
  * no shape to check and would otherwise synthesise a component out of any
  * import; the same predicate the held-reference seam and the roster naming
- * gate apply.
+ * gate apply. A local identity declared in a React file is seeded only when
+ * the registry's component judge accepts its declaration (`registryHolds`).
  *
  * A call-valued argument is followed by what its own fold says
  * (`callFoldShape`), at most `MAX_ARGUMENT_CALL_DEPTH` calls below the
@@ -906,7 +996,7 @@ function callFoldShape(jsx) {
  * the owner chain for each of them measured as roughly half of the hook
  * loop's scan-time cost on a large consumer repo.
  */
-function pushCallArgumentOccurrences(occurrences, filePath, call, owners, graph, fileGraph, argMap, opts, depth = 0) {
+function pushCallArgumentOccurrences(occurrences, filePath, call, owners, graph, fileGraph, argMap, registry, opts, depth = 0) {
     let resolvedOwners;
     const seedIdentifier = (site, index, arg, hops) => {
         if (isHostElementName(arg.ref.symbol))
@@ -924,6 +1014,8 @@ function pushCallArgumentOccurrences(occurrences, filePath, call, owners, graph,
                 filePath,
                 resolveExternalLeaf: opts?.resolveExternalLeaf,
             });
+            if (!registryHolds(registry, graph, rawComponentId))
+                continue;
             resolvedOwners ??= owners();
             emitOccurrence(occurrences, { filePath, line: arg.ref.loc.line, column: arg.ref.loc.column, props: {}, events: [] }, rawComponentId, resolvedOwners, [outerVia, ...hops, ...ft.viaTrail], argDecl !== null ? { line: argDecl.loc.line, column: argDecl.loc.column } : undefined);
         }