@lariocpt/flawless-react 0.0.0-stage → 0.3.0

package/src/docLine.ts

@@ -0,0 +1,122 @@
+// Turning a line of documentation into an argv.
+//
+// A documented example is not a bare argv: it carries a runner (`bunx`), env
+// prefixes (`FLAWLESS_E2E_ID=…`), shell quoting (`"src/**/*.tsx"`), and prose
+// after a `#`. Every one of those has to come off before parseArgs can have an
+// opinion, and the same peeling has to happen identically in three places —
+// `--check`, tests/docsLint.test.ts, and the website's lint script — or the
+// three disagree about what was even checked.
+//
+// Deliberately importless. `--check` and `--flags` must answer without pulling
+// in core.ts and the TypeScript compiler behind it (FR-031).
+
+/** Runner words a documented invocation may be prefixed with. */
+const RUNNERS = new Set(["bun", "bunx", "npx", "npm", "pnpm", "yarn", "sudo", "time", "env"]);
+
+/** How this CLI is spelled when a doc invokes it. */
+const SELF_ENTRIES = new Set(["src/cli.ts", "src/bin.ts"]);
+
+const ENV_PREFIX = /^[A-Za-z_][A-Za-z0-9_]*=/;
+
+/**
+ * Split a command line into argv, honouring quotes and dropping them.
+ *
+ * `--props='{"a":1}'` has to arrive at parseArgs as `--props={"a":1}`, quotes
+ * gone, or parsePropsJson rejects JSON that is perfectly valid in the doc.
+ *
+ * Throws on an unterminated quote: by the time a line reaches here the caller
+ * has already joined continuations, so an open quote is a real defect in the
+ * example rather than an artefact of how it was extracted.
+ */
+export function shellSplit(line: string): string[] {
+  const out: string[] = [];
+  let cur = "";
+  let started = false;
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i] as string;
+    if (quote !== null) {
+      if (c === quote) {
+        quote = null;
+        continue;
+      }
+      if (quote === '"' && c === "\\" && i + 1 < line.length) {
+        cur += line[++i] as string;
+        continue;
+      }
+      cur += c;
+      continue;
+    }
+    if (c === '"' || c === "'") {
+      quote = c;
+      started = true;
+      continue;
+    }
+    if (c === " " || c === "\t") {
+      if (started) {
+        out.push(cur);
+        cur = "";
+        started = false;
+      }
+      continue;
+    }
+    started = true;
+    cur += c;
+  }
+  if (quote !== null) throw new Error(`unterminated ${quote} quote`);
+  if (started) out.push(cur);
+  return out;
+}
+
+/**
+ * Drop an UNQUOTED trailing `#` comment.
+ *
+ * A `#` inside quotes is data — `--props '{"tag":"#a"}'` — so the scan has to
+ * track quoting rather than indexOf("#").
+ */
+export function stripTrailingComment(line: string): string {
+  let quote: '"' | "'" | null = null;
+  for (let i = 0; i < line.length; i++) {
+    const c = line[i] as string;
+    if (quote !== null) {
+      if (quote === '"' && c === "\\") i++;
+      else if (c === quote) quote = null;
+      continue;
+    }
+    if (c === '"' || c === "'") quote = c;
+    else if (c === "#") return line.slice(0, i);
+  }
+  return line;
+}
+
+/** Is this token the way a doc spells this CLI? */
+function isSelf(token: string): boolean {
+  const base = token.split("/").pop() ?? token;
+  if (base === "flawless-react") return true;
+  return SELF_ENTRIES.has(token) || SELF_ENTRIES.has(token.replace(/^\.\//, ""));
+}
+
+/**
+ * The argv of a documented flawless-react invocation, or null when the line
+ * invokes something else.
+ *
+ * Returning null rather than failing is the whole point: docs are full of
+ * `bun run test`, `playwright test --grep …` and crust pipes, and a lint that
+ * treated those as flawless invocations would report failures that are not
+ * about this tool. The cost is that a caller must assert it checked a MINIMUM
+ * number of lines — silence here is indistinguishable from a broken extractor.
+ */
+export function flawlessArgv(line: string): string[] | null {
+  const tokens = shellSplit(line);
+  let i = 0;
+  while (i < tokens.length && ENV_PREFIX.test(tokens[i] as string)) i++;
+  while (i < tokens.length && RUNNERS.has(tokens[i] as string)) {
+    i++;
+    // `bun run <script>` / `npm run <script>`: the script name is not this CLI
+    // under any spelling we can resolve, so let the isSelf check below reject.
+    if (tokens[i] === "run") i++;
+  }
+  const cmd = tokens[i];
+  if (cmd === undefined || !isSelf(cmd)) return null;
+  return tokens.slice(i + 1);
+}

package/src/emitPaths.ts

@@ -0,0 +1,51 @@
+import path from "node:path";
+
+/**
+ * A path for an emitted file to resolve against itself, rather than the
+ * absolute one the generator happened to be looking at.
+ *
+ * Generated files are committed. An absolute path in one names the machine that
+ * produced it, and the same repository lives under a different root on other
+ * machines — `/home/lario/Projects/…` on two of them, `/mnt/data/Projects/…` on
+ * a third. The consequences are worse than churn: `vitest.config.ts` aliased
+ * React to a directory that does not exist there, so the committed suite could
+ * not resolve React at all, and regenerating rewrote three files every time.
+ *
+ * The invariant is about the file's BYTES, not its runtime value. Emitted code
+ * still calls `path.resolve(<self>, rel)` and still ends up with an absolute
+ * path, because that is what Vite's aliases and Bun's onLoad filter need. Only
+ * the question "absolute from where" changes: from the emitted file, not from
+ * the machine.
+ *
+ * Always POSIX-separated, so a suite generated on Windows reads the same as one
+ * generated anywhere else.
+ */
+export function relativeToEmitted(fromDir: string, target: string): string {
+  const rel = path.relative(path.resolve(fromDir), path.resolve(target));
+  // "" means the target IS the directory; "." is what path.resolve wants back.
+  if (rel === "") return ".";
+  return rel.split(path.sep).join("/");
+}
+
+/**
+ * The out dir as the project root sees it — `flawless`, or whatever `--out` said.
+ *
+ * Emitted prose and emitted shell both name this path, and both used to spell it
+ * as the literal "flawless". Under `--out qa` that produced files telling the
+ * user to edit a directory the run never created, and an env.sh whose $PWD
+ * fallback resolved to nothing. Shared rather than redefined per task: two
+ * copies of a path rule drifting apart is its own class of bug here.
+ */
+export function outDirRel(outDir: string, projectRoot: string): string {
+  const rel = path.relative(path.resolve(projectRoot), path.resolve(outDir));
+  // "" means the out dir IS the project root. Left empty it composes into
+  // "/load/env.sh", which reads as an absolute path and points at the
+  // filesystem root — so "." here, and underOutDir drops it again.
+  if (rel === "") return ".";
+  return rel.split(path.sep).join("/");
+}
+
+/** Compose a path under the out dir, without a "./" nobody wants to read. */
+export function underOutDir(rel: string, sub: string): string {
+  return rel === "." || rel === "" ? sub : `${rel}/${sub}`;
+}

package/src/expo/detect.ts

@@ -0,0 +1,184 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import path from "node:path";
+import { detectReactCompiler } from "../reactCompiler.ts";
+import { type ExpoContext, UsageError } from "../types.ts";
+
+/**
+ * Read an Expo project off disk, the way `detectNextjs` reads a Next.js one.
+ *
+ * Deliberately the same shape: probe for the framework, throw a UsageError
+ * naming the fix when it is not there, and return a context object carrying the
+ * facts downstream needs — so a task branches once on `ctx.expo` instead of
+ * re-reading app.json.
+ *
+ * Everything here is filesystem-only. Nothing is inferred from a component, and
+ * nothing is defaulted where a wrong value would be worse than an absent one
+ * (see `sdkMajor`).
+ */
+export async function detectExpo(root: string): Promise<ExpoContext> {
+  const abs = path.resolve(root);
+  if (!existsSync(abs)) {
+    throw new UsageError(`expo: directory not found: ${abs}`);
+  }
+  if (!looksLikeExpo(abs)) {
+    throw new UsageError(
+      `expo: ${abs} does not look like an Expo project ` +
+        `(no app.json/app.config with an "expo" key, and no "expo" in package.json).`,
+    );
+  }
+
+  const pkg = readJson(path.join(abs, "package.json"));
+  const deps = {
+    ...((pkg?.dependencies as Record<string, string>) ?? {}),
+    ...((pkg?.devDependencies as Record<string, string>) ?? {}),
+  };
+
+  const routerRoot = detectRouterRoot(abs, deps);
+  // One probe for every mode (src/reactCompiler.ts), so the web and expo answers
+  // cannot drift and `perf-static` reads one fact. The boolean is all ExpoContext
+  // has ever carried; the evidence beside it reaches tasks on RunContext.
+  return {
+    root: abs,
+    routerRoot,
+    sdkMajor: majorOf(deps.expo, path.join(abs, "node_modules", "expo", "package.json")),
+    routerMajor: majorOf(
+      deps["expo-router"],
+      path.join(abs, "node_modules", "expo-router", "package.json"),
+    ),
+    reactCompiler: detectReactCompiler(abs).state === "on",
+    nativewind: detectNativewind(abs),
+    webPort: expoWebPort(pkg?.scripts as Record<string, string> | undefined),
+  };
+}
+
+function looksLikeExpo(dir: string): boolean {
+  for (const f of ["app.json", "app.config.js", "app.config.ts", "app.config.mjs"]) {
+    const p = path.join(dir, f);
+    if (!existsSync(p)) continue;
+    // A config file alone is not proof — app.json is a generic name. The `expo`
+    // key is, and for the .js/.ts forms (which we will not execute) the string
+    // is the closest honest signal.
+    if (f === "app.json") {
+      if (readJson(p)?.expo !== undefined) return true;
+      continue;
+    }
+    try {
+      if (/\bexpo\b/.test(readFileSync(p, "utf8"))) return true;
+    } catch {
+      /* unreadable config proves nothing either way */
+    }
+  }
+  const pkg = readJson(path.join(dir, "package.json"));
+  if (!pkg) return false;
+  const deps = {
+    ...((pkg.dependencies as Record<string, string>) ?? {}),
+    ...((pkg.devDependencies as Record<string, string>) ?? {}),
+  };
+  return deps.expo !== undefined;
+}
+
+/**
+ * The expo-router app directory, or undefined for a project that routes some
+ * other way (react-navigation by hand, a single-screen app).
+ *
+ * `app/` alone is not enough: the directory name is generic and a Next.js
+ * project has one too. expo-router has to actually be a dependency.
+ */
+function detectRouterRoot(dir: string, deps: Record<string, string>): string | undefined {
+  if (deps["expo-router"] === undefined) return undefined;
+  for (const rel of ["app", "src/app"]) {
+    const candidate = path.join(dir, rel);
+    if (isDir(candidate)) return candidate;
+  }
+  return undefined;
+}
+
+/** NativeWind is wired through babel — the only route by which `className` works. */
+function detectNativewind(dir: string): boolean {
+  return configMentions(
+    dir,
+    ["babel.config.js", "babel.config.cjs", "babel.config.mjs"],
+    ["nativewind"],
+  );
+}
+
+function configMentions(dir: string, files: string[], needles: string[]): boolean {
+  for (const f of files) {
+    const p = path.join(dir, f);
+    if (!existsSync(p)) continue;
+    try {
+      const text = readFileSync(p, "utf8");
+      if (needles.some((n) => text.includes(n))) return true;
+    } catch {
+      /* unreadable config proves nothing */
+    }
+  }
+  return false;
+}
+
+/**
+ * The port `expo start --web` serves on.
+ *
+ * A sibling of `devScriptPort`, not a parameterisation of it: the script key
+ * differs (`web`, then `start` — never `dev`) AND the default differs (Metro's
+ * 8081, not 3000). One function with two key lists and two defaults would encode
+ * a coincidence as a rule, which is the mistake `NEXT_SCRIPT`'s own comment
+ * warns about. Only the flag regex is genuinely shared, and it is one line.
+ */
+export function expoWebPort(scripts: Record<string, string> | undefined): number {
+  for (const key of ["web", "start"]) {
+    const script = scripts?.[key];
+    if (script === undefined) continue;
+    const m = /(?:-p|--port)[=\s]*(\d+)/.exec(script);
+    if (m?.[1]) {
+      const port = Number(m[1]);
+      if (Number.isFinite(port)) return port;
+    }
+  }
+  return 8081;
+}
+
+/**
+ * The major version of a dependency, from the project's declared range and
+ * failing that from what is actually installed.
+ *
+ * Installed truth beats a declared range on purpose: `~54.0.33` and an installed
+ * 54.0.34 agree, but `latest`, `*` and a git or file: specifier name no version
+ * at all, and node_modules does. Returns undefined when neither answers —
+ * because jest-expo's major has to MATCH the SDK's, and a guessed 54 against an
+ * SDK 53 project fails deep inside expo-modules-core with a message that names
+ * nothing. The caller says "unknown"; it never substitutes a number.
+ */
+export function majorOf(range: string | undefined, installedPkgJson: string): number | undefined {
+  const fromRange = range === undefined ? undefined : majorOfRange(range);
+  if (fromRange !== undefined) return fromRange;
+  const installed = readJson(installedPkgJson)?.version;
+  return typeof installed === "string" ? majorOfRange(installed) : undefined;
+}
+
+function majorOfRange(range: string): number | undefined {
+  // The leading digits of the first version-looking token: covers "54.0.33",
+  // "~54.0.33", "^54", ">=54.0.0 <55", and "54.x". Not "latest", "*", "next",
+  // a git url or a file: path — all of which have no major to report.
+  const m = /(?:^|[^\w.])(\d+)\.(?:\d+|x)/.exec(range) ?? /^\s*[~^>=<\s]*(\d+)\s*$/.exec(range);
+  if (!m?.[1]) return undefined;
+  const n = Number(m[1]);
+  return Number.isFinite(n) ? n : undefined;
+}
+
+function readJson(p: string): Record<string, unknown> | undefined {
+  if (!existsSync(p)) return undefined;
+  try {
+    return JSON.parse(readFileSync(p, "utf8")) as Record<string, unknown>;
+  } catch {
+    return undefined;
+  }
+}
+
+function isDir(p: string): boolean {
+  try {
+    return statSync(p).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/src/expo/refusal.ts

@@ -0,0 +1,62 @@
+import type { TaskId, TaskResult } from "../types.ts";
+
+/**
+ * A task that does not run under `--expo`, refusing by name with its reason.
+ *
+ * This carried the mode through B-16 one wave at a time without the docs lying
+ * about it, and now that B-16 is complete it carries the one task that will
+ * never run: `perf-harness`, measured-and-declined (a browser host cannot mount
+ * a route screen, which is nearly every component in a real Expo app). The
+ * `reason` is free text — a wave string while a wave was pending, a decline
+ * record now — so the message never claims "not yet" over a task that is
+ * actually declined for good. The alternative shapes were both worse:
+ *
+ *   - Rejecting `--expo` at parse time until every task is ported would mean the
+ *     flag lands in one enormous PR, which is how a seam stops being reviewable.
+ *   - Silently emitting the DOM artefacts for a React Native project would
+ *     produce a suite that runs, passes, and tests nothing — the vacuous green
+ *     this project scores itself on removing.
+ *
+ * A refusal is a TaskResult rather than a thrown error on purpose: it lands in
+ * `results[]`, in the `--ci` blob and in REPORT.md, where a machine can read it.
+ * A thrown error would exit 1 with the reason only on stderr, which is where
+ * B-13 already found `--ci` losing things it needed to say.
+ *
+ * Same shape as `e2eRoutes.ts`'s long-standing "not a Next.js run" branch — the
+ * precedent, not a new convention.
+ */
+/**
+ * The tasks that actually run under `--expo`, as the escape hatch names them.
+ *
+ * A literal `perf-static,react-rules` was correct when five tasks refused, and
+ * wrong from wave 3 onward — `unit-browser` is the whole point of the mode and
+ * the refusal was telling every reader to leave it out. Kept beside the refusal
+ * so the two cannot disagree, and pinned by a test that runs each of these under
+ * `--expo` and asserts it does NOT refuse.
+ */
+export const EXPO_IMPLEMENTED: readonly TaskId[] = [
+  "unit-browser",
+  "perf-static",
+  "a11y",
+  "react-rules",
+  "e2e",
+  "load",
+];
+
+export function expoNotImplemented(id: TaskId, reason: string): TaskResult {
+  return {
+    id,
+    ok: false,
+    outputs: [],
+    findings: [],
+    summary: `${id}: does not run under --expo (${reason}) — run --tasks ${EXPO_IMPLEMENTED.join(",")}`,
+    // The escape is spelled as the flag the reader would actually type, not as
+    // prose naming ids. Told only that something is unsupported, they have to go
+    // and read the source to find out what to select instead.
+    error:
+      `${id} does not run under --expo — ${reason}. ` +
+      `Under --expo, run \`--tasks ${EXPO_IMPLEMENTED.join(",")}\`; every other task ` +
+      `refuses rather than emit DOM artefacts for a React Native project. ` +
+      `See the Expo section of README.md.`,
+  };
+}

package/src/expo/routes.ts

@@ -0,0 +1,145 @@
+import path from "node:path";
+
+/**
+ * Map an expo-router file to its route.
+ *
+ * Close to the Next.js app router, and deliberately a SIBLING of pageFileToRoute
+ * rather than a parameterisation of it, because the central rule is different:
+ * in expo-router **the leaf file IS the route** (`app/login.tsx` -> `/login`),
+ * where Next needs a `page.tsx` inside a directory. Sharing one function would
+ * mean a `kind` parameter that changes what the last path segment means, which
+ * is the sort of coincidence-as-rule NEXT_SCRIPT's own comment warns about.
+ */
+export interface ExpoRoute {
+  /** URL path with dynamic segments kept in brackets: /items/[id]. */
+  urlPath: string;
+  /** Dynamic segment names in order: ["id"]. */
+  params: string[];
+  /** Safe file stem for a spec: items-id. */
+  specStem: string;
+  /**
+   * The `_layout` chain this route mounts inside, outermost first, as paths
+   * relative to the router root without extension: ["_layout", "(tabs)/_layout"].
+   *
+   * renderRouter needs them: a screen under `(tabs)` renders inside that Tabs
+   * navigator, and mounting it without its layouts is not the screen the app
+   * ships.
+   */
+  layouts: string[];
+}
+
+const ROUTE_EXT = /\.(tsx|jsx|ts|js)$/;
+
+/**
+ * Files expo-router does not route.
+ *
+ * `_layout` is a layout. The `+` prefix is RESERVED by expo-router for its own
+ * files — `+not-found`, `+html`, `+native-intent`, `+api` — so anything starting
+ * with it is excluded by rule rather than by listing the four, which would rot
+ * the moment expo-router adds a fifth.
+ */
+function isRoutable(base: string): boolean {
+  if (base.startsWith("+")) return false;
+  return base !== "_layout";
+}
+
+export function expoFileToRoute(file: string, routerRoot: string): ExpoRoute | undefined {
+  const abs = path.resolve(file);
+  const rel = path.relative(path.resolve(routerRoot), abs);
+  if (rel.startsWith("..") || path.isAbsolute(rel)) return undefined;
+
+  const parts = rel.split(path.sep);
+  const last = parts.pop();
+  if (!last || !ROUTE_EXT.test(last)) return undefined;
+  const base = last.replace(ROUTE_EXT, "");
+  if (!isRoutable(base)) return undefined;
+
+  const layouts = layoutChain(parts);
+
+  // The leaf contributes a segment unless it is `index`, which IS its directory.
+  const leafSegments = base === "index" ? [] : [base];
+  const segments: string[] = [];
+  const params: string[] = [];
+
+  for (const seg of [...parts, ...leafSegments]) {
+    // Route groups vanish from the URL — including as the leaf, so
+    // `app/(tabs)/index.tsx` is "/", not "/(tabs)".
+    if (/^\(.*\)$/.test(seg)) continue;
+    const rest = /^\[\.\.\.(.+)\]$/.exec(seg);
+    if (rest?.[1]) {
+      params.push(rest[1]);
+      segments.push(`[...${rest[1]}]`);
+      continue;
+    }
+    const dynamic = /^\[(.+)\]$/.exec(seg);
+    if (dynamic?.[1]) {
+      params.push(dynamic[1]);
+      segments.push(`[${dynamic[1]}]`);
+      continue;
+    }
+    segments.push(seg);
+  }
+
+  const urlPath = segments.length === 0 ? "/" : `/${segments.join("/")}`;
+  return { urlPath, params, specStem: stemFor(segments), layouts };
+}
+
+/**
+ * The `_layout` chain enclosing a route, outermost first.
+ *
+ * Derived from the path alone — every ancestor directory MAY have a layout, and
+ * whether it does is a filesystem question the caller answers. Returned as
+ * extensionless module ids because that is what renderRouter's in-memory context
+ * is keyed by.
+ */
+function layoutChain(dirs: string[]): string[] {
+  const out = ["_layout"];
+  const acc: string[] = [];
+  for (const d of dirs) {
+    acc.push(d);
+    out.push(`${acc.join("/")}/_layout`);
+  }
+  return out;
+}
+
+/**
+ * A spec stem. Collisions are REAL here in a way they are not on the Next side:
+ * `app/(a)/x.tsx` and `app/(b)/x.tsx` are different routes that both stem to
+ * "x", because groups vanish. The caller resolves that with allocateStems below
+ * rather than hoping.
+ */
+function stemFor(segments: string[]): string {
+  if (segments.length === 0) return "index";
+  return segments
+    .map((s) => s.replace(/\[\.\.\.(.+)\]/, "$1").replace(/\[(.+)\]/, "$1"))
+    .join("-")
+    .replace(/[^a-zA-Z0-9-]+/g, "-")
+    .replace(/-+/g, "-")
+    .replace(/^-|-$/g, "");
+}
+
+/**
+ * Unique stems over the FULL route list.
+ *
+ * The same invariant allocateSpecNames documents: allocate over everything, then
+ * filter. Doing it the other way makes two callers disagree about a name, and
+ * here it would silently overwrite one route's spec with another's.
+ */
+export function allocateRouteStems(routes: ExpoRoute[]): Map<ExpoRoute, string> {
+  const taken = new Set<string>();
+  const out = new Map<ExpoRoute, string>();
+  for (const r of routes) {
+    let stem = r.specStem;
+    let i = 2;
+    while (taken.has(stem)) stem = `${r.specStem}-${i++}`;
+    taken.add(stem);
+    out.set(r, stem);
+  }
+  return out;
+}
+
+/** The module id renderRouter's in-memory context keys a file by. */
+export function routeModuleId(file: string, routerRoot: string): string {
+  const rel = path.relative(path.resolve(routerRoot), path.resolve(file));
+  return rel.split(path.sep).join("/").replace(ROUTE_EXT, "");
+}

package/src/index.ts

@@ -0,0 +1,95 @@
+/**
+ * Programmatic API. CLI-equivalent entry point:
+ *
+ *   import { runFlawless } from "flawless-react";
+ *   const { results, trees, outDir } = await runFlawless({
+ *     entry: "src/components/Widget.tsx",
+ *     nextjs: ".",
+ *     tasks: ["unit-browser", "perf-static"],
+ *   });
+ *
+ * Never calls process.exit; throws UsageError for bad input.
+ */
+import { type CoreResult, runCore } from "./core.ts";
+import type { PropsShape, RootMode, TaskId } from "./types.ts";
+
+export interface RunFlawlessOptions {
+  /** Entry .tsx path or glob. Optional in Next.js mode (components glob auto-detected). */
+  entry?: string;
+  tasks?: TaskId[];
+  out?: string;
+  /** Next.js project root — enables Next.js mode ("." for cwd). */
+  nextjs?: string;
+  provider?: string;
+  apiSpec?: string;
+  swaggerUrl?: string;
+  colocate?: boolean;
+  /** "exported" emits a tree per exported component in each entry file. */
+  roots?: RootMode;
+  /** Extra globs to skip, appended to the defaults. */
+  exclude?: readonly string[];
+  useDefaultExcludes?: boolean;
+  variants?: number;
+  depth?: number;
+  includeChildren?: boolean;
+  force?: boolean;
+  report?: boolean;
+  propsOverride?: PropsShape;
+  inlineSummary?: boolean;
+  runTests?: boolean;
+  /** Progress narration on stdout (default false for the programmatic API). */
+  log?: boolean;
+  /**
+   * Suppress diagnostics on stderr (default false — they always speak, even
+   * when `log` is off). An embedder that swallows "could not parse your
+   * OpenAPI spec" has the same bug --ci had; opt out only if you route the
+   * warnings somewhere yourself.
+   */
+  quiet?: boolean;
+}
+
+export async function runFlawless(options: RunFlawlessOptions): Promise<CoreResult> {
+  return runCore({
+    pattern: options.entry as string,
+    outDir: options.out,
+    taskIds: options.tasks,
+    depth: options.depth,
+    variants: options.variants,
+    includeChildren: options.includeChildren,
+    force: options.force,
+    report: options.report,
+    propsOverride: options.propsOverride,
+    provider: options.provider,
+    apiSpec: options.apiSpec,
+    inlineSummary: options.inlineSummary,
+    nextjs: options.nextjs,
+    swaggerUrl: options.swaggerUrl,
+    colocate: options.colocate,
+    roots: options.roots,
+    exclude: options.exclude,
+    useDefaultExcludes: options.useDefaultExcludes,
+    runTests: options.runTests,
+    log: options.log ?? false,
+    quiet: options.quiet,
+  });
+}
+
+export { analyse, analyseFile, ModuleResolver, parseFile } from "./analyse/index.ts";
+export type { CoreOptions, CoreResult } from "./core.ts";
+export { DEFAULT_EXCLUDES, runCore, UsageError } from "./core.ts";
+export { detectNextjs } from "./nextjs/detect.ts";
+export { scaffold } from "./scaffold/index.ts";
+export { scaffoldUnitBrowser } from "./scaffold-tests/index.ts";
+export { ALL_TASK_IDS, findTask, TASKS } from "./tasks/index.ts";
+export { analyseTree } from "./tasks/staticPerfAnalysis.ts";
+export type {
+  ComponentInfo,
+  ComponentTree,
+  Finding,
+  HookDetail,
+  PropUsage,
+  StateInfo,
+  TaskId,
+  TaskResult,
+} from "./types.ts";
+export { VERSION } from "./version.ts";