@mittwald/flow-codemods 1.1.0-next.10

package/dist/cli/codemod.d.ts

@@ -0,0 +1,24 @@
+import type { ParsedCommand } from "./args.js";
+import { runCodemod } from "../run/jscodeshift.js";
+/**
+ * Which sources to transform, resolved against `cwd`.
+ *
+ * `src` is the default because that is where a Flow consumer's components live,
+ * and the working directory is the fallback. The caller prints the result
+ * either way — a codemod that silently ran over the wrong tree is worse than
+ * one that refused.
+ *
+ * Always returns a path rooted at `cwd` (an absolute `--path` is left alone).
+ * jscodeshift resolves a relative path against `process.cwd()`, not against
+ * whatever `cwd` a caller injected — a bare `"src"` would only be correct when
+ * the two coincide, which is true in production but not in a test that injects
+ * a different `cwd`.
+ */
+export declare const resolveSourcePath: (explicit: string | undefined, cwd: string, exists?: (path: string) => boolean) => string;
+export interface CodemodCommandDeps {
+    cwd: string;
+    log: (message: string) => void;
+    run?: typeof runCodemod;
+}
+export declare const runSingleCodemod: (parsed: ParsedCommand, { cwd, log, run }: CodemodCommandDeps) => Promise<number>;
+//# sourceMappingURL=codemod.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"codemod.d.ts","sourceRoot":"","sources":["../../src/cli/codemod.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAC/C,OAAO,EAAE,UAAU,EAAmB,MAAM,uBAAuB,CAAC;AAEpE;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,iBAAiB,aAClB,MAAM,GAAG,SAAS,OACvB,MAAM,WACH,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,KAChC,MAKF,CAAC;AAEF,MAAM,WAAW,kBAAkB;IACjC,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,GAAG,CAAC,EAAE,OAAO,UAAU,CAAC;CACzB;AAED,eAAO,MAAM,gBAAgB,WACnB,aAAa,qBACW,kBAAkB,KACjD,OAAO,CAAC,MAAM,CA6DhB,CAAC"}

package/dist/cli/codemod.js

@@ -0,0 +1,76 @@
+import { existsSync } from "node:fs";
+import { isAbsolute, join } from "node:path";
+import { allEntries, unknownCodemodMessage } from "../catalog/entries.js";
+import { runCodemod, transformExists } from "../run/jscodeshift.js";
+/**
+ * Which sources to transform, resolved against `cwd`.
+ *
+ * `src` is the default because that is where a Flow consumer's components live,
+ * and the working directory is the fallback. The caller prints the result
+ * either way — a codemod that silently ran over the wrong tree is worse than
+ * one that refused.
+ *
+ * Always returns a path rooted at `cwd` (an absolute `--path` is left alone).
+ * jscodeshift resolves a relative path against `process.cwd()`, not against
+ * whatever `cwd` a caller injected — a bare `"src"` would only be correct when
+ * the two coincide, which is true in production but not in a test that injects
+ * a different `cwd`.
+ */
+export const resolveSourcePath = (explicit, cwd, exists = existsSync) => {
+    if (explicit !== undefined) {
+        return isAbsolute(explicit) ? explicit : join(cwd, explicit);
+    }
+    return exists(join(cwd, "src")) ? join(cwd, "src") : cwd;
+};
+export const runSingleCodemod = async (parsed, { cwd, log, run = runCodemod }) => {
+    const id = parsed.id ?? "";
+    const entry = allEntries.find((candidate) => candidate.id === id);
+    // No catalogue entry is not the same as unknown: `to-remote-package` is a
+    // transform deliberately kept out of the catalogue (it is a port, not a
+    // migration — see `notAMigration` in `src/tests/remoteScope.test.ts`), and it
+    // still has to be reachable by id. Only fall back to the transform file when
+    // the catalogue does not know the id at all; a catalogued id whose action is
+    // "manual" or "none" still has no transform to run, regardless of what is on
+    // disk.
+    if (entry === undefined) {
+        if (!transformExists(id)) {
+            log(unknownCodemodMessage(id));
+            return 1;
+        }
+    }
+    else if (entry.action !== "codemod") {
+        log(`"${id}" has no codemod — it is a ${entry.action === "none" ? "behaviour change" : "manual change"}.\n\napply: ${entry.apply}`);
+        return 1;
+    }
+    const path = resolveSourcePath(parsed.path, cwd);
+    log(`Running ${id} over ${path}`);
+    const result = await run({ id, path, dry: parsed.dry, print: parsed.print });
+    if (result.errors > 0) {
+        log(`${id}: ${result.errors} file(s) failed to transform.`);
+        return 1;
+    }
+    // Not the same as "0 files changed": jscodeshift reports an empty path and a
+    // dead worker identically, so say what happened rather than implying success.
+    if (result.processedNothing) {
+        log(`${id}: no files under ${path} were processed. Is the path right?`);
+        return 1;
+    }
+    // The same trap as `processedNothing`, one field over: a transform that
+    // declines a file by returning nothing counts as `skipped`, not `unmodified`.
+    // If every file was skipped and none changed, "0 file(s) changed" would read
+    // as a clean no-op run when in fact the transform bailed on everything.
+    if (result.changed === 0 && result.skipped > 0) {
+        log(`${id}: the transform declined all ${result.skipped} file(s) it looked at, and changed none.`);
+        return 1;
+    }
+    const skipped = result.skipped > 0 ? `, ${result.skipped} skipped` : "";
+    const summary = `${id}: ${result.changed} file(s) changed, ${result.unmodified} unchanged${skipped}.`;
+    // Only a catalogued id has a migration guide entry to point at — a transform
+    // like `to-remote-package` with no catalogue entry has no anchor in
+    // `MIGRATION.md` to link, so pointing there would be a dead link.
+    const pointer = entry === undefined
+        ? ""
+        : `\nSee https://github.com/mittwald/flow/blob/main/packages/components/MIGRATION.md#${id} for what's left.`;
+    log(`${summary}${pointer}`);
+    return 0;
+};

package/dist/cli/detect.d.ts

@@ -0,0 +1,35 @@
+import { type CatalogEntry } from "../catalog/entries.js";
+import { loadDetector } from "../checks/load.js";
+import type { Finding } from "../checks/types.js";
+export interface DetectEntryResult {
+    entry: CatalogEntry;
+    findings: Finding[];
+}
+export interface RunDetectDeps {
+    /** Which entries to try. Defaults to the whole catalogue. */
+    entries?: CatalogEntry[];
+    /** Injectable for tests — defaults to the real module loader. */
+    load?: typeof loadDetector;
+}
+/**
+ * Runs every available detector over `path` and returns only the entries that
+ * found something.
+ *
+ * Only a fraction of the catalogue has a detector module so far (see
+ * `checks/load.ts`); an id with none is skipped rather than treated as a
+ * failure — the remaining detectors are mechanical follow-up work, not a bug in
+ * this command.
+ */
+export declare const runDetect: (path: string, { entries, load }?: RunDetectDeps) => Promise<DetectEntryResult[]>;
+/**
+ * Renders `runDetect`'s result as text — the presentation half kept separate
+ * from the async file-reading half, the same split `renderList` uses, so
+ * formatting is testable without touching a file. Reuses `renderList`'s
+ * vocabulary (`painter`, `wrap`, `indent`) rather than a second
+ * implementation.
+ */
+export declare const renderDetect: (results: DetectEntryResult[], path: string, { color, width }?: {
+    color?: boolean;
+    width?: number;
+}) => string;
+//# sourceMappingURL=detect.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"detect.d.ts","sourceRoot":"","sources":["../../src/cli/detect.ts"],"names":[],"mappings":"AACA,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGlD,MAAM,WAAW,iBAAiB;IAChC,KAAK,EAAE,YAAY,CAAC;IACpB,QAAQ,EAAE,OAAO,EAAE,CAAC;CACrB;AAED,MAAM,WAAW,aAAa;IAC5B,6DAA6D;IAC7D,OAAO,CAAC,EAAE,YAAY,EAAE,CAAC;IACzB,iEAAiE;IACjE,IAAI,CAAC,EAAE,OAAO,YAAY,CAAC;CAC5B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,SACd,MAAM,sBACmC,aAAa,KAC3D,OAAO,CAAC,iBAAiB,EAAE,CAgB7B,CAAC;AAeF;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,YACd,iBAAiB,EAAE,QACtB,MAAM,qBACmB;IAAE,KAAK,CAAC,EAAE,OAAO,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,KACjE,MAuBF,CAAC"}

package/dist/cli/detect.js

@@ -0,0 +1,62 @@
+import colors from "picocolors";
+import { allEntries } from "../catalog/entries.js";
+import { createCheckContext } from "../checks/context.js";
+import { loadDetector } from "../checks/load.js";
+import { indent, painter, wrap } from "./list.js";
+/**
+ * Runs every available detector over `path` and returns only the entries that
+ * found something.
+ *
+ * Only a fraction of the catalogue has a detector module so far (see
+ * `checks/load.ts`); an id with none is skipped rather than treated as a
+ * failure — the remaining detectors are mechanical follow-up work, not a bug in
+ * this command.
+ */
+export const runDetect = async (path, { entries = allEntries, load = loadDetector } = {}) => {
+    const context = createCheckContext(path);
+    const results = [];
+    for (const entry of entries) {
+        const detector = await load(entry.id);
+        if (detector === undefined) {
+            continue;
+        }
+        const findings = await detector.detect(context);
+        if (findings.length > 0) {
+            results.push({ entry, findings });
+        }
+    }
+    return results;
+};
+/** One `file:line text` row, wrapped and indented like `renderList`'s rows. */
+const findingLine = (finding, width, paint) => {
+    const location = paint.dim(`${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}`);
+};
+/**
+ * Renders `runDetect`'s result as text — the presentation half kept separate
+ * from the async file-reading half, the same split `renderList` uses, so
+ * formatting is testable without touching a file. Reuses `renderList`'s
+ * vocabulary (`painter`, `wrap`, `indent`) rather than a second
+ * implementation.
+ */
+export const renderDetect = (results, path, { color = false, width = 80 } = {}) => {
+    const paint = painter(color);
+    if (results.length === 0) {
+        return `No migrations under ${path} were found by the available detectors.\n`;
+    }
+    const noun = results.length === 1 ? "migration" : "migrations";
+    const verb = results.length === 1 ? "touches" : "touch";
+    const header = `${paint.bold(`${results.length} ${noun}`)} ${verb} ${path}\n`;
+    const body = results
+        .map(({ entry, findings }) => {
+        const mark = color ? colors.green("●") : "*";
+        const lines = [
+            `${mark} ${paint.bold(entry.id)}`,
+            ...findings.flatMap((finding) => findingLine(finding, width, paint)),
+        ];
+        return lines.join("\n");
+    })
+        .join("\n\n");
+    return `${header}\n${body}\n`;
+};

package/dist/cli/list.d.ts

@@ -0,0 +1,71 @@
+import { type CatalogEntry } from "../catalog/entries.js";
+import { type RangeDeps } from "../resolve/range.js";
+import type { ParsedCommand } from "./args.js";
+export interface RenderListInput {
+    entries: CatalogEntry[];
+    /**
+     * The version range to show migrations for. Both bounds always arrive
+     * together — there is no partial range — so omitting it entirely is what
+     * lists the whole catalogue.
+     */
+    range?: {
+        from: string;
+        to: string;
+    };
+    json: boolean;
+    /** Emit ANSI colour. Off by default so a test sees plain text. */
+    color?: boolean;
+    /** Terminal width to wrap prose to. */
+    width?: number;
+    /**
+     * Render the frame around the entries: the context on top (the range, the
+     * catch-up legend) and the summary at the bottom (the counts). On by default.
+     * `upgrade` turns it off for its by-hand section: it already printed its own
+     * heading and its own aggregate ("N codemods run, N changed something"), and
+     * this renderer's frame would just repeat both — see `runUpgrade`. Named for
+     * the whole frame, not just the top half, since it now gates both. The
+     * per-entry catch-up mark itself is unaffected — it lives in the body, not
+     * the frame.
+     */
+    frame?: boolean;
+}
+export declare const stripAnsi: (text: string) => string;
+/**
+ * The migrations for a version range, as text or JSON.
+ *
+ * Read-only by design: this is what an agent can call to plan before it changes
+ * anything. `--json` carries `apply` through unchanged, because that is the
+ * field it acts on — and it returns before any styling, so no escape sequence
+ * can ever reach a parser.
+ *
+ * `color` and `width` are arguments rather than read from the environment here,
+ * so the rendering is deterministic in a test — `painter` builds its palette
+ * from `color` alone, never from the terminal. `cli.ts` supplies them.
+ */
+export declare const renderList: ({ entries, range, json, color, width, frame, }: RenderListInput) => string;
+export interface ListDeps extends RangeDeps {
+    /**
+     * Raw output writer — matches `process.stdout.write`'s own contract: no
+     * newline is appended automatically.
+     */
+    write: (text: string) => void;
+    color?: boolean;
+    width?: number;
+}
+export declare const defaultListDeps: (cwd: string) => ListDeps;
+/**
+ * `list [revision]` — the catalogue browser (no argument) or a dry run of
+ * `upgrade <revision>` (with one).
+ *
+ * The two forms are distinguished by whether a revision was given, not by a
+ * default: unlike `upgrade`, `list` has none, because a bare `list` is a
+ * deliberately different thing — the whole catalogue, offline, no manifest
+ * read. Given a revision, this shares `resolveRange` with `upgrade`, so the
+ * range shown is exactly what `upgrade <revision>` would act on. Unlike
+ * `upgrade`, an unresolved-but-not-an-upgrade target (e.g. an exact version at
+ * or below current) is not a refusal here — `resolveRange` reports it as `ok:
+ * true`, and `list` shows it like any other range (which is typically empty,
+ * and prints "Nothing to migrate in that range.").
+ */
+export declare const runList: (parsed: ParsedCommand, deps: ListDeps) => Promise<number>;
+//# sourceMappingURL=list.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"list.d.ts","sourceRoot":"","sources":["../../src/cli/list.ts"],"names":[],"mappings":"AAEA,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAEtE,OAAO,EAGL,KAAK,SAAS,EACf,MAAM,qBAAqB,CAAC;AAC7B,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAE/C,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB;;;;OAIG;IACH,KAAK,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,EAAE,EAAE,MAAM,CAAA;KAAE,CAAC;IACrC,IAAI,EAAE,OAAO,CAAC;IACd,kEAAkE;IAClE,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,uCAAuC;IACvC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;;;;OASG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAkCD,eAAO,MAAM,SAAS,SAAU,MAAM,KAAG,MAAgC,CAAC;AAoO1E;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,UAAU,mDAOpB,eAAe,KAAG,MA0DpB,CAAC;AAEF,MAAM,WAAW,QAAS,SAAQ,SAAS;IACzC;;;OAGG;IACH,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9B,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,eAAO,MAAM,eAAe,QAAS,MAAM,KAAG,QAG5C,CAAC;AAEH;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,OAAO,WACV,aAAa,QACf,QAAQ,KACb,OAAO,CAAC,MAAM,CA+BhB,CAAC"}

package/dist/cli/list.js

@@ -0,0 +1,293 @@
+import colors from "picocolors";
+import { lte } from "semver";
+import { allEntries } from "../catalog/entries.js";
+import { selectEntries, sortBySince } from "../catalog/select.js";
+import { defaultRangeDeps, resolveRange, } from "../resolve/range.js";
+/**
+ * What the reader has to do, and the colour that says it at a glance.
+ *
+ * `plural` only differs for `codemod`, which is a countable thing; "by hand"
+ * and "no code change" describe how, not how many. `tone` names a key into the
+ * `Painter` a call site already built with `painter(color)` — not a bound
+ * colour function — so which palette applies is decided once, by the `color`
+ * argument, not baked into this module-level table. See `painter` for why.
+ */
+const actions = {
+    codemod: { label: "codemod", plural: "codemods", tone: "green" },
+    manual: { label: "by hand", plural: "by hand", tone: "yellow" },
+    none: {
+        label: "no code change",
+        plural: "no code change",
+        tone: "blue",
+    },
+};
+/**
+ * ANSI escapes have no width; measuring must ignore them.
+ *
+ * Built from a char code rather than written as a literal, so no control
+ * character sits in the source — which is also what `no-control-regex` wants.
+ */
+const ansi = new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g");
+export const stripAnsi = (text) => text.replace(ansi, "");
+const visibleWidth = (text) => stripAnsi(text).length;
+/**
+ * Wraps to `width`, measuring visible width so already-coloured text still
+ * breaks in the right place.
+ */
+const wrap = (text, width) => {
+    const lines = [];
+    let line = "";
+    for (const word of text.split(/\s+/).filter((part) => part !== "")) {
+        if (line === "") {
+            line = word;
+        }
+        else if (visibleWidth(line) + 1 + visibleWidth(word) <= width) {
+            line = `${line} ${word}`;
+        }
+        else {
+            lines.push(line);
+            line = word;
+        }
+    }
+    if (line !== "") {
+        lines.push(line);
+    }
+    return lines.length > 0 ? lines : [""];
+};
+/**
+ * Renders `code` spans as colour instead of literal backticks.
+ *
+ * The catalogue bodies are Markdown, so its prose fields carry backticks. In a
+ * terminal those are noise, but the emphasis they mark is exactly what a reader
+ * scans for — a symbol name or a command.
+ */
+const inlineCode = (text, paint) => text.replace(/`([^`]+)`/g, (_, code) => paint.code(code));
+/**
+ * Builds a palette from `color`, and only from `color`.
+ *
+ * `colors` (the module-level `picocolors` default export) auto-detects a TTY
+ * and disables itself under one — reading `colors.green` etc. directly would
+ * make the _environment_, not this argument, the real decider, silently
+ * disagreeing with `cli.ts`'s own TTY/`NO_COLOR`/`--json` check. `createColors`
+ * returns a palette with colour forced on or off, so `color` is the only input
+ * to how this renders.
+ */
+const painter = (color) => {
+    const palette = colors.createColors(color);
+    return {
+        bold: palette.bold,
+        dim: palette.dim,
+        code: palette.cyan,
+        green: palette.green,
+        yellow: palette.yellow,
+        blue: palette.blue,
+    };
+};
+const indent = "  ";
+const labelWidth = 8;
+/** One `apply` row: dim label, wrapped body beside it. */
+const field = (label, value, width, paint) => {
+    const gutter = indent + " ".repeat(labelWidth);
+    const body = wrap(inlineCode(value, paint), Math.max(width - gutter.length, 20));
+    return body.map((line, index) => index === 0
+        ? `${indent}${paint.dim(label.padEnd(labelWidth))}${line}`
+        : `${gutter}${line}`);
+};
+/**
+ * Whether `entry` shipped at or before `current` \u2014 selected because the
+ * gate no longer has a lower bound (`since <= target` alone, see
+ * `selectEntries`), not because the range newly crosses it. Only meaningful for
+ * a range-bounded list \u2014 the whole-catalogue browse has no `current` to
+ * compare against.
+ *
+ * This is what may already be done, not what is done: nothing records which
+ * migrations a project has actually performed, codemod or manual alike \u2014
+ * see `selectEntries`.
+ */
+const isCatchUp = (entry, current) => current !== undefined && lte(entry.since, current);
+const renderEntry = (entry, width, color, catchUp) => {
+    const paint = painter(color);
+    const action = actions[entry.action];
+    // Hollow vs filled: catch-up shipped at or before `current`, so it may
+    // already be handled, unlike something the upgrade is newly bringing in \u2014
+    // see the legend line in `renderContext`.
+    const symbol = catchUp ? "\u25CB" : "\u25CF";
+    const mark = color ? paint[action.tone](symbol) : catchUp ? "o" : "*";
+    const meta = [entry.kind, action.label];
+    if (entry.remotePackage) {
+        meta.push("also in flow-remote-react-components");
+    }
+    if (catchUp) {
+        meta.push("catch-up");
+    }
+    const lines = [
+        `${mark} ${paint.bold(entry.id)}  ${paint.dim(entry.since)}`,
+        indent + paint.dim(meta.join(" \u00B7 ")),
+        "",
+        ...field("apply", entry.apply, width, paint),
+    ];
+    if (entry.action === "codemod") {
+        lines.push("", `${indent}${paint.dim("$")} ${paint.code(`npx @mittwald/flow-codemods@latest ${entry.id} src`)}`);
+    }
+    return lines.join("\n");
+};
+/**
+ * What a reader needs _before_ the entries: what range this is, and — when it
+ * explains a mark they're about to see below — the catch-up legend.
+ *
+ * "" for a bare `list` (no range): there is nothing to decode, so nothing
+ * renders. Otherwise "from X to Y", or for a zero-width range "nothing newer
+ * than X" (`from`/`to` is the wrong form once they're equal — that isn't a
+ * range, it's "you're already there"), plus — when any entry below is marked
+ * catch-up — the legend for the mark. The gate has no lower bound (see
+ * `selectEntries`), so a range-bounded list can show every entry in the
+ * catalogue, not just the ones the range newly crosses; the legend says what
+ * the mark means — and, just as much, what it does not: catch-up is "may
+ * already be done", never "already done".
+ */
+const renderContext = (selected, range, color, width) => {
+    if (range === undefined) {
+        return "";
+    }
+    const catchUpCount = selected.filter((entry) => isCatchUp(entry, range.from)).length;
+    const rangeText = range.from === range.to
+        ? catchUpCount > 0
+            ? `nothing newer than ${range.to}; entries below are catch-up`
+            : `nothing newer than ${range.to}`
+        : `from ${range.from} to ${range.to}`;
+    if (catchUpCount === 0) {
+        return rangeText;
+    }
+    const paint = painter(color);
+    const mark = color ? paint[actions.codemod.tone]("○") : "o";
+    // Wrapped like every other line: unwrapped it ran to 150 characters and broke
+    // hard in any terminal narrower than that.
+    const legendGutter = "   ";
+    const legend = wrap(`catch-up: shipped at or before ${range.from} — you may already have done this. Re-running a codemod is a safe no-op; a manual step needs your own check.`, Math.max(width - legendGutter.length, 20)).map((line, index) => index === 0 ? `${mark}  ${line}` : `${legendGutter}${line}`);
+    return [rangeText, ...legend].join("\n");
+};
+/**
+ * What the reader has, after reading the entries: "N migrations · N codemods ·
+ * N by hand · N no code change".
+ *
+ * Nothing is hidden any more (see `selectEntries`), so this is just the entry
+ * count and the per-action breakdown — no separate hidden-count line.
+ */
+const renderSummary = (selected, color) => {
+    const paint = painter(color);
+    const noun = selected.length === 1 ? "migration" : "migrations";
+    const counts = Object.keys(actions)
+        .map((action) => ({
+        action,
+        count: selected.filter((entry) => entry.action === action).length,
+    }))
+        .filter(({ count }) => count > 0)
+        .map(({ action, count }) => {
+        const { label, plural, tone } = actions[action];
+        const text = `${count} ${count === 1 ? label : plural}`;
+        return color ? paint[tone](text) : text;
+    });
+    // The counts carry their own colour, so no dim around them — nesting the two
+    // makes both weaker.
+    return [paint.bold(`${selected.length} ${noun}`), ...counts].join(paint.dim(" · "));
+};
+/**
+ * The migrations for a version range, as text or JSON.
+ *
+ * Read-only by design: this is what an agent can call to plan before it changes
+ * anything. `--json` carries `apply` through unchanged, because that is the
+ * field it acts on — and it returns before any styling, so no escape sequence
+ * can ever reach a parser.
+ *
+ * `color` and `width` are arguments rather than read from the environment here,
+ * so the rendering is deterministic in a test — `painter` builds its palette
+ * from `color` alone, never from the terminal. `cli.ts` supplies them.
+ */
+export const renderList = ({ entries, range, json, color = false, width = 80, frame = true, }) => {
+    // The two paths differ in their bounds, deliberately: unbounded, this is a
+    // plain catalogue browse — every entry, sorted, regardless of whether it
+    // would apply to any given range. Bounded, it answers "what does this
+    // version range require of me", which `selectEntries` computes per entry
+    // from `since`. `range`'s two fields always arrive together (there is no
+    // partial bound any more — see `resolveRange`), so there is no sentinel to
+    // fill a missing side with; the branch below is the only thing that decides
+    // "whole catalogue" vs. "this range".
+    const selected = range === undefined
+        ? sortBySince(entries)
+        : selectEntries(entries, range.to);
+    if (json) {
+        // An object, not the bare array: the agent-facing form has to say which
+        // range it describes, or `list minor` and `list` are indistinguishable in
+        // it — and it carries `catchUp` per entry for the same reason the human
+        // form marks it.
+        return `${JSON.stringify({
+            range: range === undefined
+                ? null
+                : { current: range.from, target: range.to },
+            migrations: selected.map((entry) => ({
+                ...entry,
+                catchUp: isCatchUp(entry, range?.from),
+            })),
+        }, null, 2)}\n`;
+    }
+    if (selected.length === 0) {
+        return "Nothing to migrate in that range.\n";
+    }
+    const body = selected
+        .map((entry) => renderEntry(entry, width, color, isCatchUp(entry, range?.from)))
+        .join("\n\n");
+    if (!frame) {
+        return `${body}\n`;
+    }
+    // Context (range, legend) leads, because a reader needs both before the
+    // entries; the summary (counts) trails, because a 22-entry list scrolls the
+    // top out of sight well before the reader reaches the end — exactly when
+    // they want the counts. `context` is "" for a bare `list`, so no blank line
+    // gets left dangling above the first entry.
+    const context = renderContext(selected, range, color, width);
+    const summary = renderSummary(selected, color);
+    return `${context === "" ? "" : `${context}\n\n`}${body}\n\n${summary}\n`;
+};
+export const defaultListDeps = (cwd) => ({
+    ...defaultRangeDeps(cwd),
+    write: (text) => process.stdout.write(text),
+});
+/**
+ * `list [revision]` — the catalogue browser (no argument) or a dry run of
+ * `upgrade <revision>` (with one).
+ *
+ * The two forms are distinguished by whether a revision was given, not by a
+ * default: unlike `upgrade`, `list` has none, because a bare `list` is a
+ * deliberately different thing — the whole catalogue, offline, no manifest
+ * read. Given a revision, this shares `resolveRange` with `upgrade`, so the
+ * range shown is exactly what `upgrade <revision>` would act on. Unlike
+ * `upgrade`, an unresolved-but-not-an-upgrade target (e.g. an exact version at
+ * or below current) is not a refusal here — `resolveRange` reports it as `ok:
+ * true`, and `list` shows it like any other range (which is typically empty,
+ * and prints "Nothing to migrate in that range.").
+ */
+export const runList = async (parsed, deps) => {
+    const { revision } = parsed;
+    if (revision === undefined) {
+        deps.write(renderList({
+            entries: allEntries,
+            json: parsed.json,
+            color: deps.color,
+            width: deps.width,
+        }));
+        return 0;
+    }
+    const resolved = await resolveRange(revision, deps);
+    if (!resolved.ok) {
+        deps.write(`${resolved.reason}\n`);
+        return 1;
+    }
+    deps.write(renderList({
+        entries: allEntries,
+        range: { from: resolved.current, to: resolved.target },
+        json: parsed.json,
+        color: deps.color,
+        width: deps.width,
+    }));
+    return 0;
+};

package/dist/cli/upgrade.d.ts

@@ -0,0 +1,34 @@
+import { type CatalogEntry } from "../catalog/entries.js";
+import { type InstallRunner } from "../install.js";
+import { fetchVersions } from "../resolve/registry.js";
+import { runCodemod } from "../run/jscodeshift.js";
+import type { ParsedCommand } from "./args.js";
+export interface UpgradeDeps {
+    cwd: string;
+    fetchVersions: typeof fetchVersions;
+    install: InstallRunner;
+    runCodemod: typeof runCodemod;
+    /** Which codemods to apply. `-y` and a non-TTY pass everything through. */
+    choose: (entries: CatalogEntry[]) => Promise<CatalogEntry[]>;
+    isDirty: (cwd: string) => boolean;
+    readInstalledVersion: (cwd: string, name: string) => string | undefined;
+    log: (message: string) => void;
+}
+export declare const defaultUpgradeDeps: (cwd: string) => UpgradeDeps;
+/**
+ * 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 declare const runUpgrade: (parsed: ParsedCommand, deps: UpgradeDeps) => Promise<number>;
+//# sourceMappingURL=upgrade.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"upgrade.d.ts","sourceRoot":"","sources":["../../src/cli/upgrade.ts"],"names":[],"mappings":"AAGA,OAAO,EAAc,KAAK,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAItE,OAAO,EAGL,KAAK,aAAa,EACnB,MAAM,eAAe,CAAC;AAEvB,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAEvD,OAAO,EAAE,UAAU,EAAsB,MAAM,uBAAuB,CAAC;AACvE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,WAAW,CAAC;AAI/C,MAAM,WAAW,WAAW;IAC1B,GAAG,EAAE,MAAM,CAAC;IACZ,aAAa,EAAE,OAAO,aAAa,CAAC;IACpC,OAAO,EAAE,aAAa,CAAC;IACvB,UAAU,EAAE,OAAO,UAAU,CAAC;IAC9B,2EAA2E;IAC3E,MAAM,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC;IAC7D,OAAO,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;IAClC,oBAAoB,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,KAAK,MAAM,GAAG,SAAS,CAAC;IACxE,GAAG,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAChC;AAED,eAAO,MAAM,kBAAkB,QAAS,MAAM,KAAG,WAS/C,CAAC;AA2BH;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,UAAU,WACb,aAAa,QACf,WAAW,KAChB,OAAO,CAAC,MAAM,CAwMhB,CAAC"}