@lariocpt/flawless-react 0.0.0-stage → 0.3.1

package/src/scaffold/index.ts

@@ -0,0 +1,253 @@
+import { existsSync } from "node:fs";
+import { chmod, mkdir, readdir, readFile, rm } from "node:fs/promises";
+import path from "node:path";
+import { detectAppReact, mergePackageJson, repairReactPin } from "../packageJson.ts";
+import { classifyStamped } from "../scaffold-tests/stamp.ts";
+import type { ComponentTree, ScaffoldOptions } from "../types.ts";
+import { extractRoutes, loadApiSpec } from "./openapi.ts";
+import { renderSuite, toHostRelImport } from "./templates.ts";
+
+export interface ScaffoldResult {
+  /** Absolute paths of the files this call wrote. */
+  written: string[];
+  /** writeOnce files that already existed and were left untouched. */
+  kept: string[];
+  status: "generated" | "refreshed" | "kept";
+  /**
+   * Version in the existing marker file's generated-by banner, on a "kept"
+   * result. Undefined for a pre-banner suite — the caller must say "unknown
+   * version", never substitute its own.
+   */
+  existingVersion?: string;
+  /**
+   * host/main.tsx predates the registry split (no `from "./registry"` import),
+   * so the kept wrapper never sees newly analysed components. writeOnce is
+   * absolute — `--force` included — so the caller must name the escape:
+   * delete host/main.tsx and re-run, or port the hand wiring onto an import
+   * of ./registry. host/registry.ts is still written, inert beside it.
+   */
+  preSplitMain?: boolean;
+  /**
+   * Stale profile specs removed because their component is no longer in the
+   * host and the stamp proved the file was untouched tool output.
+   */
+  staleRemoved: string[];
+  /** Stale profile specs kept (hand work or unprovable) — the owner's call. */
+  staleKept: StaleProfileSpec[];
+  /**
+   * The kept host/main.tsx imported a provider this run no longer resolves to,
+   * and the tool re-pointed that ONE import line (specifiers as the file had
+   * them and as it now does). Everything else in the file is untouched.
+   */
+  providerImportRefresh?: { from: string; to: string };
+  /** The kept host/main.tsx names AppProvider in a shape the tool will not touch. */
+  providerImportWarning?: string;
+}
+
+/** A stale profile spec the writer refused to remove, and why. */
+export interface StaleProfileSpec {
+  abs: string;
+  /** "edited" = stamp present, body differs (hand work); "stampless" = no provenance at all. */
+  verdict: "edited" | "stampless";
+}
+
+/** The generated-by banner the marker file carries; parseExistingVersion reads it back. */
+const BANNER_RE = /Generated by flawless-react (\S+)/;
+
+export function parseExistingVersion(markerText: string): string | undefined {
+  return BANNER_RE.exec(markerText)?.[1];
+}
+
+export async function scaffold(
+  tree: ComponentTree,
+  opts: ScaffoldOptions,
+): Promise<ScaffoldResult> {
+  const outDir = path.resolve(opts.outDir);
+  // Keyed on a suite already being here, not on the directory existing. The
+  // directory is not a usable proxy: ensureClientProviderWrapper mkdirs outDir
+  // at core.ts:215, before the task loop at :298, so on any --nextjs run outDir
+  // exists by the time this is reached and a bare existsSync would claim a
+  // suite on every FIRST run.
+  const marker = path.join(outDir, "playwright.config.ts");
+  const suiteExists = existsSync(marker);
+
+  // Changed-mode: the run is narrowed, generation is not churned — nothing is
+  // written over an existing suite, and the caller reports which version wrote
+  // it (from the marker's banner; pre-banner suites have no version to name).
+  if (suiteExists && opts.keepExisting) {
+    return {
+      written: [],
+      kept: [],
+      status: "kept",
+      existingVersion: parseExistingVersion(await Bun.file(marker).text()),
+      staleRemoved: [],
+      staleKept: [],
+    };
+  }
+
+  await mkdir(outDir, { recursive: true });
+
+  // Checked before the write loop only for clarity — the file is writeOnce, so
+  // the loop below could not change the verdict either way.
+  const mainPath = path.join(outDir, "host", "main.tsx");
+  const preSplitMain =
+    // Quote- and extension-tolerant: main.tsx is user-owned, so a prettier
+    // singleQuote pass or an explicit ./registry.ts import (the suite tsconfig
+    // allows importing .ts extensions) must not read as pre-split forever.
+    existsSync(mainPath) &&
+    !/from\s+['"]\.\/registry(\.ts)?['"]/.test(await Bun.file(mainPath).text());
+
+  const providerImportPath = opts.provider ? toHostRelImport(outDir, opts.provider) : undefined;
+  const mockRoutes = opts.apiSpec ? extractRoutes(await loadApiSpec(opts.apiSpec)) : undefined;
+
+  const files = renderSuite({
+    tree,
+    extraTrees: opts.extraTrees,
+    suiteName: opts.suiteName,
+    outDir,
+    variants: opts.variants,
+    ...(opts.heaps ? { heaps: opts.heaps } : {}),
+    report: opts.report,
+    providerImportPath,
+    ...(opts.provider ? { providerFile: opts.provider } : {}),
+    mockRoutes,
+    nextjsHost: opts.nextjsHost,
+    mswSetup: opts.mswSetup,
+    ...(opts.providerWraps ? { providerWraps: opts.providerWraps } : {}),
+  });
+
+  const written: string[] = [];
+  const kept: string[] = [];
+  for (const f of files) {
+    const abs = f.absPath ?? path.join(outDir, f.relPath);
+    // Not gated on --force, unlike the colocated specs: the point of these
+    // files is that no flag rebuilds a tuned budget or hand-wired provider.
+    // Delete the file to get a fresh one, same as provider.fixtures.ts.
+    if (f.writeOnce && existsSync(abs)) {
+      kept.push(abs);
+      continue;
+    }
+    await mkdir(path.dirname(abs), { recursive: true });
+    if (f.relPath === "package.json" && existsSync(abs)) {
+      await Bun.write(
+        abs,
+        repairReactPin(
+          mergePackageJson(await Bun.file(abs).text(), f.content),
+          detectAppReact(outDir),
+        ),
+      );
+      written.push(abs);
+      continue;
+    }
+    await Bun.write(abs, f.content);
+    if (f.executable) await chmod(abs, 0o755);
+    written.push(abs);
+  }
+
+  // Profile specs are rewritten every run ONLY while their component stays
+  // host-mountable. When it leaves the host set (a new guard the analyser
+  // cannot decide, a render-mode change, a deleted file) the spec is simply
+  // no longer rendered — and without this sweep it sits in profile/ forever,
+  // failing at mount with "unknown component": a suite red by the tool's own
+  // doing. Provenance decides, exactly as for the colocated and browser
+  // specs: an untouched stamp is pure tool output (removed and reported); a
+  // mismatched stamp is hand work (kept, reported); no stamp at all is
+  // unprovable (kept, reported — protects pre-stamp suites).
+  const staleRemoved: string[] = [];
+  const staleKept: StaleProfileSpec[] = [];
+  const renderedProfile = new Set(
+    files
+      .filter((f) => f.relPath.startsWith("profile/") && f.relPath.endsWith(".profile.spec.ts"))
+      .map((f) => f.relPath),
+  );
+  const profileDir = path.join(outDir, "profile");
+  if (existsSync(profileDir)) {
+    for (const entry of (await readdir(profileDir)).sort()) {
+      if (!entry.endsWith(".profile.spec.ts")) continue;
+      if (renderedProfile.has(`profile/${entry}`)) continue;
+      const abs = path.join(profileDir, entry);
+      const verdict = classifyStamped(await readFile(abs, "utf8"));
+      if (verdict === "untouched") {
+        await rm(abs);
+        staleRemoved.push(abs);
+      } else {
+        staleKept.push({ abs, verdict });
+      }
+    }
+  }
+
+  // A kept host/main.tsx is user-owned — its ALL spread and hand wiring survive
+  // every run — but `import AppProvider from "…"` is not a tuned value: it names
+  // the provider THIS run resolved. When the provider moves, the kept import
+  // keeps pulling the old file and the whole host mounts the wrong tree. On the
+  // talkformai dogfood a pages `_app` that cannot mount began deriving to
+  // flawless/provider.tsx while main.tsx went on importing src/pages/_app, so
+  // all 18 browser mounts died as "mount: X did not render within 5000ms" — a
+  // timeout that never mentions the cause, which was a Supabase client
+  // constructor throwing inside _app. Re-point the one line and report it: an
+  // intentional repoint is then visible in git diff, not silently reverted.
+  let providerImportRefresh: { from: string; to: string } | undefined;
+  let providerImportWarning: string | undefined;
+  if (providerImportPath && kept.includes(mainPath)) {
+    const repair = await refreshProviderImport(mainPath, providerImportPath);
+    if (repair) {
+      providerImportRefresh = repair.refreshed;
+      providerImportWarning = repair.warning;
+    }
+  }
+
+  return {
+    written,
+    kept,
+    status: suiteExists ? "refreshed" : "generated",
+    preSplitMain,
+    staleRemoved,
+    staleKept,
+    ...(providerImportRefresh ? { providerImportRefresh } : {}),
+    ...(providerImportWarning ? { providerImportWarning } : {}),
+  };
+}
+
+/** Comparable module id for a specifier written inside `fromFile` (extension-blind). */
+function specifierId(fromFile: string, specifier: string): string {
+  return path.resolve(path.dirname(fromFile), specifier).replace(/\.(tsx|jsx|ts|mjs|cjs|js)$/, "");
+}
+
+/**
+ * Re-point a kept host/main.tsx's AppProvider import when it disagrees with the
+ * provider this run resolved. Returns nothing when there is nothing to say.
+ *
+ * Only the exact line the tool emits is rewritten — quote style preserved — so
+ * a named import, a multi-line import, or an aliased default is left alone and
+ * reported instead. Those shapes mean a hand edit, and hand edits are why this
+ * file is write-once.
+ */
+async function refreshProviderImport(
+  mainPath: string,
+  want: string,
+): Promise<{ refreshed?: { from: string; to: string }; warning?: string } | undefined> {
+  const text = await Bun.file(mainPath).text();
+  const wantNoExt = want.replace(/\.(tsx|jsx|ts)$/, "");
+  const match = /^import AppProvider from (['"])([^'"]+)\1;$/m.exec(text);
+  if (!match) {
+    return text.includes("AppProvider")
+      ? {
+          warning:
+            "host/main.tsx references AppProvider through an import this tool does not " +
+            "recognise — its provider import was left alone and may not match --provider",
+        }
+      : undefined;
+  }
+  const [, quote, from] = match;
+  // The pattern has both groups whenever it matched at all, so this is the
+  // checker's guard, not a case the caller can reach: nothing to refresh.
+  if (quote === undefined || from === undefined) return undefined;
+  if (specifierId(mainPath, from) === specifierId(mainPath, want)) return undefined;
+  await Bun.write(
+    mainPath,
+    text.replace(match[0], `import AppProvider from ${quote}${wantNoExt}${quote};`),
+  );
+  return { refreshed: { from, to: wantNoExt } };
+}
+
+export { renderSuite } from "./templates.ts";

package/src/scaffold/openapi.ts

@@ -0,0 +1,183 @@
+import type { MockRoute } from "../types.ts";
+
+interface OpenApiSpec {
+  openapi?: string;
+  swagger?: string;
+  paths?: Record<string, Record<string, OperationObject> | undefined>;
+  components?: { schemas?: Record<string, unknown> };
+  [k: string]: unknown;
+}
+
+interface OperationObject {
+  responses?: Record<string, ResponseObject | undefined>;
+  [k: string]: unknown;
+}
+
+interface ResponseObject {
+  content?: Record<string, MediaTypeObject | undefined>;
+  [k: string]: unknown;
+}
+
+interface MediaTypeObject {
+  schema?: unknown;
+  example?: unknown;
+  examples?: Record<string, { value?: unknown } | undefined>;
+}
+
+const HTTP_METHODS = ["get", "post", "put", "patch", "delete", "options", "head"] as const;
+
+export async function loadApiSpec(filePath: string): Promise<OpenApiSpec> {
+  const file = Bun.file(filePath);
+  if (!(await file.exists())) {
+    throw new Error(`--api: spec not found at ${filePath}`);
+  }
+  const text = await file.text();
+  const trimmed = text.trimStart();
+  const looksJson = trimmed.startsWith("{") || trimmed.startsWith("[");
+  let parsed: unknown;
+  try {
+    parsed = looksJson ? JSON.parse(text) : parseYaml(text);
+  } catch (err) {
+    throw new Error(`--api: failed to parse ${filePath}: ${(err as Error).message}`);
+  }
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error(`--api: ${filePath} did not parse to an object`);
+  }
+  const spec = parsed as OpenApiSpec;
+  if (!spec.paths || typeof spec.paths !== "object") {
+    throw new Error(`--api: ${filePath} has no 'paths' object`);
+  }
+  return spec;
+}
+
+function parseYaml(text: string): unknown {
+  const yaml = (Bun as unknown as { YAML?: { parse: (s: string) => unknown } }).YAML;
+  if (!yaml) {
+    throw new Error(
+      "YAML parsing requires Bun >= 1.2 (Bun.YAML.parse not found). Convert your spec to JSON first.",
+    );
+  }
+  return yaml.parse(text);
+}
+
+export function extractRoutes(spec: OpenApiSpec): MockRoute[] {
+  const out: MockRoute[] = [];
+  for (const [pathTpl, methods] of Object.entries(spec.paths ?? {})) {
+    if (!methods) continue;
+    for (const method of HTTP_METHODS) {
+      const op = methods[method];
+      if (!op) continue;
+      const picked = pickResponse(op);
+      const body = synthesizeBody(picked.media, spec);
+      out.push({
+        method: method.toUpperCase(),
+        path: pathTpl,
+        status: picked.status,
+        body,
+      });
+    }
+  }
+  return out;
+}
+
+function pickResponse(op: OperationObject): { status: number; media: MediaTypeObject | null } {
+  const responses = op.responses ?? {};
+  const keys = Object.keys(responses);
+  const order: string[] = ["200", "201"];
+  for (const k of keys) if (/^2\d\d$/.test(k) && !order.includes(k)) order.push(k);
+  order.push("default");
+  for (const k of keys) if (!order.includes(k)) order.push(k);
+  for (const k of order) {
+    const r = responses[k];
+    if (!r) continue;
+    return { status: parseStatus(k), media: pickMedia(r) };
+  }
+  return { status: 200, media: null };
+}
+
+function parseStatus(key: string): number {
+  if (key === "default") return 200;
+  const n = parseInt(key, 10);
+  return Number.isFinite(n) ? n : 200;
+}
+
+function pickMedia(res: ResponseObject): MediaTypeObject | null {
+  const content = res.content;
+  if (!content) return null;
+  if (content["application/json"]) return content["application/json"];
+  for (const v of Object.values(content)) if (v) return v;
+  return null;
+}
+
+function synthesizeBody(media: MediaTypeObject | null, spec: OpenApiSpec): unknown {
+  if (!media) return null;
+  if ("example" in media && media.example !== undefined) return media.example;
+  if (media.examples) {
+    for (const ex of Object.values(media.examples)) {
+      if (ex && "value" in ex) return ex.value;
+    }
+  }
+  if (media.schema !== undefined) return generateFromSchema(media.schema, spec, new Set());
+  return null;
+}
+
+function generateFromSchema(schema: unknown, spec: OpenApiSpec, visited: Set<string>): unknown {
+  if (!schema || typeof schema !== "object") return null;
+  const s = schema as Record<string, unknown>;
+
+  if (typeof s.$ref === "string") {
+    if (visited.has(s.$ref)) return null;
+    const resolved = resolveRef(s.$ref, spec);
+    if (!resolved) return null;
+    const next = new Set(visited);
+    next.add(s.$ref);
+    return generateFromSchema(resolved, spec, next);
+  }
+
+  if ("example" in s && s.example !== undefined) return s.example;
+  if (Array.isArray(s.enum) && s.enum.length > 0) return s.enum[0];
+
+  if (Array.isArray(s.allOf)) {
+    const merged: Record<string, unknown> = {};
+    for (const branch of s.allOf) {
+      const value = generateFromSchema(branch, spec, visited);
+      if (value && typeof value === "object" && !Array.isArray(value)) Object.assign(merged, value);
+    }
+    return merged;
+  }
+
+  switch (s.type) {
+    case "array":
+      return [generateFromSchema(s.items, spec, visited)].filter((v) => v !== null);
+    case "object": {
+      const obj: Record<string, unknown> = {};
+      const props = s.properties as Record<string, unknown> | undefined;
+      if (props) {
+        for (const [k, v] of Object.entries(props)) obj[k] = generateFromSchema(v, spec, visited);
+      }
+      return obj;
+    }
+    case "string":
+      return s.format === "date-time" ? new Date(0).toISOString() : "";
+    case "integer":
+    case "number":
+      return 0;
+    case "boolean":
+      return false;
+    case "null":
+      return null;
+    default:
+      return null;
+  }
+}
+
+function resolveRef(ref: string, spec: OpenApiSpec): unknown {
+  if (!ref.startsWith("#/")) return null;
+  const parts = ref.slice(2).split("/");
+  let cur: unknown = spec;
+  for (const p of parts) {
+    if (!cur || typeof cur !== "object") return null;
+    cur = (cur as Record<string, unknown>)[p];
+  }
+  return cur;
+}