@mittwald/flow-codemods 1.1.0-next.10

package/dist/resolve/range.js

@@ -0,0 +1,173 @@
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { rsort } from "semver";
+import { flowPackages } from "../flowPackages.generated.js";
+import { detectCurrentVersion, findFlowDependencies, } from "../manifest.js";
+import { fetchAllVersions, fetchVersions, intersectVersions, } from "./registry.js";
+import { resolveTarget } from "./target.js";
+/**
+ * The installed version of `name`, read from `cwd`'s `node_modules`.
+ *
+ * Lives here rather than in `upgrade.ts` (where it used to) because `list` now
+ * resolves a range too, and both commands need the identical "what's actually
+ * installed" answer — this is `resolveRange`'s default reader.
+ */
+export const readInstalledVersion = (cwd, name) => {
+    try {
+        const manifest = JSON.parse(readFileSync(join(cwd, "node_modules", name, "package.json"), "utf8"));
+        return manifest.version;
+    }
+    catch {
+        return undefined;
+    }
+};
+export const defaultRangeDeps = (cwd) => ({
+    cwd,
+    fetchVersions,
+    readInstalledVersion,
+});
+const isEnoent = (error) => error instanceof Error &&
+    "code" in error &&
+    error.code === "ENOENT";
+/**
+ * Turns a structured `UnresolvedTarget` into the one- or two-sentence message
+ * `resolveRange` returns as `reason`.
+ *
+ * `resolveTarget` reports _why_ it could not resolve `revision`; this is the
+ * "let the caller say the right thing" half. `unrecognized` covers both an
+ * unknown keyword and an unknown dist-tag — nothing about the string itself
+ * says which the caller meant, so the message lists both the keywords and the
+ * real dist-tags rather than guessing.
+ */
+const describeUnresolvedTarget = (reason) => {
+    switch (reason.kind) {
+        case "unrecognized": {
+            const tags = reason.distTags.length > 0
+                ? `, or one of these dist-tags: ${reason.distTags.join(", ")}`
+                : "";
+            return `"${reason.revision}" is not a recognised revision. Use patch, minor, major, an exact version${tags}.`;
+        }
+        case "no-candidate": {
+            const suggestion = reason.broader !== undefined
+                ? `Use "${reason.broader.keyword}" (→ ${reason.broader.target}), or name an exact version.`
+                : "No stable version has been published yet — name a dist-tag or an exact version.";
+            return `"${reason.revision}" looks for ${reason.describes}; none is published. ${suggestion}`;
+        }
+        case "unpublished": {
+            const closest = reason.closest !== undefined
+                ? ` The closest published version is ${reason.closest}.`
+                : "";
+            return `"${reason.revision}" has not been published.${closest}`;
+        }
+    }
+};
+/**
+ * What `revision` resolves to for the project at `cwd`.
+ *
+ * Reads the manifest, finds its Flow dependencies, detects the current version,
+ * fetches what every dependency has actually published, and resolves `revision`
+ * against the intersection — the same sequence `upgrade` always needed, now
+ * shared with `list <revision>`, which uses it to answer "what would `upgrade
+ * <revision>` touch?" without writing anything.
+ *
+ * Reports the resolution rather than judging it: an exact version or a stale
+ * dist-tag can resolve at or below `current`, and this function returns that
+ * target just the same. Whether that is a refusal (`upgrade`, about to write
+ * files) or a legitimate answer ("nothing between here and there" — `list`) is
+ * for the caller to decide. Two callers judging the same fact differently is
+ * fine; two callers computing the fact differently is how they drift.
+ */
+export const resolveRange = async (revision, deps) => {
+    const manifestPath = join(deps.cwd, "package.json");
+    let manifestRaw;
+    try {
+        manifestRaw = readFileSync(manifestPath, "utf8");
+    }
+    catch (error) {
+        if (isEnoent(error)) {
+            return {
+                ok: false,
+                reason: `No package.json found in ${deps.cwd}. Resolving "${revision}" needs one to read the current Flow version from — a bare "list" does not.`,
+            };
+        }
+        throw error;
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(manifestRaw);
+    }
+    catch (error) {
+        return {
+            ok: false,
+            reason: `Could not parse ${manifestPath} as JSON: ${error instanceof Error ? error.message : error}`,
+        };
+    }
+    const dependencies = findFlowDependencies(manifest, flowPackages);
+    // Destructuring the emptiness check (rather than `dependencies.length ===
+    // 0`) sidesteps a `no-non-null-assertion` lint error at every later read of
+    // `dependencies[0]` — `no-non-null-assertion` is an error in this repo's
+    // eslint config.
+    const [firstDependency] = dependencies;
+    if (firstDependency === undefined) {
+        return {
+            ok: false,
+            reason: `No Flow dependency found in ${manifestPath}. Nothing to upgrade.`,
+        };
+    }
+    const current = detectCurrentVersion(dependencies, (name) => deps.readInstalledVersion(deps.cwd, name));
+    if (current === undefined) {
+        return {
+            ok: false,
+            reason: "Could not determine the Flow version this project is on.",
+        };
+    }
+    // Fixed versioning keeps every Flow package's package.json version equal,
+    // but Lerna publishes only the packages that actually changed, so what
+    // reaches the registry diverges per package (#2887, accepted risk).
+    // Resolving from one "anchor" dependency and writing it onto all of them can
+    // pick a version some of the others never published. Resolve instead from
+    // the intersection of what every declared dependency has actually
+    // published, so the version this returns is always installable.
+    const fetched = await fetchAllVersions(dependencies.map(({ name }) => name), deps.fetchVersions);
+    const versions = intersectVersions(fetched);
+    if (versions.length === 0) {
+        return {
+            ok: false,
+            reason: `${dependencies
+                .map(({ name }) => name)
+                .join(", ")} have no published version in common. Nothing to upgrade to.`,
+        };
+    }
+    // Dist-tags come from the first declared dependency, but a tag is only kept
+    // when the version it points at is one every dependency has published — an
+    // unvalidated tag could otherwise resolve outside the intersection above.
+    const [firstFetched] = fetched;
+    const distTags = Object.fromEntries(Object.entries(firstFetched?.distTags ?? {}).filter(([, version]) => versions.includes(version)));
+    const resolved = resolveTarget({ revision, current, versions, distTags });
+    if (!resolved.ok) {
+        return { ok: false, reason: describeUnresolvedTarget(resolved.reason) };
+    }
+    const { target } = resolved;
+    // Defence in depth: `target` is drawn from `versions` (the intersection) or
+    // from a dist-tag already validated against it, so this should never find a
+    // gap. If it ever does, refuse rather than report a version some package
+    // never published — naming which package lacks it and the highest version
+    // every declared dependency has actually published.
+    const missingFrom = fetched.find((pkg) => !pkg.versions.includes(target));
+    if (missingFrom !== undefined) {
+        return {
+            ok: false,
+            reason: `${missingFrom.name} has not published ${target}. The highest version every declared Flow dependency has published is ${rsort(versions)[0]}.`,
+        };
+    }
+    return {
+        ok: true,
+        manifestPath,
+        manifestRaw,
+        manifest,
+        dependencies,
+        current,
+        target,
+        versions,
+    };
+};

package/dist/resolve/registry.d.ts

@@ -0,0 +1,33 @@
+export interface RegistryVersions {
+    versions: string[];
+    distTags: Record<string, string>;
+}
+/**
+ * Every published version of a package, plus its dist-tags.
+ *
+ * Uses the abbreviated packument media type: the full document for a package
+ * with hundreds of releases is megabytes, and none of it is needed here.
+ */
+export declare const fetchVersions: (packageName: string) => Promise<RegistryVersions>;
+export interface PackageVersions extends RegistryVersions {
+    name: string;
+}
+/**
+ * Every declared Flow dependency's packument, fetched concurrently.
+ *
+ * `fetchVersions` is injected rather than imported directly so this stays
+ * testable without a network stub — `UpgradeDeps.fetchVersions` is what
+ * production and tests both pass in here.
+ */
+export declare const fetchAllVersions: (names: string[], fetchOne: (name: string) => Promise<RegistryVersions>) => Promise<PackageVersions[]>;
+/**
+ * The versions every one of `packages` has published.
+ *
+ * Fixed versioning keeps every Flow package's `package.json` version equal, but
+ * Lerna publishes only the packages that actually changed, so what reaches the
+ * registry diverges per package (#2887, accepted risk). A target version is
+ * only safe to write onto every declared dependency when it is one of these —
+ * the intersection, not any single package's list.
+ */
+export declare const intersectVersions: (packages: PackageVersions[]) => string[];
+//# sourceMappingURL=registry.d.ts.map

package/dist/resolve/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/resolve/registry.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAwBD;;;;;GAKG;AACH,eAAO,MAAM,aAAa,gBACX,MAAM,KAClB,OAAO,CAAC,gBAAgB,CA6B1B,CAAC;AAEF,MAAM,WAAW,eAAgB,SAAQ,gBAAgB;IACvD,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,UACpB,MAAM,EAAE,YACL,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,gBAAgB,CAAC,KACpD,OAAO,CAAC,eAAe,EAAE,CACmD,CAAC;AAEhF;;;;;;;;GAQG;AACH,eAAO,MAAM,iBAAiB,aAAc,eAAe,EAAE,KAAG,MAAM,EAQrE,CAAC"}

package/dist/resolve/registry.js

@@ -0,0 +1,69 @@
+import registryUrl from "registry-url";
+/**
+ * The registry that actually serves `@mittwald`, from the consumer's npm
+ * config.
+ *
+ * Hardcoding `registry.npmjs.org` would be wrong for anyone behind a corporate
+ * mirror or a scoped private registry — `npm view` works for them because npm
+ * reads their `.npmrc`, and a CLI that ignores it would fail or, worse, answer
+ * from the wrong source.
+ */
+const registryFor = (packageName) => {
+    const scope = packageName.startsWith("@")
+        ? packageName.slice(0, packageName.indexOf("/"))
+        : undefined;
+    return registryUrl(scope).replace(/\/$/, "");
+};
+/**
+ * Every published version of a package, plus its dist-tags.
+ *
+ * Uses the abbreviated packument media type: the full document for a package
+ * with hundreds of releases is megabytes, and none of it is needed here.
+ */
+export const fetchVersions = async (packageName) => {
+    // One wrapper for every failure, not just the HTTP one: `fetch` itself rejects
+    // on DNS failure or no connection, and `json()` rejects on a malformed body.
+    // Without this those surface as a bare "fetch failed", which says nothing
+    // about what the CLI was trying to do.
+    let packument;
+    try {
+        const response = await fetch(`${registryFor(packageName)}/${packageName}`, {
+            headers: { accept: "application/vnd.npm.install-v1+json" },
+        });
+        if (!response.ok) {
+            throw new Error(`the registry answered ${response.status}`);
+        }
+        packument = (await response.json());
+    }
+    catch (error) {
+        throw new Error(`Could not read ${packageName} from the npm registry: ${error instanceof Error ? error.message : error}`, { cause: error });
+    }
+    return {
+        versions: Object.keys(packument.versions ?? {}),
+        distTags: packument["dist-tags"] ?? {},
+    };
+};
+/**
+ * Every declared Flow dependency's packument, fetched concurrently.
+ *
+ * `fetchVersions` is injected rather than imported directly so this stays
+ * testable without a network stub — `UpgradeDeps.fetchVersions` is what
+ * production and tests both pass in here.
+ */
+export const fetchAllVersions = async (names, fetchOne) => Promise.all(names.map(async (name) => ({ name, ...(await fetchOne(name)) })));
+/**
+ * The versions every one of `packages` has published.
+ *
+ * Fixed versioning keeps every Flow package's `package.json` version equal, but
+ * Lerna publishes only the packages that actually changed, so what reaches the
+ * registry diverges per package (#2887, accepted risk). A target version is
+ * only safe to write onto every declared dependency when it is one of these —
+ * the intersection, not any single package's list.
+ */
+export const intersectVersions = (packages) => {
+    const [first, ...rest] = packages;
+    if (first === undefined) {
+        return [];
+    }
+    return first.versions.filter((version) => rest.every((pkg) => pkg.versions.includes(version)));
+};

package/dist/resolve/target.d.ts

@@ -0,0 +1,63 @@
+export interface ResolveTargetInput {
+    /** `patch` | `minor` | `major` | a dist-tag | an exact version. */
+    revision: string;
+    /** The version the consumer is on. */
+    current: string;
+    /** Every published version of the anchor package. */
+    versions: string[];
+    distTags: Record<string, string>;
+}
+export type KeywordRevision = "patch" | "minor" | "major";
+/**
+ * Why `resolveTarget` could not turn `revision` into a version — the caller
+ * needs this to say something more useful than "could not resolve", because the
+ * four cases below call for genuinely different messages (unknown input, a real
+ * keyword with nothing to point at, an unknown dist-tag, an unpublished exact
+ * version).
+ */
+export type UnresolvedTarget = {
+    kind: "unrecognized";
+    revision: string;
+    /** The dist-tags that do exist, so the caller can name them. */
+    distTags: string[];
+} | {
+    kind: "no-candidate";
+    revision: KeywordRevision;
+    /** What the keyword was looking for, in prose ("the highest …"). */
+    describes: string;
+    /**
+     * The next broader keyword and what it resolves to, when one exists —
+     * `major` has none, it is already unbounded. Naming this beats hardcoding
+     * "use major": a `patch` failure's real escape is `minor`.
+     */
+    broader?: {
+        keyword: KeywordRevision;
+        target: string;
+    };
+} | {
+    kind: "unpublished";
+    revision: string;
+    /** The nearest published version, when `versions` is non-empty. */
+    closest: string | undefined;
+};
+export type ResolveTargetResult = {
+    ok: true;
+    target: string;
+} | {
+    ok: false;
+    reason: UnresolvedTarget;
+};
+/**
+ * What a revision means, as a concrete published version — or a structured
+ * reason it does not.
+ *
+ * Reports the resolution rather than judging it: it does **not** judge whether
+ * the result is an upgrade; the caller compares against `current` and refuses a
+ * sideways or downward move.
+ *
+ * Keyword resolution skips prereleases (see `highestStable`). Only an explicit
+ * dist-tag or an exact version reaches a `-next.N`, so `upgrade minor` on the
+ * stable line never drifts onto the collection branch.
+ */
+export declare const resolveTarget: ({ revision, current, versions, distTags, }: ResolveTargetInput) => ResolveTargetResult;
+//# sourceMappingURL=target.d.ts.map

package/dist/resolve/target.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"target.d.ts","sourceRoot":"","sources":["../../src/resolve/target.ts"],"names":[],"mappings":"AAEA,MAAM,WAAW,kBAAkB;IACjC,mEAAmE;IACnE,QAAQ,EAAE,MAAM,CAAC;IACjB,sCAAsC;IACtC,OAAO,EAAE,MAAM,CAAC;IAChB,qDAAqD;IACrD,QAAQ,EAAE,MAAM,EAAE,CAAC;IACnB,QAAQ,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,MAAM,eAAe,GAAG,OAAO,GAAG,OAAO,GAAG,OAAO,CAAC;AAO1D;;;;;;GAMG;AACH,MAAM,MAAM,gBAAgB,GACxB;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,MAAM,CAAC;IACjB,gEAAgE;IAChE,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB,GACD;IACE,IAAI,EAAE,cAAc,CAAC;IACrB,QAAQ,EAAE,eAAe,CAAC;IAC1B,oEAAoE;IACpE,SAAS,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,eAAe,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACxD,GACD;IACE,IAAI,EAAE,aAAa,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;IACjB,mEAAmE;IACnE,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;CAC7B,CAAC;AAEN,MAAM,MAAM,mBAAmB,GAC7B;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAiFzE;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,+CAKvB,kBAAkB,KAAG,mBA0CvB,CAAC"}

package/dist/resolve/target.js

@@ -0,0 +1,115 @@
+import { lt, major, minor, prerelease, rsort, satisfies, valid } from "semver";
+const KEYWORDS = ["patch", "minor", "major"];
+const isKeyword = (revision) => KEYWORDS.includes(revision);
+/**
+ * The range a revision keyword bounds the target to.
+ *
+ * `patch` keeps the current minor, `minor` keeps the current major, `major`
+ * accepts anything.
+ */
+const keywordRange = (revision, current) => {
+    switch (revision) {
+        case "patch":
+            return `${major(current)}.${minor(current)}.x`;
+        case "minor":
+            return `${major(current)}.x`;
+        case "major":
+            return "*";
+    }
+};
+/** Prose for what a keyword looks for — used in the "no-candidate" message. */
+const describeKeyword = (revision, current) => {
+    switch (revision) {
+        case "patch":
+            return `the highest published patch release on ${major(current)}.${minor(current)}.x`;
+        case "minor":
+            return `the highest published stable release in ${major(current)}.x`;
+        case "major":
+            return "the highest published stable release";
+    }
+};
+/**
+ * The highest stable version satisfying `range`, or `undefined`.
+ *
+ * The `prerelease(...) === null` filter is defence in depth rather than the
+ * mechanism: none of the ranges built here embeds a prerelease tag, and
+ * node-semver only matches a prerelease when a comparator carries a matching
+ * one — so `satisfies` already excludes them. The filter keeps that true if a
+ * range shape or an option ever changes.
+ */
+const highestStable = (range, versions) => {
+    const candidates = versions.filter((version) => prerelease(version) === null && satisfies(version, range));
+    return rsort(candidates)[0];
+};
+/**
+ * The next keyword broader than `revision`, and what it resolves to.
+ *
+ * `patch` is bounded to the current minor, `minor` to the current major — each
+ * has exactly one broader step. `major` is already unbounded, so it has none.
+ * This is what turns "use major" into a suggestion the caller can act on
+ * directly, and what stops a `patch` failure suggesting `major` when `minor`
+ * would already have found something.
+ */
+const broaderCandidate = (revision, current, versions) => {
+    const index = KEYWORDS.indexOf(revision);
+    for (let i = index + 1; i < KEYWORDS.length; i++) {
+        const keyword = KEYWORDS[i];
+        if (keyword === undefined) {
+            continue;
+        }
+        const target = highestStable(keywordRange(keyword, current), versions);
+        if (target !== undefined) {
+            return { keyword, target };
+        }
+    }
+    return undefined;
+};
+/**
+ * What a revision means, as a concrete published version — or a structured
+ * reason it does not.
+ *
+ * Reports the resolution rather than judging it: it does **not** judge whether
+ * the result is an upgrade; the caller compares against `current` and refuses a
+ * sideways or downward move.
+ *
+ * Keyword resolution skips prereleases (see `highestStable`). Only an explicit
+ * dist-tag or an exact version reaches a `-next.N`, so `upgrade minor` on the
+ * stable line never drifts onto the collection branch.
+ */
+export const resolveTarget = ({ revision, current, versions, distTags, }) => {
+    const tagged = distTags[revision];
+    if (tagged !== undefined) {
+        return { ok: true, target: tagged };
+    }
+    if (valid(revision) !== null) {
+        if (versions.includes(revision)) {
+            return { ok: true, target: revision };
+        }
+        const sorted = rsort(versions);
+        const closest = sorted.find((version) => lt(version, revision)) ?? sorted.at(-1);
+        return { ok: false, reason: { kind: "unpublished", revision, closest } };
+    }
+    if (!isKeyword(revision)) {
+        return {
+            ok: false,
+            reason: {
+                kind: "unrecognized",
+                revision,
+                distTags: Object.keys(distTags),
+            },
+        };
+    }
+    const target = highestStable(keywordRange(revision, current), versions);
+    if (target !== undefined) {
+        return { ok: true, target };
+    }
+    return {
+        ok: false,
+        reason: {
+            kind: "no-candidate",
+            revision,
+            describes: describeKeyword(revision, current),
+            broader: broaderCandidate(revision, current, versions),
+        },
+    };
+};

package/dist/run/jscodeshift.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Whether `id` names a transform file on disk.
+ *
+ * `runSingleCodemod` calls this to decide that before it ever reaches this
+ * module's own `existsSync` check below.
+ */
+export declare const transformExists: (id: string) => boolean;
+export interface CodemodOptions {
+    /** A catalogue id — the transform file name without its extension. */
+    id: string;
+    /** File or directory to transform. */
+    path: string;
+    dry?: boolean;
+    print?: boolean;
+}
+export interface CodemodResult {
+    changed: number;
+    unmodified: number;
+    /** Files the transform declined by returning nothing. */
+    skipped: number;
+    errors: number;
+    /** True when jscodeshift accounted for no file at all — see below. */
+    processedNothing: boolean;
+}
+/**
+ * Runs one codemod over a path.
+ *
+ * This drives jscodeshift's `Runner` directly rather than its CLI. The CLI only
+ * reports its counts as text, and scraping that text is not safe: `--print`
+ * writes the transformed source to stdout _before_ the summary, so a source
+ * comment like `// 42 ok` wins a regex looking for `(\d+) ok`. The Runner
+ * resolves with the counters as numbers, and it distinguishes `skip` (the
+ * transform returned nothing) from `nochange` (it returned identical source) —
+ * a difference the CLI's summary and any regex over it both lose.
+ *
+ * `processedNothing` exists because jscodeshift reports a path with no matching
+ * files and a worker that died before touching one the same way: every counter
+ * zero, no error. The caller must not render that as "0 files changed", which
+ * reads like success.
+ */
+export declare const runCodemod: ({ id, path, dry, print, }: CodemodOptions) => Promise<CodemodResult>;
+//# sourceMappingURL=jscodeshift.d.ts.map

package/dist/run/jscodeshift.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jscodeshift.d.ts","sourceRoot":"","sources":["../../src/run/jscodeshift.ts"],"names":[],"mappings":"AAuCA;;;;;GAKG;AACH,eAAO,MAAM,eAAe,OAAQ,MAAM,KAAG,OACd,CAAC;AAEhC,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,EAAE,EAAE,MAAM,CAAC;IACX,sCAAsC;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,CAAC,EAAE,OAAO,CAAC;IACd,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,sEAAsE;IACtE,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAUD;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,UAAU,8BAKpB,cAAc,KAAG,OAAO,CAAC,aAAa,CAoCxC,CAAC"}

package/dist/run/jscodeshift.js

@@ -0,0 +1,88 @@
+import { existsSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { unknownCodemodMessage } from "../catalog/entries.js";
+// jscodeshift ships no types for its Runner — `allowJs` in this repo's shared
+// tsconfig (packages/typescript-config/base.json) lets a deep import of a
+// plain `.js` file resolve without a type error, so no `@ts-expect-error` is
+// needed (and adding one here fails the build: "Unused '@ts-expect-error'
+// directive").
+import { run as runJscodeshift } from "jscodeshift/src/Runner.js";
+/**
+ * `<packageRoot>/src/migrations` and `<packageRoot>/src/tools`, from either
+ * `src/run` or `dist/run`.
+ *
+ * `dist` mirrors `src`'s directory depth, so one pair of relative paths serves
+ * the test run and the published binary. The transforms are not compiled into
+ * `dist`: jscodeshift puts a transform through its own babel pipeline, so it
+ * wants the `.ts` file.
+ */
+const migrationsDir = fileURLToPath(new URL("../../src/migrations", import.meta.url));
+const toolsDir = fileURLToPath(new URL("../../src/tools", import.meta.url));
+/**
+ * The transform file for `id`: `src/migrations/<id>/transform.ts` when `id`
+ * names a migration, otherwise `src/tools/<id>.ts`.
+ *
+ * Deliberately independent of the catalogue: `to-remote-package` is a transform
+ * with no catalogue entry (it is a port, not a migration — see `notAMigration`
+ * in `src/tests/remoteScope.test.ts`), and it still has to be runnable by id.
+ * It lives in `src/tools` rather than `src/migrations` for exactly that reason
+ * — there is no migration directory to put it beside.
+ */
+const transformPath = (id) => {
+    const migrationPath = `${migrationsDir}/${id}/transform.ts`;
+    return existsSync(migrationPath) ? migrationPath : `${toolsDir}/${id}.ts`;
+};
+/**
+ * Whether `id` names a transform file on disk.
+ *
+ * `runSingleCodemod` calls this to decide that before it ever reaches this
+ * module's own `existsSync` check below.
+ */
+export const transformExists = (id) => existsSync(transformPath(id));
+/**
+ * Runs one codemod over a path.
+ *
+ * This drives jscodeshift's `Runner` directly rather than its CLI. The CLI only
+ * reports its counts as text, and scraping that text is not safe: `--print`
+ * writes the transformed source to stdout _before_ the summary, so a source
+ * comment like `// 42 ok` wins a regex looking for `(\d+) ok`. The Runner
+ * resolves with the counters as numbers, and it distinguishes `skip` (the
+ * transform returned nothing) from `nochange` (it returned identical source) —
+ * a difference the CLI's summary and any regex over it both lose.
+ *
+ * `processedNothing` exists because jscodeshift reports a path with no matching
+ * files and a worker that died before touching one the same way: every counter
+ * zero, no error. The caller must not render that as "0 files changed", which
+ * reads like success.
+ */
+export const runCodemod = async ({ id, path, dry = false, print = false, }) => {
+    const transform = transformPath(id);
+    if (!existsSync(transform)) {
+        throw new Error(unknownCodemodMessage(id));
+    }
+    let stats;
+    try {
+        stats = (await runJscodeshift(transform, [path], {
+            parser: "tsx",
+            silent: true,
+            dry,
+            print,
+            // Without these the walk takes every file under the path. `upgrade` runs
+            // codemods after the install, so `node_modules` is freshly populated
+            // underneath — and non-JS files fail to parse, which shows up as
+            // `errors > 0` and hides the real change count.
+            extensions: "js,jsx,ts,tsx,cjs,mjs,cts,mts",
+            ignorePattern: ["**/node_modules/**", "**/dist/**", "**/.git/**"],
+        }));
+    }
+    catch (error) {
+        throw new Error(`Running ${id} failed: ${error instanceof Error ? error.message : error}`, { cause: error });
+    }
+    return {
+        changed: stats.ok,
+        unmodified: stats.nochange,
+        skipped: stats.skip,
+        errors: stats.error,
+        processedNothing: stats.ok + stats.nochange + stats.skip + stats.error === 0,
+    };
+};