@component-compass/cli 0.1.22 → 0.1.24

package/dist/commands/scan.js

@@ -1,745 +0,0 @@
-import { performance } from "node:perf_hooks";
-import { isAbsolute, relative, resolve } from "node:path";
-import { readFile } from "node:fs/promises";
-import { loadConfig, ConfigError } from "../config/loader.js";
-import { createLazyResolver } from "../manifest/lazy-resolver.js";
-import { buildLocalIndex } from "../local-index/index.js";
-import { detectReactComponents } from "../local-index/detect-react.js";
-import { detectVueComponents } from "../local-index/detect-vue.js";
-import { detectWebComponents } from "../local-index/detect-wc.js";
-import { parseByExt } from "../parse-by-ext.js";
-import { createProgress } from "../util/progress.js";
-import { walkFiles } from "../walker/files.js";
-import { createImportResolver } from "../walker/resolve-import.js";
-import { resolveTsconfigPath } from "../walker/tsconfig-discovery.js";
-import { buildPackageAliasLayers } from "../walker/package-alias-layers.js";
-import { Dispatcher } from "../dispatcher.js";
-import { reactPlugin, emitReact } from "@component-compass/parser-react";
-import { htmlPlugin } from "@component-compass/parser-html";
-import { litTemplatePlugin } from "@component-compass/parser-lit";
-import { emitVueTemplate } from "@component-compass/parser-vue";
-import { writeJson } from "../reporter/json.js";
-import { printSummary } from "../reporter/stdout.js";
-import { stampMeta } from "../scan/meta.js";
-import { stampGitMTime } from "../scan/git-mtime.js";
-import { stampVersion } from "../scan/stamp-version.js";
-import { applyWrapRelationships } from "../scan/wrap-relationships.js";
-import { applyEntryPackages, createEntryPackageRecorder } from "../scan/entry-packages.js";
-import { buildCemIndex } from "../scan/cem-index.js";
-import { isPnpProject } from "../util/pnp-check.js";
-import { readGitToplevel } from "../util/git.js";
-import { findWorkspaceRoot } from "../workspace/find-workspace-root.js";
-import { Logger } from "../util/log.js";
-import { errorMessage } from "@component-compass/ast-utils";
-import { createGraphBuilder, resolve as resolveGraph, } from "@component-compass/reference-graph";
-import { attachManifestEnrichment, buildComponentSeeds } from "../seeds.js";
-import { parseResultsToOccurrences } from "../occurrences.js";
-import { computeStableIdFromComponentId, computeOutputIdentity } from "../identity.js";
-import { buildScanOutput } from "../reporter/index.js";
-import { buildWorkspaceGraph, declaredDeps, findOwningPackage, resetFindOwningPackageCache, } from "../workspace/index.js";
-import { createBoundedDefinitionResolver } from "../walker/bounded-definition-resolver.js";
-import { loadGlobalComponents, detectAutoImportFramework } from "../scan/global-components.js";
-import { createDiagnosticCollector, computeOccurrenceId, externalPackageOf, posixPath } from "@component-compass/plugin-core";
-/** Map a scan result to a process exit code: 2 = scan failed, 1 = requested upload failed, 0 = ok. */
-export function scanExitCode(result) {
-    if (result.output === null)
-        return 2;
-    if (result.upload === "failed")
-        return 1;
-    return 0;
-}
-export async function runScan(opts) {
-    const log = new Logger(opts.quiet);
-    const t0 = performance.now();
-    const configPath = opts.configPath ??
-        resolve(opts.cwd ?? process.cwd(), "component-compass.config.json");
-    let cfg;
-    try {
-        cfg = await loadConfig(configPath);
-    }
-    catch (err) {
-        if (err instanceof ConfigError) {
-            log.error(err.message);
-            return { output: null, upload: "skipped" };
-        }
-        throw err;
-    }
-    if (isPnpProject(cfg.configDir)) {
-        log.error("yarn PnP detected; component-compass requires nodeLinker: node-modules.");
-        return { output: null, upload: "skipped" };
-    }
-    // Stamp meta early — throws if not a git work tree, which is a hard
-    // prerequisite for a stable repo identity.
-    const metaOpts = { cwd: cfg.configDir };
-    const repoIdOverride = opts.repoId ?? cfg.repoId;
-    if (repoIdOverride !== undefined)
-        metaOpts.repoIdOverride = repoIdOverride;
-    const meta = await stampMeta(metaOpts);
-    // Output path base. An explicit `repoRoot` override wins;
-    // otherwise the git toplevel when the scan dir sits inside a work tree; else
-    // configDir (non-git or pathological cases).
-    // Guard: outputRoot must contain configDir, else re-basing would produce
-    // `..`-prefixed paths for every file.
-    const gitToplevel = await readGitToplevel(cfg.configDir);
-    const outputRoot = opts.repoRoot
-        ? (isAbsolute(opts.repoRoot)
-            ? opts.repoRoot
-            : resolve(opts.cwd ?? process.cwd(), opts.repoRoot))
-        : (gitToplevel && !relative(gitToplevel, cfg.configDir).startsWith("..")
-            ? gitToplevel
-            : cfg.configDir);
-    // Re-base a scanRoot-relative POSIX path into outputRoot-relative POSIX.
-    // Identity when the roots coincide.
-    const rebase = (scanRel) => outputRoot === cfg.configDir
-        ? scanRel
-        : posixPath(relative(outputRoot, resolve(cfg.configDir, scanRel)));
-    if (opts.outputOverride)
-        cfg.output = opts.outputOverride;
-    const writer = opts.quiet ? () => { } : (s) => process.stderr.write(s);
-    // Ownership/resolution anchor. Walks up from configDir to the nearest
-    // enclosing workspace root (bounded by outputRoot), so scanning a monorepo
-    // subfolder still resolves against the real hoisted node_modules / tsconfig
-    // instead of a partial view rooted at the scan dir. Falls back to configDir
-    // when no enclosing workspace claims it (the common case — existing
-    // fixtures all scan from their own root).
-    const workspaceRoot = findWorkspaceRoot(cfg.configDir, outputRoot) ?? cfg.configDir;
-    if (workspaceRoot !== cfg.configDir) {
-        writer(`[scan] workspace root: ${workspaceRoot}\n`);
-    }
-    // Reset per-scan caches so in-process invocations (tests, watch mode) start
-    // clean. Memoized realpath results from a prior scan would still be valid,
-    // but explicit reset avoids state leakage if the filesystem changed.
-    resetFindOwningPackageCache();
-    const workspaceGraph = buildWorkspaceGraph(workspaceRoot);
-    const resolveImportOpts = {
-        repoRoot: workspaceRoot,
-        workspaceGraph,
-        onWarning: (msg) => writer(`[scan] tsconfig: ${msg}\n`),
-    };
-    if (cfg.aliases)
-        resolveImportOpts.aliases = cfg.aliases;
-    resolveImportOpts.packageAliasLayers = buildPackageAliasLayers(workspaceGraph, (msg) => writer(`[scan] tsconfig(workspace): ${msg}\n`));
-    const tsconfigPath = resolveTsconfigPath({
-        configDir: cfg.configDir,
-        repoRoot: workspaceRoot,
-        ...(cfg.tsconfigPath !== undefined ? { tsconfigPath: cfg.tsconfigPath } : {}),
-    });
-    if (tsconfigPath)
-        resolveImportOpts.tsconfigPath = tsconfigPath;
-    const resolveImport = createImportResolver(resolveImportOpts);
-    const collector = createDiagnosticCollector();
-    // Build global CEM index once per scan. Enumerates every package under
-    // <root>/node_modules, finds CEM/CCM files, and builds byTag + byPackageName
-    // maps so parsers can resolve hyphenated tags without consumer-side config.
-    // Parsers consume cemIndex.
-    const cemIndex = await buildCemIndex(workspaceRoot);
-    // Identity resolution (leafPackage + modulePath) runs unconditionally for
-    // external imports. `manifestPatterns` is the per-package gate for manifest
-    // IO only. `["**"]` opts every package in — picomatch's `*` won't cross `/`
-    // so it misses scoped names, but `**` does. The workspace gate inside
-    // extractDerived (realpathSync check for node_modules in path) decides which
-    // packages actually get extractor enrichment; published packages bail
-    // immediately, so there is no meaningful performance cost for the wider gate.
-    const manifestPatterns = ["**"];
-    // Entry-package provenance capture. Fed by the resolver's walk for
-    // both lanes (JS relabel via lookupExternalLeaf, side-effect priming via
-    // resolveLazyManifest); drained into applyEntryPackages post-resolve.
-    const entryPackageRecorder = createEntryPackageRecorder();
-    const lazyResolver = createLazyResolver({
-        resolveImport,
-        repoRoot: workspaceRoot,
-        collector,
-        manifestPatterns,
-        onEntryPackage: entryPackageRecorder.record,
-    });
-    // Warm-up: load each declared dep's root CEM/CCM (if any) so tag-only
-    // consumers (HTML files, Vue templates with no JS-side import for the tag)
-    // can resolve external custom elements via lookupByTag. Cheap (one
-    // package.json + one manifest read per dep) and matches the lazy
-    // resolver's terminal-load step in depth — no barrel walking, no
-    // re-export chasing. `.warm()` returns a WarmedResolver whose lookupByTag
-    // is the only typed access to the byTag index.
-    const declared = declaredDeps(workspaceGraph);
-    const warmedResolver = lazyResolver.warm(declared);
-    const files = await walkFiles({
-        root: cfg.configDir,
-        include: cfg.include,
-        exclude: cfg.exclude,
-        gitignore: cfg.gitignore,
-    });
-    if (files.length === 0) {
-        log.warn(`No files matched include globs: ${cfg.include.join(", ")}`);
-    }
-    // Sort files so JS/TS/Vue process before HTML; this primes the by-tag cache
-    // in the lazy resolver before plain HTML files (which only have tag names,
-    // no import specifiers) need to look up custom elements.
-    const orderedFiles = [...files].sort((a, b) => {
-        const aHtml = /\.html?$/.test(a) ? 1 : 0;
-        const bHtml = /\.html?$/.test(b) ? 1 : 0;
-        return aHtml - bHtml;
-    });
-    const dispatcher = new Dispatcher([reactPlugin, htmlPlugin, litTemplatePlugin]);
-    const results = [];
-    // Single-pass scan: one IO + one parse per file, shared across the local-
-    // index build and plugin dispatch. ASTs are cached for the gap between the
-    // two phases, then evicted post-dispatch to bound peak memory on large
-    // monorepos. Two progress reporters cover each phase so the user sees both
-    // legs — phase 2's plugin dispatch can dominate on JSX-heavy repos, and a
-    // single phase-1-only reporter looked frozen at 99% during phase 2.
-    if (tsconfigPath) {
-        const rel = relative(cfg.configDir, tsconfigPath);
-        writer(`[scan] using tsconfig: ${rel || tsconfigPath}\n`);
-    }
-    else {
-        writer("[scan] tsconfig: not found (path aliases will not resolve)\n");
-    }
-    const isTTY = !!process.stderr.isTTY;
-    const parseProgress = createProgress({
-        total: orderedFiles.length,
-        writer,
-        isTTY,
-        label: "Parsing",
-    });
-    const astCache = new Map();
-    const sourceCache = new Map();
-    const localDefs = [];
-    // Graph builder for the reference-graph engine. Populated during Phase 1
-    // (alongside the local-definition scan) so both the local index and the
-    // graph see every file exactly once. The engine's Resolve phase runs after
-    // Phase 2's plugin dispatch and its output is merged with the
-    // Vue/Lit/HTML occurrences before Assemble.
-    const graphBuilder = createGraphBuilder({ moduleResolver: resolveImport, repoRoot: cfg.configDir });
-    // Generated GlobalComponents declarations: the Vue-ecosystem
-    // registry of globally-available components (Nuxt writes one). Loaded once
-    // per scan; misses degrade to diagnostics, never gates.
-    const autoImports = loadGlobalComponents(cfg.configDir);
-    if (autoImports !== null) {
-        for (const s of autoImports.stale) {
-            collector.emit({
-                code: "auto-import-stale-entry",
-                severity: "warning",
-                filePath: autoImports.declarationPath,
-                componentName: s.componentName,
-                // s.target is absolute (global-components.ts resolves in-repo
-                // entries to an absolute path before checking existence) — emit
-                // repo-relative POSIX so the artefact stays portable across machines,
-                // matching the convention used for occurrence/component filePaths.
-                target: posixPath(relative(cfg.configDir, s.target)),
-            });
-        }
-    }
-    else {
-        const framework = detectAutoImportFramework(cfg.configDir);
-        if (framework !== null) {
-            const missing = {
-                code: "auto-import-manifest-missing",
-                severity: "warning",
-                filePath: framework.expectedPath,
-                detail: "auto-import framework detected but no components manifest was found — auto-imported components can't be resolved. Run `nuxt prepare` (or any dev/build) and re-scan.",
-            };
-            collector.emit(missing);
-            // Surface at scan time, not only in the artifact.
-            log.warn(formatDiagnostic(missing));
-        }
-    }
-    // ── Phase 1: read + parse + emit local definitions ──────────────────────
-    for (const file of orderedFiles) {
-        const source = await readFile(file, "utf8").catch(() => "");
-        if (!source) {
-            parseProgress.tick();
-            continue;
-        }
-        let parsed;
-        try {
-            parsed = parseByExt(file, source);
-        }
-        catch (err) {
-            // parseByExt throws on unrecoverable syntax (EOF mid-expression, malformed
-            // SFC). Mirror the plugin-loop's warn-and-continue pattern so one broken
-            // file can't tank the scan.
-            log.warn(`[component-compass] parse failure in ${file}: ${errorMessage(err)}`);
-            parseProgress.tick();
-            continue;
-        }
-        // `unsupported` extensions never reach phase 2; skip caching to bound
-        // peak memory on scans whose include glob covers unsupported file types.
-        if (parsed.kind === "unsupported") {
-            parseProgress.tick();
-            continue;
-        }
-        astCache.set(file, parsed);
-        sourceCache.set(file, source);
-        // Detectors record `componentId.source.filePath` as POSIX repo-relative so
-        // it joins with seeds + parser occurrences without a normalisation step.
-        const relPath = posixPath(relative(cfg.configDir, file));
-        // Detectors feed the local-definition index, which is output-space
-        // Rebase to outputRoot before handing paths to them.
-        const outRel = rebase(relPath);
-        if (parsed.kind === "babel") {
-            localDefs.push(...detectReactComponents(parsed.ast, outRel, parsed.source));
-            localDefs.push(...detectWebComponents(parsed.ast, outRel));
-            // Vue script-mode catches `defineComponent` in plain .ts/.js, mirroring
-            // local-index/index.ts routing for non-SFC files.
-            localDefs.push(...detectVueComponents({ kind: "script", program: parsed.ast, source: parsed.source }, outRel));
-            // Emit JSX references into the graph for later resolution by the engine.
-            // relPath is repo-relative POSIX — the same form used for FileGraph keys.
-            try {
-                const fileBuilder = graphBuilder.beginFile(relPath);
-                emitReact({
-                    file: relPath,
-                    source,
-                    ast: parsed.ast,
-                    fileBuilder,
-                    // Side-effect imports prime the lazy resolver: mirrors the Vue
-                    // lane's priming (emit-template.ts), warming byTag for tag
-                    // resolution and feeding entry-package provenance.
-                    // exportName "" = side-effect signal. Anchor is absolute here,
-                    // which resolveLeaf handles identically — the Vue lane
-                    // (emit-template.ts, below) anchors absolute too, for the same
-                    // reason.
-                    onSideEffectImport: (spec) => {
-                        warmedResolver.resolveLazyManifest(file, spec, "");
-                    },
-                });
-            }
-            catch (err) {
-                log.warn(`[component-compass] emit failure in ${file}: ${errorMessage(err)}`);
-            }
-        }
-        else if (parsed.kind === "vue") {
-            const wrapper = parsed.scriptAst !== undefined
-                ? { descriptor: parsed.descriptor, scriptProgram: parsed.scriptAst }
-                : { descriptor: parsed.descriptor };
-            const sfcDefs = detectVueComponents({ kind: "sfc", wrapper }, outRel);
-            localDefs.push(...sfcDefs);
-            try {
-                const fileBuilder = graphBuilder.beginFile(relPath, "vue");
-                emitVueTemplate({
-                    file: relPath,
-                    source,
-                    wrapper,
-                    fileBuilder,
-                    // Anchor on the absolute `file`, discarding the emitter's own
-                    // repo-relative `_from` (relPath, relative to cfg.configDir).
-                    // resolveLazyManifest ultimately calls resolveImport(from, spec),
-                    // which rebases a non-absolute `from` onto the import resolver's
-                    // repoRoot — workspaceRoot, not cfg.configDir (walker/resolve-
-                    // import.ts). Those coincide for every scan rooted at its own
-                    // workspace root, but whenever cfg.configDir sits in a workspace
-                    // subdirectory (consumer-ci's per-app targets), rebasing the
-                    // relative anchor onto workspaceRoot produces a path that doesn't
-                    // exist, and the node_modules walk starts from the wrong
-                    // directory — nested per-app deps become unreachable. The
-                    // React/babel lane (emitReact's onSideEffectImport, above) already
-                    // anchors on the absolute `file` for the same reason; mirror it
-                    // here instead of "simplifying" this back to the emitter's arg.
-                    resolveLazyManifest: (_from, spec, exportName) => warmedResolver.resolveLazyManifest(file, spec, exportName),
-                    // Reuse detectVueComponents' resolved symbol so the SFC's local-index
-                    // seed and the engine's owner ComponentId hash to the same id —
-                    // otherwise the SFC seed is pruned as an unreachable local.
-                    ...(sfcDefs[0]?.exportName !== undefined ? { sfcSymbol: sfcDefs[0].exportName } : {}),
-                    ...(autoImports !== null ? { resolveAutoImport: autoImports.lookup } : {}),
-                    collector,
-                });
-            }
-            catch (err) {
-                log.warn(`[component-compass] emit failure in ${file}: ${errorMessage(err)}`);
-            }
-        }
-        parseProgress.tick();
-    }
-    parseProgress.done();
-    const localIndex = buildLocalIndex(localDefs, collector);
-    // ── Phase 2: dispatch plugins with shared oxc Program through ctx.ast ────
-    // walkProgress total is the cached-file count: files dropped by phase 1
-    // (empty source / parse failure / unsupported extension) aren't in the
-    // cache and won't be walked.
-    const walkProgress = createProgress({
-        total: astCache.size,
-        writer,
-        isTTY,
-        label: "Walking",
-    });
-    for (const file of orderedFiles) {
-        const parsed = astCache.get(file);
-        const source = sourceCache.get(file);
-        if (!parsed || parsed.kind === "unsupported" || source === undefined)
-            continue;
-        // Carrier shape per file-kind; plugins narrow internally via their own
-        // ctx.ast cast. `babel` → oxc Program, `vue` → VueParseWrapper,
-        // `html` → parse5 Document. Unsupported never reaches here.
-        const astForCtx = parsed.kind === "babel" ? parsed.ast :
-            parsed.kind === "vue" ? (parsed.scriptAst !== undefined
-                ? { descriptor: parsed.descriptor, scriptProgram: parsed.scriptAst }
-                : { descriptor: parsed.descriptor }) :
-                parsed.kind === "html" ? parsed.document :
-                    undefined;
-        for (const plugin of dispatcher.allPluginsFor(file)) {
-            try {
-                results.push(plugin.parse(file, source, {
-                    localIndex,
-                    config: cfg,
-                    resolveImport,
-                    resolveLazyManifest: warmedResolver.resolveLazyManifest,
-                    resolveLocalExport: warmedResolver.resolveLocalExport,
-                    lookupByTag: warmedResolver.lookupByTag,
-                    repoRoot: outputRoot,
-                    collector,
-                    ast: astForCtx,
-                    cemIndex,
-                }));
-            }
-            catch (err) {
-                log.warn(`[component-compass] parse failure in ${file}: ${errorMessage(err)}`);
-            }
-        }
-        // Evict after dispatch — keeps peak heap proportional to one file, not
-        // the whole repo, on large monorepos.
-        astCache.delete(file);
-        sourceCache.delete(file);
-        walkProgress.tick();
-    }
-    walkProgress.done();
-    // ── Resolve phase: engine walks the populated graph ──────────────────────
-    // Produces EngineOccurrence[] for every component reference in the graph:
-    // external packages, workspace siblings, local symbols, and relative-
-    // specifier imports alike.
-    //
-    // tagIndex serves tag-based emitters (parser-vue, parser-lit,
-    // parser-html). External lookups try the warmed lazy
-    // resolver first (populated by `.warm()`'s declared-dep eager-load and by
-    // side-effect-import priming, both re-export-aware — sees barrels the
-    // static CemIndex glob can't reach, e.g. nested node_modules leaves),
-    // falling back to CemIndex.byTag for tags whose package was never imported
-    // or warmed. Local lookups go through the workspace-WC entries in
-    // LocalDefinitionIndex.byTag.
-    // The collector is the same shared one parsers emit through; the engine adds
-    // its own diagnostics (low-confidence-tag, etc.).
-    const tagIndex = {
-        externalByTag: (tag) => {
-            const warmed = warmedResolver.lookupByTag(tag);
-            if (warmed && warmed.source.type === "external") {
-                return { packageName: externalPackageOf(warmed.source) };
-            }
-            const hit = cemIndex.byTag.get(tag);
-            if (!hit)
-                return undefined;
-            return { packageName: hit.packageName };
-        },
-        localByTag: (tag) => {
-            const hit = localIndex.byTag.get(tag);
-            if (!hit || hit.componentId.source.type !== "local")
-                return undefined;
-            return { filePath: hit.componentId.source.filePath, exportName: hit.exportName };
-        },
-    };
-    // Bounded re-export resolver pins an un-walked workspace member's identity to
-    // its definition file so ids are scope-invariant between whole-repo and
-    // single-app scans. Only invoked for out-of-graph members.
-    const resolveLocalDefinition = createBoundedDefinitionResolver({
-        moduleResolver: resolveImport,
-        onWarning: (msg) => writer(`[scan] ${msg}\n`),
-    });
-    const resolveOpts = {
-        wrapCallback: (pkg, exportName) => warmedResolver.lookupReactWrapper(pkg, exportName),
-        // Follow external aggregator barrels to the leaf package that
-        // defines the export. Graph keys are configDir-relative — rebase before
-        // handing to the resolver's Node-resolution walk. Same-package hits are
-        // ignored by the engine but still terminal-load the leaf CEM, which is
-        // what makes wrapCallback hit for undeclared-transitive direct imports.
-        // Uses `lookupExternalLeaf` (not `resolveLazyManifest`) so these
-        // engine-driven visits stay out of `snapshotComponents()` /
-        // `snapshotManifestRefs()` — otherwise an undeclared package's full CEM
-        // catalog gets broadcast as zero-occurrence components.
-        resolveExternalLeaf: (fromFile, specifier, exportName) => {
-            const absFrom = isAbsolute(fromFile) ? fromFile : resolve(cfg.configDir, fromFile);
-            const hit = warmedResolver.lookupExternalLeaf(absFrom, specifier, exportName);
-            if (!hit)
-                return null;
-            return { leafPackage: hit.leafPackage, modulePath: hit.modulePath, exportName: hit.exportName };
-        },
-        tagIndex,
-        collector,
-    };
-    // Workspace-membership seam: findOwningPackage is the ONE membership
-    // predicate (docs/CONTEXT.md). Never re-derive "is this path first-party".
-    // Hooks attach at build() time so both engine lane-classification sites
-    // (direct-import branch and wrapper-folding's composition fallbacks)
-    // reach them through the Graph.
-    const graph = graphBuilder.build({
-        workspaceMembership: (p) => findOwningPackage(workspaceGraph, p) !== null,
-        resolveLocalDefinition,
-    });
-    const { occurrences: engineOccurrences, registry } = resolveGraph(graph, resolveOpts);
-    const t1 = performance.now();
-    // Drain the shared collector.
-    const rawDiagnostics = collector.drain();
-    if (!opts.quiet) {
-        for (const d of rawDiagnostics) {
-            log.warn(formatDiagnostic(d));
-        }
-    }
-    // Normalise diagnostic filePaths to repo-relative POSIX so the artefact is
-    // portable across machines (matches the convention used for occurrences and
-    // component identity). Warn logs above keep the original absolute path for
-    // click-through ergonomics in the terminal.
-    const diagnostics = rawDiagnostics.map((d) => ({
-        ...d,
-        filePath: isAbsolute(d.filePath) ? posixPath(relative(outputRoot, d.filePath)) : d.filePath,
-    }));
-    const snapshot = warmedResolver
-        .snapshotComponents()
-        .map((c) => ({ component: c }));
-    const manifests = warmedResolver.snapshotManifestRefs();
-    // Registry entries are keyed by graph key (configDir-relative); the roster
-    // lives in output space. Rebase once here through the same `rebase` every
-    // other engine path uses, so the join compares like with like. Keyed on
-    // both `symbol` and `exportName` since `hasLocal` must also answer by the
-    // local symbol when the entry's `exportName` is an alias.
-    const rebasedEntries = registry.localEntries().map((e) => ({ ...e, filePath: rebase(e.filePath) }));
-    const rebasedKeys = new Set(rebasedEntries.flatMap((e) => [`${e.filePath}::${e.symbol}`, `${e.filePath}::${e.exportName}`]));
-    const rosterRegistry = {
-        hasLocal: (filePath, exportName) => rebasedKeys.has(`${filePath}::${exportName}`),
-        localEntries: () => rebasedEntries,
-    };
-    const seeds = buildComponentSeeds(results, localIndex, outputRoot, workspaceGraph, rosterRegistry, meta.repo.id);
-    // Occurrences from the Vue/Lit/HTML parsers (reactPlugin.parse is a no-op).
-    const legacyOccurrences = parseResultsToOccurrences(results, outputRoot);
-    // Convert EngineOccurrence → OutputOccurrence and merge with the parser output.
-    // Engine occurrences carry rawComponentId (structured ComponentId); translate
-    // to the stable short-hash string via computeStableIdFromComponentId, then
-    // re-derive occurrenceId using the final hashed componentId (matches the
-    // convention in occurrences.ts so rollup correlates correctly).
-    //
-    // Also accumulate seeds for engine-discovered components (external or local)
-    // that weren't already seeded by the parser path or the snapshot.
-    // Without seeds, these components won't appear in components[] and their ids
-    // won't be in validIds — causing composition edges to them to be silently
-    // dropped during applyCompositionRollup.
-    const engineSeeds = new Map();
-    // Track wraps cross-links emitted by the engine so we can patch them onto
-    // seeds that were built before the engine ran (manifest snapshot path).
-    // Keys are componentId hashes; values are the wraps field from EngineOccurrence.
-    const wrapsById = new Map();
-    const resolvedEngineOccurrences = engineOccurrences.map((eo) => {
-        // Normalise local filePaths in rawComponentId / rawOwnerComponentId to
-        // output-space POSIX so the stable hash matches the one produced for seeds
-        // built from the local index (which uses output-space relative paths).
-        const normalisedComponentId = normaliseEngineLocalId(eo.rawComponentId, cfg.configDir, rebase);
-        const componentId = computeStableIdFromComponentId(normalisedComponentId);
-        // Resolve rawOwnerComponentId → hashed ownerComponentId string (if present).
-        // Must be computed BEFORE occurrenceId so it can participate in the hash
-        // (distinguishes fanned-out occurrences that share the same JSX call site).
-        const ownerComponentId = eo.rawOwnerComponentId !== undefined
-            ? computeStableIdFromComponentId(normaliseEngineLocalId(eo.rawOwnerComponentId, cfg.configDir, rebase))
-            : eo.ownerComponentId;
-        // eo.filePath is a scanRoot-relative graph key — rebase to outputRoot for
-        // both the occurrenceId hash and the emitted OutputOccurrence.filePath.
-        const outFile = rebase(eo.filePath);
-        const occurrenceId = computeOccurrenceId(componentId, outFile, eo.line, eo.column, ownerComponentId);
-        // Normalise absolute `via`/`viaChain` specifiers (e.g. GlobalComponents
-        // entries for in-repo Vue components — see global-components.ts) to
-        // output-space POSIX through the same rebase used for local identity
-        // paths above. Authored specifiers are never absolute, so the isAbsolute
-        // guard only ever fires for these synthetic entries. `via` is always
-        // `viaChain[0]` (see engine/index.ts) — derive it from the normalised
-        // chain so the two stay in sync.
-        const normalisedViaChain = eo.viaChain.map((v) => normaliseVia(v, cfg.configDir, rebase));
-        const via = normalisedViaChain[0] ?? normaliseVia(eo.via, cfg.configDir, rebase);
-        // Propagate wraps cross-link so it reaches OutputComponent.identity.wraps.
-        // We record it in wrapsById so it can be patched onto pre-existing seeds
-        // (manifest snapshot path) that were built before the engine ran.
-        if (eo.wraps !== undefined && !wrapsById.has(componentId)) {
-            wrapsById.set(componentId, eo.wraps);
-        }
-        // Ensure a seed exists for this component so it appears in components[].
-        // Local seeds are already seeded from localIndex (step 3 of buildComponentSeeds);
-        // this covers external occurrences whose package has no manifest snapshot entry.
-        if (!engineSeeds.has(componentId)) {
-            const existingSeed = seeds.find((s) => s.id === componentId);
-            if (!existingSeed) {
-                const identity = computeOutputIdentity({
-                    componentId: normalisedComponentId,
-                    repoId: meta.repo.id,
-                    workspaceGraph,
-                    outputRoot,
-                    ...(eo.definition !== undefined ? { definitionLoc: eo.definition } : {}),
-                });
-                // Attach wraps cross-link to the identity when present.
-                if (eo.wraps !== undefined)
-                    identity.wraps = eo.wraps;
-                engineSeeds.set(componentId, { id: componentId, identity, manifest: null });
-            }
-        }
-        return {
-            componentId,
-            filePath: outFile,
-            line: eo.line,
-            column: eo.column,
-            via,
-            viaChain: normalisedViaChain,
-            props: eo.props,
-            occurrenceId,
-            depth: eo.depth,
-            ...(ownerComponentId !== undefined ? { ownerComponentId } : {}),
-            ...(eo.events && eo.events.length > 0 ? { events: eo.events } : {}),
-        };
-    });
-    // Merge engine seeds into the primary seeds array (deduplication via existingSeed check above).
-    // Patch wraps onto pre-existing seeds (manifest snapshot path) where the engine
-    // resolved a wrapCallback hit — those seeds were built before resolveGraph ran.
-    const allSeeds = [
-        ...seeds.map((s) => {
-            const wraps = wrapsById.get(s.id);
-            if (wraps === undefined)
-                return s;
-            return { ...s, identity: { ...s.identity, wraps } };
-        }),
-        ...engineSeeds.values(),
-    ];
-    // Attach manifest enrichment to every observed seed — parser-observed and
-    // engine-discovered alike — via the ONE enrichment seam. Must run after
-    // engine seeds are merged in so engine-only-discovered components (Vue
-    // tag-only usages, wrap targets) are eligible for enrichment too, and before
-    // buildScanOutput so the manifest lands in the emitted artefact.
-    attachManifestEnrichment(allSeeds, snapshot, workspaceGraph);
-    const occurrences = [...legacyOccurrences, ...resolvedEngineOccurrences];
-    const partialStats = {
-        filesScanned: files.length,
-        filesWithUsage: countFilesWithUsage(occurrences),
-        scanDurationMs: Math.round(t1 - t0),
-    };
-    const rawScanOutput = buildScanOutput(meta, manifests, partialStats, allSeeds, occurrences, diagnostics);
-    // Post-resolve aggregation: stamp logicalId on every component and
-    // emit wraps relationship edges — no synthetic zero-occurrence rows.
-    // Leaf-package-lane records for UNOBSERVED targets match no row and
-    // drop — the relationship edge carries that provenance.
-    const { components: withRelationships, relationships } = applyWrapRelationships(rawScanOutput.components);
-    const aggregated = applyEntryPackages(withRelationships, entryPackageRecorder.drain());
-    const scanOutput = {
-        ...rawScanOutput,
-        components: aggregated,
-        relationships,
-        stats: { ...rawScanOutput.stats, componentsDetected: aggregated.length },
-    };
-    // Both functions join their root arg with output-space (outputRoot-relative)
-    // component/occurrence filePaths — must use outputRoot, not cfg.configDir,
-    // or the join produces a path that doesn't exist on disk once the two roots
-    // diverge (git-mtime lookups silently return empty; version resolution
-    // walks up from the wrong directory).
-    await stampGitMTime(outputRoot, scanOutput.components);
-    await stampVersion(outputRoot, scanOutput.components, scanOutput.occurrences);
-    // cfg.output is a physical write destination (relative to the scan
-    // invocation / config dir), not an output-space artefact field — stays
-    // configDir-relative.
-    const outputPath = isAbsolute(cfg.output) ? cfg.output : resolve(cfg.configDir, cfg.output);
-    await writeJson(scanOutput, outputPath);
-    if (!opts.quiet) {
-        printSummary(scanOutput, outputPath);
-    }
-    let upload = "skipped";
-    if (opts.upload) {
-        try {
-            const { createAuthedUploader } = await import("../auth/upload-auth.js");
-            const uploader = await createAuthedUploader({
-                ...(opts.hostOverride !== undefined ? { flagHost: opts.hostOverride } : {}),
-                ...(cfg.host !== undefined ? { configHost: cfg.host } : {}),
-            });
-            const result = await uploader.upload(JSON.stringify(scanOutput));
-            upload = result.status === "inserted" ? "ok" : "exists";
-            log.info(result.status === "inserted"
-                ? `Uploaded scan ${result.scanId} → ${uploader.base}${result.url}`
-                : `Scan ${result.scanId} already exists at ${uploader.base}${result.url}; no changes.`);
-        }
-        catch (err) {
-            upload = "failed";
-            const { formatAuthError } = await import("../auth/session.js");
-            const authMsg = formatAuthError(err);
-            const msg = authMsg ?? (err instanceof Error ? err.message : String(err));
-            log.error(`Upload failed: ${msg}`);
-        }
-    }
-    return { output: scanOutput, upload };
-}
-function countFilesWithUsage(occurrences) {
-    const files = new Set();
-    for (const o of occurrences)
-        files.add(o.filePath);
-    return files.size;
-}
-/**
- * Normalise a local-source ComponentId's filePath to output-space
- * (outputRoot-relative POSIX) so the stable hash matches the one produced
- * for seeds built from the local index.
- *
- * The engine emits one of two shapes: an absolute path (relative-specifier
- * import whose target didn't resolve to a graph key) or a scanRoot-relative
- * graph key (the common case — `graph.resolveToGraphKey` succeeds because
- * the target file is part of this scan; owner refs are always this shape,
- * per the FileGraph-key convention). Both are normalised to scanRoot-relative
- * first, then projected into output-space via `rebase` — `rebase` alone
- * isn't enough because it expects a scanRoot-relative input, not an
- * absolute one.
- */
-function normaliseEngineLocalId(c, configDir, rebase) {
-    if (c.source.type !== "local")
-        return c;
-    const fp = c.source.filePath;
-    const scanRel = isAbsolute(fp) ? posixPath(relative(configDir, fp)) : fp;
-    return {
-        ...c,
-        source: { type: "local", filePath: rebase(scanRel) },
-    };
-}
-/**
- * Rebase an absolute `via.specifier` (or `viaChain[n].specifier`) to
- * output-space POSIX, mirroring `normaliseEngineLocalId`'s treatment of
- * local ComponentId filePaths. The GlobalComponents reader
- * (scan/global-components.ts) emits absolute specifiers for in-repo
- * entries — parser-vue stamps them straight into `viaOverride.specifier` —
- * so without this the artefact leaks machine-local absolute paths.
- * Authored specifiers (explicit imports) are always bare/relative import
- * strings, never absolute, so the `isAbsolute` guard only ever fires for
- * these synthetic auto-import entries.
- */
-function normaliseVia(v, configDir, rebase) {
-    if (!("specifier" in v) || v.specifier === undefined || !isAbsolute(v.specifier))
-        return v;
-    const scanRel = posixPath(relative(configDir, v.specifier));
-    return { ...v, specifier: rebase(scanRel) };
-}
-function assertUnreachable(x) {
-    throw new Error(`Unhandled diagnostic code: ${x.code}`);
-}
-function formatDiagnostic(d) {
-    const tag = d.severity === "warning" ? "warn " : "info ";
-    switch (d.code) {
-        case "jsx-shape-unsupported":
-            return `${tag} [component-compass] ${d.code} at ${d.filePath}:${d.line ?? "?"} — ${d.detail}`;
-        case "low-confidence-tag":
-            return `${tag} [component-compass] ${d.code} at ${d.filePath}:${d.line ?? "?"} — <${d.tagName}>`;
-        case "local-index-duplicate-tag":
-            return `${tag} [component-compass] ${d.code} at ${d.filePath} — <${d.tagName}> conflicts with ${d.conflictsWith}`;
-        case "cycle-detected":
-            return `${tag} [component-compass] ${d.code} at ${d.filePath} (export: ${d.exportName})`;
-        case "chain-too-deep":
-            return `${tag} [component-compass] ${d.code} at ${d.filePath} (export: ${d.exportName}, depth: ${d.depth})`;
-        case "unresolved-import":
-            return `${tag} [component-compass] ${d.code} at ${d.filePath}:${d.line}:${d.column} — could not resolve '${d.specifier}'`;
-        case "lazy-import-unsupported":
-            return `${tag} [component-compass] ${d.code} at ${d.filePath}:${d.line}:${d.column} — '${d.specifier}': ${d.detail}`;
-        case "unresolved-reference":
-            return `${tag} [component-compass] ${d.code} at ${d.filePath}:${d.line}:${d.column} — ${d.symbol}${d.memberChain.length ? `.${d.memberChain.join(".")}` : ""}`;
-        case "cycle-in-resolution":
-            return `${tag} [component-compass] ${d.code} at ${d.filePath}:${d.line}:${d.column} — ${d.symbol} (depth ${d.depth})`;
-        case "unresolved-component-tag":
-            return `${tag} [component-compass] ${d.code} at ${d.filePath}:${d.line ?? "?"}:${d.column ?? "?"} — <${d.tagName}> has no import, auto-import entry, or tag registration`;
-        case "auto-import-stale-entry":
-            return `${tag} [component-compass] ${d.code} in ${d.filePath} — ${d.componentName} → ${d.target} (file missing; regenerate the manifest)`;
-        case "auto-import-manifest-missing":
-            return `${tag} [component-compass] ${d.code} at ${d.filePath} — ${d.detail}`;
-        default:
-            return assertUnreachable(d);
-    }
-}
-//# sourceMappingURL=scan.js.map