@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/src/analyse/serverActionReturns.ts

@@ -0,0 +1,213 @@
+import ts from "typescript";
+import type { PropValue } from "../types.ts";
+import { ownReturns } from "./ownReturns.ts";
+import { literalToValue } from "./renderPath.ts";
+
+/**
+ * What each exported action of a "use server" module actually returns, when
+ * that can be read off the source without evaluating anything.
+ *
+ * The bail policy is literalToValue's, deliberately: a mock built from a wrong
+ * guess is worse than the honest {} stub, because the spec goes green against
+ * data the action can never produce. So a name is recorded only when every
+ * non-exit return collapses to ONE literal-derivable value:
+ *
+ * - `redirect(...)` / `permanentRedirect(...)` / `notFound()` returns are
+ *   exits, not values — Next aborts rendering there, so they say nothing
+ *   about what a caller receives. Only when the callee is provably
+ *   next/navigation's (extractGuards learned this first): a project-local
+ *   redirect() that RETURNS something would otherwise have its value
+ *   silently discounted and the recorded literal would disagree with what
+ *   the action really returns.
+ * - Two distinct literal values bail (which one would the mock pick?);
+ *   byte-identical duplicates from two branches collapse fine.
+ * - Any non-literal return bails the whole name, even beside a literal one:
+ *   a literal happy path next to a computed error path is two shapes, and
+ *   mocking just the literal hides the one the component crashes on.
+ * - A bare `return;` is a value ({} ≠ undefined) the mock cannot express,
+ *   so it bails too.
+ *
+ * Keyed by MODULE-side export name ("default" for the default export) —
+ * that is the name a vi.mock factory or a host stub has to provide.
+ */
+export function extractServerActionReturns(sf: ts.SourceFile): Record<string, PropValue> {
+  const exits = exitBindings(sf);
+  const out: Record<string, PropValue> = {};
+  for (const [name, fn] of exportedFunctions(sf)) {
+    const value = singleReturnValue(fn, exits);
+    if (value !== undefined) out[name] = value;
+  }
+  return out;
+}
+
+const EXIT_CALLEES = new Set(["redirect", "permanentRedirect", "notFound"]);
+
+interface ExitBindings {
+  /** Local names bound to a next/navigation exit, aliases resolved. */
+  locals: Set<string>;
+  /** Namespace locals of next/navigation, for `nav.redirect(...)`. */
+  namespaces: Set<string>;
+}
+
+function exitBindings(sf: ts.SourceFile): ExitBindings {
+  const locals = new Set<string>();
+  const namespaces = new Set<string>();
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    if (stmt.moduleSpecifier.text !== "next/navigation") continue;
+    const bindings = stmt.importClause?.namedBindings;
+    if (!bindings) continue;
+    if (ts.isNamedImports(bindings)) {
+      for (const el of bindings.elements) {
+        if (EXIT_CALLEES.has((el.propertyName ?? el.name).text)) locals.add(el.name.text);
+      }
+    } else if (ts.isNamespaceImport(bindings)) {
+      namespaces.add(bindings.name.text);
+    }
+  }
+  return { locals, namespaces };
+}
+
+function isExitCall(expr: ts.Expression, exits: ExitBindings): boolean {
+  if (!ts.isCallExpression(expr)) return false;
+  const callee = expr.expression;
+  if (ts.isIdentifier(callee)) return exits.locals.has(callee.text);
+  return (
+    ts.isPropertyAccessExpression(callee) &&
+    ts.isIdentifier(callee.expression) &&
+    exits.namespaces.has(callee.expression.text) &&
+    EXIT_CALLEES.has(callee.name.text)
+  );
+}
+
+export type ActionFn = ts.FunctionDeclaration | ts.ArrowFunction | ts.FunctionExpression;
+
+/**
+ * Calls that hand back their function argument with the SAME call signature.
+ *
+ * `export const getCurrentUser = cache(async (): Promise<User> => …)` is the
+ * standard Next.js DAL idiom — the dogfood app's `lib/dal.ts` uses it three
+ * times — and a `CallExpression` initializer was skipped outright, so every
+ * consumer of this list saw the module as having no such export. Downstream that
+ * is a `{}` mock plus an uninferred-return TODO on a function whose return type
+ * is written down two characters away.
+ *
+ * A CLOSED table, not "any call with one function argument", because the reason
+ * for the original skip is real for most wrappers: `withPagination(async ():
+ * Promise<User[]> => …)` may well return `Promise<Page<User>>`, and unwrapping it
+ * hands the emitter the inner shape for a function that never produces it — a
+ * wrong fixture, which this repo treats as worse than none.
+ *
+ * These two are typed `<T>(fn: T) => T` and `(cb, keyParts?, opts?) => typeof cb`
+ * respectively, so for them the inner annotation IS the effective return type.
+ * Widening this set means showing the same of whatever is added — there is no
+ * type checker here to work it out.
+ */
+const IDENTITY_WRAPPERS = new Set(["cache", "unstable_cache"]);
+
+/**
+ * The function inside an allowlisted wrapper call, or undefined.
+ *
+ * Exactly one function-like argument, so `unstable_cache(fn, keyParts, opts)`
+ * resolves (only argument 0 is function-like) while anything passing two
+ * callbacks bails rather than pick one.
+ */
+function unwrapIdentityWrapper(init: ts.Expression): ActionFn | undefined {
+  if (!ts.isCallExpression(init)) return undefined;
+  // `cache(…)` and `React.cache(…)` both, keyed on the member name — the import
+  // could be aliased either way and this list is about the callee's identity.
+  const callee = init.expression;
+  const name = ts.isIdentifier(callee)
+    ? callee.text
+    : ts.isPropertyAccessExpression(callee) && ts.isIdentifier(callee.name)
+      ? callee.name.text
+      : undefined;
+  if (name === undefined || !IDENTITY_WRAPPERS.has(name)) return undefined;
+  const fns = init.arguments.filter(
+    (a): a is ts.ArrowFunction | ts.FunctionExpression =>
+      ts.isArrowFunction(a) || ts.isFunctionExpression(a),
+  );
+  return fns.length === 1 ? fns[0] : undefined;
+}
+
+/** Exported name → its function node, local declarations resolved in-file. */
+export function exportedFunctions(sf: ts.SourceFile): Array<[string, ActionFn]> {
+  // Every top-level function-ish declaration, exported or not: an export
+  // clause (`export { doSave as save }`) points at a local one.
+  const locals = new Map<string, ActionFn>();
+  const out: Array<[string, ActionFn]> = [];
+  for (const stmt of sf.statements) {
+    const modifiers = ts.canHaveModifiers(stmt) ? ts.getModifiers(stmt) : undefined;
+    const exported = modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+    const isDefault = modifiers?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword) ?? false;
+    if (ts.isFunctionDeclaration(stmt)) {
+      if (stmt.name) locals.set(stmt.name.text, stmt);
+      if (exported && isDefault) out.push(["default", stmt]);
+      else if (exported && stmt.name) out.push([stmt.name.text, stmt]);
+      continue;
+    }
+    if (ts.isVariableStatement(stmt)) {
+      for (const d of stmt.declarationList.declarations) {
+        if (!ts.isIdentifier(d.name) || d.initializer === undefined) continue;
+        const init = d.initializer;
+        const fn =
+          ts.isArrowFunction(init) || ts.isFunctionExpression(init)
+            ? init
+            : unwrapIdentityWrapper(init);
+        if (!fn) continue;
+        locals.set(d.name.text, fn);
+        if (exported) out.push([d.name.text, fn]);
+      }
+      continue;
+    }
+    // `export { doSave as save }` — the exported name is what importers bind
+    // to. A re-export from another file has no local to resolve; skipped
+    // HERE — sourceCache's findExportedDecl is the cross-file chase, and
+    // callers that want it (resolveDepReturns) walk barrels through that.
+    if (
+      ts.isExportDeclaration(stmt) &&
+      stmt.moduleSpecifier === undefined &&
+      stmt.exportClause &&
+      ts.isNamedExports(stmt.exportClause)
+    ) {
+      for (const el of stmt.exportClause.elements) {
+        const local = locals.get((el.propertyName ?? el.name).text);
+        if (local) out.push([el.name.text, local]);
+      }
+    }
+  }
+  return out;
+}
+
+/** The one literal value every non-exit return yields, else undefined. */
+function singleReturnValue(fn: ActionFn, exits: ExitBindings): PropValue | undefined {
+  // A generator's `return` sets the iterator's final result — calling the
+  // action yields an AsyncGenerator object, never a promise of that literal.
+  if (!ts.isArrowFunction(fn) && fn.asteriskToken) return undefined;
+  // A concise arrow body IS the single return expression.
+  if (ts.isArrowFunction(fn) && !ts.isBlock(fn.body)) {
+    const expr = unparenthesize(fn.body);
+    return isExitCall(expr, exits) ? undefined : literalToValue(expr);
+  }
+  if (!fn.body || !ts.isBlock(fn.body)) return undefined;
+
+  let value: PropValue | undefined;
+  let seen = false;
+  for (const ret of ownReturns(fn.body)) {
+    const expr = ret.expression === undefined ? undefined : unparenthesize(ret.expression);
+    if (expr !== undefined && isExitCall(expr, exits)) continue;
+    // Bare `return;` or a non-literal expression: a value we cannot express.
+    const v = expr === undefined ? undefined : literalToValue(expr);
+    if (v === undefined) return undefined;
+    if (seen && JSON.stringify(v) !== JSON.stringify(value)) return undefined;
+    value = v;
+    seen = true;
+  }
+  return seen ? value : undefined;
+}
+
+function unparenthesize(expr: ts.Expression): ts.Expression {
+  let e = expr;
+  while (ts.isParenthesizedExpression(e)) e = e.expression;
+  return e;
+}

package/src/analyse/sourceCache.ts

@@ -0,0 +1,263 @@
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+
+/**
+ * Parsed-source cache for the secondary files the analyser reads while
+ * resolving types across modules. Without it, every `ComponentProps<typeof X>`
+ * and every imported props type re-reads and re-parses the same file — the
+ * shadcn pattern makes that happen dozens of times per run.
+ *
+ * Failures are cached as misses too, so an unreadable path is attempted once.
+ */
+/**
+ * The leading prologue directive of a module, tolerating a license header or
+ * any run of comments before it. Shared so "use client" and "use server" cannot
+ * drift apart.
+ *
+ * The scan is head-bounded, deliberately: this runs once per IMPORTED module
+ * in a sweep, not once per file, and full-parsing to find a one-line directive
+ * would multiply the parse count by the import fan-out. 64KB covers any
+ * realistic license banner (the longest common ones run ~2–4KB) with slack; a
+ * directive hidden behind a LARGER header is the acknowledged miss of the
+ * bound — misclassified as not carrying it — and would need the bound raised,
+ * not the regex changed.
+ */
+export function readPrologueDirective(file: string): string | undefined {
+  try {
+    const head = readFileSync(file, "utf8").slice(0, 65536);
+    const m = /^\s*(?:\/\/[^\n]*\n|\/\*[\s\S]*?\*\/\s*)*["']([^"']+)["']\s*;?/.exec(head);
+    return m?.[1];
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Top-level export names of a module.
+ *
+ * Needed to stub a "use server" module for the browser bundle: exporting only
+ * the names a component imports directly leaves a transitive importer — the
+ * zustand store importing logoutAction, say — with "No matching export", and the
+ * bundle fails just as hard as it did unstubbed.
+ */
+export function exportedNames(sf: ts.SourceFile): string[] {
+  const out = new Set<string>();
+  for (const stmt of sf.statements) {
+    const exported = ts.canHaveModifiers(stmt)
+      ? ts.getModifiers(stmt)?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword)
+      : false;
+    if (ts.isVariableStatement(stmt) && exported) {
+      for (const d of stmt.declarationList.declarations) {
+        if (ts.isIdentifier(d.name)) out.add(d.name.text);
+      }
+      continue;
+    }
+    if ((ts.isFunctionDeclaration(stmt) || ts.isClassDeclaration(stmt)) && exported) {
+      // `export default function doSave()` exports "default", not "doSave" —
+      // the name is only local. Recording the name handed the server-action
+      // stub a named export the module never had, so a real default import
+      // failed to bind against it.
+      const isDefault = ts.getModifiers(stmt)?.some((m) => m.kind === ts.SyntaxKind.DefaultKeyword);
+      if (isDefault) out.add("default");
+      else if (stmt.name) out.add(stmt.name.text);
+      continue;
+    }
+    // `export { a, b as c }` — the exported name is what importers bind to.
+    if (ts.isExportDeclaration(stmt) && stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+      for (const el of stmt.exportClause.elements) out.add(el.name.text);
+    }
+  }
+  return [...out].sort();
+}
+
+/**
+ * The module and module-side name a local binding was imported under.
+ *
+ * `import type { User as U } from "./x"` looked up as "U" gives
+ * `{ specifier: "./x", importedName: "User" }`. Default and namespace imports
+ * are not reported: neither names a single exported declaration this chase can
+ * continue to.
+ */
+function importedFrom(
+  sf: ts.SourceFile,
+  local: string,
+): { specifier: string; importedName: string } | undefined {
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    const bindings = stmt.importClause?.namedBindings;
+    if (!bindings || !ts.isNamedImports(bindings)) continue;
+    for (const el of bindings.elements) {
+      if (el.name.text !== local) continue;
+      return {
+        specifier: stmt.moduleSpecifier.text,
+        importedName: (el.propertyName ?? el.name).text,
+      };
+    }
+  }
+  return undefined;
+}
+
+/** Where a re-export chase landed: the declaring file and its parse. */
+export interface RelocatedExport<T> {
+  sf: ts.SourceFile;
+  file: string;
+  decl: T;
+}
+
+/** Barrel chains deeper than this are machine-generated; stop looking. */
+const MAX_RELOCATION_DEPTH = 8;
+/** Runaway backstop across the whole walk — cycles are caught by `visited`,
+ * so this only stops pathological generated fan-outs. It counts file::name
+ * pairs, NOT breadth per level: a wide shadcn-style barrel (40+ star arms)
+ * must still reach its last arm. */
+const MAX_RELOCATION_FILES = 512;
+
+/**
+ * Find `name`'s declaration starting at `file`, chasing barrel re-exports.
+ * ESM semantics drive the order inside each file: a matching declaration
+ * first, then local export clauses (`export { Real as Renamed };` — the
+ * clause itself makes the local declaration exported), then explicit
+ * re-export clauses (`export { A as B } from "./x"`, rename-aware — these
+ * SHADOW star exports), then star re-exports (`export * from "./x"`) in
+ * declaration order. `export * as ns from` exports one namespace object,
+ * never the names behind it, and is not followed.
+ *
+ * `find` receives `viaReexport: true` for every file reached through a
+ * re-export chain — matchers use it to refuse non-exported declarations,
+ * which a star chase must never bind (a private same-named interface in an
+ * earlier arm would silently produce a wrong-shape fixture).
+ *
+ * Depth-bounded and cycle-guarded, deliberately NOT the props hop budget:
+ * component → barrel → types.ts would exhaust MAX_HOPS before a single
+ * member resolved, and relocation is finding where a name LIVES, not a
+ * semantic resolution hop.
+ */
+export function findExportedDecl<T>(
+  file: string,
+  name: string,
+  cache: SourceFileCache,
+  resolver: { resolve(spec: string, importer: string): string | undefined } | undefined,
+  find: (sf: ts.SourceFile, name: string, viaReexport: boolean) => T | undefined,
+  // For lookups reached through an IMPORT binding, the root file must vouch
+  // only for its exports too: TS never binds a private declaration to an
+  // import, so a private same-named decl in the directly-resolved module
+  // shadowing a star re-export would produce a type-illegal result. Local
+  // export clauses stay permissive — the clause itself vouches.
+  requireExportAtRoot = false,
+): RelocatedExport<T> | undefined {
+  const visited = new Set<string>();
+  const walk = (f: string, wanted: string, depth: number): RelocatedExport<T> | undefined => {
+    const key = `${f}::${wanted}`;
+    if (visited.has(key) || depth > MAX_RELOCATION_DEPTH || visited.size >= MAX_RELOCATION_FILES)
+      return undefined;
+    visited.add(key);
+    const sf = cache.get(f);
+    if (!sf) return undefined;
+    const hit = find(sf, wanted, depth > 0 || requireExportAtRoot);
+    if (hit !== undefined) return { sf, file: f, decl: hit };
+
+    const localClauses: ts.NamedExports[] = [];
+    const named: Array<{ clause: ts.NamedExports; spec: string }> = [];
+    const stars: string[] = [];
+    for (const stmt of sf.statements) {
+      if (!ts.isExportDeclaration(stmt)) continue;
+      if (!stmt.moduleSpecifier) {
+        if (stmt.exportClause && ts.isNamedExports(stmt.exportClause)) {
+          localClauses.push(stmt.exportClause);
+        }
+        continue;
+      }
+      if (!ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+      if (stmt.exportClause) {
+        if (ts.isNamedExports(stmt.exportClause)) {
+          named.push({ clause: stmt.exportClause, spec: stmt.moduleSpecifier.text });
+        }
+        continue;
+      }
+      stars.push(stmt.moduleSpecifier.text);
+    }
+
+    for (const clause of localClauses) {
+      for (const el of clause.elements) {
+        if (el.name.text !== wanted) continue;
+        const local = (el.propertyName ?? el.name).text;
+        const localHit = find(sf, local, false);
+        if (localHit !== undefined) return { sf, file: f, decl: localHit };
+        // No local DECLARATION of that name — but the file may have imported it
+        // and re-exported the binding:
+        //
+        //   import type { User } from "@scope/shared";
+        //   export type { User };
+        //
+        // ESM treats that as an export of this module, and it is how a package
+        // republishes a type it does not own. The chase stopped here, so a
+        // function annotated `Promise<User>` behind such a file resolved to
+        // nothing — which on the dogfood app is every export of lib/dal.ts.
+        const from = importedFrom(sf, local);
+        if (from) {
+          const target = resolver?.resolve(from.specifier, f);
+          if (target) {
+            const relocated = walk(target, from.importedName, depth + 1);
+            if (relocated) return relocated;
+          }
+        }
+      }
+    }
+    for (const { clause, spec } of named) {
+      for (const el of clause.elements) {
+        if (el.name.text !== wanted) continue;
+        const target = resolver?.resolve(spec, f);
+        if (!target) continue;
+        const relocated = walk(target, (el.propertyName ?? el.name).text, depth + 1);
+        if (relocated) return relocated;
+      }
+    }
+    for (const spec of stars) {
+      const target = resolver?.resolve(spec, f);
+      if (!target) continue;
+      const relocated = walk(target, wanted, depth + 1);
+      if (relocated) return relocated;
+    }
+    return undefined;
+  };
+  return walk(file, name, 0);
+}
+
+export class SourceFileCache {
+  private files = new Map<string, ts.SourceFile | null>();
+  private directives = new Map<string, string | null>();
+
+  /**
+   * True iff `abs` opens with the given prologue directive. Reads the file head
+   * only — full-parsing every imported module to answer this would multiply the
+   * parse count by the import fan-out of every entry file in a sweep.
+   */
+  hasPrologueDirective(abs: string, directive: string): boolean {
+    let hit = this.directives.get(abs);
+    if (hit === undefined) {
+      hit = readPrologueDirective(abs) ?? null;
+      this.directives.set(abs, hit);
+    }
+    return hit === directive;
+  }
+
+  /** Parse `abs` as TSX. Undefined on any read/parse failure. */
+  get(abs: string): ts.SourceFile | undefined {
+    const hit = this.files.get(abs);
+    if (hit !== undefined) return hit ?? undefined;
+    let sf: ts.SourceFile | null = null;
+    try {
+      sf = ts.createSourceFile(
+        abs,
+        readFileSync(abs, "utf8"),
+        ts.ScriptTarget.ES2022,
+        true,
+        ts.ScriptKind.TSX,
+      );
+    } catch {
+      sf = null;
+    }
+    this.files.set(abs, sf);
+    return sf ?? undefined;
+  }
+}

package/src/analyse/spreadSiblings.ts

@@ -0,0 +1,98 @@
+import ts from "typescript";
+import type { PropUsage } from "../types.ts";
+import type { ParsedComponentUnit } from "./parseFile.ts";
+import { posOf } from "./pos.ts";
+
+/**
+ * Props spread into a same-file sibling are READ there. NavLink's
+ * `Props<T> = Omit<...> & {...}` defeats the syntactic type layer — nothing
+ * resolves, nothing destructures — and NavLink's own body only forwards
+ * `props` to NavLinkInner, where `props.href.toString()` dies on
+ * `undefined.toString` in the default-mount spec. When a component hands its
+ * props param to components defined in the same file, those siblings' prop
+ * names and member reads become evidence for the {} floor in
+ * synthesiseDefaults. Transitively: NavLink → NavLinkInner → NavLinkShell.
+ */
+export function inheritSpreadSiblingProps(
+  unit: ParsedComponentUnit,
+  siblings: readonly ParsedComponentUnit[],
+  known: ReadonlySet<string>,
+  unresolvedProps: string[],
+  propUsage: PropUsage[],
+  sourceFile: ts.SourceFile,
+): void {
+  const byName = new Map<string, ParsedComponentUnit>();
+  for (const c of siblings) if (!byName.has(c.componentName)) byName.set(c.componentName, c);
+
+  const claim = (name: string, member: string | undefined, node: ts.Node): void => {
+    // These two never get a value floor: `{}` renders "[object Object]" as a
+    // className and is an invalid child as children. Left undefined, they
+    // render as nothing — which is what a defaults-only mount expects.
+    if (name === "children" || name === "className") return;
+    if (known.has(name)) return;
+    if (!unresolvedProps.includes(name)) unresolvedProps.push(name);
+    if (member !== undefined) {
+      propUsage.push({
+        propName: name,
+        kind: "member-access",
+        member,
+        pos: posOf(node, sourceFile),
+      });
+    }
+  };
+
+  const queue: ParsedComponentUnit[] = [unit];
+  const seen = new Set<ParsedComponentUnit>([unit]);
+
+  const scan = (c: ParsedComponentUnit): void => {
+    const visit = (n: ts.Node): void => {
+      if (c.paramName !== undefined) {
+        if (
+          ts.isJsxSpreadAttribute(n) &&
+          ts.isIdentifier(n.expression) &&
+          n.expression.text === c.paramName
+        ) {
+          const owner = n.parent?.parent;
+          const tag =
+            owner && (ts.isJsxOpeningElement(owner) || ts.isJsxSelfClosingElement(owner))
+              ? owner.tagName
+              : undefined;
+          if (tag !== undefined && ts.isIdentifier(tag)) {
+            const target = byName.get(tag.text);
+            if (target !== undefined && !seen.has(target)) {
+              seen.add(target);
+              queue.push(target);
+            }
+          }
+          return;
+        }
+        if (ts.isPropertyAccessExpression(n) && ts.isIdentifier(n.expression)) {
+          if (n.expression.text === c.paramName) {
+            // props.href — and props.href.toString() reads a member off it.
+            const member =
+              n.parent !== undefined &&
+              ts.isPropertyAccessExpression(n.parent) &&
+              n.parent.expression === n
+                ? n.parent.name.text
+                : undefined;
+            claim(n.name.text, member, n);
+          }
+          return;
+        }
+      }
+      // href.toString() on the component's OWN destructured binding — the
+      // sibling that destructures (NavLinkShell) carries the same evidence.
+      if (ts.isPropertyAccessExpression(n) && ts.isIdentifier(n.expression)) {
+        if (c.destructuredProps.includes(n.expression.text)) {
+          claim(c.destructuredAliases.get(n.expression.text) ?? n.expression.text, n.name.text, n);
+        }
+      }
+      ts.forEachChild(n, visit);
+    };
+    ts.forEachChild(c.bodyNode, visit);
+  };
+
+  while (queue.length > 0) {
+    scan(queue.shift() as ParsedComponentUnit);
+  }
+}

package/src/analyse/walkChildren.ts

@@ -0,0 +1,98 @@
+import ts from "typescript";
+import type { SourcePosition } from "../types.ts";
+import type { ImportBinding } from "./parseFile.ts";
+import { posOf } from "./pos.ts";
+import type { ModuleResolver } from "./resolveModule.ts";
+
+export interface ChildRef {
+  /** Full tag as written in JSX: "Card", "UI.Badge". */
+  localName: string;
+  /** Absolute path to the module holding the component. */
+  absPath: string;
+  /** Preferred component name inside the target file (named import / member tag). */
+  exportedName?: string;
+  /** First JSX usage site. */
+  pos: SourcePosition;
+}
+
+/**
+ * Walk JSX in `bodyNode`, collect referenced child components that resolve to a
+ * project-local module — via relative import, tsconfig path alias, or a
+ * same-file component declaration. Bare package imports are skipped.
+ */
+export function walkChildren(
+  bodyNode: ts.Node,
+  imports: Map<string, ImportBinding>,
+  entryFile: string,
+  sourceFile: ts.SourceFile,
+  resolver: ModuleResolver,
+  localComponents: Set<string>,
+  selfName: string,
+): ChildRef[] {
+  const seen = new Set<string>();
+  const out: ChildRef[] = [];
+
+  const visit = (n: ts.Node): void => {
+    if (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n)) {
+      const tag = n.tagName;
+      let rootName: string | undefined;
+      let fullName: string | undefined;
+      let memberName: string | undefined;
+
+      if (ts.isIdentifier(tag)) {
+        rootName = tag.text;
+        fullName = tag.text;
+      } else if (ts.isPropertyAccessExpression(tag)) {
+        let root: ts.Expression = tag.expression;
+        const segments: string[] = [tag.name.text];
+        while (ts.isPropertyAccessExpression(root)) {
+          segments.unshift(root.name.text);
+          root = root.expression;
+        }
+        if (ts.isIdentifier(root)) {
+          rootName = root.text;
+          fullName = `${root.text}.${segments.join(".")}`;
+          memberName = segments[segments.length - 1];
+        }
+      }
+
+      if (rootName && fullName && /^[A-Z]/.test(rootName) && !seen.has(fullName)) {
+        const binding = imports.get(rootName);
+        if (binding && !binding.isTypeOnly) {
+          const abs = resolver.resolve(binding.specifier, entryFile);
+          if (abs) {
+            seen.add(fullName);
+            out.push({
+              localName: fullName,
+              absPath: abs,
+              exportedName: resolveExportedName(binding, rootName, memberName),
+              pos: posOf(n, sourceFile),
+            });
+          }
+        } else if (!binding && localComponents.has(rootName) && rootName !== selfName) {
+          // Same-file secondary component.
+          seen.add(fullName);
+          out.push({
+            localName: fullName,
+            absPath: entryFile,
+            exportedName: rootName,
+            pos: posOf(n, sourceFile),
+          });
+        }
+      }
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(bodyNode, visit);
+  return out;
+}
+
+function resolveExportedName(
+  binding: ImportBinding,
+  rootName: string,
+  memberName: string | undefined,
+): string | undefined {
+  if (binding.kind === "namespace") return memberName;
+  if (binding.kind === "named") return binding.importedName ?? rootName;
+  return undefined; // default import — primary component of the target file
+}