@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/src/analyse/bootability.ts

@@ -0,0 +1,257 @@
+import { readdirSync } from "node:fs";
+import path from "node:path";
+import { flattenTrees } from "../scaffold-tests/registry.ts";
+import type { ComponentTree } from "../types.ts";
+import { isAuthLibSpecifier } from "./authShims.ts";
+import { providerShimModules } from "./providerWraps.ts";
+
+/**
+ * Will this suite boot at all?
+ *
+ * Vitest resolves a spec's imports when it COLLECTS the file, before a single
+ * test runs, and a module it cannot resolve takes the whole file down with the
+ * message `Failed to resolve import "x"`. That failure is loud in the run log
+ * and absent from REPORT.md, so lightswind-ui-library's first run read as
+ * "401 files failed, no tests" with nothing explaining itself — while every one
+ * of those files imported `framer-motion`, a package the app declares nowhere
+ * and has nowhere on disk, because it expects its CONSUMERS to provide it.
+ *
+ * This module answers the question at generation time: for every bare package
+ * specifier the analysed sources import, is the package installed anywhere the
+ * suite will look for it? It is a diagnostic, not a gate — a suite can still be
+ * worth generating for the components that DO boot.
+ */
+
+/** One module that the analysed sources import and the suite cannot resolve. */
+export interface UnresolvableImport {
+  /** Specifier as written in the source (`framer-motion`, `@scope/pkg/sub`). */
+  specifier: string;
+  /** The package whose presence was tested (`framer-motion`, `@scope/pkg`). */
+  pkg: string;
+  /** How many analysed components import it. */
+  count: number;
+  /** Up to this many component names, for the report's examples column. */
+  examples: string[];
+}
+
+/** Vite owns these: loaders, not node resolution, so they are never a miss. */
+const ASSET_SUFFIXES = [
+  ".css",
+  ".module.css",
+  ".scss",
+  ".sass",
+  ".less",
+  ".styl",
+  ".svg",
+  ".png",
+  ".jpg",
+  ".jpeg",
+  ".gif",
+  ".webp",
+  ".avif",
+  ".ico",
+  ".bmp",
+  ".mp3",
+  ".mp4",
+  ".webm",
+  ".wav",
+  ".ogg",
+  ".mov",
+  ".woff",
+  ".woff2",
+  ".ttf",
+  ".eot",
+  ".otf",
+  ".md",
+  ".mdx",
+  ".txt",
+  ".csv",
+  ".wasm",
+  ".graphql",
+  ".gql",
+];
+
+/**
+ * Specifier → package name, or undefined when the specifier is not a bare
+ * package reference at all: relative, absolute, a runtime scheme (`node:`,
+ * `bun:`, `virtual:`), or an asset vite resolves with a loader. `@scope/pkg/sub`
+ * answers `@scope/pkg`.
+ */
+export function packageNameOf(specifier: string): string | undefined {
+  if (!specifier) return undefined;
+  if (specifier.startsWith(".") || specifier.startsWith("/")) return undefined;
+  // `@/…` is the most common path alias in React, and a scope of nothing is not
+  // a package: npm requires a name after the `@`.
+  if (specifier.startsWith("@/")) return undefined;
+  if (/^[a-z]+:/.test(specifier) && !specifier.startsWith("@")) return undefined;
+  const bare = specifier.split(/[?#]/)[0] ?? specifier;
+  const lower = bare.toLowerCase();
+  if (ASSET_SUFFIXES.some((ext) => lower.endsWith(ext))) return undefined;
+  const parts = bare.split("/");
+  if (parts[0]?.startsWith("@")) return parts.length >= 2 ? `${parts[0]}/${parts[1]}` : undefined;
+  return parts[0];
+}
+
+/**
+ * Specifiers the suite already answers without the package being installed:
+ * the provider shims (canonical name and alias modules) and the auth stubs.
+ * `next/*`, `server-only` and `client-only` join because the specs `vi.mock`
+ * the framework's own namespace and every Next app resolves those through
+ * Next's bundler, not through a package on disk.
+ */
+function isStubsIt(specifier: string, pkg: string): boolean {
+  if (pkg === "server-only" || pkg === "client-only") return true;
+  if (specifier.startsWith("next/")) return true;
+  if (providerShimModules().includes(pkg)) return true;
+  return isAuthLibSpecifier(specifier);
+}
+
+/**
+ * Names of the packages in `<dir>/node_modules`, with `@scope/pkg` entries
+ * expanded (a scope directory is not a package). Cached per directory: a sweep
+ * walks the same two or three ancestors thousands of times.
+ */
+function installedNames(
+  dir: string,
+  cache: Map<string, Set<string> | undefined>,
+): Set<string> | undefined {
+  const nm = path.join(dir, "node_modules");
+  const seen = cache.get(nm);
+  if (seen !== undefined) return seen;
+  let out: Set<string> | undefined;
+  try {
+    out = new Set<string>();
+    for (const entry of readdirSync(nm)) {
+      if (entry.startsWith(".")) continue;
+      // A scope directory is not a package: `@acme` answers to no import, and
+      // adding it would make every `@acme/*` specifier look installed.
+      if (entry.startsWith("@")) {
+        try {
+          for (const inner of readdirSync(path.join(nm, entry))) out.add(`${entry}/${inner}`);
+        } catch {
+          /* unreadable scope: nothing to add */
+        }
+        continue;
+      }
+      out.add(entry);
+    }
+  } catch {
+    out = undefined;
+  }
+  cache.set(nm, out);
+  return out;
+}
+
+/**
+ * Is this specifier present in the node_modules of `dir` or any ancestor?
+ * Checked by prefix so a subpath (`framer-motion/dom`) counts as its package:
+ * exports-map and file-level correctness is not what this reports, and a false
+ * "missing" is worse than a false "present".
+ */
+function isInstalled(
+  pkg: string,
+  fromDirs: string[],
+  cache: Map<string, Set<string> | undefined>,
+): boolean {
+  for (const start of fromDirs) {
+    let dir = start;
+    for (let hop = 0; hop < 12; hop++) {
+      const names = installedNames(dir, cache);
+      if (names) {
+        const parts = pkg.split("/");
+        for (let n = parts.length; n > 0; n--) {
+          if (names.has(parts.slice(0, n).join("/"))) return true;
+        }
+      }
+      const up = path.dirname(dir);
+      if (up === dir) break;
+      dir = up;
+    }
+  }
+  return false;
+}
+
+/**
+ * Whether a component gets a spec of its own.
+ *
+ * `exportKind: "none"` is a same-file secondary — the module never exports it, so
+ * no spec can import it and the scaffolder writes none. TWO places read that fact
+ * through this one predicate: the scaffolder's spec targets and
+ * `findUnresolvableImports` below. They must not disagree, because the warning is
+ * a promise about a spec — naming an unresolvable import in a component that gets
+ * no spec promises a collect failure that cannot happen. (Witness,
+ * react-router-devtools: the run warned `clsx` for the unexported `Icon` in
+ * `plugins/icon-library/icon-library.tsx`, whose file the host cannot import
+ * either — and the plane has no clsx failure, because there is no clsx-importing
+ * spec to fail.)
+ */
+export function hasSpec(info: { exportKind?: "default" | "named" | "none" }): boolean {
+  return info.exportKind !== "none";
+}
+
+/**
+ * The bare packages the components that GET A SPEC import, installed nowhere the
+ * suite will resolve them.
+ *
+ * Resolution is per IMPORTER, because that is what vite does: the walk-up
+ * starts at the file holding the import, so a package installed by a nested
+ * package is found by that package's components and missed by everyone else —
+ * whose specs really do fail, which is exactly what this reports. `extraDirs`
+ * adds roots that are not source directories: the suite directory (its own
+ * node_modules holds the test stack) and the project root.
+ *
+ * Returns nothing when NO node_modules tree is visible from any of those
+ * directories. A Yarn-PnP or never-installed checkout cannot be judged by
+ * looking for a directory layout it does not use, and a report that called
+ * every import missing would be a lie with a straight face.
+ */
+export function findUnresolvableImports(
+  trees: ComponentTree[],
+  extraDirs: string[] = [],
+): UnresolvableImport[] {
+  const cache = new Map<string, Set<string> | undefined>();
+  // Bail condition first: is there anything to judge against at all?
+  const sourceDirs = flattenTrees(trees).map((c) => path.dirname(c.info.filePath));
+  const anyTree = [...sourceDirs, ...extraDirs].some((dir) => {
+    let at = dir;
+    for (let hop = 0; hop < 12; hop++) {
+      if (installedNames(at, cache) !== undefined) return true;
+      const up = path.dirname(at);
+      if (up === at) break;
+      at = up;
+    }
+    return false;
+  });
+  if (!anyTree) return [];
+
+  const bySpec = new Map<string, { pkg: string; names: Set<string> }>();
+  for (const { info } of flattenTrees(trees)) {
+    // Only what will have a spec: see hasSpec. An unexported component's import
+    // is a fact about the app, not about this run — no spec imports it, so no
+    // spec fails collecting it.
+    if (!hasSpec(info)) continue;
+    const fromDirs = [path.dirname(info.filePath), ...extraDirs];
+    for (const mi of info.moduleImports ?? []) {
+      // `import type` is erased before vite sees it; a side-effect import has
+      // no binding to lose, and neither is collected here anyway.
+      if (mi.isTypeOnly) continue;
+      // The analyser already resolved it — through a tsconfig `paths` alias or a
+      // relative path — so the file is on disk and vite will find it too. This
+      // is what keeps `@/components/ui` off the list in the app that aliases it.
+      if (mi.resolvedPath) continue;
+      const pkg = packageNameOf(mi.specifier);
+      if (!pkg || isStubsIt(mi.specifier, pkg)) continue;
+      if (isInstalled(pkg, fromDirs, cache)) continue;
+      const row = bySpec.get(mi.specifier) ?? { pkg, names: new Set<string>() };
+      row.names.add(info.componentName);
+      bySpec.set(mi.specifier, row);
+    }
+  }
+
+  const out: UnresolvableImport[] = [];
+  for (const [specifier, row] of bySpec) {
+    const examples = [...row.names].sort().slice(0, 3);
+    out.push({ specifier, pkg: row.pkg, count: row.names.size, examples });
+  }
+  return out.sort((a, b) => b.count - a.count || (a.specifier < b.specifier ? -1 : 1));
+}

package/src/analyse/childBridge.ts

@@ -0,0 +1,302 @@
+import ts from "typescript";
+import { DATE_PROP_SENTINEL, type DataDepInfo, type MockField, type MockShape } from "../types.ts";
+
+/**
+ * The bridge: what a rendered CHILD needs on a prop flows BACK into what
+ * the parent's fixtures carry.
+ *
+ * A spec renders its children for real, and the child reads fields nobody
+ * upstream thought to fill. Drop passes `date={drop.createdAt}` to a
+ * RelativeTime that calls date.getTime() — the chain read on drop stops at
+ * `.createdAt`, the dep fixture has no idea the value is a Date, and the
+ * mount dies inside the child with `undefined is not an object`, or worse a
+ * plausible ISO STRING where `toLocaleTimeString` was expected. The child
+ * knew — its own typed prop resolved to a Date stand-in — but that knowledge
+ * never crossed the JSX boundary. It does now, two ways:
+ *
+ *   bridgePropValues — attr sites rooted at a PROP of the unit, applied by
+ *                       synthesiseDefaults: the unit's DEFAULTS gain nested
+ *                       values (drop.createdAt becomes a live Date).
+ *   bridgeDataShapes  — attr sites rooted at a data dep or the element of
+ *                       `dep.map(item => …)`: the mock fixture grows the
+ *                       fields the child will read off what it is handed.
+ */
+
+/** tag → attr → the value that child's own defaults put on that prop. */
+export type ChildExpected = Record<string, Record<string, unknown>>;
+
+/**
+ * Propagate a child's expected prop value into an unresolved prop's
+ * stand-in. `member` marks a `date={drop.createdAt}` site (the value is one
+ * hop INTO the prop); without it the whole prop flows in (`drop={item}`).
+ * Returns a fresh value when anything changed, undefined when not.
+ */
+export function bridgePropValues(
+  current: unknown,
+  member: string | undefined,
+  expected: unknown,
+): unknown {
+  if (expected === undefined) return undefined;
+  if (member === undefined) return richer(expected, current) ? expected : undefined;
+  const base =
+    current !== null && typeof current === "object" && !Array.isArray(current)
+      ? (current as Record<string, unknown>)
+      : {};
+  if (!richer(expected, base[member])) return undefined;
+  return { ...base, [member]: expected };
+}
+
+/** Would `want` survive more reads than `have`? The sentinel Date ranks as Date. */
+function richer(want: unknown, have: unknown): boolean {
+  return rank(want) > rank(have);
+}
+
+function rank(v: unknown): number {
+  if (v === DATE_PROP_SENTINEL) return 3;
+  if (v === null || typeof v !== "object") return typeof v === "string" ? 1 : 0;
+  if (Array.isArray(v)) return 2;
+  return 4;
+}
+
+/**
+ * A child's expected VALUE as a fixture SHAPE. Booleans are skipped: no
+ * boolean kind exists, and injecting a truthy stand-in could flip a branch
+ * every later assertion reads.
+ *
+ * Strings split in two. A synth-seeded placeholder ("flawless-handle", "")
+ * carries no evidence about WHICH string fits, so it merges as the generic
+ * string kind. A string that survived synthesis VERBATIM is type evidence —
+ * an arm of a literal union ('like' | 'repost' | …) — and the mock must
+ * emit exactly that: NotificationList indexes ICONS by n.kind, and a
+ * plausible-but-wrong 'flawless-kind' looks up undefined and crashes the
+ * render. Verbatim strings ride as the field's `equals` value.
+ */
+interface Wanted {
+  shape: MockShape;
+  equals?: unknown;
+}
+
+function valueToShape(v: unknown): Wanted | undefined {
+  if (v === DATE_PROP_SENTINEL) return { shape: { kind: "date" } };
+  if (typeof v === "number") return { shape: { kind: "number" } };
+  if (typeof v === "string") {
+    if (v === "" || v.startsWith("flawless-")) return { shape: { kind: "string" } };
+    return { shape: { kind: "string" }, equals: v };
+  }
+  // A MISSING element means "no evidence" and mockValues renders []; an
+  // UNKNOWN element means "render {}" — Replies learned the difference the
+  // hard way when [] became [{}] and started mounting a crashing child.
+  if (Array.isArray(v)) return { shape: { kind: "array" } };
+  if (v !== null && typeof v === "object") {
+    const fields: MockField[] = [];
+    for (const [name, fv] of Object.entries(v as Record<string, unknown>)) {
+      const w = valueToShape(fv);
+      if (!w) continue;
+      fields.push({
+        name,
+        shape: w.shape,
+        rendersAsText: false,
+        ...(w.equals !== undefined ? { equals: w.equals as MockField["equals"] } : {}),
+      });
+    }
+    return { shape: { kind: "object", fields } };
+  }
+  return undefined;
+}
+
+/** Fold `wanted` into `existing`; existing evidence wins unless it is vaguer. */
+function mergeShape(existing: MockShape | undefined, wanted: MockShape): MockShape {
+  // Unknown carries no evidence; it may never overwrite (or replace) a shape
+  // that knows more.
+  if (wanted.kind === "unknown") return existing ?? wanted;
+  if (!existing) return wanted;
+  if (existing.kind === "unknown" || existing.kind === "truthy-object") return wanted;
+  if (existing.kind === "array") {
+    if (wanted.kind === "array" && wanted.element && !existing.element)
+      return { kind: "array", element: wanted.element };
+    return existing;
+  }
+  if (existing.kind === "object" && wanted.kind === "object") {
+    const fields = [...existing.fields];
+    for (const w of wanted.fields) {
+      const at = fields.findIndex((f) => f.name === w.name);
+      const prev = at === -1 ? undefined : fields[at];
+      if (prev === undefined) {
+        fields.push(w);
+        continue;
+      }
+      const merged = { ...prev, shape: mergeShape(prev.shape, w.shape) };
+      // A literal the parent never knew about is pure gain; a literal the
+      // parent inferred from a comparison site (`kind === "repost"`) stays.
+      if (merged.equals === undefined && w.equals !== undefined) merged.equals = w.equals;
+      fields[at] = merged;
+    }
+    return { kind: "object", fields };
+  }
+  // A child that calls Date methods outranks a rendered ISO string.
+  if (wanted.kind === "date" && (existing.kind === "string" || existing.kind === "date-string"))
+    return wanted;
+  return existing;
+}
+
+const ELEM_METHODS = new Set(["map", "filter", "find", "some", "every", "forEach", "flatMap"]);
+
+interface Site {
+  tag: string;
+  attr: string;
+  root: string;
+  path: string[];
+}
+
+/**
+ * Fill a data dep's fixture with what the rendered children read off the
+ * values handed to them. `items` reaches `<Drop drop={item.drop}>` through
+ * `items.map(item => …)`: the Drop child's own defaults say drop carries a
+ * body and a Date createdAt, so the array element's `drop` field grows them.
+ */
+export function bridgeDataShapes(
+  bodyNode: ts.Node,
+  dataDeps: DataDepInfo[],
+  childExpected: ChildExpected,
+): void {
+  const depVars = new Set(
+    dataDeps.map((d) => d.varName).filter((v): v is string => v !== undefined),
+  );
+  if (depVars.size === 0) return;
+
+  // `items.map(item => …)` binds item to the ELEMENT of items.
+  const elemAliases = new Map<string, string>();
+  const collectAliases = (n: ts.Node): void => {
+    if (
+      ts.isCallExpression(n) &&
+      ts.isPropertyAccessExpression(n.expression) &&
+      ts.isIdentifier(n.expression.expression) &&
+      depVars.has(n.expression.expression.text) &&
+      ELEM_METHODS.has(n.expression.name.text)
+    ) {
+      const cb = n.arguments[0];
+      const param =
+        cb && (ts.isArrowFunction(cb) || ts.isFunctionExpression(cb))
+          ? cb.parameters[0]
+          : undefined;
+      if (param && ts.isIdentifier(param.name)) {
+        elemAliases.set(param.name.text, n.expression.expression.text);
+      }
+    }
+    ts.forEachChild(n, collectAliases);
+  };
+  ts.forEachChild(bodyNode, collectAliases);
+
+  // JSX attr sites whose value is rooted at a dep var or an element alias.
+  const sites: Site[] = [];
+  const rootedAt = (expr: ts.Expression): { root: string; path: string[] } | undefined => {
+    let n: ts.Node = expr;
+    const path: string[] = [];
+    while (ts.isPropertyAccessExpression(n)) {
+      path.unshift(n.name.text);
+      n = n.expression;
+    }
+    if (ts.isIdentifier(n) && (depVars.has(n.text) || elemAliases.has(n.text))) {
+      return { root: n.text, path };
+    }
+    return undefined;
+  };
+  const collectSites = (n: ts.Node): void => {
+    if (ts.isJsxAttribute(n)) {
+      const init = n.initializer;
+      const expr = init ? (ts.isJsxExpression(init) ? init.expression : init) : undefined;
+      const tag = owningTag(n);
+      const attr = ts.isIdentifier(n.name) ? n.name.text : n.name.getText();
+      if (expr && tag) {
+        // Ternary/logical branches all reach the child — take every leaf.
+        const queue: ts.Node[] = [expr];
+        while (queue.length > 0) {
+          const e = queue.shift() as ts.Node;
+          if (
+            ts.isConditionalExpression(e) ||
+            ts.isBinaryExpression(e) ||
+            ts.isParenthesizedExpression(e) ||
+            ts.isJsxExpression(e)
+          ) {
+            e.getChildren().forEach((c) => queue.push(c));
+            continue;
+          }
+          const found = rootedAt(e as ts.Expression);
+          if (found) sites.push({ tag, attr, root: found.root, path: found.path });
+        }
+      }
+    }
+    ts.forEachChild(n, collectSites);
+  };
+  collectSites(bodyNode);
+  if (sites.length === 0) return;
+
+  for (const site of sites) {
+    const wanted = valueToShape(childExpected[site.tag]?.[site.attr]);
+    if (!wanted) continue;
+    const aliasOf = elemAliases.get(site.root);
+    for (const dep of dataDeps) {
+      const isElem = aliasOf !== undefined && dep.varName === aliasOf;
+      const isVar = dep.varName === site.root;
+      if (!isVar && !isElem) continue;
+      if (isElem) {
+        // A `.map()` site writes the ELEMENT, so only an array dep can take it.
+        if (dep.shape.kind !== "array") continue;
+        const element = applyPath(dep.shape.element ?? { kind: "unknown" }, wanted, site.path);
+        dep.shape = { kind: "array", element };
+      } else {
+        dep.shape = applyPath(dep.shape, wanted, site.path);
+      }
+    }
+  }
+}
+
+/**
+ * Merge `wanted` at `path` below `root`, rebuilding objects on the way so a
+ * shape shared between two deps cannot leak. A path hop that does not exist
+ * yet grows an object field; the merge lands at the end of the path.
+ */
+function applyPath(root: MockShape, wanted: Wanted, path: string[]): MockShape {
+  if (path.length === 0) return mergeShape(root, wanted.shape);
+  if (root.kind !== "object") {
+    // The read went THROUGH this hop, so it has to be an object whatever
+    // the body inferred here — unless what stands here already answers it.
+    if (root.kind !== "unknown" && root.kind !== "truthy-object") return root;
+    root = { kind: "object", fields: [] };
+  }
+  // `path.length === 0` returned above, so the hop exists. Named because the
+  // indexed reads below need `string`, not `string | undefined`.
+  const head = path[0];
+  if (head === undefined) return root;
+  const tail = path.slice(1);
+  const fields = [...root.fields];
+  const at = fields.findIndex((f) => f.name === head);
+  const prev = at === -1 ? undefined : fields[at];
+  // A literal rides on the FIELD standing at the END of the path.
+  const atEnd = tail.length === 0 && wanted.equals !== undefined;
+  if (prev === undefined) {
+    const made = applyPath({ kind: "unknown" }, wanted, tail);
+    const field: MockField = { name: head, shape: made, rendersAsText: false };
+    if (atEnd) field.equals = wanted.equals as MockField["equals"];
+    fields.push(field);
+  } else {
+    const merged = { ...prev, shape: applyPath(prev.shape, wanted, tail) };
+    if (atEnd && merged.equals === undefined) merged.equals = wanted.equals as MockField["equals"];
+    fields[at] = merged;
+  }
+  return { kind: "object", fields };
+}
+
+/** The JSX element an attribute belongs to — its tag text, for child lookups. */
+function owningTag(n: ts.Node): string | undefined {
+  let cur: ts.Node = n.parent;
+  while (
+    cur &&
+    !(ts.isJsxOpeningElement(cur) || ts.isJsxSelfClosingElement(cur) || ts.isJsxElement(cur))
+  ) {
+    cur = cur.parent;
+  }
+  if (!cur) return undefined;
+  if (ts.isJsxElement(cur)) cur = cur.openingElement;
+  return ts.isJsxOpeningLikeElement(cur) ? cur.tagName.getText() : undefined;
+}

package/src/analyse/childrenIntoSlot.ts

@@ -0,0 +1,66 @@
+import ts from "typescript";
+
+/**
+ * True when the component hands its `children` prop to an element that only
+ * accepts ELEMENT children: an `asChild` element (Radix Slot semantics — the
+ * element is replaced by its child, and Slot clones an element, never a text
+ * node) or a bare `<Slot>` / `<Slottable>`.
+ *
+ * The app always passes a real element to these, but a unit fixture passes
+ * plain text, and every such mount dies at render with
+ * "Primitive.button failed to slot onto its children. Expected a single React
+ * element child or Slottable" (miro-clone: Hint, Actions, ConfirmModal —
+ * each one a Trigger-wrap). The flag makes the unit template pass a
+ * <span>{CHILD_TEXT}</span> instead of the bare string — which renders
+ * identically through every non-slot children site too.
+ */
+export function childrenIntoSlot(bodyNode: ts.Node): boolean {
+  let found = false;
+  const walk = (n: ts.Node): void => {
+    if (found) return;
+    if (ts.isJsxElement(n)) {
+      const opening = n.openingElement;
+      const tag = plainTagName(opening);
+      // Qualified tags (<Radix.Slot>) are skipped: the local name is
+      // unknowable, and asChild detection does not need the name at all.
+      const isSlotEl = tag === "Slot" || tag === "Slottable";
+      const asChild = opening.attributes.properties.some(isAsChildAttr);
+      if ((isSlotEl || asChild) && n.children.some(isChildrenExpr)) {
+        found = true;
+        return;
+      }
+    }
+    ts.forEachChild(n, walk);
+  };
+  walk(bodyNode);
+  return found;
+}
+
+/** The JSX children slot holding exactly the `{children}` identifier expression. */
+function isChildrenExpr(n: ts.Node): boolean {
+  return (
+    ts.isJsxExpression(n) &&
+    n.expression !== undefined &&
+    ts.isIdentifier(n.expression) &&
+    n.expression.text === "children"
+  );
+}
+
+/** `asChild`, `asChild={true}`, `asChild={cond}` — everything except an explicit false. */
+function isAsChildAttr(p: ts.JsxAttributeLike): boolean {
+  if (!ts.isJsxAttribute(p) || !ts.isIdentifier(p.name) || p.name.text !== "asChild") return false;
+  const init = p.initializer;
+  if (init === undefined) return true; // bare `asChild`
+  if (ts.isStringLiteral(init)) return init.text !== "false";
+  if (ts.isJsxExpression(init) && init.expression) {
+    const e = init.expression;
+    if (e.kind === ts.SyntaxKind.FalseKeyword) return false;
+    return true;
+  }
+  return false;
+}
+
+/** The JSX opening tag as a plain identifier, if it is one. */
+function plainTagName(opening: ts.JsxOpeningElement): string | undefined {
+  return ts.isIdentifier(opening.tagName) ? opening.tagName.text : undefined;
+}