@mittwald/flow-codemods 1.1.0-next.10

package/README.md

@@ -0,0 +1,106 @@
+# @mittwald/flow-codemods
+
+Codemods and an upgrade CLI for consumers of [Flow](https://flow.mittwald.de),
+mittwald's design system. Run it with `npx` — there is no reason to install it
+as a dependency.
+
+```shell
+npx @mittwald/flow-codemods@latest upgrade
+```
+
+## Commands
+
+### `upgrade [revision]`
+
+Bumps every `@mittwald/flow-*` dependency in `package.json` to a resolved
+target, installs, then runs the codemod of every migration up to that target.
+
+`revision` is one of:
+
+- `patch` — stays inside the current minor
+- `minor` (default) — stays inside the current major
+- `major` — no ceiling
+- a dist-tag, e.g. `latest` or `next`
+- an exact version, e.g. `1.4.0`
+
+The target is resolved from the versions every declared Flow dependency has
+actually published — not just one of them — so the command never writes a
+version some dependency lacks.
+
+`dependencies`, `devDependencies` and `optionalDependencies` are rewritten.
+**`peerDependencies` are reported and left alone**: a peer range states which
+versions your package supports, not one it installs, and narrowing `^1.0.0` to
+`^1.0.14` would change what _your_ consumers are allowed to install. That is
+your call, not the command's.
+
+After installing, `upgrade` runs the codemod of every migration whose `since` is
+at or below the target and prints the ones with no codemod, for you to apply by
+hand.
+
+**There is deliberately no lower bound.** Nothing records which migrations a
+project already performed, so `upgrade` offers all of them rather than guessing
+from the version you happen to be on — a project that never ran the command can
+catch up. Re-running a codemod is safe: every transform is tested for it.
+
+Options:
+
+- `-y`, `--yes` — accept every default (which codemods to run). Implied when
+  stdin is not a TTY, so CI and agent runs never block on a prompt.
+- `--dry` — resolve the target and print what would change, but write nothing
+  and skip the install. Codemods still run in this mode, against whatever is
+  currently installed rather than the target — their output is indicative, not
+  exact.
+- `--allow-dirty` — run even though the working tree has uncommitted changes.
+  Codemods rewrite files in place; without this flag, `upgrade` refuses on a
+  dirty tree so a bad run is still `git checkout`-able.
+- `--path <dir>` — sources to run the codemods against. Defaults to `./src` when
+  that directory exists, otherwise the project root. Give it explicitly if your
+  sources live somewhere else — an unrelated `src/` next to them would otherwise
+  win.
+- `--print` — print each codemod's transformed output.
+
+### `list [revision]`
+
+Shows migrations — codemod and by-hand alike — without touching the project. The
+read-only planning entry point: run it before `upgrade` to see what a bump would
+involve.
+
+- `list` (no argument) — the whole catalogue. Offline: reads no manifest, hits
+  no network.
+- `list [revision]` — the same manifest read, registry fetch, and revision
+  resolution `upgrade [revision]` does, showing exactly the range it would act
+  on, without writing anything. `revision` takes the same values as `upgrade`'s
+  — `patch` | `minor` | `major` | a dist-tag | an exact version — and there is
+  no default: only a given revision switches `list` into this form.
+
+Options:
+
+- `--json` — machine-readable output: an object with `range`
+  (`current`/`target`, or `null` for the offline whole-catalogue form) and
+  `migrations`, each entry carrying `catchUp`
+
+### `<id> [path]`
+
+Runs a single codemod by its catalogue id (see `list`) against `path` — which
+defaults to `./src` when that directory exists, otherwise the project root.
+
+Options: `--dry`, `--print` — same meaning as under `upgrade`.
+
+### `to-remote-package`
+
+A port, not a migration: it rewrites every `@mittwald/flow-react-components`
+import to `@mittwald/flow-remote-react-components`. It has no catalogue entry —
+no version range calls for it, and it never shows up in `list` or `upgrade`. Run
+it deliberately when moving an app into an mStudio extension; on a normal app it
+rewrites every Flow import.
+
+```shell
+npx @mittwald/flow-codemods@latest to-remote-package src
+```
+
+## Exit codes
+
+`0` on success, `1` on a refusal — dirty tree, unresolvable revision, failed
+install, an unknown id, or an id whose migration has no codemod — and `1` when a
+codemod reports an error, is declined for every file it looked at, or found
+nothing under `path` to process.

package/dist/catalog/entries.d.ts

@@ -0,0 +1,17 @@
+import type { MigrationEntry } from "./types.js";
+/**
+ * A catalogue entry as the CLI sees it — no body.
+ *
+ * This is the only module that imports the generated file, so nothing else
+ * depends on how it is shaped.
+ */
+export type CatalogEntry = Omit<MigrationEntry, "body">;
+export declare const allEntries: CatalogEntry[];
+/**
+ * Shared refusal for an id that names no codemod — `runSingleCodemod` (against
+ * the catalogue) and `runCodemod` (against `src/migrations`/`src/tools` on
+ * disk) each hit this independently, so the message is defined once and reused
+ * rather than kept in sync by hand in both places.
+ */
+export declare const unknownCodemodMessage: (id: string) => string;
+//# sourceMappingURL=entries.d.ts.map

package/dist/catalog/entries.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"entries.d.ts","sourceRoot":"","sources":["../../src/catalog/entries.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAEjD;;;;;GAKG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,CAAC;AAExD,eAAO,MAAM,UAAU,EAAE,YAAY,EAAe,CAAC;AAErD;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,OAAQ,MAAM,KAAG,MAC+C,CAAC"}

package/dist/catalog/entries.js

@@ -0,0 +1,9 @@
+import { migrations } from "../migrations.generated.js";
+export const allEntries = migrations;
+/**
+ * Shared refusal for an id that names no codemod — `runSingleCodemod` (against
+ * the catalogue) and `runCodemod` (against `src/migrations`/`src/tools` on
+ * disk) each hit this independently, so the message is defined once and reused
+ * rather than kept in sync by hand in both places.
+ */
+export const unknownCodemodMessage = (id) => `"${id}" is not a codemod in this package. Run \`flow-codemods list\` to see the available ids.`;

package/dist/catalog/select.d.ts

@@ -0,0 +1,28 @@
+import type { CatalogEntry } from "./entries.js";
+/**
+ * Oldest first — the order the changes shipped, which is the order to apply
+ * them.
+ */
+export declare const sortBySince: (entries: CatalogEntry[]) => CatalogEntry[];
+/**
+ * The entries that a move to `target` calls for.
+ *
+ * The gate is the exact version, not a major/minor/patch granularity: a
+ * revision keyword bounds `target`, and the set falls out of that. So `upgrade
+ * patch` — target = highest patch of the current minor — selects exactly the
+ * entries of the active minor, and `upgrade minor` selects every entry of the
+ * active major.
+ *
+ * One rule, for every entry: `since <= target`. There used to be a second,
+ * lower bound (`current < since`) for entries with no codemod, on the
+ * assumption that a consumer already applied everything behind their version.
+ * That was a guess, not a fact — nothing records which migrations a project has
+ * performed — and it was wrong for the case this tool exists for: someone who
+ * never ran it never did the manual steps either. Dropping it for codemods
+ * (idempotent — see `transformCoverage.test.ts`) but keeping it for manual
+ * entries only hid exactly the migrations that consumer needed to see. The
+ * `catch-up` rendering in `src/cli/list.ts` now carries the distinction instead
+ * of the gate hiding it.
+ */
+export declare const selectEntries: (entries: CatalogEntry[], target: string) => CatalogEntry[];
+//# sourceMappingURL=select.d.ts.map

package/dist/catalog/select.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"select.d.ts","sourceRoot":"","sources":["../../src/catalog/select.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAEjD;;;GAGG;AACH,eAAO,MAAM,WAAW,YAAa,YAAY,EAAE,KAAG,YAAY,EAG/D,CAAC;AAEJ;;;;;;;;;;;;;;;;;;;GAmBG;AACH,eAAO,MAAM,aAAa,YACf,YAAY,EAAE,UACf,MAAM,KACb,YAAY,EACmD,CAAC"}

package/dist/catalog/select.js

@@ -0,0 +1,27 @@
+import { compare, lte } from "semver";
+/**
+ * Oldest first — the order the changes shipped, which is the order to apply
+ * them.
+ */
+export const sortBySince = (entries) => entries.toSorted((a, b) => compare(a.since, b.since) || a.id.localeCompare(b.id));
+/**
+ * The entries that a move to `target` calls for.
+ *
+ * The gate is the exact version, not a major/minor/patch granularity: a
+ * revision keyword bounds `target`, and the set falls out of that. So `upgrade
+ * patch` — target = highest patch of the current minor — selects exactly the
+ * entries of the active minor, and `upgrade minor` selects every entry of the
+ * active major.
+ *
+ * One rule, for every entry: `since <= target`. There used to be a second,
+ * lower bound (`current < since`) for entries with no codemod, on the
+ * assumption that a consumer already applied everything behind their version.
+ * That was a guess, not a fact — nothing records which migrations a project has
+ * performed — and it was wrong for the case this tool exists for: someone who
+ * never ran it never did the manual steps either. Dropping it for codemods
+ * (idempotent — see `transformCoverage.test.ts`) but keeping it for manual
+ * entries only hid exactly the migrations that consumer needed to see. The
+ * `catch-up` rendering in `src/cli/list.ts` now carries the distinction instead
+ * of the gate hiding it.
+ */
+export const selectEntries = (entries, target) => sortBySince(entries.filter((entry) => lte(entry.since, target)));

package/dist/catalog/types.d.ts

@@ -0,0 +1,48 @@
+/**
+ * What kind of change the entry describes.
+ *
+ * - `migration` — the old path is gone, at runtime or in the types.
+ * - `deprecation` — the old path still works and warns.
+ *
+ * Descriptive only: it is rendered as a label and does **not** affect
+ * selection. It used to — a `deprecation` was offered as soon as its
+ * replacement existed and a `migration` only once the consumer crossed `since`
+ * — but the gate is one rule now (`since <= target`, see `selectEntries`), so
+ * both behave alike. The distinction still tells a reader whether their code
+ * compiles today, which is why the field stays.
+ */
+export type MigrationKind = "migration" | "deprecation";
+/**
+ * What has to happen.
+ *
+ * - `codemod` — `src/migrations/<id>/transform.ts` does it.
+ * - `manual` — a person or an agent has to change code.
+ * - `none` — behaviour changed, no code change required. An agent needs this
+ *   spelled out, or it keeps looking for something to edit.
+ */
+export type MigrationAction = "codemod" | "manual" | "none";
+export interface MigrationEntry {
+    /**
+     * Dashed and lowercase. Doubles as the `src/migrations/<id>` directory name
+     * and, when `action` is `codemod`, that directory's `transform.ts` file, and
+     * as the `MIGRATION.md` heading anchor.
+     */
+    id: string;
+    /** The exact version the change shipped in. */
+    since: string;
+    /** Heading text for the guide. */
+    title: string;
+    kind: MigrationKind;
+    action: MigrationAction;
+    /**
+     * Whether the entry also applies to `@mittwald/flow-remote-react-components`.
+     * Held to that package's real export surface by `remoteScope.test.ts` — do
+     * not guess it.
+     */
+    remotePackage: boolean;
+    /** What to change, imperative and specific enough to execute. */
+    apply: string;
+    /** The guide entry as Markdown. Headings inside it start at level 4. */
+    body: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/catalog/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/catalog/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,aAAa,GAAG,WAAW,GAAG,aAAa,CAAC;AAExD;;;;;;;GAOG;AACH,MAAM,MAAM,eAAe,GAAG,SAAS,GAAG,QAAQ,GAAG,MAAM,CAAC;AAE5D,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,EAAE,EAAE,MAAM,CAAC;IACX,+CAA+C;IAC/C,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,aAAa,CAAC;IACpB,MAAM,EAAE,eAAe,CAAC;IACxB;;;;OAIG;IACH,aAAa,EAAE,OAAO,CAAC;IACvB,iEAAiE;IACjE,KAAK,EAAE,MAAM,CAAC;IACd,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;CACd"}

package/dist/checks/context.d.ts

@@ -0,0 +1,16 @@
+import type { CheckContext } from "./types.js";
+/**
+ * Ripgrep's `-t ts` type: `.ts`, `.tsx`, `.cts`, `.mts`. Named once here so the
+ * 21 detect/verify modules that translate a `rg -t ts '...'` field do not each
+ * repeat the list.
+ */
+export declare const tsExtensions: string[];
+/**
+ * The shared `CheckContext` implementation — the only place under `src/checks`,
+ * `src/detect` or `src/verify` that touches the filesystem. Pure Node
+ * (`node:fs/promises`, regexes): no `rg`, `grep`, `tsc`, or any other
+ * subprocess, so this runs the same on Windows, in a minimal CI container, or
+ * without ripgrep installed.
+ */
+export declare const createCheckContext: (path: string) => CheckContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/checks/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/checks/context.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAW,MAAM,YAAY,CAAC;AAExD;;;;GAIG;AACH,eAAO,MAAM,YAAY,UAAkC,CAAC;AA0B5D;;;;;;GAMG;AACH,eAAO,MAAM,kBAAkB,SAAU,MAAM,KAAG,YA0CjD,CAAC"}

package/dist/checks/context.js

@@ -0,0 +1,72 @@
+import { readFile, readdir } from "node:fs/promises";
+import { extname, join } from "node:path";
+/**
+ * Ripgrep's `-t ts` type: `.ts`, `.tsx`, `.cts`, `.mts`. Named once here so the
+ * 21 detect/verify modules that translate a `rg -t ts '...'` field do not each
+ * repeat the list.
+ */
+export const tsExtensions = [".ts", ".tsx", ".cts", ".mts"];
+/**
+ * Directories a check must never walk into.
+ *
+ * Not optional: `upgrade` runs `verify` after an install, so a walk without
+ * this excludes a freshly populated `node_modules` — the exact omission that
+ * was a Critical on this branch for the codemod runner (see `ignorePattern` in
+ * `src/run/jscodeshift.ts`). `dist` and `.git` are excluded for the same
+ * reason: build output and VCS internals are not the consumer's code.
+ */
+const excludedDirs = new Set(["node_modules", "dist", ".git"]);
+const walk = async (dir) => {
+    const entries = await readdir(dir, { withFileTypes: true });
+    const found = await Promise.all(entries.map(async (entry) => {
+        if (entry.isDirectory()) {
+            return excludedDirs.has(entry.name) ? [] : walk(join(dir, entry.name));
+        }
+        return entry.isFile() ? [join(dir, entry.name)] : [];
+    }));
+    return found.flat();
+};
+/**
+ * The shared `CheckContext` implementation — the only place under `src/checks`,
+ * `src/detect` or `src/verify` that touches the filesystem. Pure Node
+ * (`node:fs/promises`, regexes): no `rg`, `grep`, `tsc`, or any other
+ * subprocess, so this runs the same on Windows, in a minimal CI container, or
+ * without ripgrep installed.
+ */
+export const createCheckContext = (path) => {
+    const files = async (extensions) => {
+        const all = await walk(path);
+        return extensions === undefined
+            ? all
+            : all.filter((file) => extensions.includes(extname(file)));
+    };
+    const read = (file) => readFile(file, "utf8");
+    const search = async (pattern, extensions) => {
+        const candidates = await files(extensions);
+        // A fresh, non-global copy of `pattern`: `.test()` on a `g`-flagged regex
+        // is stateful (it advances `lastIndex`), which would silently skip matches
+        // on later lines of the same file, or later files, depending on what the
+        // caller passed in.
+        const matcher = new RegExp(pattern.source, pattern.flags.replace("g", ""));
+        const findings = [];
+        for (const file of candidates) {
+            let content;
+            try {
+                content = await read(file);
+            }
+            catch {
+                // Unreadable — permissions, a broken symlink, binary content a strict
+                // decode chokes on. A check skips that one file rather than failing
+                // the whole run over it.
+                continue;
+            }
+            content.split("\n").forEach((line, index) => {
+                if (matcher.test(line)) {
+                    findings.push({ file, line: index + 1, text: line.trim() });
+                }
+            });
+        }
+        return findings;
+    };
+    return { path, files, read, search };
+};

package/dist/checks/load.d.ts

@@ -0,0 +1,13 @@
+import type { Detector, Verifier } from "./types.js";
+/**
+ * Loads the detector for a catalogue id, or `undefined` when none exists yet.
+ *
+ * Only a fraction of the catalogue has a module so far — the rest follow in
+ * later work. `detect`/`verify` (the CLI commands) must treat a missing module
+ * as "nothing to run for this id" rather than a failure, so callers can loop
+ * over the whole catalogue without special-casing which ids are covered.
+ */
+export declare const loadDetector: (id: string) => Promise<Detector | undefined>;
+/** The `verify` counterpart of {@link loadDetector}. */
+export declare const loadVerifier: (id: string) => Promise<Verifier | undefined>;
+//# sourceMappingURL=load.d.ts.map

package/dist/checks/load.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"load.d.ts","sourceRoot":"","sources":["../../src/checks/load.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAuBrD;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,OACnB,MAAM,KACT,OAAO,CAAC,QAAQ,GAAG,SAAS,CAiB9B,CAAC;AAEF,wDAAwD;AACxD,eAAO,MAAM,YAAY,OACnB,MAAM,KACT,OAAO,CAAC,QAAQ,GAAG,SAAS,CAW9B,CAAC"}

package/dist/checks/load.js

@@ -0,0 +1,53 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+/**
+ * `<packageRoot>/{src,dist}/detect` and `.../verify`, resolved from wherever
+ * this module itself runs — `src/checks/load.ts` under vitest (the `.ts`
+ * sources), `dist/checks/load.js` from the built binary (the compiled `.js`).
+ * Both mirror the same directory depth, so one relative path serves both.
+ *
+ * Unlike `src/transforms` (see the equivalent comment on `transformsDir` in
+ * `src/run/jscodeshift.ts`), detect and verify modules compile into `dist`
+ * normally: nothing here needs jscodeshift's babel pipeline, so there is no
+ * reason to keep them as raw `.ts`.
+ */
+const detectDir = fileURLToPath(new URL("../detect", import.meta.url));
+const verifyDir = fileURLToPath(new URL("../verify", import.meta.url));
+/**
+ * Whether `<dir>/<id>` exists as either a compiled `.js` (the built binary) or
+ * a source `.ts` (running under vitest, straight from `src`).
+ */
+const exists = (dir, id) => existsSync(`${dir}/${id}.js`) || existsSync(`${dir}/${id}.ts`);
+/**
+ * Loads the detector for a catalogue id, or `undefined` when none exists yet.
+ *
+ * Only a fraction of the catalogue has a module so far — the rest follow in
+ * later work. `detect`/`verify` (the CLI commands) must treat a missing module
+ * as "nothing to run for this id" rather than a failure, so callers can loop
+ * over the whole catalogue without special-casing which ids are covered.
+ */
+export const loadDetector = async (id) => {
+    if (!exists(detectDir, id)) {
+        return undefined;
+    }
+    // `@vite-ignore`: the id is only known at runtime, so this can never be a
+    // static specifier a bundler could pre-resolve — under plain Node (the
+    // built binary) that is a non-issue, but vitest runs test files through
+    // Vite's own module graph, and without the comment Vite tries to rewrite
+    // this into a glob import and fails with "Unknown variable dynamic
+    // import". The comment tells it to leave the import alone and let Node's
+    // loader resolve it, same as the built binary does.
+    const detectModule = (await import(
+    /* @vite-ignore */ `../detect/${id}.js`));
+    return detectModule.detector;
+};
+/** The `verify` counterpart of {@link loadDetector}. */
+export const loadVerifier = async (id) => {
+    if (!exists(verifyDir, id)) {
+        return undefined;
+    }
+    // See the matching comment in `loadDetector` above.
+    const verifyModule = (await import(
+    /* @vite-ignore */ `../verify/${id}.js`));
+    return verifyModule.verifier;
+};

package/dist/checks/types.d.ts

@@ -0,0 +1,49 @@
+/** Where a check found something, so the reader can go look. */
+export interface Finding {
+    file: string;
+    line: number;
+    text: string;
+}
+/**
+ * What a check gets. Pure Node — no subprocess, so this works on Windows, in a
+ * minimal container, and without ripgrep installed.
+ */
+export interface CheckContext {
+    /** Absolute path to the consumer's sources. */
+    path: string;
+    /** Files under `path`, with node_modules / dist / .git excluded. */
+    files(extensions?: string[]): Promise<string[]>;
+    read(file: string): Promise<string>;
+    /** Every match across those files. Most checks need only this. */
+    search(pattern: RegExp, extensions?: string[]): Promise<Finding[]>;
+}
+export interface Detector {
+    detect(context: CheckContext): Promise<Finding[]>;
+}
+export interface VerifyResult {
+    /** False when something the check _can_ decide is still wrong. */
+    ok: boolean;
+    findings: Finding[];
+    /**
+     * What a person must still judge — beyond just running the typechecker.
+     * Printed under the migration's name. An empty array means this module's own
+     * check is the whole story (aside from the typecheck below): nothing further
+     * for a person to weigh.
+     */
+    hints: string[];
+    /**
+     * The `tsc --noEmit` reminder, kept separate from `hints` so a command can
+     * tell "still needs a person's judgement" apart from "still needs the routine
+     * typecheck" instead of string-sniffing prose. Running it is a global check
+     * and this CLI wraps no commands, so it never becomes a `Finding`. Present
+     * whenever this migration's correctness depends in some way on the
+     * typechecker — including to explain that it does _not_ catch a particular
+     * class of mistake here, which is itself worth telling a person running `tsc
+     * --noEmit` out of habit.
+     */
+    typecheckHint?: string;
+}
+export interface Verifier {
+    verify(context: CheckContext): Promise<VerifyResult>;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/checks/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/checks/types.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAChE,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,oEAAoE;IACpE,KAAK,CAAC,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IAChD,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IACpC,kEAAkE;IAClE,MAAM,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACpE;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC;CACnD;AAED,MAAM,WAAW,YAAY;IAC3B,kEAAkE;IAClE,EAAE,EAAE,OAAO,CAAC;IACZ,QAAQ,EAAE,OAAO,EAAE,CAAC;IACpB;;;;;OAKG;IACH,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB;;;;;;;;;OASG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,QAAQ;IACvB,MAAM,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC,CAAC;CACtD"}

package/dist/cli/args.d.ts

@@ -0,0 +1,22 @@
+export type Command = "upgrade" | "list" | "codemod" | "help" | "version";
+export interface ParsedCommand {
+    command: Command;
+    /**
+     * `upgrade` always has one (defaulted below when not given explicitly).
+     * `list` has one only when given — that presence/absence is what
+     * distinguishes "the whole catalogue" from "the range this revision would
+     * touch". `patch` | `minor` | `major` | a dist-tag | an exact version.
+     */
+    revision?: string;
+    /** `codemod` only. */
+    id?: string;
+    /** Sources to transform. Unset means "decide at run time". */
+    path?: string;
+    json: boolean;
+    yes: boolean;
+    dry: boolean;
+    print: boolean;
+    allowDirty: boolean;
+}
+export declare const parseArguments: (argv: string[]) => ParsedCommand;
+//# sourceMappingURL=args.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"args.d.ts","sourceRoot":"","sources":["../../src/cli/args.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,OAAO,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAAC;AAE1E,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,OAAO,CAAC;IACjB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sBAAsB;IACtB,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,8DAA8D;IAC9D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,OAAO,CAAC;IACd,GAAG,EAAE,OAAO,CAAC;IACb,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,EAAE,OAAO,CAAC;CACrB;AAQD,eAAO,MAAM,cAAc,SAAU,MAAM,EAAE,KAAG,aAqD/C,CAAC"}

package/dist/cli/args.js

@@ -0,0 +1,56 @@
+import { parseArgs } from "node:util";
+/**
+ * The default revision. `minor` stays inside the current major, so the command
+ * never crosses a breaking boundary without being asked to.
+ */
+const defaultRevision = "minor";
+export const parseArguments = (argv) => {
+    const { values, positionals } = parseArgs({
+        args: argv,
+        allowPositionals: true,
+        strict: true,
+        options: {
+            help: { type: "boolean", short: "h" },
+            version: { type: "boolean", short: "V" },
+            yes: { type: "boolean", short: "y" },
+            json: { type: "boolean" },
+            dry: { type: "boolean" },
+            print: { type: "boolean" },
+            "allow-dirty": { type: "boolean" },
+            path: { type: "string" },
+        },
+    });
+    const flags = {
+        json: values.json === true,
+        yes: values.yes === true,
+        dry: values.dry === true,
+        print: values.print === true,
+        allowDirty: values["allow-dirty"] === true,
+    };
+    const [first, second] = positionals;
+    if (values.version === true) {
+        return { command: "version", ...flags };
+    }
+    if (values.help === true || first === undefined) {
+        return { command: "help", ...flags };
+    }
+    if (first === "upgrade") {
+        return {
+            command: "upgrade",
+            revision: second ?? defaultRevision,
+            path: values.path,
+            ...flags,
+        };
+    }
+    if (first === "list") {
+        // No default here, unlike `upgrade`: `revision` unset is what makes a
+        // bare `list` the catalogue browser rather than `list minor`.
+        return { command: "list", revision: second, ...flags };
+    }
+    return {
+        command: "codemod",
+        id: first,
+        path: second ?? values.path,
+        ...flags,
+    };
+};

package/dist/cli/choose.d.ts

@@ -0,0 +1,31 @@
+import type { CatalogEntry } from "../catalog/entries.js";
+export interface CreateChooseInput {
+    /** `-y` — accept every default. */
+    yes: boolean;
+    /** Whether stdin is a TTY. */
+    isTTY: boolean;
+    /**
+     * Whether this is an unattended runner.
+     *
+     * Injected rather than read from `process.env` in here: a hidden environment
+     * read underneath the caller's explicit parameters makes the function behave
+     * differently in CI than in a test that sets every input it can see — which
+     * is exactly how the cancel case below passed locally and failed on the
+     * runner, where `CI` is set and the prompt therefore never ran.
+     */
+    isCI: boolean;
+    /** Resolves to the ids the user picked. */
+    prompt: (entries: CatalogEntry[]) => Promise<string[]>;
+    /** Reports that the prompt was cancelled. */
+    onCancel: (message: string) => void;
+}
+/**
+ * Which codemods to run — interactively, or with everything passed through.
+ *
+ * `-y` and a non-TTY stdin both skip the prompt: an agent or CI run has nobody
+ * to answer it. `isCI` is checked too, on top of `isTTY` — a `docker run -t`
+ * allocates a TTY with nobody watching it, so that flag is what actually
+ * distinguishes a human from an unattended runner there.
+ */
+export declare const createChoose: ({ yes, isTTY, isCI, prompt, onCancel, }: CreateChooseInput) => ((entries: CatalogEntry[]) => Promise<CatalogEntry[]>);
+//# sourceMappingURL=choose.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"choose.d.ts","sourceRoot":"","sources":["../../src/cli/choose.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D,MAAM,WAAW,iBAAiB;IAChC,mCAAmC;IACnC,GAAG,EAAE,OAAO,CAAC;IACb,8BAA8B;IAC9B,KAAK,EAAE,OAAO,CAAC;IACf;;;;;;;;OAQG;IACH,IAAI,EAAE,OAAO,CAAC;IACd,2CAA2C;IAC3C,MAAM,EAAE,CAAC,OAAO,EAAE,YAAY,EAAE,KAAK,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACvD,6CAA6C;IAC7C,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CACrC;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,4CAMtB,iBAAiB,KAAG,CAAC,CACtB,OAAO,EAAE,YAAY,EAAE,KACpB,OAAO,CAAC,YAAY,EAAE,CAAC,CAwB3B,CAAC"}

package/dist/cli/choose.js

@@ -0,0 +1,31 @@
+/**
+ * Which codemods to run — interactively, or with everything passed through.
+ *
+ * `-y` and a non-TTY stdin both skip the prompt: an agent or CI run has nobody
+ * to answer it. `isCI` is checked too, on top of `isTTY` — a `docker run -t`
+ * allocates a TTY with nobody watching it, so that flag is what actually
+ * distinguishes a human from an unattended runner there.
+ */
+export const createChoose = ({ yes, isTTY, isCI, prompt, onCancel, }) => {
+    const interactive = !yes && isTTY && !isCI;
+    return async (entries) => {
+        if (!interactive || entries.length === 0) {
+            return entries;
+        }
+        let ids;
+        try {
+            ids = await prompt(entries);
+        }
+        catch {
+            // Ctrl+C here used to reject straight out of `runUpgrade`, so the last
+            // thing the user saw was an inquirer stack trace — after the manifest had
+            // been written and the install had run. Those cannot be taken back, so
+            // treat the cancel as "no codemods" and let the caller report what did
+            // happen. Any prompt failure lands here; none of them is a reason to lose
+            // the bump.
+            onCancel("Cancelled at the codemod prompt. The dependency bump and the install already happened — no codemods were run.");
+            return [];
+        }
+        return entries.filter((entry) => ids.includes(entry.id));
+    };
+};