@mittwald/flow-codemods 1.1.0-next.10

package/dist/cli/upgrade.js

@@ -0,0 +1,217 @@
+import { writeFileSync } from "node:fs";
+import { isAbsolute, relative } from "node:path";
+import { gt } from "semver";
+import { allEntries } from "../catalog/entries.js";
+import { selectEntries } from "../catalog/select.js";
+import { flowPackages } from "../flowPackages.generated.js";
+import { hasUncommittedChanges } from "../git.js";
+import { detectPackageManagerIn, runInstall, } from "../install.js";
+import { applyTarget, isWritable } from "../manifest.js";
+import { fetchVersions } from "../resolve/registry.js";
+import { readInstalledVersion, resolveRange } from "../resolve/range.js";
+import { runCodemod } from "../run/jscodeshift.js";
+import { resolveSourcePath } from "./codemod.js";
+import { renderList } from "./list.js";
+export const defaultUpgradeDeps = (cwd) => ({
+    cwd,
+    fetchVersions,
+    install: runInstall,
+    runCodemod,
+    choose: async (entries) => entries,
+    isDirty: hasUncommittedChanges,
+    readInstalledVersion,
+    log: (message) => process.stdout.write(`${message}\n`),
+});
+/**
+ * Whether `path` lies outside `cwd`.
+ *
+ * `--path` can point anywhere, including outside the repository the dirty-tree
+ * guard checks. `path` is always resolved (see `resolveSourcePath`), so this is
+ * a plain prefix test via `relative` rather than a string comparison that a
+ * trailing slash or `..` segment could fool.
+ */
+const isOutside = (path, cwd) => {
+    const rel = relative(cwd, path);
+    return rel !== "" && (rel.startsWith("..") || isAbsolute(rel));
+};
+/**
+ * The indentation the manifest already uses, read from its first indented line.
+ *
+ * Reusing it (instead of always emitting 2 spaces) keeps the rewrite to the
+ * dependency lines a consumer actually cares about — a tabs- or 4-space project
+ * otherwise gets its whole `package.json` reformatted inside the upgrade diff.
+ */
+const detectIndent = (raw) => {
+    const match = /\n([ \t]+)\S/.exec(raw);
+    return match?.[1] ?? "  ";
+};
+/**
+ * Bump every Flow dependency, install, then run the codemods the resolved range
+ * calls for — and end by naming what no codemod covers.
+ *
+ * The order is not cosmetic: the codemods run against the installed target, so
+ * `tsc` can be green when the command returns. `--dry` skips both the manifest
+ * write and the install, so the codemods it still runs act against whatever is
+ * currently installed rather than the target — their output is indicative, not
+ * exact.
+ *
+ * Selection has no lower bound at all (see `selectEntries`) — every entry with
+ * `since <= target` is in, codemod or manual — so a project already on `target`
+ * still gets a full pass: it skips only the write and the install, which
+ * genuinely have nothing to do.
+ */
+export const runUpgrade = async (parsed, deps) => {
+    const { cwd, log } = deps;
+    const dry = parsed.dry === true;
+    // Resolved before the dirty-tree guard below: an explicit --path can point
+    // outside the repository the guard would otherwise check, and codemods
+    // rewrite files in place there just the same.
+    const path = resolveSourcePath(parsed.path, cwd);
+    const outsideRepo = isOutside(path, cwd);
+    if (!parsed.allowDirty &&
+        (deps.isDirty(cwd) || (outsideRepo && deps.isDirty(path)))) {
+        log("The working tree has uncommitted changes. Codemods rewrite files in place, so commit or stash first — or pass --allow-dirty.");
+        return 1;
+    }
+    const { revision } = parsed;
+    if (revision === undefined) {
+        // args.ts always defaults this for the "upgrade" command — this only
+        // guards a ParsedCommand built by hand without it, so it is not a second
+        // source of truth for the default.
+        log("No revision given.");
+        return 1;
+    }
+    const range = await resolveRange(revision, deps);
+    if (!range.ok) {
+        log(range.reason);
+        return 1;
+    }
+    const { manifestPath, manifestRaw, manifest, dependencies, current, target } = range;
+    // A stale dist-tag or an exact version at or below `current` resolves
+    // without complaint — `resolveRange` deliberately does not judge that
+    // (`list` treats the same fact as a legitimate answer). There is nothing to
+    // bump or install in that case, but that does not mean there is nothing to
+    // run: selection has no lower bound (see `selectEntries`). A consumer can
+    // already be sitting on `target` having never run this tool once, which is
+    // the exact gap this command exists to close, so the migration pass below
+    // still runs; only the bump and the install are skipped.
+    // One reporter for both branches: a peer range is reported, never rewritten
+    // (see `writableFields` in manifest.ts), and `--dry` must say the same thing
+    // the real run does.
+    const reportDependencies = () => {
+        for (const dependency of dependencies) {
+            log(isWritable(dependency)
+                ? `  ${dependency.name} → ${target}`
+                : `  ${dependency.name} ${dependency.range} — left as it is, ${dependency.field} states what your package supports, not what it installs`);
+        }
+    };
+    const bump = gt(target, current);
+    if (!bump) {
+        // Nothing to write or install — fall through to the codemod pass below.
+        log(`Already on ${current}; "${revision}" resolves to ${target}. No dependency bump needed — checking for codemods to catch up on, since nothing records whether this project already ran them.`);
+    }
+    else if (dry) {
+        log(`Upgrading Flow from ${current} to ${target} (--dry)`);
+        log(`--dry: would write the following to ${manifestPath}:`);
+        reportDependencies();
+        log("--dry: skipping the install.");
+    }
+    else {
+        log(`Upgrading Flow from ${current} to ${target}`);
+        const indent = detectIndent(manifestRaw);
+        writeFileSync(manifestPath, `${JSON.stringify(applyTarget(manifest, target, flowPackages), null, indent)}\n`, "utf8");
+        reportDependencies();
+        const manager = detectPackageManagerIn(cwd);
+        log(`Installing with ${manager}`);
+        try {
+            deps.install(manager, cwd);
+        }
+        catch (error) {
+            log(`The dependency bump was written but the install failed, so package.json is on\n${target} while node_modules still holds ${current}.\n\nEither re-run this command once the install works, or undo the bump with\n  git checkout package.json\n\n${error instanceof Error ? error.message : error}`);
+            return 1;
+        }
+    }
+    const selected = selectEntries(allEntries, target);
+    const automatic = selected.filter((entry) => entry.action === "codemod");
+    const byHand = selected.filter((entry) => entry.action !== "codemod");
+    const chosen = await deps.choose(automatic);
+    // Only meaningful once a bump actually moves the installed version away
+    // from `target` — when there is no bump, the codemods below run against
+    // exactly `target` already, so there is no "not exact" caveat to raise.
+    if (dry && bump && chosen.length > 0) {
+        log(`\n--dry: running the codemods against the currently installed version, not ${target} — their output is indicative, not exact.`);
+    }
+    let hadFailure = false;
+    const incomplete = [];
+    let ranCount = 0;
+    let changedCount = 0;
+    for (const entry of chosen) {
+        ranCount += 1;
+        let result;
+        try {
+            result = await deps.runCodemod({
+                id: entry.id,
+                path,
+                dry: parsed.dry,
+                print: parsed.print,
+            });
+        }
+        catch (error) {
+            hadFailure = true;
+            incomplete.push(entry.id);
+            log(`  ${entry.id}: failed to run — ${error instanceof Error ? error.message : error}`);
+            continue;
+        }
+        if (result.changed > 0) {
+            changedCount += 1;
+        }
+        // Same three-way distinction as the single-codemod command: "0 changed" on
+        // its own would read as success where nothing was looked at, or where the
+        // transform declined everything it saw.
+        if (result.errors > 0) {
+            hadFailure = true;
+            log(`  ${entry.id}: ${result.errors} file(s) failed to transform`);
+        }
+        else if (result.processedNothing) {
+            hadFailure = true;
+            log(`  ${entry.id}: no files under ${path} were processed`);
+        }
+        else if (result.changed === 0 && result.skipped > 0) {
+            hadFailure = true;
+            log(`  ${entry.id}: declined all ${result.skipped} file(s) it looked at`);
+        }
+        else {
+            log(`  ${entry.id}: ${result.changed} file(s) changed`);
+        }
+    }
+    // Selection has no lower bound (see `selectEntries`), so this loop can run
+    // every codemod in the catalogue on a project that never crossed a version
+    // at all — "N run, 0 changed" is the confirmation that there was nothing to
+    // catch up on, not a list of new work.
+    if (ranCount > 0) {
+        log(`\n${ranCount} codemod${ranCount === 1 ? "" : "s"} run, ${changedCount} changed something.`);
+    }
+    if (byHand.length > 0) {
+        log(`\n${byHand.length} migration(s) in this range have no codemod — apply them by hand:\n`);
+        // `frame: false` — this already printed the heading above and, further
+        // down, its own aggregate ("N codemods run, N changed something");
+        // renderList's own frame (the range/legend on top, the counts at the
+        // bottom) would just repeat both for the same list. `range` is still
+        // passed so each entry gets its catch-up mark — a manual entry that
+        // shipped at or before `current` may already be done, and the mark is
+        // the only thing left that says so now that hiding it is gone.
+        log(renderList({
+            entries: byHand,
+            range: { from: current, to: target },
+            json: false,
+            frame: false,
+        }));
+    }
+    else {
+        log("\nNo migration in this range required a change by hand.");
+    }
+    if (incomplete.length > 0) {
+        log(`\n${incomplete.length} codemod(s) did not complete: ${incomplete.join(", ")}`);
+    }
+    return hadFailure ? 1 : 0;
+};

package/dist/cli/verify.d.ts

@@ -0,0 +1,77 @@
+import { type CatalogEntry } from "../catalog/entries.js";
+import { loadVerifier } from "../checks/load.js";
+import type { VerifyResult } from "../checks/types.js";
+export interface VerifyEntryResult {
+    entry: CatalogEntry;
+    result: VerifyResult;
+}
+export interface RunVerifyDeps {
+    /** Which entries to try. Defaults to the whole catalogue. */
+    entries?: CatalogEntry[];
+    /** Injectable for tests — defaults to the real module loader. */
+    load?: typeof loadVerifier;
+}
+/**
+ * Runs every available verifier over `path`.
+ *
+ * Only a fraction of the catalogue has a verifier module so far (see
+ * `checks/load.ts`); an id with none is skipped, not reported as a failure —
+ * the remaining verifiers are follow-up work, not something this run got
+ * wrong.
+ */
+export declare const runVerify: (path: string, { entries, load }?: RunVerifyDeps) => Promise<VerifyEntryResult[]>;
+/**
+ * Three counts, not one pass/fail verdict — conflating them is exactly the "23
+ * entries still need a person" problem this replaces: with every verifier in
+ * place, almost all of them would carry at least the typecheck reminder, so
+ * counting "has a hint" swamps the entries that actually need a person's
+ * judgement with the ones that only need the same routine `tsc --noEmit` run.
+ *
+ * - `failed` — `ok: false`: this run found something concretely wrong.
+ * - `needsReview` — `ok: true` but `hints` is non-empty: nothing this module
+ *   could decide is wrong, but a person still has to judge something no
+ *   compiler check can catch.
+ * - `verified` — `ok: true` and `hints` is empty: nothing left for a person to
+ *   judge here (the typecheck below may still apply). Deliberately not
+ *   "done"/"complete": see `checks/types.ts`'s doc comment on `VerifyResult`
+ *   for why `ok: true` never means the migration is finished.
+ *
+ * `typecheckCount` is tallied separately again: it is not a judgement call like
+ * `needsReview`, and `tsc --noEmit` is one command a person runs once for the
+ * whole project, not once per entry — so it is reported as a single closing
+ * line, not folded into any of the three per-entry buckets.
+ */
+export declare const summarize: (results: VerifyEntryResult[]) => {
+    failed: number;
+    needsReview: number;
+    verified: number;
+    typecheckCount: number;
+};
+/**
+ * Renders `runVerify`'s result as text — the presentation half kept separate
+ * from the async file-reading half, the same split `renderList` uses.
+ *
+ * Prints only what needs attention. An entry that is `ok: true` with no hints
+ * has nothing left for a person to judge (the closing typecheck line still
+ * covers it if it relies on one) — it swells the count in the header and
+ * nothing else, the same way `verified` is counted but never itself printed.
+ * That is the fix for the four problems the maintainer called out: a passing
+ * entry whose only hint was the typecheck reminder no longer earns a block at
+ * all, the reminder itself moves out of the loop to one line at the end,
+ * hints stop repeating their own label, and findings show a path relative to
+ * `path` instead of the absolute one the header already established.
+ */
+export declare const renderVerify: (results: VerifyEntryResult[], path: string, { color, width }?: {
+    color?: boolean;
+    width?: number;
+}) => string;
+/**
+ * Whether a `verify` run should exit non-zero: exactly when at least one
+ * verifier decided `ok: false`. A hint alone — even every entry carrying one —
+ * is the normal "a person still has to look" state, not a failure, so it must
+ * never flip this. Kept as its own pure function (over `results`, not
+ * `process.exitCode` directly) so a test can drive it with injected fakes
+ * instead of spawning the CLI.
+ */
+export declare const verifyExitCode: (results: VerifyEntryResult[]) => number;
+//# sourceMappingURL=verify.d.ts.map

package/dist/cli/verify.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../src/cli/verify.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAGvD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,iEAAiE;IACjE,IAAI,CAAC,EAAE,OAAO,YAAY,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,SACd,MAAM,sBACmC,aAAa,KAC3D,OAAO,CAAC,iBAAiB,EAAE,CAa7B,CAAC;AA2DF;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,eAAO,MAAM,SAAS,YACX,iBAAiB,EAAE,KAC3B;IACD,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,cAAc,EAAE,MAAM,CAAC;CAqBxB,CAAC;AAEF;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,YAAY,YACd,iBAAiB,EAAE,QACtB,MAAM,qBACmB;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KACjE,MA8BF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,cAAc,YAAa,iBAAiB,EAAE,KAAG,MACZ,CAAC"}

package/dist/cli/verify.js

@@ -0,0 +1,148 @@
+import { relative } from "node:path";
+import colors from "picocolors";
+import { allEntries } from "../catalog/entries.js";
+import { createCheckContext } from "../checks/context.js";
+import { loadVerifier } from "../checks/load.js";
+import { indent, painter, wrap } from "./list.js";
+/**
+ * Runs every available verifier over `path`.
+ *
+ * Only a fraction of the catalogue has a verifier module so far (see
+ * `checks/load.ts`); an id with none is skipped, not reported as a failure —
+ * the remaining verifiers are follow-up work, not something this run got
+ * wrong.
+ */
+export const runVerify = async (path, { entries = allEntries, load = loadVerifier } = {}) => {
+    const context = createCheckContext(path);
+    const results = [];
+    for (const entry of entries) {
+        const verifier = await load(entry.id);
+        if (verifier === undefined) {
+            continue;
+        }
+        results.push({ entry, result: await verifier.verify(context) });
+    }
+    return results;
+};
+/** One `path:line  text` row, path shown relative to the search root. */
+const findingLine = (finding, width, paint, root) => {
+    const location = paint.dim(`${relative(root, finding.file)}:${finding.line}`);
+    const body = wrap(finding.text, Math.max(width - indent.length, 20));
+    return body.map((line, index) => index === 0 ? `${indent}${location}  ${line}` : `${indent}  ${line}`);
+};
+/**
+ * One hint, wrapped and indented under its migration. No repeated label — a
+ * hint that wraps to several lines said "hint" once per line before this,
+ * which is the label, not the content, taking up the repetition.
+ */
+const hintLine = (hint, width) => wrap(hint, Math.max(width - indent.length, 20)).map((line) => `${indent}${line}`);
+/**
+ * Renders one migration's block: `!` for `ok: false`, `?` for `ok: true` with
+ * a hint — the only two states this function is ever called for, see
+ * `renderVerify`'s filter. Findings first, then hints; the `typecheckHint`
+ * never appears here — it is one global action, folded into the closing line
+ * instead of repeated under every entry that relies on it.
+ */
+const renderEntry = ({ entry, result }, width, color, root) => {
+    const paint = painter(color);
+    const mark = result.ok
+        ? color
+            ? colors.yellow("?")
+            : "?"
+        : color
+            ? colors.red("!")
+            : "!";
+    const lines = [
+        `${mark} ${paint.bold(entry.id)}`,
+        ...result.findings.flatMap((finding) => findingLine(finding, width, paint, root)),
+        ...result.hints.flatMap((hint) => hintLine(hint, width)),
+    ];
+    return lines.join("\n");
+};
+/**
+ * Three counts, not one pass/fail verdict — conflating them is exactly the "23
+ * entries still need a person" problem this replaces: with every verifier in
+ * place, almost all of them would carry at least the typecheck reminder, so
+ * counting "has a hint" swamps the entries that actually need a person's
+ * judgement with the ones that only need the same routine `tsc --noEmit` run.
+ *
+ * - `failed` — `ok: false`: this run found something concretely wrong.
+ * - `needsReview` — `ok: true` but `hints` is non-empty: nothing this module
+ *   could decide is wrong, but a person still has to judge something no
+ *   compiler check can catch.
+ * - `verified` — `ok: true` and `hints` is empty: nothing left for a person to
+ *   judge here (the typecheck below may still apply). Deliberately not
+ *   "done"/"complete": see `checks/types.ts`'s doc comment on `VerifyResult`
+ *   for why `ok: true` never means the migration is finished.
+ *
+ * `typecheckCount` is tallied separately again: it is not a judgement call like
+ * `needsReview`, and `tsc --noEmit` is one command a person runs once for the
+ * whole project, not once per entry — so it is reported as a single closing
+ * line, not folded into any of the three per-entry buckets.
+ */
+export const summarize = (results) => {
+    let failed = 0;
+    let needsReview = 0;
+    let verified = 0;
+    let typecheckCount = 0;
+    for (const { result } of results) {
+        if (!result.ok) {
+            failed++;
+        }
+        else if (result.hints.length > 0) {
+            needsReview++;
+        }
+        else {
+            verified++;
+        }
+        if (result.typecheckHint !== undefined) {
+            typecheckCount++;
+        }
+    }
+    return { failed, needsReview, verified, typecheckCount };
+};
+/**
+ * Renders `runVerify`'s result as text — the presentation half kept separate
+ * from the async file-reading half, the same split `renderList` uses.
+ *
+ * Prints only what needs attention. An entry that is `ok: true` with no hints
+ * has nothing left for a person to judge (the closing typecheck line still
+ * covers it if it relies on one) — it swells the count in the header and
+ * nothing else, the same way `verified` is counted but never itself printed.
+ * That is the fix for the four problems the maintainer called out: a passing
+ * entry whose only hint was the typecheck reminder no longer earns a block at
+ * all, the reminder itself moves out of the loop to one line at the end,
+ * hints stop repeating their own label, and findings show a path relative to
+ * `path` instead of the absolute one the header already established.
+ */
+export const renderVerify = (results, path, { color = false, width = 80 } = {}) => {
+    const paint = painter(color);
+    if (results.length === 0) {
+        return `No verifiers are available yet for anything under ${path}.\n`;
+    }
+    const { failed, needsReview, typecheckCount } = summarize(results);
+    const header = [
+        `${paint.bold(String(results.length))} checked`,
+        `${paint.bold(String(failed))} failed`,
+        `${paint.bold(String(needsReview))} needs review`,
+    ].join(" · ");
+    const needsAttention = results.filter(({ result }) => !result.ok || result.hints.length > 0);
+    const body = needsAttention.length === 0
+        ? "Nothing needs attention."
+        : needsAttention
+            .map((entryResult) => renderEntry(entryResult, width, color, path))
+            .join("\n\n");
+    const typecheckLine = typecheckCount === 0
+        ? ""
+        : `\n\nThen run \`tsc --noEmit\` once — ${typecheckCount} of these rely on it.`;
+    return `${header}\n\n${body}${typecheckLine}\n`;
+};
+/**
+ * Whether a `verify` run should exit non-zero: exactly when at least one
+ * verifier decided `ok: false`. A hint alone — even every entry carrying one —
+ * is the normal "a person still has to look" state, not a failure, so it must
+ * never flip this. Kept as its own pure function (over `results`, not
+ * `process.exitCode` directly) so a test can drive it with injected fakes
+ * instead of spawning the CLI.
+ */
+export const verifyExitCode = (results) => results.some(({ result }) => !result.ok) ? 1 : 0;

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.d.ts","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":""}

package/dist/cli.js

@@ -0,0 +1,117 @@
+#!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { parseArguments } from "./cli/args.js";
+import { createChoose } from "./cli/choose.js";
+import { runSingleCodemod } from "./cli/codemod.js";
+import { defaultListDeps, runList } from "./cli/list.js";
+import { defaultUpgradeDeps, runUpgrade } from "./cli/upgrade.js";
+const usage = `flow-codemods — migrate a codebase across Flow versions
+
+Usage:
+  flow-codemods upgrade [revision]   Bump every Flow dependency, install, run codemods
+  flow-codemods <id> [path]          Run a single codemod
+  flow-codemods list [revision]      Show the migrations for the whole catalogue, or
+                                      for the range a revision would touch
+
+Revision: patch | minor | major | a dist-tag (latest, next) | an exact version.
+"upgrade" defaults to minor, which stays inside the current major. "list" has
+no default — without one it lists the whole catalogue, offline.
+
+Options:
+  -y, --yes          Accept every default. Implied when stdin is not a TTY.
+      --allow-dirty  Run even though the working tree has uncommitted changes
+      --dry          Do not write files
+      --print        Print the transformed output
+      --path         Sources to transform
+      --json         Machine-readable output for "list"
+  -h, --help         Show this text
+  -V, --version      Show the version
+`;
+const main = async () => {
+    const parsed = parseArguments(process.argv.slice(2));
+    // Deliberate single ordered report stream: every command-level failure below
+    // that a real invocation can hit — `list`'s and `upgrade`'s range resolution,
+    // `codemod`'s and `upgrade`'s injected `log` — writes to stdout, interleaved
+    // with the rest of that command's normal output, in the order it happened.
+    // (The `default` case is dead code — `Command` is exhaustively covered above
+    // it — so its stderr write never actually runs.) Only the top-level
+    // rejection handler below (an unexpected throw, not a command refusing)
+    // writes to stderr. So `2>/dev/null` on this CLI does not suppress a
+    // refusal reason today — do not "fix" a command's own failure message onto
+    // stderr without weighing that.
+    switch (parsed.command) {
+        case "help":
+            process.stdout.write(usage);
+            return 0;
+        case "version": {
+            // `readFileSync` rather than an import attribute: `with { type: "json" }`
+            // was the newest syntax in this package and the only thing forcing the
+            // Node floor above what the rest of the code needs. Consumers reach this
+            // CLI through `npx`, so that floor is theirs, not the repo's.
+            const manifest = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8"));
+            process.stdout.write(`${manifest.version}\n`);
+            return 0;
+        }
+        case "list":
+            return await runList(parsed, {
+                ...defaultListDeps(process.cwd()),
+                // Colour only when a person is looking at a terminal. `NO_COLOR` is
+                // the cross-tool convention for turning it off; a pipe or a file gets
+                // plain text so the output stays greppable.
+                color: process.stdout.isTTY === true &&
+                    process.env.NO_COLOR === undefined &&
+                    !parsed.json,
+                // Clamped at both ends: a terminal can report an unusably small width
+                // (or none at all), and beyond ~100 columns long prose gets harder to
+                // read rather than easier.
+                width: Math.min(Math.max(process.stdout.columns ?? 80, 60), 100),
+            });
+        case "codemod":
+            return await runSingleCodemod(parsed, {
+                cwd: process.cwd(),
+                log: (message) => process.stdout.write(`${message}\n`),
+            });
+        case "upgrade": {
+            // Loaded here, not at the top: `list` and a single-codemod run never
+            // prompt, and paying for the prompt library's module graph on every
+            // invocation is the kind of cost a CLI is judged by.
+            const { checkbox } = await import("@inquirer/prompts");
+            // `-y` accepts every default, and no TTY implies it: CI and agent runs
+            // have nobody to answer the prompt. That is also why the dirty-tree guard
+            // exists — see git.ts.
+            const choose = createChoose({
+                yes: parsed.yes,
+                isTTY: process.stdin.isTTY === true,
+                isCI: process.env.CI !== undefined,
+                onCancel: (message) => process.stdout.write(`${message}\n`),
+                prompt: (entries) => checkbox({
+                    message: "Which codemods should run?",
+                    choices: entries.map((entry) => ({
+                        name: `${entry.id} — ${entry.title}`,
+                        value: entry.id,
+                        checked: true,
+                    })),
+                }),
+            });
+            return runUpgrade(parsed, {
+                ...defaultUpgradeDeps(process.cwd()),
+                choose,
+            });
+        }
+        default:
+            process.stderr.write(`"${parsed.command}" is not implemented yet\n`);
+            return 1;
+    }
+};
+// `process.exitCode` rather than `process.exit()`: exiting explicitly can
+// terminate the process before a pending write to stdout has flushed, which on
+// POSIX is the common case when stdout is a pipe. Every command exits through
+// here, including `list --json` and the upgrade report, so the output that would
+// be truncated is the largest output this CLI produces. Nothing keeps a handle
+// open, so Node exits on its own once the event loop drains.
+main().then((code) => {
+    process.exitCode = code;
+}, (error) => {
+    process.stderr.write(`${error instanceof Error ? error.message : error}\n`);
+    process.exitCode = 1;
+});

package/dist/detect/align-to-combine.d.ts

@@ -0,0 +1,8 @@
+import type { Detector } from "../checks/types.js";
+/**
+ * Translated from the catalogue's `detect: rg -t ts '\bAlign(Props)?\b'` — see
+ * the translation rule in the plan: `rg -t ts 'PATTERN'` becomes
+ * `search(/PATTERN/, tsExtensions)`.
+ */
+export declare const detector: Detector;
+//# sourceMappingURL=align-to-combine.d.ts.map

package/dist/detect/align-to-combine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"align-to-combine.d.ts","sourceRoot":"","sources":["../../src/detect/align-to-combine.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;GAIG;AACH,eAAO,MAAM,QAAQ,EAAE,QAEtB,CAAC"}

package/dist/detect/align-to-combine.js

@@ -0,0 +1,9 @@
+import { tsExtensions } from "../checks/context.js";
+/**
+ * Translated from the catalogue's `detect: rg -t ts '\bAlign(Props)?\b'` — see
+ * the translation rule in the plan: `rg -t ts 'PATTERN'` becomes
+ * `search(/PATTERN/, tsExtensions)`.
+ */
+export const detector = {
+    detect: (context) => context.search(/\bAlign(Props)?\b/, tsExtensions),
+};

package/dist/detect/overlay-controller-add-on-close-return-type.d.ts

@@ -0,0 +1,9 @@
+import type { Detector } from "../checks/types.js";
+/**
+ * Translated from the catalogue's `detect: rg -t ts 'addOnClose|addOnOpen'`.
+ * Every call site needs a by-hand look at its handler — see
+ * `src/verify/overlay-controller-add-on-close-return-type.ts` for why no
+ * compiler check can narrow this list further.
+ */
+export declare const detector: Detector;
+//# sourceMappingURL=overlay-controller-add-on-close-return-type.d.ts.map

package/dist/detect/overlay-controller-add-on-close-return-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"overlay-controller-add-on-close-return-type.d.ts","sourceRoot":"","sources":["../../src/detect/overlay-controller-add-on-close-return-type.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;GAKG;AACH,eAAO,MAAM,QAAQ,EAAE,QAEtB,CAAC"}

package/dist/detect/overlay-controller-add-on-close-return-type.js

@@ -0,0 +1,10 @@
+import { tsExtensions } from "../checks/context.js";
+/**
+ * Translated from the catalogue's `detect: rg -t ts 'addOnClose|addOnOpen'`.
+ * Every call site needs a by-hand look at its handler — see
+ * `src/verify/overlay-controller-add-on-close-return-type.ts` for why no
+ * compiler check can narrow this list further.
+ */
+export const detector = {
+    detect: (context) => context.search(/addOnClose|addOnOpen/, tsExtensions),
+};

package/dist/detect/tooltip-trigger-delay-type.d.ts

@@ -0,0 +1,11 @@
+import type { Detector } from "../checks/types.js";
+/**
+ * Translated from the catalogue's `detect: rg -t ts 'TooltipTrigger'`. This
+ * over-matches on purpose — every `TooltipTrigger` usage, not just the ones
+ * with a numeric `delay` — because a regex can't tell a numeric literal from a
+ * string one without a full parse; the reader looks at each hit. See
+ * `src/verify/tooltip-trigger-delay-type.ts` for why the real check is left to
+ * `tsc --noEmit` instead.
+ */
+export declare const detector: Detector;
+//# sourceMappingURL=tooltip-trigger-delay-type.d.ts.map

package/dist/detect/tooltip-trigger-delay-type.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tooltip-trigger-delay-type.d.ts","sourceRoot":"","sources":["../../src/detect/tooltip-trigger-delay-type.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAEnD;;;;;;;GAOG;AACH,eAAO,MAAM,QAAQ,EAAE,QAEtB,CAAC"}

package/dist/detect/tooltip-trigger-delay-type.js

@@ -0,0 +1,12 @@
+import { tsExtensions } from "../checks/context.js";
+/**
+ * Translated from the catalogue's `detect: rg -t ts 'TooltipTrigger'`. This
+ * over-matches on purpose — every `TooltipTrigger` usage, not just the ones
+ * with a numeric `delay` — because a regex can't tell a numeric literal from a
+ * string one without a full parse; the reader looks at each hit. See
+ * `src/verify/tooltip-trigger-delay-type.ts` for why the real check is left to
+ * `tsc --noEmit` instead.
+ */
+export const detector = {
+    detect: (context) => context.search(/TooltipTrigger/, tsExtensions),
+};

package/dist/flowPackages.generated.d.ts

@@ -0,0 +1,3 @@
+/** Every package published from the Flow monorepo, which all share one version. */
+export declare const flowPackages: string[];
+//# sourceMappingURL=flowPackages.generated.d.ts.map

package/dist/flowPackages.generated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flowPackages.generated.d.ts","sourceRoot":"","sources":["../src/flowPackages.generated.ts"],"names":[],"mappings":"AAIA,mFAAmF;AACnF,eAAO,MAAM,YAAY,EAAE,MAAM,EAahC,CAAC"}