@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/src/tasks/perfHarness.ts

@@ -0,0 +1,145 @@
+import path from "node:path";
+import { expoNotImplemented } from "../expo/refusal.ts";
+import { scaffold } from "../scaffold/index.ts";
+import { flattenTrees, hostEligibility } from "../scaffold-tests/registry.ts";
+import type { RunContext, Task, TaskResult } from "../types.ts";
+import { VERSION } from "../version.ts";
+
+export const perfHarness: Task = {
+  id: "perf-harness",
+  label: "Generate performance testing harness",
+  description: "Playwright + React.Profiler + react-scan suite",
+  needsTree: true,
+  async run(ctx: RunContext): Promise<TaskResult> {
+    // Wave 4 was measured and DECLINED, not deferred (2026-09-12, census in
+    // docs/archive/backlog-completed-2026-10.md B-16 + docs/archive/2026-09-expo-probes.md): on
+    // an expo-router app the component population is route screens, the host
+    // cannot mount anything that needs a navigator (renderRouter is
+    // jest-bound), and the profile click scenarios are onClick-only — so the
+    // measured ceiling on the dogfood app was ~0 of 32 components. A host
+    // built anyway would be a red spec on healthy components or a suite that
+    // tests nothing. Revisit condition, recorded in the backlog: an adopter
+    // with a real components/ directory of non-route, navigator-free
+    // components. The one opening — a Metro-served real-app perf lane, using
+    // wave 6's infrastructure — is mapped and probe-gated in
+    // docs/archive/wave4-metro-perf-plan.md; it stays declined until a probe
+    // clears, because on a React-Compiler app the only honest signal is nulled.
+    if (ctx.expo) {
+      return expoNotImplemented(
+        "perf-harness",
+        "measured-and-declined 2026-09-12 — ~0 host-mountable components on an " +
+          "all-route-screens app; docs/archive/backlog-completed-2026-10.md B-16 records the evidence " +
+          "and the revisit condition",
+      );
+    }
+    const [first, ...rest] = ctx.trees;
+    if (!first) {
+      return {
+        id: "perf-harness",
+        ok: false,
+        outputs: [],
+        findings: [],
+        summary: "no components to scaffold",
+        error: "no components",
+      };
+    }
+    const suiteName = path.basename(path.resolve(ctx.outDir)).replace(/[^a-zA-Z0-9_-]+/g, "-");
+    const res = await scaffold(first, {
+      outDir: ctx.outDir,
+      extraTrees: rest,
+      suiteName,
+      variants: ctx.variants,
+      heaps: ctx.heaps,
+      force: ctx.force,
+      // An explicit --force outranks changed-mode's keep: forcing IS asking
+      // for the regeneration that changed-mode otherwise declines to churn.
+      keepExisting: ctx.changed !== undefined && !ctx.force,
+      report: ctx.report,
+      provider: ctx.provider,
+      apiSpec: ctx.apiSpec,
+      nextjsHost: ctx.nextjs !== undefined,
+      mswSetup: ctx.nextjs !== undefined,
+      providerWraps: ctx.providerWraps,
+    });
+    if (res.status === "kept") {
+      return {
+        id: "perf-harness",
+        ok: true,
+        outputs: [],
+        findings: [],
+        status: "kept",
+        summary: `harness kept (generated by flawless-react ${res.existingVersion ?? "unknown version"}, tool is ${VERSION})`,
+      };
+    }
+    // The number of components the host can actually mount, not the number of
+    // entry trees. Those differ by more than half in a real app — most of what
+    // the sweep finds is a server component or a compound part — and reporting
+    // the tree count claimed a coverage the suite never had.
+    const flat = flattenTrees([first, ...rest]);
+    const hosted = flat.filter((c) => hostEligibility(c.info).eligible);
+    const names = hosted.map((c) => c.info.componentName);
+    const covered = `${names.length} of ${flat.length} component(s): ${names.join(", ")}`;
+    const keptNote =
+      res.kept.length > 0
+        ? `; kept ${res.kept.map((f) => path.relative(path.resolve(ctx.outDir), f)).join(", ")} (delete one to regenerate it)`
+        : "";
+    // One-time migration for pre-split suites. writeOnce is absolute (--force
+    // included — budgets.json rests on that promise), so the tool cannot fix
+    // the monolith itself: host/registry.ts was written inert beside it, and
+    // delete-to-regenerate is the escape.
+    const migrationNote = res.preSplitMain
+      ? "; host/main.tsx predates the registry split and cannot mount newly analysed components" +
+        " — delete it and re-run (provider wiring regenerates from --provider), or port your" +
+        ' hand wiring and import "./registry"'
+      : "";
+    if (res.preSplitMain) {
+      console.warn(
+        `[flawless] ${path.join(ctx.outDir, "host/main.tsx")} predates the registry split:` +
+          " it bakes in its own component tables, so newly analysed components cannot mount" +
+          " through it, and no flag may rewrite a write-once file — delete host/main.tsx and" +
+          " re-run (provider wiring regenerates from --provider), or port your hand wiring" +
+          ' and import "./registry".',
+      );
+    }
+    // A component that left the host set stops being rendered, but its profile
+    // spec would otherwise sit in profile/ forever, failing at mount with
+    // "unknown component" — the suite red by the tool's own doing. The sweep
+    // retires the ones whose stamp proves them untouched tool output, and
+    // names the ones it refused to touch (hand work or unprovable).
+    const staleRemovedNote =
+      res.staleRemoved.length > 0
+        ? `; retired ${res.staleRemoved.length} stale profile spec(s) whose component left the host — ` +
+          res.staleRemoved.map((f) => path.relative(path.resolve(ctx.outDir), f)).join(", ")
+        : "";
+    const staleKeptNote =
+      res.staleKept.length > 0
+        ? `; kept ${res.staleKept.length} stale profile spec(s) — ` +
+          res.staleKept
+            .map((f) => `${path.relative(path.resolve(ctx.outDir), f.abs)} (${f.verdict})`)
+            .join(", ") +
+          " (delete to retire)"
+        : "";
+    // The provider lives in a file the tool owns, but main.tsx's import of it
+    // is kept — so when the provider moves, the kept harness mounts the OLD
+    // provider and every mount fails on an opaque 5000ms timeout. scaffold
+    // re-points that one line; the run has to say which host it re-pointed.
+    const providerNote = res.providerImportRefresh
+      ? `; re-pointed host/main.tsx's provider import ${res.providerImportRefresh.from} → ` +
+        `${res.providerImportRefresh.to} (the harness is kept, this line is not)`
+      : "";
+    if (res.providerImportWarning) {
+      console.warn(`[flawless] ${res.providerImportWarning}.`);
+    }
+    return {
+      id: "perf-harness",
+      ok: true,
+      outputs: res.written,
+      findings: [],
+      status: res.status,
+      summary:
+        res.status === "refreshed"
+          ? `refreshed perf suite for ${covered}${keptNote}${providerNote}${migrationNote}${staleRemovedNote}${staleKeptNote}`
+          : `scaffolded perf suite for ${covered}${migrationNote}${staleRemovedNote}${staleKeptNote}`,
+    };
+  },
+};

package/src/tasks/staticPerfAnalysis.ts

@@ -0,0 +1,510 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import type {
+  ChildAttrInfo,
+  ComponentInfo,
+  ComponentTree,
+  EffectFeatures,
+  Finding,
+  ReactCompilerProbe,
+  RunContext,
+  SourcePosition,
+  SpecQualityBucket,
+  Task,
+  TaskResult,
+} from "../types.ts";
+
+const MEMO_HOOKS = new Set(["useMemo", "useCallback", "memo", "useRef"]);
+const CHILD_RERENDER_THRESHOLD = 3;
+const MEMO_HOOK_NAMES = new Set(["useMemo", "useCallback"]);
+const EFFECT_HOOK_NAMES = new Set(["useEffect", "useLayoutEffect"]);
+const PLAIN_IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/;
+const MEMO_WRAPPED_NOTE = " — child is React.memo-wrapped; this prop defeats memoisation.";
+
+/** Attr value kinds recreated on every render (new reference each time). */
+const UNSTABLE_ATTR_KINDS = new Set<ChildAttrInfo["valueKind"]>([
+  "object-literal",
+  "array-literal",
+  "arrow",
+  "function",
+]);
+/** Attrs that are not regular props (memoisation-irrelevant or unanalysable). */
+const NON_PROP_ATTRS = new Set(["key", "ref", "children", "...spread"]);
+/** Attr value kinds that are referentially stable across parent rerenders. */
+const STABLE_ATTR_KINDS = new Set<ChildAttrInfo["valueKind"]>([
+  "string",
+  "number",
+  "boolean-true",
+  "null",
+  "member",
+  "identifier",
+]);
+
+const ATTR_KIND_LABEL: Partial<Record<ChildAttrInfo["valueKind"], string>> = {
+  "object-literal": "an inline object literal",
+  "array-literal": "an inline array literal",
+  arrow: "an inline arrow function",
+  function: "an inline function expression",
+};
+
+interface PerfReport {
+  component: string;
+  file: string;
+  findings: Finding[];
+  /** Per component in this tree: props no fixture could synthesise. */
+  specQuality: SpecQualityBucket[];
+}
+
+/** What one walk of one tree collects. */
+interface Collected {
+  findings: Finding[];
+  specQuality: SpecQualityBucket[];
+}
+
+/** One rule and how many findings of it the compiler made redundant. */
+interface SuppressedTally {
+  rule: string;
+  count: number;
+}
+
+/**
+ * The three rules whose advice the React Compiler implements by itself.
+ *
+ * It memoises props and JSX at the call site, so "a new reference on every
+ * render" is false post-compilation and a hand-written `memo()` wrapper is work
+ * the build already did — the React docs go further and call adding one contrary
+ * to guidance. The other six rules are untouched by it: correct dependency
+ * arrays are what the compiler RELIES on, effects run per render whatever got
+ * memoised, and `set-state-in-render` is a correctness bug, not a scale.
+ *
+ * Bail-outs are deliberately not modelled. A component that violates the Rules
+ * of React is not compiled — but the react-rules task owns that detection, and
+ * these flags are global, so perf-static treats compiler state as global instead
+ * of second-guessing per-file compilation success.
+ */
+const MEMO_FAMILY_RULES: readonly string[] = [
+  "perf/no-memoisation-with-children",
+  "perf/unstable-child-prop",
+  "perf/missing-memo-leaf",
+];
+
+/** The rule that is spec quality, not app perf, and so never a finding. */
+export const SPEC_QUALITY_RULE = "perf/unresolved-prop";
+
+export const staticPerfAnalysis: Task = {
+  id: "perf-static",
+  label: "Static React perf analysis",
+  description:
+    "Surface rerender / memoisation risks from the parsed tree, and the props no fixture could synthesise",
+  needsTree: true,
+  async run(ctx: RunContext): Promise<TaskResult> {
+    const reportsDir = path.join(ctx.outDir, "reports");
+    await mkdir(reportsDir, { recursive: true });
+
+    // Absent only on a hand-built context (a task run outside runCore). Say the
+    // run did not look rather than assuming either way — `undetermined` runs
+    // every rule, which is the safe direction, and says so.
+    const compiler: ReactCompilerProbe = ctx.reactCompiler ?? {
+      state: "undetermined",
+      evidence: "this run did not read the project's configs",
+    };
+    const suppress = compiler.state === "on" ? MEMO_FAMILY_RULES : [];
+
+    const allFindings: Finding[] = [];
+    const written: string[] = [];
+    const total = new Map<string, number>(suppress.map((rule) => [rule, 0]));
+    // Keyed `file::component` — the registry's own dedupe convention. A leaf
+    // rendered by forty parents is forty trees, and per-prop counting turned
+    // that into 148 "perf findings" for one button.
+    const gaps = new Map<string, { component: string; file: string; props: Set<string> }>();
+
+    for (const tree of ctx.trees) {
+      const report = analyseTree(tree);
+      const kept: Finding[] = [];
+      const here = new Map<string, number>();
+      for (const finding of report.findings) {
+        if (!suppress.includes(finding.rule)) {
+          kept.push(finding);
+          continue;
+        }
+        here.set(finding.rule, (here.get(finding.rule) ?? 0) + 1);
+      }
+      for (const [rule, n] of here) total.set(rule, (total.get(rule) ?? 0) + n);
+      for (const finding of kept) allFindings.push(finding);
+      for (const gap of report.specQuality) {
+        const key = `${gap.file}::${gap.component}`;
+        const bucket = gaps.get(key) ?? {
+          component: gap.component,
+          file: gap.file,
+          props: new Set<string>(),
+        };
+        for (const prop of gap.props) bucket.props.add(prop);
+        gaps.set(key, bucket);
+      }
+
+      const out = path.join(reportsDir, `${report.component}.perf-static.json`);
+      // The state and the gaps ride along with every report file, because the
+      // numbers they explain are in there: a zero memo-finding count written by a
+      // compiler-on run means "the compiler does this", and neither it nor a
+      // component whose props all synthesised can be told apart by the counts.
+      await Bun.write(
+        out,
+        `${JSON.stringify(
+          {
+            component: report.component,
+            file: report.file,
+            findings: kept,
+            reactCompiler: compiler,
+            specQuality: report.specQuality,
+            ...(here.size > 0 ? { suppressed: tally(here) } : {}),
+          },
+          null,
+          2,
+        )}\n`,
+      );
+      written.push(out);
+    }
+
+    const suppressed = tally(total);
+    const components = [...gaps.values()]
+      .map((gap) => ({ component: gap.component, file: gap.file, props: [...gap.props].sort() }))
+      .sort((a, b) =>
+        a.file === b.file ? (a.component < b.component ? -1 : 1) : a.file < b.file ? -1 : 1,
+      );
+    const specQuality: TaskResult["specQuality"] =
+      components.length > 0
+        ? {
+            rule: SPEC_QUALITY_RULE,
+            props: components.reduce((n, c) => n + c.props.length, 0),
+            components,
+          }
+        : undefined;
+
+    const notes = [compilerNote(compiler, suppressed), specQualityNote(specQuality)].filter(
+      (note) => note !== "",
+    );
+    return {
+      id: "perf-static",
+      ok: true,
+      outputs: written,
+      findings: allFindings,
+      summary:
+        `static perf analysis: ${allFindings.length} finding(s) across ` +
+        `${ctx.trees.length} root(s)` +
+        (notes.length > 0 ? ` — ${notes.join("; ")}` : ""),
+      reactCompiler: {
+        state: compiler.state,
+        evidence: compiler.evidence,
+        ...(suppress.length > 0 ? { suppressed } : {}),
+      },
+      ...(specQuality ? { specQuality } : {}),
+    };
+  },
+};
+
+/** Sorted so two runs of one tree diff clean, and a rule is never dropped. */
+function tally(counts: Map<string, number>): SuppressedTally[] {
+  return [...counts.entries()]
+    .map(([rule, count]) => ({ rule, count }))
+    .sort((a, b) => (a.rule < b.rule ? -1 : 1));
+}
+
+/**
+ * The one honest line for the two compiler states that change what the number
+ * means.
+ *
+ * `off` says nothing: nothing was suppressed, and a task summary that reports the
+ * absence of its own special case on every run teaches nobody anything. `on` is
+ * suppression, and suppression is never silent. `undetermined` is the one a
+ * reader could otherwise mistake for a checked `off` — the memo findings it
+ * printed may be work a compiler-on build already did.
+ */
+function compilerNote(compiler: ReactCompilerProbe, suppressed: SuppressedTally[]): string {
+  if (compiler.state === "on") {
+    const findings = suppressed.reduce((n, s) => n + s.count, 0);
+    return (
+      `${suppressed.length} memo rule(s) suppressed, ${findings} finding(s) the ` +
+      `React Compiler already memoises (${compiler.evidence})`
+    );
+  }
+  if (compiler.state === "undetermined") {
+    return "react-compiler state undetermined; memo-family findings may be pre-compiled noise on a compiler-on app";
+  }
+  return "";
+}
+
+/**
+ * The spec-quality half of the count, said apart.
+ *
+ * The finding number above means "rerender work worth doing in your app", and
+ * keeping it that way is the whole point: the dogfood run's 926 were 127 of that
+ * plus 713 of this, which read as an alarming backlog and were really the
+ * analyser's own fixture limits.
+ */
+function specQualityNote(specQuality: TaskResult["specQuality"]): string {
+  if (!specQuality) return "";
+  return (
+    `${specQuality.props} spec-quality prop gap(s) across ` +
+    `${specQuality.components.length} component(s), counted apart from the findings`
+  );
+}
+
+export function analyseTree(tree: ComponentTree): PerfReport {
+  const out: Collected = { findings: [], specQuality: [] };
+  walk(tree, out);
+  return {
+    component: tree.entry.componentName,
+    file: tree.entry.filePath,
+    findings: out.findings,
+    specQuality: out.specQuality,
+  };
+}
+
+function walk(node: ComponentTree, out: Collected): void {
+  inspect(node, out);
+  for (const c of node.children) walk(c, out);
+}
+
+function inspect(node: ComponentTree, out: Collected): void {
+  const info = node.entry;
+  const names = knownNamesOf(info);
+  inspectMemoisation(info, node.children.length, out.findings);
+  collectSpecQuality(info, out);
+  inspectHookDeps(info, names, out.findings);
+  inspectChildAttrs(node, names, out.findings);
+  inspectRenderSetters(info, out.findings);
+}
+
+/** Names recoverable from a ComponentInfo alone — no AST scope is available here. */
+interface KnownNames {
+  propNames: Set<string>;
+  stateVars: Set<string>;
+  setterNames: Set<string>;
+  refNames: Set<string>;
+  memoResultNames: Set<string>;
+}
+
+function knownNamesOf(info: ComponentInfo): KnownNames {
+  const propNames = new Set([...Object.keys(info.propsShape), ...info.unresolvedProps]);
+  const stateVars = new Set<string>();
+  const setterNames = new Set<string>();
+  const refNames = new Set<string>();
+  for (const s of info.state ?? []) {
+    if (s.kind === "useRef") refNames.add(s.varName);
+    else stateVars.add(s.varName);
+    if (s.setterName) setterNames.add(s.setterName);
+  }
+  const memoResultNames = new Set<string>();
+  for (const d of info.hookDetails ?? []) {
+    if (d.resultName) memoResultNames.add(d.resultName);
+  }
+  return { propNames, stateVars, setterNames, refNames, memoResultNames };
+}
+
+function at(
+  pos: SourcePosition | undefined,
+  fallbackFile: string,
+): Pick<Finding, "file" | "line" | "column"> {
+  return pos
+    ? { file: pos.file, line: pos.line, column: pos.column }
+    : { file: fallbackFile, line: 1, column: 1 };
+}
+
+function inspectMemoisation(info: ComponentInfo, childCount: number, findings: Finding[]): void {
+  const memoised =
+    info.hooks.some((h) => MEMO_HOOKS.has(h)) || (info.wrappers ?? []).includes("memo");
+  if (childCount < CHILD_RERENDER_THRESHOLD || memoised) return;
+  findings.push({
+    rule: "perf/no-memoisation-with-children",
+    severity: "warn",
+    ...at(info.pos, info.filePath),
+    message:
+      `${info.componentName} renders ${childCount} child component(s) but uses none of ` +
+      `useMemo/useCallback/memo/useRef — every parent rerender will rerender all children.`,
+    source: "perf-static",
+  });
+}
+
+/**
+ * The ninth check, and the only one that is not about the app.
+ *
+ * One bucket per component naming the props no fixture could synthesise — NOT a
+ * finding. As a per-prop finding it said "button.tsx: 148 perf findings" about a
+ * component with one prop family the analyser could not resolve, and the rerender
+ * findings that needed someone's attention hid underneath it.
+ *
+ * The prop NAMES are the actionable half: `--props '{"x":1}'` or the spec's
+ * `DEFAULTS` address a prop by name, never by the line of the type literal it was
+ * declared on, which is the only thing the old per-prop positions added.
+ */
+function collectSpecQuality(info: ComponentInfo, out: Collected): void {
+  if (info.unresolvedProps.length === 0) return;
+  out.specQuality.push({
+    component: info.componentName,
+    file: info.filePath,
+    props: [...info.unresolvedProps].sort(),
+  });
+}
+
+function inspectHookDeps(info: ComponentInfo, names: KnownNames, findings: Finding[]): void {
+  const details = info.hookDetails;
+  if (!details || details.length === 0) return;
+  const exempt = new Set([...names.setterNames, ...names.refNames]);
+  // Identifiers we can attribute confidently without a scope; derived locals
+  // are deliberately excluded (too noisy from ComponentInfo alone).
+  const trackable = new Set([...names.propNames, ...names.stateVars, ...names.memoResultNames]);
+
+  for (const d of details) {
+    // Bail: the extractor flagged this hook as unreliable to reason about.
+    if (d.depsHasComplex || !d.callbackIsInline || d.readsBareParamsObject) continue;
+    const where = at(d.pos, info.filePath);
+
+    if (MEMO_HOOK_NAMES.has(d.name) && d.missingDepsArray) {
+      findings.push({
+        rule: "perf/hook-missing-deps-array",
+        severity: "warn",
+        ...where,
+        message:
+          `${info.componentName}: ${d.name} has no dependency array — it recomputes on ` +
+          `every render, so the hook buys nothing.`,
+        source: "perf-static",
+      });
+    }
+
+    if (EFFECT_HOOK_NAMES.has(d.name) && d.missingDepsArray && d.effectFeatures) {
+      const f = d.effectFeatures;
+      if (f.fetch || f.setInterval || f.setTimeout || f.addEventListener) {
+        findings.push({
+          rule: "perf/effect-every-render",
+          severity: "warn",
+          ...where,
+          message:
+            `${info.componentName}: ${d.name} has no dependency array yet starts ` +
+            `${effectFeatureList(f)} — it re-runs on every single render.`,
+          source: "perf-static",
+        });
+      }
+    }
+
+    if (d.deps === undefined) continue;
+    const plainDeps = new Set(d.deps.filter((x) => PLAIN_IDENTIFIER.test(x)));
+
+    const missing = d.callbackReads.filter(
+      (r) => !plainDeps.has(r) && !exempt.has(r) && trackable.has(r),
+    );
+    if (missing.length > 0) {
+      const list = missing.map((m) => `"${m}"`).join(", ");
+      findings.push({
+        rule: "perf/hook-missing-dependency",
+        severity: "warn",
+        ...where,
+        message:
+          `${info.componentName}: ${d.name} reads ${list} but omits ` +
+          `${missing.length === 1 ? "it" : "them"} from its deps — the callback closes over ` +
+          `stale values (stale-closure risk).`,
+        source: "perf-static",
+      });
+    }
+
+    for (const dep of d.deps) {
+      if (!PLAIN_IDENTIFIER.test(dep)) continue;
+      if (!trackable.has(dep) || exempt.has(dep)) continue;
+      if (d.callbackReads.includes(dep)) continue;
+      findings.push({
+        rule: "perf/hook-extraneous-dependency",
+        severity: "warn",
+        ...where,
+        message:
+          `${info.componentName}: ${d.name} lists "${dep}" in its deps but never reads it — ` +
+          `the hook re-fires whenever "${dep}" changes, for no benefit.`,
+        source: "perf-static",
+      });
+    }
+  }
+}
+
+function effectFeatureList(f: EffectFeatures): string {
+  const parts: string[] = [];
+  if (f.fetch) parts.push("a fetch");
+  if (f.setInterval) parts.push("setInterval");
+  if (f.setTimeout) parts.push("setTimeout");
+  if (f.addEventListener) parts.push("addEventListener");
+  return parts.join(" + ");
+}
+
+function inspectChildAttrs(node: ComponentTree, names: KnownNames, findings: Finding[]): void {
+  const info = node.entry;
+  const attrs = info.childAttrs;
+  if (!attrs) return;
+
+  const childByTag = new Map<string, ComponentTree>();
+  for (const c of node.children) {
+    childByTag.set(c.entry.localTag ?? c.entry.componentName, c);
+  }
+
+  for (const a of attrs) {
+    if (!UNSTABLE_ATTR_KINDS.has(a.valueKind)) continue;
+    if (NON_PROP_ATTRS.has(a.attr)) continue;
+    const childIsMemo = (childByTag.get(a.tag)?.entry.wrappers ?? []).includes("memo");
+    const kind = ATTR_KIND_LABEL[a.valueKind] ?? "an unstable value";
+    findings.push({
+      rule: "perf/unstable-child-prop",
+      severity: "warn",
+      ...at(a.pos, info.filePath),
+      message:
+        `${info.componentName} passes ${kind} as "${a.attr}" to <${a.tag}> — a new reference ` +
+        `on every render${childIsMemo ? MEMO_WRAPPED_NOTE : "."}`,
+      source: "perf-static",
+    });
+  }
+
+  if ((info.state?.length ?? 0) === 0) return;
+  const stableIds = new Set([
+    ...names.propNames,
+    ...names.stateVars,
+    ...names.setterNames,
+    ...names.memoResultNames,
+  ]);
+  for (const c of node.children) {
+    if (c.children.length !== 0) continue;
+    if ((c.entry.wrappers ?? []).includes("memo")) continue;
+    const tag = c.entry.localTag ?? c.entry.componentName;
+    const childAttrs = attrs.filter((a) => a.tag === tag);
+    // Only flag when every prop is provably stable; spreads, unstable kinds and
+    // identifiers we cannot attribute all bail (zero-attr children qualify).
+    const allStable = childAttrs.every(
+      (a) =>
+        a.valueKind !== "spread" &&
+        STABLE_ATTR_KINDS.has(a.valueKind) &&
+        (a.valueKind !== "identifier" ||
+          (a.identifier !== undefined && stableIds.has(a.identifier))),
+    );
+    if (!allStable) continue;
+    findings.push({
+      rule: "perf/missing-memo-leaf",
+      severity: "warn",
+      ...at(childAttrs[0]?.pos ?? c.entry.pos, info.filePath),
+      message:
+        `<${tag}> is a leaf receiving only stable props from stateful ${info.componentName} ` +
+        `but is not React.memo-wrapped — every state change rerenders it for nothing.`,
+      source: "perf-static",
+    });
+  }
+}
+
+function inspectRenderSetters(info: ComponentInfo, findings: Finding[]): void {
+  for (const s of info.state ?? []) {
+    for (const call of s.setterCalls) {
+      if (call.context !== "render" || call.guarded) continue;
+      findings.push({
+        rule: "perf/set-state-in-render",
+        severity: "error",
+        ...at(call.pos, info.filePath),
+        message:
+          `${info.componentName} calls ${s.setterName ?? `the "${s.varName}" setter`}() ` +
+          `unguarded during render — this triggers an infinite re-render loop.`,
+        source: "perf-static",
+      });
+    }
+  }
+}

package/src/tasks/types.ts

@@ -0,0 +1 @@
+export type { Finding, RunContext, Task, TaskId, TaskResult } from "../types.ts";