@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/src/analyse/extractRenderMode.ts

@@ -0,0 +1,165 @@
+import ts from "typescript";
+import type { RenderMode } from "../types.ts";
+import type { ImportBinding } from "./parseFile.ts";
+import { emptyEnv, initialRenderExpression, type RenderEnv } from "./renderPath.ts";
+
+/**
+ * How a component can be mounted in a test, and why.
+ *
+ * Some components genuinely cannot be rendered standalone, and generating a
+ * render-based assertion for them produces a red suite that says nothing. A
+ * design-system "part" (`<Dialog.Content>`, `<Select.Item>`) throws
+ * "SelectRootContext is missing" outside its Root; a root layout returns
+ * `<html>`, which React cannot mount inside a container div; a hydrator
+ * returns null. Naming the situation lets the scaffolder assert what IS true
+ * instead of pretending.
+ */
+
+/** Headless-UI packages whose parts require a Root ancestor. */
+const COMPOUND_PACKAGES = /^@(base-ui|radix-ui|ariakit)(\/|$)/;
+
+/** Members that ARE the provider — these render fine on their own. */
+const ROOT_MEMBERS = new Set(["Root", "Provider"]);
+
+export interface RenderModeResult {
+  mode: RenderMode;
+  /** Human-readable reason, emitted into the spec and the run report. */
+  note?: string;
+}
+
+export function extractRenderMode(
+  bodyNode: ts.Node,
+  imports: Map<string, ImportBinding>,
+  isAsync: boolean,
+  env: RenderEnv = emptyEnv(),
+  /** Render modes of the other components declared in the same file. */
+  localModes?: Map<string, RenderMode>,
+): RenderModeResult {
+  const expr = initialRenderExpression(bodyNode, env)?.expr;
+
+  if (expr && isNullLiteral(expr)) {
+    return {
+      mode: "null",
+      note: "returns null — asserted as an empty container rather than visible output",
+    };
+  }
+
+  // The part is often nested rather than the root: DialogContent returns
+  // <DialogPortal><DialogPrimitive.Popup>…, so checking only the root tag
+  // misses it. Scan the whole unconditional render subtree instead.
+  const part = findUnrootedCompoundPart(expr, imports);
+  if (part) {
+    return {
+      mode: "compound-part",
+      note:
+        `renders <${part.root}.${part.member}> from ${part.specifier}, which throws outside its ` +
+        `Root. Wrap renderTarget() in the matching <Root open> to assert its content.`,
+    };
+  }
+
+  // A part can also be reached one hop away: DropdownMenuSubContent returns
+  // <DropdownMenuContent>, which is itself a part declared in the same file. The
+  // scan above only sees `X.Member` tags, so without this the wrapper looks
+  // perfectly renderable and its spec fails with "MenuRootContext is missing".
+  const localPart = findLocalCompoundPart(expr, localModes);
+  if (localPart) {
+    return {
+      mode: "compound-part",
+      note:
+        `renders <${localPart}>, itself a compound part that throws outside its Root. ` +
+        `Wrap renderTarget() in the matching <Root open> to assert its content.`,
+    };
+  }
+
+  const intrinsic = intrinsicTagOf(expr);
+  if (intrinsic === "html") {
+    return {
+      mode: "document-root",
+      note: "returns a document root (<html>) — React cannot mount that inside a container",
+    };
+  }
+
+  return { mode: isAsync ? "rsc" : "client" };
+}
+
+function isNullLiteral(expr: ts.Expression): boolean {
+  return expr.kind === ts.SyntaxKind.NullKeyword;
+}
+
+/**
+ * A compound-package part rendered without its own Root anywhere in the same
+ * subtree. A component that renders `<X.Root>` around its parts supplies its
+ * own context and is perfectly renderable, so it must not be flagged.
+ */
+function findUnrootedCompoundPart(
+  expr: ts.Expression | undefined,
+  imports: Map<string, ImportBinding>,
+): { root: string; member: string; specifier: string } | undefined {
+  if (!expr) return undefined;
+
+  const parts: Array<{ root: string; member: string; specifier: string }> = [];
+  const rootsProvided = new Set<string>();
+
+  const visit = (n: ts.Node): void => {
+    let tagName: ts.JsxTagNameExpression | undefined;
+    if (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n)) tagName = n.tagName;
+    if (tagName && ts.isPropertyAccessExpression(tagName)) {
+      let root: ts.Expression = tagName.expression;
+      while (ts.isPropertyAccessExpression(root)) root = root.expression;
+      if (ts.isIdentifier(root)) {
+        const binding = imports.get(root.text);
+        if (binding && COMPOUND_PACKAGES.test(binding.specifier)) {
+          const member = tagName.name.text;
+          if (ROOT_MEMBERS.has(member)) rootsProvided.add(root.text);
+          else parts.push({ root: root.text, member, specifier: binding.specifier });
+        }
+      }
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(expr);
+
+  return parts.find((p) => !rootsProvided.has(p.root));
+}
+
+/**
+ * The first same-file component in this subtree that is itself a compound part.
+ *
+ * Resolution is one hop and same-file only: a cross-file wrapper would need the
+ * child tree, which is built later and not available here.
+ */
+function findLocalCompoundPart(
+  expr: ts.Expression | undefined,
+  localModes: Map<string, RenderMode> | undefined,
+): string | undefined {
+  if (!expr || !localModes || localModes.size === 0) return undefined;
+
+  let found: string | undefined;
+  const visit = (n: ts.Node): void => {
+    if (found) return;
+    let tagName: ts.JsxTagNameExpression | undefined;
+    if (ts.isJsxOpeningElement(n) || ts.isJsxSelfClosingElement(n)) tagName = n.tagName;
+    if (tagName && ts.isIdentifier(tagName) && localModes.get(tagName.text) === "compound-part") {
+      found = tagName.text;
+      return;
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(expr);
+  return found;
+}
+
+function intrinsicTagOf(expr: ts.Expression | undefined): string | undefined {
+  const tagName = jsxTagName(expr);
+  if (!tagName || !ts.isIdentifier(tagName)) return undefined;
+  return /^[a-z]/.test(tagName.text) ? tagName.text : undefined;
+}
+
+function jsxTagName(expr: ts.Expression | undefined): ts.JsxTagNameExpression | undefined {
+  if (!expr) return undefined;
+  let node: ts.Expression = expr;
+  while (ts.isParenthesizedExpression(node)) node = node.expression;
+  if (ts.isJsxElement(node)) return node.openingElement.tagName;
+  if (ts.isJsxSelfClosingElement(node)) return node.tagName;
+  return undefined;
+}

package/src/analyse/extractRootTag.ts

@@ -0,0 +1,117 @@
+import ts from "typescript";
+import { domOnlyResolver, type HostTagResolver } from "./hostTag.ts";
+import { emptyEnv, initialRenderExpression, type RenderEnv } from "./renderPath.ts";
+
+/**
+ * The JSX root a component renders on its happy path, as a tag name.
+ *
+ * Consumers turn this into an assertion about the rendered container, so a
+ * wrong answer is a red spec in someone else's repo. Every case where the root
+ * is not pinned down by syntax alone — a fragment, a conditional, a qualified
+ * tag, a second return with a different root — gives up instead of guessing.
+ * The tag is returned as written and may be uppercase (`ButtonPrimitive`); the
+ * caller decides whether a component root is useful to it.
+ */
+export function extractRootTag(
+  bodyNode: ts.Node,
+  env: RenderEnv = emptyEnv(),
+  /**
+   * Which tags count as host elements. Defaults to the lowercase-intrinsic rule
+   * this function has always used, so every existing caller is unchanged.
+   */
+  hostTag: HostTagResolver = domOnlyResolver,
+): string | undefined {
+  // The INITIAL render, not the last return: a component that opens collapsed
+  // renders its guard branch, and describing it by the expanded branch below
+  // would name a tag the spec never produces.
+  const root = initialRenderExpression(bodyNode, env)?.expr;
+  if (!root) return undefined;
+  // A fragment renders no host element to assert against, and a conditional
+  // root depends on props the spec picks independently of this analysis.
+  if (!ts.isJsxElement(root) && !ts.isJsxSelfClosingElement(root)) return undefined;
+
+  const tag = plainTagName(root);
+  if (tag === undefined) return undefined;
+  // Host elements only, as the field's own contract says. A component root is
+  // not an answer to "what element does this render" — shadcn's Button returns
+  // <ButtonPrimitive>, and reporting that let a caller conclude the render
+  // contained an element called "ButtonPrimitive" and no button at all. Every
+  // consumer wants a real tag: the spec's querySelector, the content-model
+  // wrapper, the ambiguity census.
+  //
+  // The predicate moved to hostTag.ts, and with it the answer for React Native:
+  // <View> is a host element even though it is capitalised, because THIS FILE
+  // imports it from "react-native". Under the default resolver the test is the
+  // same lowercase one it has always been. Without this, rootTag was undefined
+  // for every RN component, which silently took the root-tag contract test, the
+  // WRAP_IN table and the ambiguity census down with it.
+  const resolved = hostTag(tag);
+  if (resolved === undefined) return undefined;
+
+  // The MODULE-SIDE name, so `import { View as Box }` reports "View". Agreement
+  // between returns is checked on the tag as written, which is what the source
+  // actually repeats.
+  return everyReturnAgrees(bodyNode, root, tag) ? resolved.name : undefined;
+}
+
+function unwrapParens(expr: ts.Expression): ts.Expression {
+  let current = expr;
+  while (ts.isParenthesizedExpression(current)) current = current.expression;
+  return current;
+}
+
+function plainTagName(el: ts.JsxElement | ts.JsxSelfClosingElement): string | undefined {
+  const tagName = ts.isJsxElement(el) ? el.openingElement.tagName : el.tagName;
+  // <UI.Badge /> renders whatever the namespace object holds under that key;
+  // "Badge" and "UI.Badge" are both lies about the emitted element.
+  return ts.isIdentifier(tagName) ? tagName.text : undefined;
+}
+
+/**
+ * Every other return in the component must render the same tag or nothing at
+ * all. `if (!user) return null` leaves the happy-path root unambiguous, while
+ * `if (loading) return <Skeleton />` means the rendered root is decided by
+ * props and no single tag describes the component.
+ */
+function everyReturnAgrees(bodyNode: ts.Node, root: ts.Expression, tag: string): boolean {
+  let agrees = true;
+
+  const compatible = (expr: ts.Expression | undefined): boolean => {
+    if (expr === undefined || expr === root) return true;
+    if (rendersNothing(expr)) return true;
+    if (ts.isJsxElement(expr) || ts.isJsxSelfClosingElement(expr)) {
+      return plainTagName(expr) === tag;
+    }
+    // `return content` may hold any element; unknowable without a type checker.
+    return false;
+  };
+
+  const visit = (n: ts.Node): void => {
+    if (!agrees) return;
+    // Returns inside a nested callback belong to that callback — a `.map` row,
+    // a render prop — not to the component.
+    if (n !== bodyNode && isFunctionBoundary(n)) return;
+    if (ts.isReturnStatement(n)) {
+      const expr = n.expression ? unwrapParens(n.expression) : undefined;
+      if (!compatible(expr)) {
+        agrees = false;
+        return;
+      }
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(bodyNode);
+
+  return agrees;
+}
+
+function rendersNothing(expr: ts.Expression): boolean {
+  if (expr.kind === ts.SyntaxKind.NullKeyword || expr.kind === ts.SyntaxKind.FalseKeyword) {
+    return true;
+  }
+  return ts.isIdentifier(expr) && expr.text === "undefined";
+}
+
+function isFunctionBoundary(n: ts.Node): boolean {
+  return ts.isArrowFunction(n) || ts.isFunctionExpression(n) || ts.isFunctionDeclaration(n);
+}

package/src/analyse/extractState.ts

@@ -0,0 +1,361 @@
+import ts from "typescript";
+import type { SetterCallSite, StateInfo, StateJsxFlow, StateKind } from "../types.ts";
+import { posOf } from "./pos.ts";
+import { collectRefs, hookCalleeName } from "./refs.ts";
+import { literalToValue } from "./renderPath.ts";
+
+const INITIAL_RAW_MAX = 120;
+
+/**
+ * Extracts useState/useReducer/useRef declarations from a component body,
+ * with setter call sites (context + guard classification) and JSX flows.
+ * Purely syntactic — companion to extractInteractions/extractProps.
+ */
+export function extractState(bodyNode: ts.Node, sourceFile: ts.SourceFile): StateInfo[] {
+  const out: StateInfo[] = [];
+
+  const visit = (n: ts.Node): void => {
+    if (ts.isVariableDeclaration(n) && n.initializer && ts.isCallExpression(n.initializer)) {
+      const hook = hookCalleeName(n.initializer.expression);
+      // useActionState(action, initialState) has useReducer's shape exactly, and
+      // its initial state is a literal in the source. Without it, `state` was
+      // opaque, every guard on it was undecidable, and — once an undecidable
+      // render started refusing rather than guessing — two correct React 19 form
+      // components lost their whole spec to a refusal that was simply wrong.
+      if (
+        hook === "useState" ||
+        hook === "useReducer" ||
+        hook === "useRef" ||
+        hook === "useActionState"
+      ) {
+        const info = buildStateInfo(n, n.initializer, hook, bodyNode, sourceFile);
+        if (info) out.push(info);
+      }
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(bodyNode, visit);
+
+  return out;
+}
+
+function buildStateInfo(
+  decl: ts.VariableDeclaration,
+  call: ts.CallExpression,
+  kind: StateKind,
+  bodyNode: ts.Node,
+  sourceFile: ts.SourceFile,
+): StateInfo | undefined {
+  let varName: string | undefined;
+  let setterName: string | undefined;
+  if (kind !== "useRef" && ts.isArrayBindingPattern(decl.name)) {
+    const el0 = decl.name.elements[0];
+    const el1 = decl.name.elements[1];
+    if (el0 && ts.isBindingElement(el0) && ts.isIdentifier(el0.name)) varName = el0.name.text;
+    if (el1 && ts.isBindingElement(el1) && ts.isIdentifier(el1.name)) setterName = el1.name.text;
+  } else if (ts.isIdentifier(decl.name)) {
+    varName = decl.name.text;
+  }
+  if (varName === undefined) return undefined;
+
+  // useReducer(reducer, initialState) and useActionState(action, initialState) —
+  // the init value is the second argument in both.
+  const initExpr =
+    kind === "useReducer" || kind === "useActionState" ? call.arguments[1] : call.arguments[0];
+  const initialValue = initExpr ? literalToValue(initExpr) : undefined;
+  const initialRaw = initExpr ? initExpr.getText(sourceFile).slice(0, INITIAL_RAW_MAX) : "";
+  const typeKind = classifyTypeKind(call.typeArguments?.[0], initExpr);
+
+  const setterCalls: SetterCallSite[] = [];
+  if (kind === "useRef") {
+    collectRefAssignments(bodyNode, sourceFile, varName, setterCalls);
+  } else if (setterName !== undefined) {
+    collectSetterCalls(bodyNode, sourceFile, setterName, setterCalls);
+  }
+
+  return {
+    kind,
+    varName,
+    setterName,
+    initialValue,
+    initialRaw,
+    typeKind,
+    pos: posOf(decl, sourceFile),
+    setterCalls,
+    flowsToJsx: collectJsxFlows(bodyNode, sourceFile, varName),
+    setterCalledInEffect: setterCalls.some((c) => c.context === "effect"),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Initial value / type classification
+// ---------------------------------------------------------------------------
+
+function classifyTypeKind(
+  typeArg: ts.TypeNode | undefined,
+  initExpr: ts.Expression | undefined,
+): StateInfo["typeKind"] {
+  if (typeArg) return typeKindFromTypeNode(typeArg);
+  if (initExpr) return typeKindFromExpression(initExpr);
+  return "unknown";
+}
+
+function typeKindFromTypeNode(t: ts.TypeNode): StateInfo["typeKind"] {
+  switch (t.kind) {
+    case ts.SyntaxKind.StringKeyword:
+      return "string";
+    case ts.SyntaxKind.NumberKeyword:
+      return "number";
+    case ts.SyntaxKind.BooleanKeyword:
+      return "boolean";
+    default:
+      break;
+  }
+  if (ts.isLiteralTypeNode(t) && t.literal.kind === ts.SyntaxKind.NullKeyword) return "null";
+  if (ts.isArrayTypeNode(t)) return "array";
+  if (ts.isTypeLiteralNode(t)) return "object";
+  return "unknown";
+}
+
+function typeKindFromExpression(e: ts.Expression): StateInfo["typeKind"] {
+  if (ts.isStringLiteral(e) || ts.isNoSubstitutionTemplateLiteral(e)) return "string";
+  if (ts.isNumericLiteral(e)) return "number";
+  if (e.kind === ts.SyntaxKind.TrueKeyword || e.kind === ts.SyntaxKind.FalseKeyword) {
+    return "boolean";
+  }
+  if (e.kind === ts.SyntaxKind.NullKeyword) return "null";
+  if (ts.isArrayLiteralExpression(e)) return "array";
+  if (ts.isObjectLiteralExpression(e)) return "object";
+  if (isNegativeNumber(e)) return "number";
+  return "unknown";
+}
+
+function isNegativeNumber(e: ts.Expression): e is ts.PrefixUnaryExpression {
+  return (
+    ts.isPrefixUnaryExpression(e) &&
+    e.operator === ts.SyntaxKind.MinusToken &&
+    ts.isNumericLiteral(e.operand)
+  );
+}
+
+// ---------------------------------------------------------------------------
+// Setter call sites
+// ---------------------------------------------------------------------------
+
+function collectSetterCalls(
+  bodyNode: ts.Node,
+  sourceFile: ts.SourceFile,
+  setterName: string,
+  out: SetterCallSite[],
+): void {
+  const visit = (n: ts.Node): void => {
+    if (
+      ts.isCallExpression(n) &&
+      ts.isIdentifier(n.expression) &&
+      n.expression.text === setterName
+    ) {
+      out.push({
+        pos: posOf(n, sourceFile),
+        ...classifyContext(n, bodyNode),
+        argKind: classifyArgKind(n),
+      });
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(bodyNode, visit);
+}
+
+/** `ref.current = ...` assignments are the useRef equivalent of setter calls. */
+function collectRefAssignments(
+  bodyNode: ts.Node,
+  sourceFile: ts.SourceFile,
+  varName: string,
+  out: SetterCallSite[],
+): void {
+  const visit = (n: ts.Node): void => {
+    if (
+      ts.isBinaryExpression(n) &&
+      n.operatorToken.kind === ts.SyntaxKind.EqualsToken &&
+      ts.isPropertyAccessExpression(n.left) &&
+      ts.isIdentifier(n.left.expression) &&
+      n.left.expression.text === varName &&
+      n.left.name.text === "current"
+    ) {
+      out.push({
+        pos: posOf(n, sourceFile),
+        ...classifyContext(n, bodyNode),
+        argKind: "expression",
+      });
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(bodyNode, visit);
+}
+
+function classifyArgKind(call: ts.CallExpression): SetterCallSite["argKind"] {
+  const arg = call.arguments[0];
+  if (!arg) return "none";
+  if (ts.isArrowFunction(arg) || ts.isFunctionExpression(arg)) return "updater";
+  if (literalToValue(arg) !== undefined) return "literal";
+  return "expression";
+}
+
+function classifyContext(
+  node: ts.Node,
+  bodyNode: ts.Node,
+): Pick<SetterCallSite, "context" | "enclosingName" | "guarded"> {
+  // Outermost function-like strictly below the component body node.
+  let outermostFn: ts.Node | undefined;
+  for (let p = node.parent; p && p !== bodyNode; p = p.parent) {
+    if (isFunctionBoundary(p)) outermostFn = p;
+  }
+  const guarded = hasConditionalBetween(node, outermostFn ?? bodyNode);
+  if (!outermostFn) return { context: "render", guarded };
+
+  const parent = outermostFn.parent;
+
+  if (parent && ts.isCallExpression(parent) && parent.arguments.some((a) => a === outermostFn)) {
+    const hook = hookCalleeName(parent.expression);
+    if (hook === "useEffect" || hook === "useLayoutEffect") {
+      return { context: "effect", enclosingName: hook, guarded };
+    }
+    if (hook === "useCallback" || hook === "useMemo") {
+      return { context: "callback", enclosingName: hook, guarded };
+    }
+  }
+
+  // const handleAdd = () => ... — variable-initializer handlers.
+  if (parent && ts.isVariableDeclaration(parent) && ts.isIdentifier(parent.name)) {
+    const name = parent.name.text;
+    const context = /^(handle|on)[A-Z]/.test(name) ? ("handler" as const) : ("unknown" as const);
+    return { context, enclosingName: name, guarded };
+  }
+
+  // onClick={() => ...} — inline JSX attribute handlers.
+  if (parent && ts.isJsxExpression(parent) && parent.parent && ts.isJsxAttribute(parent.parent)) {
+    const attrName = parent.parent.name.getText();
+    const context = /^on[A-Z]/.test(attrName) ? ("handler" as const) : ("unknown" as const);
+    return { context, enclosingName: attrName, guarded };
+  }
+
+  return { context: "unknown", enclosingName: nearestName(outermostFn), guarded };
+}
+
+function nearestName(fn: ts.Node): string | undefined {
+  if ((ts.isFunctionDeclaration(fn) || ts.isFunctionExpression(fn)) && fn.name) return fn.name.text;
+  const parent = fn.parent;
+  if (parent && ts.isCallExpression(parent)) return hookCalleeName(parent.expression);
+  if (parent && ts.isPropertyAssignment(parent) && ts.isIdentifier(parent.name)) {
+    return parent.name.text;
+  }
+  return undefined;
+}
+
+function hasConditionalBetween(node: ts.Node, stop: ts.Node): boolean {
+  for (let p = node.parent; p && p !== stop; p = p.parent) {
+    if (ts.isIfStatement(p) || ts.isConditionalExpression(p)) return true;
+    if (
+      ts.isBinaryExpression(p) &&
+      (p.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken ||
+        p.operatorToken.kind === ts.SyntaxKind.BarBarToken)
+    ) {
+      return true;
+    }
+  }
+  return false;
+}
+
+function isFunctionBoundary(n: ts.Node): boolean {
+  return ts.isArrowFunction(n) || ts.isFunctionExpression(n) || ts.isFunctionDeclaration(n);
+}
+
+// ---------------------------------------------------------------------------
+// JSX flows
+// ---------------------------------------------------------------------------
+
+function collectJsxFlows(
+  bodyNode: ts.Node,
+  sourceFile: ts.SourceFile,
+  varName: string,
+): StateJsxFlow[] {
+  const flows: StateJsxFlow[] = [];
+  // collectRefs also covers useRef `x.current` reads: the receiver `x` of the
+  // property access is a reference position, so no separate walk is needed.
+  const refs = collectRefs(bodyNode, sourceFile, new Set([varName]), undefined);
+  for (const ref of refs) {
+    const flow = classifyJsxFlow(ref.node, bodyNode, sourceFile);
+    if (flow) flows.push(flow);
+  }
+  return flows;
+}
+
+function classifyJsxFlow(
+  refNode: ts.Node,
+  bodyNode: ts.Node,
+  sourceFile: ts.SourceFile,
+): StateJsxFlow | undefined {
+  let crossedFunction = false;
+  // The value SELECTS the child here rather than rendering:
+  // `{mode === 'write' ? <A/> : <B/>}` and `{mode && <X/>}` never put
+  // 'write' on screen. Only the raw value in text position is a witness.
+  // Chain-position tests — `refNode === p.condition` misses every nested
+  // read (`items.find((i) => i.id === mode) ? …`), so containment decides.
+  const selectsBranch = (n: ts.Node): boolean => {
+    if (ts.isConditionalExpression(n) && containsNode(n.condition, refNode)) return true;
+    if (
+      ts.isBinaryExpression(n) &&
+      n.operatorToken.kind === ts.SyntaxKind.AmpersandAmpersandToken &&
+      containsNode(n.left, refNode)
+    )
+      return true;
+    return false;
+  };
+  let selectsOnly = false;
+  for (let p = refNode.parent; p && p !== bodyNode; p = p.parent) {
+    if (!selectsOnly && selectsBranch(p)) selectsOnly = true;
+    if (
+      ts.isJsxExpression(p) &&
+      p.parent &&
+      (ts.isJsxElement(p.parent) || ts.isJsxFragment(p.parent))
+    ) {
+      const tag = ts.isJsxElement(p.parent)
+        ? p.parent.openingElement.tagName.getText(sourceFile)
+        : "<fragment>";
+      return {
+        via: selectsOnly ? "condition" : "child",
+        tag,
+        pos: posOf(refNode, sourceFile),
+      };
+    }
+    if (ts.isJsxAttribute(p) && !crossedFunction) {
+      const owner = p.parent.parent;
+      const tag =
+        owner && (ts.isJsxOpeningElement(owner) || ts.isJsxSelfClosingElement(owner))
+          ? owner.tagName.getText(sourceFile)
+          : "<dynamic>";
+      return {
+        via: "attr",
+        tag,
+        attr: p.name.getText(sourceFile),
+        pos: posOf(refNode, sourceFile),
+      };
+    }
+    if (isFunctionBoundary(p)) crossedFunction = true;
+  }
+  return undefined;
+}
+
+/** Subtree containment — TS nodes carry no position-based ancestry helper. */
+function containsNode(root: ts.Node, target: ts.Node): boolean {
+  if (root === target) return true;
+  let found = false;
+  const visit = (n: ts.Node): void => {
+    if (found || n === target) {
+      found = true;
+      return;
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(root, visit);
+  return found;
+}