@component-compass/reference-graph 0.1.22 → 0.1.24

package/dist/engine/index.js

@@ -10,8 +10,9 @@ 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 { hasOnlyHostElementNames, isHostElementName } from "./host-element.js";
+import { hasOnlyHostElementNames, isHostElementName, HOOK_NAME } from "./host-element.js";
 import { firstDynamicImport } from "./component-shape.js";
+import { creditedTerminals, 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
@@ -118,238 +119,176 @@ export function resolve(graph, opts) {
                 ? { fileUsageIdx, kind, parentUsageIdx }
                 : { fileUsageIdx, kind };
         }
+        return occurrences.length - lengthBefore;
     };
-    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;
-            const viaOverride = fileGraph.ownership[usageIdx]?.viaOverride;
-            const jsxDepth = fileGraph.ownership[usageIdx]?.depth ?? 0;
-            const jsxParentUsageIdx = fileGraph.ownership[usageIdx]?.parentUsageIdx;
-            const jsxLengthBefore = occurrences.length;
-            // 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) {
-                    if (!isHostElementRoot(usage.ref)) {
-                        // No import record and no declaration in scope: the engine cannot
-                        // attribute this usage. Surface it instead of
-                        // dropping it silently — `info`, because the usual cause is a
-                        // global or macro-provided binding the scan cannot see.
-                        opts?.collector?.emit({
-                            code: "unresolved-reference",
-                            severity: "info",
-                            filePath,
-                            line: usage.loc.line,
-                            column: usage.loc.column,
-                            symbol: usage.ref.symbol,
-                            memberChain: [...usage.ref.memberChain],
-                        });
-                    }
-                    continue;
-                }
-                pushLocalOccurrence(occurrences, filePath, usage, decl, graph, fileGraph, argMap, ownerRef, helperIndex, opts, viaOverride);
-                stampComposition(jsxLengthBefore, "jsx", usageIdx, jsxDepth, jsxParentUsageIdx);
-                continue;
-            }
-            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);
-            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) {
-                    // A JSX usage whose import failed to resolve is a dropped local
-                    // reference — surface it instead of vanishing.
-                    opts?.collector?.emit({
-                        code: "unresolved-import",
-                        severity: "warning",
-                        filePath,
-                        line: usage.loc.line,
-                        column: usage.loc.column,
-                        specifier: matchedImport.specifier,
-                    });
-                    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 folded = walkWithFolding(graph, fileGraph, refType, argMap);
-                const jsxTerminals = folded.filter((t) => t.type.kind === "JSX");
-                if (jsxTerminals.length === 0) {
-                    emitLazyImportUnsupported(opts, filePath, usage.loc, refType);
-                    continue;
-                }
-                // 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 },
-                };
-                if (viaOverride !== undefined) {
-                    // Prop-forward: parser has pre-decided the owner — single-occurrence path.
-                    const rawOwnerComponentId = ownerIdFromRef(graph, ownerRef, fileGraph.filePath);
-                    for (const ft of jsxTerminals) {
-                        const rawComponentId = componentIdFromIdentity(ft.identity, fallbackComponentId, fileGraph.dialect, {
-                            filePath,
-                            resolveExternalLeaf: opts?.resolveExternalLeaf,
-                        });
-                        const viaChain = [viaOverride];
-                        const provisionalId = serialiseComponentId(rawComponentId);
-                        const occurrenceId = computeOccurrenceId(provisionalId, filePath, usage.loc.line, usage.loc.column, rawOwnerComponentId !== undefined ? serialiseComponentId(rawOwnerComponentId) : undefined);
-                        occurrences.push({
-                            rawComponentId,
-                            filePath,
-                            line: usage.loc.line,
-                            column: usage.loc.column,
-                            via: viaChain[0] ?? outerVia,
-                            viaChain,
-                            props: projectPropUsages(usage.props),
-                            events: usage.events ?? [],
-                            occurrenceId,
-                            depth: 0,
-                            ...(rawOwnerComponentId !== undefined ? { rawOwnerComponentId } : {}),
-                        });
-                    }
-                }
-                else {
-                    // Helper-call fanout: resolve owner chain and emit per (terminal × resolution).
-                    const ownerResolutions = resolveOwnerChain(ownerRef, graph, helperIndex, createCycleGuard());
-                    for (const ft of jsxTerminals) {
-                        const rawComponentId = componentIdFromIdentity(ft.identity, fallbackComponentId, fileGraph.dialect, {
-                            filePath,
-                            resolveExternalLeaf: opts?.resolveExternalLeaf,
-                        });
-                        for (const res of ownerResolutions) {
-                            const rawOwnerComponentId = ownerIdFromResolution(graph, res.ownerDecl);
-                            const viaChain = [...res.viaPrefix, outerVia, ...ft.viaTrail];
-                            const provisionalId = serialiseComponentId(rawComponentId);
-                            const occurrenceId = computeOccurrenceId(provisionalId, filePath, usage.loc.line, usage.loc.column, rawOwnerComponentId !== undefined ? serialiseComponentId(rawOwnerComponentId) : undefined);
-                            occurrences.push({
-                                rawComponentId,
-                                filePath,
-                                line: usage.loc.line,
-                                column: usage.loc.column,
-                                via: viaChain[0] ?? outerVia,
-                                viaChain,
-                                props: projectPropUsages(usage.props),
-                                events: usage.events ?? [],
-                                occurrenceId,
-                                depth: 0,
-                                ...(rawOwnerComponentId !== undefined ? { rawOwnerComponentId } : {}),
-                            });
-                        }
-                    }
-                }
-                stampComposition(jsxLengthBefore, "jsx", usageIdx, jsxDepth, jsxParentUsageIdx);
-                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 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);
-            // Normalize absolute path → repo-relative graph key when possible.
-            const resolvedNormTarget = resolvedAbsTarget !== null && graph.resolveToGraphKey
+            if (!resolvedAbsTarget)
+                return { kind: "import-failed", specifier: matchedImport.specifier };
+            const resolvedTarget = 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 foldedTerminals = walkWithFolding(graph, fileGraph, refType, argMap);
-                const jsxTerminals = foldedTerminals.filter((t) => t.type.kind === "JSX");
-                if (jsxTerminals.length === 0) {
-                    emitLazyImportUnsupported(opts, filePath, usage.loc, refType);
-                    continue;
+            // 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;
+                    }
                 }
-                const siblingFallback = workspaceSiblingFallback(graph, resolvedNormTarget, matchedImport, effectiveImported, fileGraph.dialect);
-                const localFallback = siblingFallback !== undefined && siblingFallback.kind !== "custom-element"
-                    ? { ...siblingFallback, export: compoundExportName(siblingFallback.export, residual) }
-                    : siblingFallback;
-                for (const ft of jsxTerminals) {
-                    pushOccurrence(occurrences, filePath, usage, matchedImport, compoundExportName(effectiveImported, residual), packageName, graph, fileGraph, ft, ownerRef, helperIndex, opts, localFallback, viaOverride);
+                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;
+                    }
                 }
             }
-            else {
-                // 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 = { type: { kind: "JSX" }, 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);
-                }
+            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);
             }
-            stampComposition(jsxLengthBefore, "jsx", usageIdx, jsxDepth, jsxParentUsageIdx);
+            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) {
+        for (let usageIdx = 0; usageIdx < fileGraph.jsxUsages.length; usageIdx++) {
+            const usage = fileGraph.jsxUsages[usageIdx];
+            if (!usage)
+                continue;
+            const ownership = fileGraph.ownership[usageIdx];
+            const lengthBefore = occurrences.length;
+            const outcome = pushJsxUsageOccurrences(filePath, fileGraph, usage, ownership);
+            const admitted = stampComposition(lengthBefore, "jsx", usageIdx, ownership?.depth ?? 0, ownership?.parentUsageIdx);
+            if (admitted === 0)
+                reportDroppedRender(opts, filePath, fileGraph.dialect, usage, outcome);
         }
         // Tag-usage resolution (Vue auto-imports, Lit tag-only references, HTML).
         for (let i = 0; i < fileGraph.tagUsages.length; i++) {
@@ -433,7 +372,7 @@ export function resolve(graph, opts) {
                 continue;
             if (!registry.hasLocal(filePath, decl.symbol))
                 continue;
-            const holderJsx = walkWithFolding(graph, fileGraph, decl.value, argMap).filter((t) => t.type.kind === "JSX");
+            const holderJsx = creditedTerminals(walkWithFolding(graph, fileGraph, decl.value, argMap));
             const foldedAway = foldedHolder(holderJsx, filePath);
             if (foldedAway !== null)
                 folded.set(entryKey(filePath, decl.symbol), foldedAway);
@@ -470,10 +409,7 @@ export function resolve(graph, opts) {
                 loc: { line: 0, column: 0 },
                 originFile: filePath,
             };
-            const owners = () => resolveOwnerChain(ownerRef, graph, helperIndex, createCycleGuard()).map((res) => ({
-                rawOwnerComponentId: ownerIdFromResolution(graph, res.ownerDecl),
-                viaPrefix: res.viaPrefix,
-            }));
+            const owners = () => chainOwners(graph, helperIndex, ownerRef);
             const lengthBefore = occurrences.length;
             pushCallArgumentOccurrences(occurrences, filePath, call, owners, graph, fileGraph, argMap, opts);
             compactSlice(lengthBefore);
@@ -696,29 +632,65 @@ effectiveImported, consumerDialect) {
     };
 }
 /**
- * Derive the `wraps` cross-link for a given component identity by calling the
- * optional `wrapCallback`. Only fires for external react-component identities —
- * local components are user-written code, not wrappers. Returns undefined when
- * the callback is absent, returns null, or the identity is not an external
- * react-component.
+ * THE occurrence constructor: one occurrence per owner, `viaChain` being the
+ * owner's prefix followed by `chain`. Every emission path calls it; never
+ * build an `EngineOccurrence` literal anywhere else. The `occurrenceId` it
+ * computes is provisional, keyed on the serialised componentId; scan.ts
+ * re-derives it from the hashed componentId.
  */
-function computeWraps(rawComponentId, wrapCallback) {
-    if (wrapCallback === undefined ||
-        rawComponentId.kind !== "react-component" ||
-        rawComponentId.source.type !== "external") {
-        return undefined;
+function emitOccurrence(occurrences, site, rawComponentId, owners, chain, definition) {
+    const provisionalId = serialiseComponentId(rawComponentId);
+    for (const { rawOwnerComponentId, viaPrefix } of owners) {
+        const viaChain = [...viaPrefix, ...chain];
+        occurrences.push({
+            rawComponentId,
+            filePath: site.filePath,
+            line: site.line,
+            column: site.column,
+            via: viaChain[0] ?? chain[0],
+            viaChain,
+            props: site.props,
+            events: site.events,
+            occurrenceId: computeOccurrenceId(provisionalId, site.filePath, site.line, site.column, rawOwnerComponentId !== undefined ? serialiseComponentId(rawOwnerComponentId) : undefined),
+            depth: 0,
+            ...(definition !== undefined ? { definition } : {}),
+            ...(rawOwnerComponentId !== undefined ? { rawOwnerComponentId } : {}),
+        });
     }
-    const hit = wrapCallback(rawComponentId.source.package, rawComponentId.export);
-    if (!hit)
-        return undefined;
-    return { kind: "custom-element", tagName: hit.tagName, packageName: hit.packageName };
+}
+function usageSite(filePath, usage) {
+    return {
+        filePath,
+        line: usage.loc.line,
+        column: usage.loc.column,
+        props: projectPropUsages(usage.props),
+        events: usage.events ?? [],
+    };
+}
+/** The owner chain of `ownerRef`, one owner per resolution with its `helper-call` prefix. */
+function chainOwners(graph, helperIndex, ownerRef) {
+    return resolveOwnerChain(ownerRef, graph, helperIndex, createCycleGuard()).map((res) => ({
+        rawOwnerComponentId: ownerIdFromResolution(graph, res.ownerDecl),
+        viaPrefix: res.viaPrefix,
+    }));
+}
+/**
+ * Owners of a JSX usage. A `viaOverride` means the parser pre-decided the
+ * owner (prop-forward): one owner, no prefix. Otherwise the owner chain fans
+ * out, each resolution contributing its `helper-call` prefix.
+ */
+function usageOwners(graph, helperIndex, ownerRef, viaOverride, fallbackFile) {
+    if (viaOverride !== undefined) {
+        return [{ rawOwnerComponentId: ownerIdFromRef(graph, ownerRef, fallbackFile), viaPrefix: [] }];
+    }
+    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) {
+effectiveImported, packageName, graph, fileGraph, ft, ownerRef, helperIndex, opts, fallbackOverride, viaOverride, definition) {
     const fallback = fallbackOverride ?? {
         kind: componentKindFor(fileGraph.dialect),
         export: effectiveImported,
@@ -729,82 +701,63 @@ effectiveImported, packageName, graph, fileGraph, ft, ownerRef, helperIndex, opt
         fallbackSpecifier: matchedImport.specifier,
         resolveExternalLeaf: opts?.resolveExternalLeaf,
     });
-    // Derive wraps cross-link for external react-component occurrences.
-    // wrapCallback only fires for external packages — local react-components are
-    // user-written, not wrappers. Does NOT affect rawComponentId or hashing.
-    const wraps = computeWraps(rawComponentId, opts?.wrapCallback);
     const outerVia = viaOverride ?? {
         kind: "direct-import",
         specifier: matchedImport.specifier,
         import: matchedImport.imported,
     };
-    if (viaOverride !== undefined) {
-        // Prop-forward: parser has pre-decided the owner — single-occurrence path.
-        const rawOwnerComponentId = ownerIdFromRef(graph, ownerRef, filePath);
-        const viaChain = [viaOverride];
-        const provisionalId = serialiseComponentId(rawComponentId);
-        const occurrenceId = computeOccurrenceId(provisionalId, filePath, usage.loc.line, usage.loc.column, rawOwnerComponentId !== undefined ? serialiseComponentId(rawOwnerComponentId) : undefined);
-        occurrences.push({
-            rawComponentId,
-            filePath,
-            line: usage.loc.line,
-            column: usage.loc.column,
-            via: viaChain[0] ?? outerVia,
-            viaChain,
-            props: projectPropUsages(usage.props),
-            events: usage.events ?? [],
-            occurrenceId,
-            depth: 0,
-            ...(rawOwnerComponentId !== undefined ? { rawOwnerComponentId } : {}),
-            ...(wraps !== undefined ? { wraps } : {}),
-        });
+    emitOccurrence(occurrences, usageSite(filePath, usage), rawComponentId, usageOwners(graph, helperIndex, ownerRef, viaOverride, filePath), viaOverride !== undefined ? [viaOverride] : [outerVia, ...ft.viaTrail], 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
+ * `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
+ * 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))
+        return;
+    const at = { filePath, line: usage.loc.line, column: usage.loc.column };
+    const positional = { ...at, symbol: usage.ref.symbol, memberChain: [...usage.ref.memberChain] };
+    if (outcome.kind === "import-failed") {
+        collector.emit({ code: "unresolved-import", severity: "warning", ...at, specifier: outcome.specifier });
         return;
     }
-    // Helper-call fanout: resolve owner chain and emit per resolution.
-    const ownerResolutions = resolveOwnerChain(ownerRef, graph, helperIndex, createCycleGuard());
-    for (const res of ownerResolutions) {
-        const rawOwnerComponentId = ownerIdFromResolution(graph, res.ownerDecl);
-        const viaChain = [...res.viaPrefix, outerVia, ...ft.viaTrail];
-        // 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, rawOwnerComponentId !== undefined ? serialiseComponentId(rawOwnerComponentId) : undefined);
-        occurrences.push({
-            rawComponentId,
-            filePath,
-            line: usage.loc.line,
-            column: usage.loc.column,
-            via: viaChain[0] ?? outerVia,
-            viaChain,
-            props: projectPropUsages(usage.props),
-            events: usage.events ?? [],
-            occurrenceId,
-            depth: 0,
-            ...(rawOwnerComponentId !== undefined ? { rawOwnerComponentId } : {}),
-            ...(wraps !== undefined ? { wraps } : {}),
+    if (outcome.kind === "unbound") {
+        collector.emit({ code: "unresolved-reference", severity: "info", ...positional });
+        return;
+    }
+    const di = outcome.value === null ? null : firstDynamicImport(outcome.value);
+    if (di) {
+        collector.emit({
+            code: "lazy-import-unsupported",
+            severity: "warning",
+            ...at,
+            specifier: di.specifier,
+            detail: `the import() target could not be resolved to a component${di.originFile === filePath ? "" : ` (declared in ${di.originFile})`}`,
         });
+        return;
     }
-}
-/**
- * A fold that reached no JSX while an import() sits in the walked value is a
- * lazy shape the pipeline could not resolve to a component: a `.then` callback
- * that does more than pick a property, or a target whose component shape could
- * not be confirmed. Report it at the render site so the miss is visible, and
- * name the file the `import()` is declared in when that is not the render file.
- */
-function emitLazyImportUnsupported(opts, filePath, loc, value) {
-    const di = opts?.collector ? firstDynamicImport(value) : null;
-    if (!di)
+    const decided = renderOutcome(outcome.evaluation);
+    if (decided.kind === "silent")
         return;
-    opts?.collector?.emit({
-        code: "lazy-import-unsupported",
-        severity: "warning",
-        filePath,
-        line: loc.line,
-        column: loc.column,
-        specifier: di.specifier,
-        detail: `the import() target could not be resolved to a component${di.originFile === filePath ? "" : ` (declared in ${di.originFile})`}`,
-    });
+    if (dialect !== "react")
+        return;
+    if (decided.kind === "credit") {
+        collector.emit({ code: "unresolved-reference", severity: "info", ...positional });
+        return;
+    }
+    collector.emit({ code: decided.code, severity: "info", ...positional });
 }
 /**
  * Push local-scope occurrences for a symbol declared in the same file (no import).
@@ -817,82 +770,27 @@ function pushLocalOccurrence(occurrences, filePath, usage, decl, graph, fileGrap
     // 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 folded = walkWithFolding(graph, fileGraph, value, argMap);
-    const jsxTerminals = folded.filter((t) => t.type.kind === "JSX");
-    // A reference that resolves to no JSX terminal — a function parameter
-    // (`<Component/>` inside a factory body), a hook-return destructure, or an
-    // unresolvable alias — emits no occurrence.
-    if (jsxTerminals.length === 0) {
-        emitLazyImportUnsupported(opts, filePath, usage.loc, value);
-        return;
-    }
+    const evaluation = walkWithFolding(graph, fileGraph, value, argMap);
+    const jsxTerminals = creditedTerminals(evaluation);
+    if (jsxTerminals.length === 0)
+        return { evaluation, value };
     const outerVia = viaOverride ?? { kind: "local-component" };
-    if (viaOverride !== undefined) {
-        // Prop-forward: parser has pre-decided the owner — single-occurrence path.
-        const rawOwnerComponentId = ownerIdFromRef(graph, ownerRef, fileGraph.filePath);
-        for (const ft of jsxTerminals) {
-            const fallback = {
-                kind: componentKindFor(fileGraph.dialect),
-                export: compoundExportName(usage.ref.symbol, usage.ref.memberChain),
-                source: { type: "local", filePath },
-            };
-            const rawComponentId = componentIdFromIdentity(ft.identity, fallback, fileGraph.dialect, {
-                filePath,
-                resolveExternalLeaf: opts?.resolveExternalLeaf,
-            });
-            const viaChain = [viaOverride];
-            const provisionalId = serialiseComponentId(rawComponentId);
-            const occurrenceId = computeOccurrenceId(provisionalId, filePath, usage.loc.line, usage.loc.column, rawOwnerComponentId !== undefined ? serialiseComponentId(rawOwnerComponentId) : undefined);
-            occurrences.push({
-                rawComponentId,
-                filePath,
-                line: usage.loc.line,
-                column: usage.loc.column,
-                via: viaChain[0] ?? outerVia,
-                viaChain,
-                props: projectPropUsages(usage.props),
-                events: usage.events ?? [],
-                occurrenceId,
-                depth: 0,
-                definition: { line: decl.loc.line, column: decl.loc.column },
-                ...(rawOwnerComponentId !== undefined ? { rawOwnerComponentId } : {}),
-            });
-        }
-        return;
-    }
-    // Helper-call fanout: resolve owner chain and emit per (terminal × resolution).
-    const ownerResolutions = resolveOwnerChain(ownerRef, graph, helperIndex, createCycleGuard());
+    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 fallback = {
-            kind: componentKindFor(fileGraph.dialect),
-            export: compoundExportName(usage.ref.symbol, usage.ref.memberChain),
-            source: { type: "local", filePath },
-        };
         const rawComponentId = componentIdFromIdentity(ft.identity, fallback, fileGraph.dialect, {
             filePath,
             resolveExternalLeaf: opts?.resolveExternalLeaf,
         });
-        for (const res of ownerResolutions) {
-            const rawOwnerComponentId = ownerIdFromResolution(graph, res.ownerDecl);
-            const viaChain = [...res.viaPrefix, outerVia, ...ft.viaTrail];
-            const provisionalId = serialiseComponentId(rawComponentId);
-            const occurrenceId = computeOccurrenceId(provisionalId, filePath, usage.loc.line, usage.loc.column, rawOwnerComponentId !== undefined ? serialiseComponentId(rawOwnerComponentId) : undefined);
-            occurrences.push({
-                rawComponentId,
-                filePath,
-                line: usage.loc.line,
-                column: usage.loc.column,
-                via: viaChain[0] ?? outerVia,
-                viaChain,
-                props: projectPropUsages(usage.props),
-                events: usage.events ?? [],
-                occurrenceId,
-                depth: 0,
-                definition: { line: decl.loc.line, column: decl.loc.column },
-                ...(rawOwnerComponentId !== undefined ? { rawOwnerComponentId } : {}),
-            });
-        }
+        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
@@ -939,7 +837,7 @@ function pushArgumentSiteOccurrences(occurrences, filePath, holder, call, holder
         const folded = foldedArgument(graph, fileGraph, call, holderJsx, argMap);
         if (folded?.arg.kind !== "ReturnTypeOf")
             return;
-        const innerJsx = walkWithFolding(graph, fileGraph, folded.arg, argMap).filter((t) => t.type.kind === "JSX");
+        const innerJsx = creditedTerminals(walkWithFolding(graph, fileGraph, folded.arg, argMap));
         pushArgumentSiteOccurrences(occurrences, filePath, holder, folded.arg, innerJsx, graph, fileGraph, argMap, opts, depth + 1);
         return;
     }
@@ -978,8 +876,6 @@ function callFoldShape(jsx) {
         return "product";
     return credited === jsx.length ? "wrapper" : null;
 }
-/** React's own hook predicate (`isHookName` in rules-of-hooks and the compiler). */
-const HOOK_NAME = /^use[A-Z0-9]/;
 /**
  * THE argument-site push seam: one `passed-as-argument` occurrence per
  * (identifier argument that resolves to a component) × (owner). The
@@ -1021,34 +917,15 @@ function pushCallArgumentOccurrences(occurrences, filePath, call, owners, graph,
         // and `buildComponentId` returns the fallback only for a null one. The
         // relabel seam's signature requires a fallback all the same.
         const unusedFallback = makeLocalComponentId(filePath, arg.ref.symbol, fileGraph.dialect);
-        for (const ft of walkWithFolding(graph, fileGraph, arg, argMap)) {
-            if (ft.type.kind !== "JSX" || ft.identity === null)
+        for (const ft of creditedTerminals(walkWithFolding(graph, fileGraph, arg, argMap))) {
+            if (ft.identity === null)
                 continue;
             const rawComponentId = componentIdFromIdentity(ft.identity, unusedFallback, fileGraph.dialect, {
                 filePath,
                 resolveExternalLeaf: opts?.resolveExternalLeaf,
             });
-            const wraps = computeWraps(rawComponentId, opts?.wrapCallback);
             resolvedOwners ??= owners();
-            for (const { rawOwnerComponentId, viaPrefix } of resolvedOwners) {
-                const viaChain = [...viaPrefix, outerVia, ...hops, ...ft.viaTrail];
-                const occurrenceId = computeOccurrenceId(serialiseComponentId(rawComponentId), filePath, arg.ref.loc.line, arg.ref.loc.column, rawOwnerComponentId !== undefined ? serialiseComponentId(rawOwnerComponentId) : undefined);
-                occurrences.push({
-                    rawComponentId,
-                    filePath,
-                    line: arg.ref.loc.line,
-                    column: arg.ref.loc.column,
-                    via: viaChain[0] ?? outerVia,
-                    viaChain,
-                    props: {},
-                    events: [],
-                    occurrenceId,
-                    depth: 0,
-                    ...(argDecl !== null ? { definition: { line: argDecl.loc.line, column: argDecl.loc.column } } : {}),
-                    ...(rawOwnerComponentId !== undefined ? { rawOwnerComponentId } : {}),
-                    ...(wraps !== undefined ? { wraps } : {}),
-                });
-            }
+            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);
         }
     };
     const seedArguments = (site, siteDepth) => {
@@ -1061,7 +938,7 @@ function pushCallArgumentOccurrences(occurrences, filePath, call, owners, graph,
         }
         if (arg.kind !== "ReturnTypeOf" || callDepth >= MAX_ARGUMENT_CALL_DEPTH)
             return;
-        const argJsx = walkWithFolding(graph, fileGraph, arg, argMap).filter((t) => t.type.kind === "JSX");
+        const argJsx = creditedTerminals(walkWithFolding(graph, fileGraph, arg, argMap));
         const shape = callFoldShape(argJsx);
         if (shape === "product") {
             seedArguments(arg, callDepth + 1);
@@ -1098,27 +975,10 @@ function findTagOwnership(ownership, usageIdx) {
  */
 function pushTagOccurrence(occurrences, filePath, usage, rawComponentId, ownerRef, viaOverride, graph, helperIndex) {
     const via = viaOverride ?? { kind: "html-tag" };
-    // Owner-chain fanout uses the same machinery as JsxUsage.
-    const ownerResolutions = resolveOwnerChain(ownerRef, graph, helperIndex, createCycleGuard());
-    for (const res of ownerResolutions) {
-        const rawOwnerComponentId = ownerIdFromResolution(graph, res.ownerDecl);
-        const viaChain = [...res.viaPrefix, via];
-        const provisionalId = serialiseComponentId(rawComponentId);
-        const occurrenceId = computeOccurrenceId(provisionalId, filePath, usage.loc.line, usage.loc.column, rawOwnerComponentId !== undefined ? serialiseComponentId(rawOwnerComponentId) : undefined);
-        occurrences.push({
-            rawComponentId,
-            filePath,
-            line: usage.loc.line,
-            column: usage.loc.column,
-            via: viaChain[0] ?? via,
-            viaChain,
-            props: projectPropUsages(usage.props),
-            events: usage.events ?? [],
-            occurrenceId,
-            depth: 0,
-            ...(rawOwnerComponentId !== undefined ? { rawOwnerComponentId } : {}),
-        });
-    }
+    // Owner-chain fanout uses the same machinery as JsxUsage, a `viaOverride`
+    // notwithstanding.
+    const owners = chainOwners(graph, helperIndex, ownerRef);
+    emitOccurrence(occurrences, usageSite(filePath, usage), rawComponentId, owners, [via]);
 }
 /**
  * Decide the `kind` for a JSX-emitted ComponentId. A concrete