@lariocpt/flawless-react 0.0.0-stage → 0.3.0

package/src/analyse/extractDisclosures.ts

@@ -0,0 +1,186 @@
+import ts from "typescript";
+import type { LabelSource } from "../types.ts";
+
+/**
+ * Elements that only exist in the DOM after something is clicked.
+ *
+ * A menu, dialog or popover mounts its content lazily, so a spec that queries an
+ * item straight after render finds nothing — and the failure looks like a wrong
+ * selector rather than a missing step. The shape is the same across
+ * base-ui/radix/shadcn and is recognisable by structure alone:
+ *
+ *   <DropdownMenu>                       <- disclosure root
+ *     <DropdownMenuTrigger>…</…>         <- the thing to click
+ *     <DropdownMenuContent>              <- gated subtree
+ *       <DropdownMenuItem>Light</…>      <- only mounted once open
+ *
+ * A `*Trigger` with a sibling subtree rooted at `*Content` / `*Popup` / `*Panel`
+ * / `*Portal` / `*Popover` — that is the whole rule. No package allowlist, so it
+ * also covers a project's own wrappers.
+ */
+
+const TRIGGER_TAG = /Trigger$/;
+const GATED_ROOT_TAG = /(Content|Popup|Panel|Portal|Overlay|Popover)$/;
+
+export interface Disclosure {
+  /** How a spec finds the element to click first. */
+  trigger: LabelSource;
+  /** Every node that only mounts after that click. */
+  gated: Set<ts.Node>;
+}
+
+export function findDisclosures(root: ts.Node): Disclosure[] {
+  const out: Disclosure[] = [];
+
+  const visit = (n: ts.Node): void => {
+    const tag = openingTagName(n);
+    if (tag && TRIGGER_TAG.test(tag)) {
+      const found = disclosureFor(n, root);
+      if (found) out.push(found);
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(root);
+
+  return out;
+}
+
+/** The gated subtrees that sit beside `trigger`, and how to click it. */
+function disclosureFor(trigger: ts.Node, root: ts.Node): Disclosure | undefined {
+  const handle = triggerHandle(trigger);
+  if (handle.kind === "none") return undefined;
+
+  for (let a = trigger.parent; a && a !== root.parent; a = a.parent) {
+    if (!ts.isJsxElement(a) && !ts.isJsxFragment(a)) continue;
+    const gatedRoots = a.children.filter((child) => {
+      if (contains(child, trigger)) return false;
+      const tag = openingTagName(child);
+      return tag !== undefined && GATED_ROOT_TAG.test(tag);
+    });
+    if (gatedRoots.length === 0) continue;
+    // An enclosing root written `open` / `open={true}` / `defaultOpen` mounts
+    // its content right away — nothing to open first, so nothing is gated.
+    // (An expression like `open={isOpen}` stays gated: its initial value
+    // belongs to render-state this structural pass cannot see.)
+    if (ts.isJsxElement(a) && isAlwaysOpen(a.openingElement)) return undefined;
+
+    const gated = new Set<ts.Node>();
+    for (const subtree of gatedRoots) collectAll(subtree, gated);
+    return { trigger: handle, gated };
+  }
+  return undefined;
+}
+
+/** `open`/`defaultOpen` written as a bare attribute or a literal `true`. */
+function isAlwaysOpen(opening: ts.JsxOpeningElement): boolean {
+  for (const p of opening.attributes.properties) {
+    if (!ts.isJsxAttribute(p) || !ts.isIdentifier(p.name)) continue;
+    if (p.name.text !== "open" && p.name.text !== "defaultOpen") continue;
+    const init = p.initializer;
+    if (init === undefined) return true;
+    if (ts.isJsxExpression(init) && init.expression?.kind === ts.SyntaxKind.TrueKeyword) {
+      return true;
+    }
+  }
+  return false;
+}
+
+/**
+ * Something a spec can use to click the trigger.
+ *
+ * Literal text is taken from anywhere in the trigger's subtree, INCLUDING the
+ * JSX inside attributes: base-ui's `render={<Button/>}` slot and shadcn's
+ * `<span className="sr-only">` both put the only human-readable label somewhere
+ * a direct-children scan never looks. Clicking that span bubbles to the button,
+ * so it is a valid handle.
+ */
+function triggerHandle(trigger: ts.Node): LabelSource {
+  const attrs = jsxAttributes(trigger);
+  const testid = stringAttr(attrs, "data-testid");
+  if (testid) return { kind: "testid", value: testid };
+  const aria = stringAttr(attrs, "aria-label");
+  if (aria) return { kind: "aria", value: aria };
+
+  const texts: string[] = [];
+  const visit = (n: ts.Node): void => {
+    if (ts.isJsxText(n)) {
+      const t = n.text.replace(/\s+/g, " ").trim();
+      if (t) texts.push(t);
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(trigger);
+
+  // More than one candidate and we cannot tell which identifies the trigger.
+  const unique = [...new Set(texts)];
+  const only = unique.length === 1 ? unique[0] : undefined;
+  if (only && only.length >= 2) return { kind: "text", value: only };
+  // Nothing names the trigger because the APP CONSUMER is its content —
+  // `<AlertDialogTrigger asChild>{children}</AlertDialogTrigger>`. A unit
+  // spec passes CHILD_TEXT as children, so that text is the click handle.
+  if (childrenExprInSubtree(trigger)) return { kind: "children" };
+  return { kind: "none" };
+}
+
+/** True when the subtree renders the `{children}` identifier expression. */
+function childrenExprInSubtree(n: ts.Node): boolean {
+  if (
+    ts.isJsxExpression(n) &&
+    n.expression !== undefined &&
+    ts.isIdentifier(n.expression) &&
+    n.expression.text === "children"
+  ) {
+    return true;
+  }
+  let found = false;
+  ts.forEachChild(n, (c) => {
+    if (!found && childrenExprInSubtree(c)) found = true;
+  });
+  return found;
+}
+
+function contains(haystack: ts.Node, needle: ts.Node): boolean {
+  for (let n: ts.Node | undefined = needle; n; n = n.parent) {
+    if (n === haystack) return true;
+  }
+  return false;
+}
+
+function collectAll(n: ts.Node, into: Set<ts.Node>): void {
+  into.add(n);
+  ts.forEachChild(n, (c) => collectAll(c, into));
+}
+
+function openingTagName(n: ts.Node): string | undefined {
+  const tagName = ts.isJsxElement(n)
+    ? n.openingElement.tagName
+    : ts.isJsxSelfClosingElement(n)
+      ? n.tagName
+      : undefined;
+  return tagName && ts.isIdentifier(tagName) ? tagName.text : undefined;
+}
+
+function jsxAttributes(n: ts.Node): ts.JsxAttributes | undefined {
+  if (ts.isJsxElement(n)) return n.openingElement.attributes;
+  if (ts.isJsxSelfClosingElement(n)) return n.attributes;
+  return undefined;
+}
+
+function stringAttr(attrs: ts.JsxAttributes | undefined, name: string): string | undefined {
+  if (!attrs) return undefined;
+  for (const a of attrs.properties) {
+    if (!ts.isJsxAttribute(a)) continue;
+    if (!ts.isIdentifier(a.name) || a.name.text !== name) continue;
+    const init = a.initializer;
+    if (init && ts.isStringLiteral(init)) return init.text;
+    if (
+      init &&
+      ts.isJsxExpression(init) &&
+      init.expression &&
+      ts.isStringLiteral(init.expression)
+    ) {
+      return init.expression.text;
+    }
+  }
+  return undefined;
+}

package/src/analyse/extractFetchCalls.ts

@@ -0,0 +1,81 @@
+import ts from "typescript";
+import type { FetchCallInfo } from "../types.ts";
+import { posOf } from "./pos.ts";
+import { hookCalleeName } from "./refs.ts";
+
+const EFFECT_HOOKS = new Set(["useEffect", "useLayoutEffect"]);
+
+/**
+ * Collect fetch() call sites with their URL shape. Interpolations become
+ * :holes named after the interpolated identifier (or the property name of a
+ * member access); anything unnameable becomes :param. Non-literal URLs
+ * (variables, function results) are skipped — better no spec than a wrong one.
+ */
+export function extractFetchCalls(bodyNode: ts.Node, sourceFile: ts.SourceFile): FetchCallInfo[] {
+  const out: FetchCallInfo[] = [];
+
+  const visit = (n: ts.Node): void => {
+    if (ts.isCallExpression(n) && ts.isIdentifier(n.expression) && n.expression.text === "fetch") {
+      const urlArg = n.arguments[0];
+      const parsed = urlArg ? parseUrlArg(urlArg) : undefined;
+      if (parsed) {
+        out.push({
+          urlTemplate: parsed.template,
+          holes: parsed.holes,
+          method: readMethod(n.arguments[1]),
+          pos: posOf(n, sourceFile),
+          inEffect: isInsideEffect(n, bodyNode),
+        });
+      }
+    }
+    ts.forEachChild(n, visit);
+  };
+  ts.forEachChild(bodyNode, visit);
+  return out;
+}
+
+export function parseUrlArg(arg: ts.Expression): { template: string; holes: string[] } | undefined {
+  if (ts.isStringLiteral(arg) || ts.isNoSubstitutionTemplateLiteral(arg)) {
+    return { template: arg.text, holes: [] };
+  }
+  if (ts.isTemplateExpression(arg)) {
+    let template = arg.head.text;
+    const holes: string[] = [];
+    for (const span of arg.templateSpans) {
+      const hole = holeName(span.expression, holes.length);
+      holes.push(hole);
+      template += `:${hole}${span.literal.text}`;
+    }
+    return { template, holes };
+  }
+  return undefined;
+}
+
+function holeName(expr: ts.Expression, index: number): string {
+  if (ts.isIdentifier(expr)) return expr.text;
+  if (ts.isPropertyAccessExpression(expr) && ts.isIdentifier(expr.name)) return expr.name.text;
+  return `param${index}`;
+}
+
+export function readMethod(init: ts.Expression | undefined): string {
+  if (!init || !ts.isObjectLiteralExpression(init)) return "GET";
+  for (const p of init.properties) {
+    if (!ts.isPropertyAssignment(p)) continue;
+    const name = ts.isIdentifier(p.name) || ts.isStringLiteral(p.name) ? p.name.text : undefined;
+    if (name !== "method") continue;
+    if (ts.isStringLiteral(p.initializer)) return p.initializer.text.toUpperCase();
+  }
+  return "GET";
+}
+
+function isInsideEffect(call: ts.Node, bodyNode: ts.Node): boolean {
+  let cur: ts.Node | undefined = call.parent;
+  while (cur && cur !== bodyNode) {
+    if (ts.isCallExpression(cur)) {
+      const name = hookCalleeName(cur.expression);
+      if (name && EFFECT_HOOKS.has(name)) return true;
+    }
+    cur = cur.parent;
+  }
+  return false;
+}

package/src/analyse/extractFlows.ts

@@ -0,0 +1,239 @@
+import ts from "typescript";
+import { VOID_ELEMENTS } from "./hostProps.ts";
+import { domOnlyResolver, type HostTagResolver } from "./hostTag.ts";
+import { nativeAcceptsChildrenByName } from "./nativeProps.ts";
+import { initialRenderExpression, type RenderEnv, reachability } from "./renderPath.ts";
+
+/**
+ * Whether `children` and `className` actually reach the DOM.
+ *
+ * Both are the basis for assertions on components that render no literal copy of
+ * their own — the whole shadcn/ui layer, which was 40% of the generated specs and
+ * every one of them assertion-free. Accepting a prop is not the same as
+ * rendering it, so each rule below insists on seeing the value flow somewhere it
+ * can be observed, and gives up otherwise.
+ */
+
+export interface RenderFlows {
+  /** A sentinel child passed in will appear in the markup. */
+  children: boolean;
+  /** A className passed in will land on some element. */
+  className: boolean;
+}
+
+export function extractFlows(
+  bodyNode: ts.Node,
+  env: RenderEnv,
+  hostTag: HostTagResolver = domOnlyResolver,
+): RenderFlows {
+  const initial = initialRenderExpression(bodyNode, env);
+  if (!initial) return { children: false, className: false };
+  const { expr: root, scope } = initial;
+  const reached = (n: ts.Node): boolean => reachability(n, root, scope) === "yes";
+
+  return {
+    children: childrenFlow(root, reached, hostTag),
+    // NativeWind compiles className into a `style` at BUILD time, through babel.
+    // The string does not survive to the rendered tree under jest-expo, and
+    // react-native-web consumes it without forwarding anything either (measured:
+    // docs/archive/2026-08-expo-probes.md, P1). So "a className passed in will
+    // land on some element" is both unfalsifiable AND unsatisfiable on native,
+    // and asserting it would be a test that can never pass.
+    //
+    // childrenFlow is unaffected: a sentinel child under a <View> genuinely renders.
+    className:
+      hostTag("View")?.dialect === "native" ? false : classNameFlow(root, reached, hostTag),
+  };
+}
+
+/**
+ * `{children}` rendered directly, or a `{...props}` spread onto a host element
+ * that can hold children.
+ *
+ * The spread case is how the entire shadcn layer works — `<div {...props} />`
+ * never mentions children by name — so leaving it out would miss most of the
+ * components this rule exists for. Void elements are excluded: <input {...props}/>
+ * accepts the prop and renders nothing.
+ */
+function childrenFlow(
+  root: ts.Node,
+  reached: (n: ts.Node) => boolean,
+  hostTag: HostTagResolver,
+): boolean {
+  let found = false;
+  const visit = (n: ts.Node): void => {
+    if (found) return;
+    if (
+      ts.isJsxExpression(n) &&
+      n.expression &&
+      ts.isIdentifier(n.expression) &&
+      n.expression.text === "children" &&
+      n.parent &&
+      (ts.isJsxElement(n.parent) || ts.isJsxFragment(n.parent)) &&
+      reached(n)
+    ) {
+      found = true;
+      return;
+    }
+    if (ts.isJsxSpreadAttribute(n) && reached(n)) {
+      const owner = n.parent?.parent;
+      const owned = owner ? resolvedOf(owner, hostTag) : undefined;
+      if (owned && acceptsChildren(owned) && !explicitChildrenOverrideSpread(owner)) {
+        found = true;
+        return;
+      }
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(root);
+  return found;
+}
+
+/**
+ * JSX explicit children REPLACE spread children — `<svg {...props}><path/></svg>`
+ * never renders `props.children`, and every icon in the corpus is exactly that
+ * shape (SVGProps-typed, children accepted via the spread, fixed paths rendered).
+ * The sentinel-child test against one is not a failing component, it is a test
+ * asserting a JSX precedence rule backwards, so the flow must not report true.
+ */
+function explicitChildrenOverrideSpread(owner: ts.Node | undefined): boolean {
+  if (!owner || !ts.isJsxElement(owner.parent)) return false;
+  return owner.parent.children.some(
+    (c) =>
+      (ts.isJsxText(c) && c.getText().trim().length > 0) ||
+      ts.isJsxElement(c) ||
+      ts.isJsxSelfClosingElement(c) ||
+      ts.isJsxFragment(c) ||
+      (ts.isJsxExpression(c) && c.expression !== undefined),
+  );
+}
+
+/**
+ * The `className` identifier appearing inside a `className=` attribute on a HOST
+ * element — directly, as an argument to any call (cn/clsx/twMerge), or inside a
+ * template span.
+ *
+ * Host-only is the load-bearing part. `<SeparatorPrimitive className={cn(…)} />`
+ * hands the class to another component, and whether that component puts it on a
+ * DOM node is its business, not something this file can see. Asserting on it
+ * would be a claim about a third-party implementation.
+ *
+ * The other way this goes wrong is a `{...props}` spread positioned AFTER the
+ * attribute on the same element, which overwrites it. That is checked rather
+ * than assumed.
+ */
+function classNameFlow(
+  root: ts.Node,
+  reached: (n: ts.Node) => boolean,
+  hostTag: HostTagResolver,
+): boolean {
+  let found = false;
+  const visit = (n: ts.Node): void => {
+    if (found) return;
+    if (
+      ts.isJsxAttribute(n) &&
+      ts.isIdentifier(n.name) &&
+      n.name.text === "className" &&
+      hostTagOf(n.parent?.parent, hostTag) !== undefined &&
+      reached(n) &&
+      mentionsClassName(n) &&
+      !overwrittenBySpread(n)
+    ) {
+      found = true;
+      return;
+    }
+    ts.forEachChild(n, visit);
+  };
+  visit(root);
+  return found;
+}
+
+function mentionsClassName(attr: ts.JsxAttribute): boolean {
+  let found = false;
+  const visit = (n: ts.Node): void => {
+    if (found) return;
+    if (ts.isIdentifier(n) && n.text === "className" && n !== attr.name) {
+      found = true;
+      return;
+    }
+    ts.forEachChild(n, visit);
+  };
+  if (attr.initializer) visit(attr.initializer);
+  return found;
+}
+
+/** A spread later in the same attribute list wins, so the className is lost. */
+function overwrittenBySpread(attr: ts.JsxAttribute): boolean {
+  const list = attr.parent;
+  if (!list || !ts.isJsxAttributes(list)) return false;
+  const index = list.properties.indexOf(attr);
+  if (index < 0) return false;
+  return list.properties
+    .slice(index + 1)
+    .some((p) => ts.isJsxSpreadAttribute(p) && !isClassNameSafeSpread(p));
+}
+
+/**
+ * `{...props}` after className is only harmful when props can carry className.
+ * A rest binding that had className destructured out of it cannot.
+ */
+function isClassNameSafeSpread(spread: ts.JsxSpreadAttribute): boolean {
+  if (!ts.isIdentifier(spread.expression)) return false;
+  const name = spread.expression.text;
+  // `const { className, ...props }` — the rest holds everything BUT className.
+  for (let n: ts.Node | undefined = spread; n; n = n.parent) {
+    if (!ts.isFunctionDeclaration(n) && !ts.isArrowFunction(n) && !ts.isFunctionExpression(n)) {
+      continue;
+    }
+    const first = n.parameters[0];
+    if (!first || !ts.isObjectBindingPattern(first.name)) return false;
+    let sawClassName = false;
+    let restMatches = false;
+    for (const el of first.name.elements) {
+      if (!ts.isBindingElement(el)) continue;
+      if (el.dotDotDotToken) {
+        restMatches = ts.isIdentifier(el.name) && el.name.text === name;
+        continue;
+      }
+      if (ts.isIdentifier(el.name) && el.name.text === "className") sawClassName = true;
+    }
+    return sawClassName && restMatches;
+  }
+  return false;
+}
+
+/** Whether a resolved host element can hold children, in either dialect. */
+function acceptsChildren(el: { name: string; dialect: "dom" | "native" }): boolean {
+  return el.dialect === "native"
+    ? nativeAcceptsChildrenByName(el.name)
+    : !VOID_ELEMENTS.has(el.name);
+}
+
+function resolvedOf(node: ts.Node, hostTag: HostTagResolver) {
+  const tagName = ts.isJsxOpeningElement(node)
+    ? node.tagName
+    : ts.isJsxSelfClosingElement(node)
+      ? node.tagName
+      : undefined;
+  if (!tagName || !ts.isIdentifier(tagName)) return undefined;
+  return hostTag(tagName.text);
+}
+
+function hostTagOf(node: ts.Node | undefined, hostTag: HostTagResolver): string | undefined {
+  if (!node) return undefined;
+  const tagName = ts.isJsxOpeningElement(node)
+    ? node.tagName
+    : ts.isJsxSelfClosingElement(node)
+      ? node.tagName
+      : undefined;
+  if (!tagName || !ts.isIdentifier(tagName)) return undefined;
+  return hostTag(tagName.text)?.name;
+}
+
+/**
+ * The SECOND copy of VOID_ELEMENTS lived here, three lines below its own use,
+ * while hostProps.ts exported the authoritative one — and the two had already
+ * drifted (this copy was missing "param"). Deleted in favour of the table that
+ * also answers the question for React Native, where "does this element take
+ * children" is a per-element fact rather than a list of fourteen tag names.
+ */