@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/bin/flawless-react

@@ -0,0 +1,4 @@
+#!/usr/bin/env bun
+import { main } from "../src/cli.ts";
+
+await main(Bun.argv.slice(2));

package/package.json

@@ -1,6 +1,69 @@
 {
   "name": "@lariocpt/flawless-react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.3.1",
+  "description": "Multi-task quality kit for React components: scaffolds Playwright perf harness + Vitest unit + browser tests, runs static perf analysis, an accessibility scan, and Biome-driven React correctness rules. Point it at a .tsx file or glob and pick what to run.",
+  "type": "module",
+  "author": "Lario Borges",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lariocpt/flawless-react.git"
+  },
+  "bugs": {
+    "url": "https://github.com/lariocpt/flawless-react/issues"
+  },
+  "homepage": "https://lariocpt.github.io/flawless-react-website/",
+  "keywords": [
+    "react",
+    "testing",
+    "playwright",
+    "vitest",
+    "accessibility",
+    "performance",
+    "biome",
+    "code-generation"
+  ],
+  "license": "MIT",
+  "bin": {
+    "flawless-react": "./bin/flawless-react"
+  },
+  "module": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "scripts",
+    ".agents/skills",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "test:watch": "bun test --watch",
+    "dev": "bun src/cli.ts",
+    "build": "bun build --compile --minify --outfile bin/flawless-react-bin src/bin.ts",
+    "lint": "biome lint",
+    "format": "biome format --write",
+    "check": "biome check",
+    "check:fix": "biome check --write",
+    "postinstall": "node scripts/postinstall.mjs"
+  },
+  "dependencies": {
+    "@clack/prompts": "^0.7.0",
+    "@biomejs/biome": "2.5.1",
+    "typescript": "^5.6.0"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@types/react": "^18.3.0"
+  },
+  "engines": {
+    "bun": ">=1.1.0"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public"
+  }
+}

package/scripts/postinstall.d.mts

@@ -0,0 +1,46 @@
+// Types for postinstall.mjs, which stays plain JavaScript ON PURPOSE: npm runs it
+// before anything is installed, so it may not need a transpile step, a bun runtime,
+// or a dependency that is not in node_modules yet. That also means tsc never saw it
+// — the file was shipped untyped until tests/skills-prompt.test.ts imported it.
+// This declaration is the seam: the implementation keeps its runtime shape, and the
+// gate's contract is written down where a change to it has to be stated.
+
+/** What `hasBun` injects to probe for the runtime: a `spawnSync`-shaped call. */
+type RunProbe = (
+  command: string,
+  args: readonly string[],
+) => { error?: unknown; status: number | null };
+
+/**
+ * The answer from the install gate. `reason` is present on every "no" and
+ * `dir` on every "yes" plus the "already installed" case — the caller that
+ * spawns the picker needs the directory, the tests need the reason.
+ */
+export interface SkillGate {
+  ask: boolean;
+  dir?: string;
+  reason?: string;
+}
+
+export declare function hasBun(run?: RunProbe): boolean;
+
+export declare function shouldAsk(options: {
+  env: Record<string, string | undefined>;
+  stdinTty: boolean;
+  stdoutTty: boolean;
+  bunAvailable?: boolean;
+  exists?: (path: string) => boolean;
+}): SkillGate;
+
+export declare function askSkills(options: {
+  bin: string;
+  bun?: string;
+  spawnFn?: (
+    command: string,
+    args: readonly string[],
+    options: { cwd?: string; stdio?: string },
+  ) => {
+    on: (event: string, listener: (argument: unknown) => void) => void;
+  };
+  log?: (line: string) => void;
+}): Promise<string>;

package/scripts/postinstall.mjs

@@ -0,0 +1,127 @@
+// flawless-react — npm postinstall.
+//
+// Asks, once, in a terminal: want the agent skills? Everything here is a
+// best-effort fast path. Install scripts are unreliable by design (npm 12 blocks
+// them by default, `--ignore-scripts` skips them, a proxy can swallow stdout), so
+// the real surface is the CLI itself: an interactive run makes the same offer, and
+// `flawless-react skills install` is always there. What this file owns is the
+// moment a user has just decided to use the tool and has not run it yet.
+//
+// Kept deliberately small: node built-ins only, and it can never fail an install.
+// The gate is `shouldAsk` below — a pure function, so tests cover every reason to
+// stay silent rather than only the one that is easy to trigger.
+import { spawn, spawnSync } from "node:child_process";
+import { existsSync, readdirSync } from "node:fs";
+import path from "node:path";
+
+/** Keep in step with SKILL_PREFIX in src/skills/data.ts — the prefix IS ownership. */
+const SKILL_PREFIX = "flawless-";
+
+/** Whether the picker can actually be run: the CLI is a bun script. */
+export function hasBun(run = spawnSync) {
+  const probe = run("bun", ["--version"]);
+  return !probe.error && probe.status === 0;
+}
+
+/**
+ * Should this install ask? Returns `{ ask, dir }` to ask in, or `{ ask, reason }`.
+ *
+ * The order matters and so does each test. `CI` and a missing TTY come first,
+ * because an unanswered question in a build pipeline is a hung job. A global
+ * install asks nothing: the cwd is wherever npm happened to run, not a project.
+ * `INIT_CWD` is npm's own "where the user ran this" and the only reliable answer,
+ * because a dependency's postinstall runs with cwd set to the package directory,
+ * which is inside node_modules — writing `.agents/skills` there would bury the
+ * files where no agent looks. Anything under node_modules is refused outright.
+ * The bun probe is last because it costs a subprocess: the checks before it are
+ * free, and if bun is absent the picker cannot run anyway.
+ */
+export function shouldAsk({
+  env,
+  stdinTty,
+  stdoutTty,
+  bunAvailable = true,
+  exists = existsSync,
+}) {
+  if (env.FLAWLESS_NO_SKILLS) return { ask: false, reason: "FLAWLESS_NO_SKILLS is set" };
+  if (env.CI) return { ask: false, reason: "CI" };
+  if (env.npm_config_global === "true") return { ask: false, reason: "global install" };
+  if (!stdinTty || !stdoutTty) return { ask: false, reason: "not a terminal" };
+
+  const dir = env.INIT_CWD && path.resolve(env.INIT_CWD);
+  if (!dir) return { ask: false, reason: "no INIT_CWD" };
+  if (dir.includes(`${path.sep}node_modules${path.sep}`) || dir.endsWith("node_modules")) {
+    return { ask: false, reason: "inside node_modules" };
+  }
+  if (!exists(dir)) return { ask: false, reason: "project directory is gone" };
+
+  // A project that already has one of ours was set up on purpose; the skills
+  // themselves are the marker, so neither question needs to store a decline.
+  for (const base of [".agents/skills", ".claude/skills"]) {
+    let entries = [];
+    try {
+      entries = readdirSync(path.join(dir, base), { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    if (entries.some((e) => e.name.startsWith(SKILL_PREFIX) && (e.isDirectory() || e.isSymbolicLink()))) {
+      return { ask: false, reason: "already installed", dir };
+    }
+  }
+
+  if (!bunAvailable) return { ask: false, reason: "no bun on PATH to run the picker" };
+  return { ask: true, dir };
+}
+
+/**
+ * Hand the terminal to the picker. Nothing is decided here about WHICH skills: the
+ * menu owns that, and running it in-process would mean duplicating the installer in
+ * plain JavaScript. So this spawns the CLI with inherited stdio — which also means
+ * the one question in the whole install is clack's, not a second prompt that then
+ * has to hand a half-used stdin to a child.
+ */
+export function askSkills({ bin, bun = "bun", spawnFn = spawn, log = console.error }) {
+  return new Promise((resolve) => {
+    const gate = shouldAsk({
+      env: process.env,
+      stdinTty: Boolean(process.stdin.isTTY),
+      stdoutTty: Boolean(process.stdout.isTTY),
+      bunAvailable: hasBun(),
+    });
+    if (!gate.ask) {
+      resolve(gate.reason ?? "not asked");
+      return;
+    }
+    log("");
+    log("  flawless-react ships agent skills: guides that teach Claude Code, Codex,");
+    log("  Cursor and OpenCode how to drive this tool instead of guessing at it.");
+    log(`  Pick what to install into ${gate.dir}/.agents/skills (Esc installs nothing):`);
+
+    const child = spawnFn(bun, [bin, "skills", "install"], {
+      cwd: gate.dir,
+      stdio: "inherit",
+    });
+    child.on("error", (err) =>
+      log(`  flawless-react: could not run the skills picker (${err.message}). Later:`),
+    );
+    child.on("close", (code) => {
+      if (code) {
+        log(`  flawless-react: the skills picker exited ${code}. Run it yourself any time:`);
+      }
+      log("    bunx flawless-react skills install");
+      resolve(code === null ? "killed" : `exit ${code}`);
+    });
+  });
+}
+
+// npm runs this file directly. Errors are swallowed on purpose: a broken prompt is
+// not a reason to fail an install, and a postinstall that throws takes the user's
+// dependency tree down with it.
+if (import.meta.main) {
+  try {
+    await askSkills({ bin: new URL("../bin/flawless-react", import.meta.url).pathname });
+  } catch {
+    // Declining on the user's behalf is better than aborting their install.
+  }
+  process.exit(0);
+}

package/src/analyse/authShims.ts

@@ -0,0 +1,220 @@
+/**
+ * Provider-bound auth libraries — the ones that THROW when a component renders
+ * without their provider mounted. `@clerk/nextjs` refuses on a missing
+ * publishableKey before anything else runs; its hooks refuse outside
+ * ClerkProvider; next-auth's useSession refuses outside SessionProvider. A
+ * browser host bundles every analysed component into ONE module graph (the
+ * kiranism dogfood run: Accordion's profile spec died on "Missing
+ * publishableKey" because AppSidebar's Clerk import poisoned the shared
+ * bundle), and jsdom units mount components bare, with no app layout to
+ * supply the provider.
+ *
+ * Neither plane can meaningfully run a real auth handshake, so the whole
+ * library is replaced with a signed-out stub — same philosophy as the global
+ * next/navigation mock in setup.ts. The stub is generated from the export
+ * names the analysis actually saw imported, because ESM named imports have to
+ * bind: a catch-all default export cannot satisfy `import { useUser }`.
+ */
+import { readFileSync } from "node:fs";
+import ts from "typescript";
+
+/** Package names matched exactly or by subpath ("next-auth/react", "@clerk/nextjs/server"). */
+const AUTH_LIB_PREFIXES = [
+  "@clerk/nextjs",
+  "@clerk/clerk-react",
+  "next-auth",
+  // The Supabase auth layer, in both its generations: `auth-helpers-*` is the
+  // tutorial stack (talkformai's pages/_app builds a client in a useState
+  // initializer, so with no env file the CONSTRUCTOR throws before a single
+  // spec runs — 17 files, 26 tests, all dead on
+  // "either NEXT_PUBLIC_SUPABASE_URL and NEXT_PUBLIC_SUPABASE_ANON_KEY env
+  // variables or supabaseUrl and supabaseKey are required!"), and `@supabase/ssr`
+  // is its replacement. Both are provider-bound: the session context they
+  // supply is exactly what a unit mount cannot have. `@supabase/supabase-js`
+  // itself stays unstubbed — it is the SDK rather than the provider, and a
+  // stubbed `from().select()` chain would turn a named failure into undefined
+  // results quietly flowing through an assertion.
+  "@supabase/auth-helpers-nextjs",
+  "@supabase/auth-helpers-react",
+  "@supabase/ssr",
+];
+
+export function isAuthLibSpecifier(specifier: string): boolean {
+  return AUTH_LIB_PREFIXES.some((p) => specifier === p || specifier.startsWith(`${p}/`));
+}
+
+export interface AuthStub {
+  /** Module-side export names to bind (the "cn" of `import { cn as cx }`), sorted, no "default". */
+  names: string[];
+  hasDefault: boolean;
+}
+
+/** The part of ModuleImportInfo the collector reads, so a raw file can feed it too. */
+interface AuthImportEvidence {
+  specifier: string;
+  names: readonly string[];
+  importedNames?: readonly string[];
+  isTypeOnly?: boolean;
+}
+
+/**
+ * Import declarations of a file the analysis never visits. The app resolver is
+ * mounted by every spec without being an analysed component, so its auth
+ * imports would stay unstubbed while its module graph runs for real:
+ * talkformai's pages/_app.tsx is the only file importing
+ * `createPagesBrowserClient` / `SessionContextProvider`, and with no env file in
+ * the repo the real client threw from its constructor — 17 spec files, 26
+ * tests, none of them reaching an assertion. The import table is all the
+ * collector needs; the shim binds the names.
+ */
+function fileImportEvidence(file: string): AuthImportEvidence[] {
+  let sf: ts.SourceFile;
+  try {
+    sf = ts.createSourceFile(
+      file,
+      readFileSync(file, "utf8"),
+      ts.ScriptTarget.ES2022,
+      true,
+      ts.ScriptKind.TSX,
+    );
+  } catch {
+    return [];
+  }
+  const out: AuthImportEvidence[] = [];
+  for (const stmt of sf.statements) {
+    if (!ts.isImportDeclaration(stmt) || !ts.isStringLiteral(stmt.moduleSpecifier)) continue;
+    const clause = stmt.importClause;
+    if (!clause || clause.isTypeOnly) continue;
+    const names: string[] = [];
+    const importedNames: string[] = [];
+    if (clause.name) {
+      names.push(clause.name.text);
+      importedNames.push("default");
+    }
+    const bindings = clause.namedBindings;
+    if (bindings && ts.isNamedImports(bindings)) {
+      for (const el of bindings.elements) {
+        names.push(el.name.text);
+        importedNames.push(el.propertyName?.text ?? el.name.text);
+      }
+    } else if (bindings && ts.isNamespaceImport(bindings)) {
+      names.push(bindings.name.text);
+      importedNames.push(bindings.name.text);
+    }
+    if (names.length === 0) continue;
+    out.push({ specifier: stmt.moduleSpecifier.text, names, importedNames });
+  }
+  return out;
+}
+
+/**
+ * Specifier → the export names any analysed file imports from it. Collect from
+ * EVERY analysed component, not just the mountable ones: an excluded component
+ * is still imported transitively by a hosted neighbour, and one unstubbed
+ * throw poisons the whole bundle. Namespace imports are indistinguishable
+ * here (the analyser records the local name as the module-side name); a repo
+ * that does `import * as clerk from "@clerk/nextjs"` will see undefined
+ * members and the dogfood failure will name the specifier.
+ */
+export function collectAuthStubs(
+  infos: Iterable<{ moduleImports?: readonly AuthImportEvidence[] }>,
+  extraFiles: readonly string[] = [],
+): Map<string, AuthStub> {
+  const acc = new Map<string, { names: Set<string>; hasDefault: boolean }>();
+  const absorb = (mi: AuthImportEvidence): void => {
+    if (mi.isTypeOnly || !isAuthLibSpecifier(mi.specifier)) return;
+    let entry = acc.get(mi.specifier);
+    if (!entry) {
+      entry = { names: new Set(), hasDefault: false };
+      acc.set(mi.specifier, entry);
+    }
+    const e = entry;
+    mi.names.forEach((local, i) => {
+      const moduleSide = mi.importedNames?.[i] ?? local;
+      if (moduleSide === "default") e.hasDefault = true;
+      else e.names.add(moduleSide);
+    });
+  };
+  for (const info of infos) for (const mi of info.moduleImports ?? []) absorb(mi);
+  for (const file of extraFiles) for (const mi of fileImportEvidence(file)) absorb(mi);
+  return new Map(
+    [...acc.entries()]
+      .sort(([a], [b]) => (a < b ? -1 : 1))
+      .map(([spec, e]) => [spec, { names: [...e.names].sort(), hasDefault: e.hasDefault }]),
+  );
+}
+
+/**
+ * A signed-out snapshot: everything falsy-but-present so `user?.firstName`
+ * renders nothing instead of throwing. Unknown property reads follow shape
+ * heuristics — verb names get an async no-op (awaiting undefined throws),
+ * `*List` gets an empty array (mapping undefined throws) — and otherwise
+ * undefined. Regenerated per call so no test can mutate another's view.
+ */
+const SNAPSHOT = `const __snap = () => new Proxy({ isLoaded: true, isLoading: false, isSignedIn: false, userId: null, sessionId: null, orgId: null, orgRole: null, user: null, organization: null, session: null, data: null, status: "unauthenticated" }, { get: (t, k) => k in t ? t[k] : typeof k === "string" && (/^(sign|set|get|reload|redirect|create)/i.test(k) || k === "auth" || k === "currentUser") ? async () => __snap() : typeof k === "string" && k.endsWith("List") ? [] : undefined });`;
+
+/** Render children — for providers (hooks need their subtree mounted) and unknown widgets (empty is safe). */
+const AS_CHILD = `const __asChild = (props) => (props && props.children !== undefined ? props.children : null);`;
+
+/**
+ * Per-export stub expression. The signed-out state decides the three named
+ * conditionals; hooks get the snapshot; the known async API surface gets an
+ * awaited snapshot (components `await auth()` and destructure it); providers
+ * must mount children; unknown widgets render children too — no children,
+ * nothing renders, which is the honest signed-out picture for a UserButton.
+ */
+function stubExpr(name: string): string {
+  if (name === "Show") return "(props) => (props && props.when ? props.children : null)";
+  // Signed-out means SignedIn renders nothing and SignedOut renders its
+  // children; `<Show when>` is the generic conditional.
+  if (name === "SignedIn") return "() => null";
+  if (name === "SignedOut") return "__asChild";
+  // Hooks return the snapshot, not a renderable — destructuring a component
+  // stub (`const { userId } = useAuth()`) would hand back a function.
+  if (/^use[A-Z]/.test(name)) return "() => __snap()";
+  // Known async API surface: components `await auth()` and destructure it.
+  if (
+    /^(signIn|signUp|signOut|reload|redirect|setActive|setSession|getSession|getServerSession|getAuth|getCurrentUser|currentUser|createOrganization)$/.test(
+      name,
+    ) ||
+    name === "auth" ||
+    name === "clerkClient"
+  ) {
+    return "async () => __snap()";
+  }
+  // Providers must mount children or nothing under them renders; unknown
+  // names are treated the same way — a widget with no children renders null.
+  return "__asChild";
+}
+
+function preamble(specifier: string): string {
+  return [
+    `// flawlessly-generated signed-out stub for "${specifier}": the real library throws`,
+    "// without its provider/keys, which neither the perf host nor a bare unit mount",
+    "// can supply. Export names come from the analysis of this repo's components.",
+    SNAPSHOT,
+    AS_CHILD,
+  ].join("\n");
+}
+
+/** ESM source for the perf-harness host bundle (Bun plugin onLoad body). */
+export function authShimEsm(specifier: string, stub: AuthStub): string {
+  const lines = [preamble(specifier)];
+  for (const n of stub.names) lines.push(`export const ${n} = ${stubExpr(n)};`);
+  if (stub.hasDefault) lines.push(`export default __asChild;`);
+  return lines.join("\n");
+}
+
+/** A vi.mock block for the unit plane's setup.ts (factory-local: vitest hoists the call). */
+export function authShimVitestBlock(specifier: string, stub: AuthStub): string {
+  const exports = stub.names.map((n) => `${JSON.stringify(n)}: ${stubExpr(n)}`);
+  if (stub.hasDefault) exports.push(`default: __asChild`);
+  return `
+vi.mock(${JSON.stringify(specifier)}, () => {
+${preamble(specifier)
+  .split("\n")
+  .map((l) => `  ${l}`)
+  .join("\n")}
+  return { ${exports.join(", ")} };
+});`;
+}