@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/src/reactCompiler.ts

@@ -0,0 +1,165 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import type { ReactCompilerProbe } from "./types.ts";
+
+/** Expo's own flag, in the app config a person edits. Parsed: it is JSON. */
+const APP_CONFIG = "app.json";
+
+/** Next ≥15's stable `reactCompiler` flag, plus its earlier `experimental` home. */
+const NEXT_CONFIGS = ["next.config.ts", "next.config.js", "next.config.mjs", "next.config.cjs"];
+
+/** The project's Babel entry — where the plugin goes when Babel runs at all. */
+const BABEL_CONFIGS = ["babel.config.js", "babel.config.cjs", "babel.config.mjs"];
+
+/**
+ * Bundler configs whose presence means "this project's transform pipeline is
+ * declared here, in this file". Deliberately a list of config-file CONVENTIONS
+ * we recognise and not a general scan: a bundler we do not know has no honest
+ * answer, and says so.
+ */
+const BUNDLER_CONFIGS = [
+  "vite.config.ts",
+  "vite.config.js",
+  "vite.config.mjs",
+  "webpack.config.js",
+  "webpack.config.cjs",
+  "webpack.config.mjs",
+  "webpack.config.ts",
+  "rspack.config.js",
+  "rsbuild.config.ts",
+  "rsbuild.config.js",
+];
+
+const PLUGIN_NEEDLE = "babel-plugin-react-compiler";
+
+/** `reactCompiler: true`, `"reactCompiler": true`, `'react-compiler': false`. */
+const FLAG_ASSIGNMENT = /["']?(reactCompiler|react-compiler)["']?\s*:\s*(true|false)/;
+
+/**
+ * Read the React Compiler state for a project root.
+ *
+ * The ladder is the same in every mode, and it is a ladder of authority rather
+ * than a search: a positive spelling in any config the project actually uses
+ * turns it on, and only the absence of every positive spelling in every config
+ * we could read turns it off.
+ *
+ * Everything read here is a config file, as text, never executed — and never
+ * package.json or a lockfile. The dogfood web app's `bun.lock` carries
+ * `babel-plugin-react-compiler` because Next ships it as a dependency of its
+ * own while the compiler is OFF; a dependency-presence check would have
+ * suppressed 127 valid findings on that run. Dependency presence ≠ activation.
+ *
+ * If a future preset ships the compiler ON by default (bare-RN's
+ * `@react-native/babel-preset` and newer Expo SDKs have been moving that way),
+ * the version-keyed default table belongs in this file: read the installed
+ * preset's SHIPPED DEFAULT as text. Asking the project's babel config that
+ * question by executing it is never the answer.
+ */
+export function detectReactCompiler(root: string): ReactCompilerProbe {
+  const abs = path.resolve(root);
+  const positives: string[] = [];
+  const read: string[] = [];
+
+  // Expo's flag first, parsed rather than grepped: app.json is JSON, so the key
+  // is decisive in a way no text scan is. `app.config.{js,ts}` is not read at
+  // all — executing a project's config to ask it a question is not something a
+  // static analyser does, and the babel plugin spelling below still catches a
+  // project that turns the compiler on that way.
+  const appJson = readJson(path.join(abs, APP_CONFIG));
+  if (appJson) {
+    read.push(APP_CONFIG);
+    const experiments = (appJson.expo as { experiments?: Record<string, unknown> } | undefined)
+      ?.experiments;
+    if (experiments?.reactCompiler === true) {
+      positives.push(`${APP_CONFIG} experiments.reactCompiler`);
+    }
+  }
+
+  for (const file of [...NEXT_CONFIGS, ...BABEL_CONFIGS, ...BUNDLER_CONFIGS]) {
+    const text = readText(path.join(abs, file));
+    if (text === undefined) continue;
+    read.push(file);
+    const positive = configSaysOn(file, text);
+    if (positive !== undefined) positives.push(positive);
+  }
+
+  // The first positive names a sufficient reason, so several spellings in one
+  // project cost one evidence line, not a list.
+  if (positives.length > 0) return { state: "on", evidence: positives[0] as string };
+
+  if (read.length === 0) {
+    return {
+      state: "undetermined",
+      evidence: "no app.json, next.config, babel config or recognised bundler config to read",
+    };
+  }
+  const more = read.length > 3 ? `, +${read.length - 3} more` : "";
+  return {
+    state: "off",
+    evidence: `no React Compiler flag in ${read.slice(0, 3).join(", ")}${more}`,
+  };
+}
+
+/**
+ * What one config file says. Undefined means the file does not speak about the
+ * compiler at all — which is not the same as it saying no, and is why the caller
+ * collects what was READ separately from what was POSITIVE.
+ *
+ * Order matters. An explicit assignment wins over the plugin name because a
+ * preset option is the gate; the plugin name wins over the bare flag word
+ * because the bare word can be anything (`isReactCompilerEnabled` in a comment,
+ * a local variable) — kept only because it is a real spelling of expo's preset
+ * options and the detector has always accepted it.
+ */
+function configSaysOn(file: string, text: string): string | undefined {
+  const flag = FLAG_ASSIGNMENT.exec(text);
+  if (flag) {
+    return flag[2] === "true" ? `${file} ${flag[1]}` : undefined;
+  }
+  if (text.includes(PLUGIN_NEEDLE)) return `${file} ${PLUGIN_NEEDLE}`;
+  if (/\breactCompiler\b/.test(text)) return `${file} reactCompiler`;
+  return undefined;
+}
+
+/**
+ * The project root a framework-less run's configs sit in.
+ *
+ * The same upward walk `ignoreRootFor` makes for the same reason: the tool is
+ * run from wherever the person happens to be, and the configs are not
+ * necessarily beside the out dir. The first ancestor that is a project — a
+ * `.git` or a `package.json` — wins, so a run from a monorepo package reads that
+ * package's configs rather than the repo's. Unlike the ignore case there is no
+ * last-resort answer: a tree with no package.json anywhere has no configs to
+ * read either, so the caller gets its own start back and says undetermined.
+ */
+export function configRootFor(outDir: string): string {
+  let dir = path.resolve(outDir);
+  for (;;) {
+    if (existsSync(path.join(dir, ".git")) || existsSync(path.join(dir, "package.json"))) {
+      return dir;
+    }
+    const parent = path.dirname(dir);
+    if (parent === dir) return path.resolve(outDir);
+    dir = parent;
+  }
+}
+
+function readText(p: string): string | undefined {
+  if (!existsSync(p)) return undefined;
+  try {
+    return readFileSync(p, "utf8");
+  } catch {
+    // An unreadable config proves nothing. It is not evidence of an absent flag.
+    return undefined;
+  }
+}
+
+function readJson(p: string): Record<string, unknown> | undefined {
+  const text = readText(p);
+  if (text === undefined) return undefined;
+  try {
+    return JSON.parse(text) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}

package/src/reporters/findings.ts

@@ -0,0 +1,156 @@
+import { mkdir } from "node:fs/promises";
+import path from "node:path";
+import { relativeToEmitted } from "../emitPaths.ts";
+import { A11Y_REPORT } from "../tasks/a11yScan.ts";
+import { REACT_RULES_REPORT } from "../tasks/eslintReactRules.ts";
+import type { ComponentInfo, ComponentTree, Finding, TaskId, TaskResult } from "../types.ts";
+
+export function printFindings(findings: Finding[]): void {
+  if (findings.length === 0) return;
+  const byFile = new Map<string, Finding[]>();
+  for (const f of findings) {
+    const list = byFile.get(f.file) ?? [];
+    list.push(f);
+    byFile.set(f.file, list);
+  }
+  for (const [file, list] of byFile) {
+    process.stdout.write(`\n${path.relative(process.cwd(), file)}\n`);
+    for (const f of list) {
+      const sev = f.severity === "error" ? "ERROR" : "warn ";
+      process.stdout.write(`  ${sev}  ${f.line}:${f.column}  ${f.rule}  ${f.message}\n`);
+    }
+  }
+}
+
+export function printSummaryTable(results: TaskResult[]): void {
+  process.stdout.write("\nSummary:\n");
+  for (const r of results) {
+    const status = r.ok ? "ok" : "FAIL";
+    const findings = r.findings.length;
+    const outputs = r.outputs.length;
+    process.stdout.write(
+      `  [${status}] ${r.id.padEnd(14)} files:${outputs} findings:${findings}  ${r.summary}\n`,
+    );
+    if (r.error) process.stdout.write(`         error: ${r.error}\n`);
+  }
+}
+
+export async function writeSummaryJson(outDir: string, results: TaskResult[]): Promise<string> {
+  const reportsDir = path.join(outDir, "reports");
+  await mkdir(reportsDir, { recursive: true });
+  const out = path.join(reportsDir, "summary.json");
+  const body = {
+    ts: new Date().toISOString(),
+    results: results.map((r) => ({
+      id: r.id,
+      ok: r.ok,
+      summary: r.summary,
+      outputs: r.outputs.length,
+      findings: r.findings.length,
+      error: r.error,
+    })),
+  };
+  await Bun.write(out, `${JSON.stringify(body, null, 2)}\n`);
+  return out;
+}
+
+export async function writeInlineSummaries(
+  trees: ComponentTree[],
+  results: TaskResult[],
+  outDir: string,
+): Promise<string[]> {
+  // Keyed on filePath::componentName — the registry.ts dedupe convention.
+  // Keyed on the bare name, a/Header.tsx and b/Header.tsx collapse into one
+  // entry: the second file never gets its sidecar, and every finding routed to
+  // it is silently dropped from the report.
+  const byComponent = new Map<string, Finding[]>();
+  const components = new Map<string, ComponentTree>();
+  for (const t of trees) collectComponents(t, components);
+
+  for (const r of results) {
+    for (const f of r.findings) {
+      const owner = findOwner(f.file, components);
+      if (!owner) continue;
+      const list = byComponent.get(owner) ?? [];
+      list.push(f);
+      byComponent.set(owner, list);
+    }
+  }
+
+  const written: string[] = [];
+  for (const [key, tree] of components) {
+    const name = tree.entry.componentName;
+    const dir = path.dirname(tree.entry.filePath);
+    const out = path.join(dir, `${name}.flawless.json`);
+    const findings = byComponent.get(key) ?? [];
+    const counts: Record<TaskId | "total", number> = {
+      "perf-harness": 0,
+      "unit-browser": 0,
+      "perf-static": 0,
+      a11y: 0,
+      "react-rules": 0,
+      e2e: 0,
+      load: 0,
+      total: findings.length,
+    };
+    for (const f of findings) counts[f.source] += 1;
+    const top = [...findings]
+      .sort((a, b) => severityWeight(b.severity) - severityWeight(a.severity))
+      .slice(0, 3)
+      .map((f) => ({
+        rule: f.rule,
+        severity: f.severity,
+        line: f.line,
+        column: f.column,
+        message: f.message,
+      }));
+    // Every path here is relative to THIS file, not to the machine that wrote
+    // it. The sidecar lands beside the analysed source and is committed like any
+    // other generated file, so an absolute path in one names the developer who
+    // ran the tool — src/emitPaths.ts exists to stop exactly that, and this was
+    // the one emitted file its sentinel sweep did not cover. Resolve with
+    // path.resolve(dirname(<this file>), value).
+    const rel = (target: string): string => relativeToEmitted(dir, target);
+    const body = {
+      component: name,
+      file: rel(tree.entry.filePath),
+      counts,
+      top,
+      // a11y and react-rules are SWEEPS: each writes a single aggregate for the
+      // whole run, and only perf-static reports per component. These two used
+      // to be spelled `${name}.a11y.json` and `${name}.react-rules.json` —
+      // files no run has ever produced — so two thirds of this map pointed at
+      // nothing, and the published docs copied the wrong names from it.
+      reports: {
+        a11y: rel(path.join(outDir, "reports", A11Y_REPORT)),
+        reactRules: rel(path.join(outDir, "reports", REACT_RULES_REPORT)),
+        perfStatic: rel(path.join(outDir, "reports", `${name}.perf-static.json`)),
+      },
+    };
+    await Bun.write(out, `${JSON.stringify(body, null, 2)}\n`);
+    written.push(out);
+  }
+  return written;
+}
+
+/** filePath::componentName — the same key registry.ts flattens and dedupes on. */
+function componentKey(entry: ComponentInfo): string {
+  return `${entry.filePath}::${entry.componentName}`;
+}
+
+function collectComponents(tree: ComponentTree, into: Map<string, ComponentTree>): void {
+  const key = componentKey(tree.entry);
+  if (!into.has(key)) into.set(key, tree);
+  for (const c of tree.children) collectComponents(c, into);
+}
+
+function findOwner(file: string, components: Map<string, ComponentTree>): string | undefined {
+  for (const [key, tree] of components) {
+    if (path.resolve(tree.entry.filePath) === path.resolve(file)) return key;
+  }
+  return undefined;
+}
+
+function severityWeight(s: "error" | "warn"): number {
+  return s === "error" ? 2 : 1;
+}