@mittwald/flow-codemods 1.3.4 → 1.4.0-next.0

package/README.md

@@ -60,6 +60,56 @@ and where to get the right one — rather than installing with the wrong manager
 The log line names the agent, the pin and the command it actually ran, so a
 wrong detection is visible instead of silent.
 
+#### Peer requirements
+
+Before the install, `upgrade` prints what the Flow packages you declare peer on
+at the target — react, react-dom, react-hook-form, `@internationalized/date`,
+next, i18next — grouped by range and naming every package that asks for it:
+
+```
+Peer requirements at 1.2.4 — what the Flow packages you declare ask of your
+project:
+
+  next ^16.2.3 — optional
+    @mittwald/flow-react-components
+  react ^19.2.0 — required
+    required by @mittwald/flow-react-components
+    optional for @mittwald/ext-bridge
+```
+
+Each peer carries its status, because that is the question you have: **must I
+install this at all?** One package requiring it settles that, however many
+others call it optional — so `react` above reads `required`, and the two sides
+are broken out underneath. Where every package agrees, the status alone carries
+it.
+
+**Optionality is per package**, and it comes from `peerDependenciesMeta`: the
+same `react ^19.2.0` is a hard requirement of `flow-react-components` and an
+optional peer of `ext-bridge`. An optional peer need not be installed at all —
+it only has to match the range if it is. Most of what Flow peers on is optional,
+so the ranges alone would tell a Vite project it needs Next 16.
+
+Your package manager reports conflicts too, but only the ones it decides to name
+— Yarn's "`@mittwald/ext-bridge` and other dependencies" never enumerates the
+others. This list names every one of them, and it is printed **before** the
+install, so a failed install still leaves it on screen. `list [revision]` prints
+the same thing without touching anything.
+
+The list covers the Flow packages your `package.json` **declares**. A project
+depending only on `flow-react-components` never sees what `flow-remote-core`
+peers on, because it never asks for it.
+
+These are the ranges Flow declares, **not** a check of what you have installed.
+Nothing here reads your `node_modules`; whether your project satisfies them is
+the package manager's call during the install.
+
+A Flow-internal peer the target does not satisfy gets its own warning. Flow
+publishes those as exact pins and releases only the packages that changed, so
+the pin usually names a neighbouring release rather than the version you are
+installing — your package manager will report the conflict. Rarely the pinned
+version was never published at all; see the publish-hole caveat in the
+repository's release docs.
+
 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.
@@ -105,8 +155,11 @@ involve.
 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`
+  (`current`/`target`, or `null` for the offline whole-catalogue form),
+  `migrations`, each entry carrying `catchUp`, and `peers` — `external` and
+  `flowPins`, each a list of `{ peer, range, requiredBy, optionalFor }`, or
+  `null` for the offline whole-catalogue form, which has no target to read them
+  at
 
 ### `<id> [path]`
 

package/dist/cli/list.d.ts

@@ -1,4 +1,5 @@
 import { type CatalogEntry } from "../catalog/entries.js";
+import type { PeerSummary } from "../resolve/peers.js";
 import { type RangeDeps } from "../resolve/range.js";
 import type { ParsedCommand } from "./args.js";
 export interface RenderListInput {
@@ -13,6 +14,15 @@ export interface RenderListInput {
         to: string;
     };
     json: boolean;
+    /**
+     * The peer ranges the Flow packages declare at `range.to`, from
+     * `resolveRange`.
+     *
+     * Only meaningful together with `range`, and omitted by `upgrade`, which
+     * prints its own peer section before the install rather than inside this list
+     * — see `runUpgrade`.
+     */
+    peers?: PeerSummary;
     /** Emit ANSI colour. Off by default so a test sees plain text. */
     color?: boolean;
     /** Terminal width to wrap prose to. */
@@ -47,7 +57,6 @@ export interface RenderListInput {
      */
     frame?: boolean;
 }
-export declare const stripAnsi: (text: string) => string;
 /**
  * The invocation to print when nobody says otherwise.
  *
@@ -67,7 +76,7 @@ export declare const defaultInvoke = "npx @mittwald/flow-codemods@latest";
  * 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, path, invoke, frame, }: RenderListInput) => string;
+export declare const renderList: ({ entries, range, json, peers, color, width, path, invoke, frame, }: RenderListInput) => string;
 export interface ListDeps extends RangeDeps {
     /**
      * Raw output writer — matches `process.stdout.write`'s own contract: no

package/dist/cli/list.js

@@ -1,8 +1,9 @@
-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";
+import { renderPeers } from "./peers.js";
+import { painter, wrap } from "./text.js";
 /**
  * What the reader has to do, and the colour that says it at a glance.
  *
@@ -21,39 +22,6 @@ const actions = {
         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.
  *
@@ -62,27 +30,6 @@ const wrap = (text, width) => {
  * 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,
-    };
-};
 /**
  * The invocation to print when nobody says otherwise.
  *
@@ -210,7 +157,7 @@ const renderSummary = (selected, color) => {
  * 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, path = "src", invoke = defaultInvoke, frame = true, }) => {
+export const renderList = ({ entries, range, json, peers, color = false, width = 80, path = "src", invoke = defaultInvoke, 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
@@ -235,10 +182,21 @@ export const renderList = ({ entries, range, json, color = false, width = 80, pa
                 ...entry,
                 catchUp: isCatchUp(entry, range?.from),
             })),
+            // `null` rather than omitted, so a consumer can tell "no peers at this
+            // target" from "this form does not carry peers" — a bare `list` has no
+            // range to read them at.
+            peers: peers ?? null,
         }, null, 2)}\n`;
     }
+    // A property of the range, not of the entries, so it prints even when no
+    // migration falls in it: a consumer already sitting on `target` can still be
+    // missing a peer, and that is exactly the range that selects nothing.
+    const peerSection = peers === undefined || range === undefined
+        ? ""
+        : renderPeers({ summary: peers, target: range.to, color, width });
     if (selected.length === 0) {
-        return "Nothing to migrate in that range.\n";
+        const nothing = "Nothing to migrate in that range.\n";
+        return peerSection === "" ? nothing : `${nothing}\n${peerSection}`;
     }
     const body = selected
         .map((entry) => renderEntry(entry, width, color, isCatchUp(entry, range?.from), path, invoke))
@@ -253,7 +211,7 @@ export const renderList = ({ entries, range, json, color = false, width = 80, pa
     // 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`;
+    return `${context === "" ? "" : `${context}\n\n`}${peerSection === "" ? "" : `${peerSection}\n`}${body}\n\n${summary}\n`;
 };
 export const defaultListDeps = (cwd) => ({
     ...defaultRangeDeps(cwd),
@@ -295,6 +253,7 @@ export const runList = async (parsed, deps) => {
         entries: allEntries,
         range: { from: resolved.current, to: resolved.target },
         json: parsed.json,
+        peers: resolved.peers,
         color: deps.color,
         width: deps.width,
         path: deps.path,

package/dist/cli/peers.d.ts

@@ -0,0 +1,22 @@
+import type { PeerSummary } from "../resolve/peers.js";
+export interface RenderPeersInput {
+    summary: PeerSummary;
+    /** The version the ranges were read at. */
+    target: string;
+    /** Emit ANSI colour. Off by default so a test sees plain text. */
+    color?: boolean;
+    /** Terminal width to wrap prose to. */
+    width?: number;
+}
+/**
+ * The peer ranges the Flow packages declare at `target`.
+ *
+ * Returns `""` when there is nothing to say, so a caller can print it
+ * unconditionally.
+ *
+ * The closing line is not a disclaimer for its own sake: without it the list
+ * reads as a check that passed. It is not one — nothing here looks at what the
+ * project has installed (see `collectPeers`), and a reader who assumes
+ * otherwise would take silence for a green light.
+ */
+export declare const renderPeers: ({ summary, target, color, width, }: RenderPeersInput) => string;

package/dist/cli/peers.js

@@ -0,0 +1,73 @@
+import { hasPeers } from "../resolve/peers.js";
+import { painter, wrap } from "./text.js";
+const indent = "  ";
+/**
+ * One requirement: the peer and its range on top, who asks for it below.
+ *
+ * The askers go on their own wrapped line rather than trailing the range — at
+ * eight Flow packages the list is longer than the range it belongs to, and
+ * inline it pushes the next range off the scannable left edge.
+ *
+ * Both lists are labelled, even when only one is present. An unlabelled list
+ * with a marker appended somewhere would leave the reader guessing how far the
+ * marker reaches — and "does this project actually need react?" is the whole
+ * question this output exists to answer.
+ */
+const renderRequirement = ({ peer, range, requiredBy, optionalFor }, width, paint) => {
+    const gutter = indent.repeat(2);
+    const required = requiredBy.length > 0;
+    // The status sits on the peer line, in colour, because it answers the
+    // question the reader actually has — "must I install this at all?" — and one
+    // package requiring it settles that no matter how many others call it
+    // optional. Underneath everything is dim, so each entry has exactly one
+    // bright thing to land on when scanning.
+    const status = required ? paint.yellow("required") : paint.dim("optional");
+    // Only a disagreement earns the two labelled lines. Where every package
+    // treats the peer the same way, the labels would repeat what the status
+    // already said, once per entry, for the whole list.
+    const rows = required && optionalFor.length > 0
+        ? [
+            ["required by ", requiredBy],
+            ["optional for ", optionalFor],
+        ]
+        : [["", required ? requiredBy : optionalFor]];
+    const askers = rows
+        .flatMap(([label, names]) => wrap(`${label}${names.join(", ")}`, Math.max(width - gutter.length, 20)).map((line) => `${gutter}${paint.dim(line)}`))
+        .join("\n");
+    return `${indent}${paint.bold(peer)} ${paint.code(range)} — ${status}\n${askers}`;
+};
+/**
+ * The peer ranges the Flow packages declare at `target`.
+ *
+ * Returns `""` when there is nothing to say, so a caller can print it
+ * unconditionally.
+ *
+ * The closing line is not a disclaimer for its own sake: without it the list
+ * reads as a check that passed. It is not one — nothing here looks at what the
+ * project has installed (see `collectPeers`), and a reader who assumes
+ * otherwise would take silence for a green light.
+ */
+export const renderPeers = ({ summary, target, color = false, width = 80, }) => {
+    if (!hasPeers(summary)) {
+        return "";
+    }
+    const paint = painter(color);
+    const sections = [];
+    if (summary.external.length > 0) {
+        sections.push([
+            ...wrap(`Peer requirements at ${paint.bold(target)} — what the Flow packages you declare ask of your project:`, width),
+            "",
+            ...summary.external.map((requirement) => renderRequirement(requirement, width, paint)),
+            "",
+            ...wrap(paint.dim("Ranges as Flow declares them, not a check of what you have installed — your package manager decides that during the install. An optional peer need not be installed at all; it only has to match the range if it is."), width),
+        ].join("\n"));
+    }
+    if (summary.flowPins.length > 0) {
+        sections.push([
+            ...wrap(paint.yellow(`${summary.flowPins.length} Flow-internal peer pin(s) do not accept ${target}. Flow publishes these as exact pins and releases only the packages that changed, so a pin usually names a neighbouring release rather than the version you are installing — your package manager will report the conflict. Rarely the pinned version was never published at all (#2887).`), width),
+            "",
+            ...summary.flowPins.map((requirement) => renderRequirement(requirement, width, paint)),
+        ].join("\n"));
+    }
+    return `${sections.join("\n\n")}\n`;
+};

package/dist/cli/text.d.ts

@@ -0,0 +1,27 @@
+/**
+ * A palette key from `painter()` — see the `tone` field on `actions` in
+ * `list.ts`.
+ */
+export type Tone = "green" | "yellow" | "blue";
+export declare const stripAnsi: (text: string) => string;
+/**
+ * Wraps to `width`, measuring visible width so already-coloured text still
+ * breaks in the right place.
+ */
+export declare const wrap: (text: string, width: number) => string[];
+export interface Painter extends Record<Tone, (text: string) => string> {
+    bold: (text: string) => string;
+    dim: (text: string) => string;
+    code: (text: string) => string;
+}
+/**
+ * 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.
+ */
+export declare const painter: (color: boolean) => Painter;

package/dist/cli/text.js

@@ -0,0 +1,62 @@
+/**
+ * Terminal text helpers shared by the renderers in this directory.
+ *
+ * They live here rather than in `list.ts` because `peers.ts` needs them too,
+ * and `list.ts` imports `peers.ts` to render its own peer section — keeping
+ * them there would make that pair circular.
+ */
+import colors from "picocolors";
+/**
+ * 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.
+ */
+export 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 : [""];
+};
+/**
+ * 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.
+ */
+export 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,
+    };
+};

package/dist/cli/upgrade.js

@@ -12,6 +12,7 @@ import { readInstalledVersion, resolveRange } from "../resolve/range.js";
 import { runCodemod } from "../run/jscodeshift.js";
 import { displaySourcePath, resolveSourcePath } from "./codemod.js";
 import { renderList } from "./list.js";
+import { renderPeers } from "./peers.js";
 export const defaultUpgradeDeps = (cwd) => ({
     cwd,
     fetchVersions,
@@ -86,7 +87,7 @@ export const runUpgrade = async (parsed, deps) => {
         log(range.reason);
         return 1;
     }
-    const { manifestPath, manifestRaw, manifest, dependencies, current, target } = range;
+    const { manifestPath, manifestRaw, manifest, dependencies, current, target, peers, } = 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
@@ -105,15 +106,36 @@ export const runUpgrade = async (parsed, deps) => {
                 : `  ${dependency.name} ${dependency.range} — left as it is, ${dependency.field} states what your package supports, not what it installs`);
         }
     };
+    // Printed before the install in every branch, never after it: the install
+    // can fail (and returns early below), yet a peer range the new version needs
+    // is exactly what the reader wants in hand when it does. It is also the one
+    // part of this output that stays true when nothing is bumped at all — a
+    // project sitting on `target` can still be missing a peer.
+    const reportPeers = () => {
+        const rendered = renderPeers({
+            summary: peers,
+            target,
+            color: deps.color,
+            width: deps.width,
+        });
+        if (rendered !== "") {
+            // Blank line on both sides: this sits between the dependency list and
+            // whatever the install prints next, and without the trailing one the
+            // package manager's first line reads as part of the summary.
+            log(`\n${rendered.trimEnd()}\n`);
+        }
+    };
     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.`);
+        reportPeers();
     }
     else if (dry) {
         log(`Upgrading Flow from ${current} to ${target} (--dry)`);
         log(`--dry: would write the following to ${manifestPath}:`);
         reportDependencies();
+        reportPeers();
         log("--dry: skipping the install.");
     }
     else {
@@ -121,6 +143,7 @@ export const runUpgrade = async (parsed, deps) => {
         const indent = detectIndent(manifestRaw);
         writeFileSync(manifestPath, `${JSON.stringify(applyTarget(manifest, target, flowPackages), null, indent)}\n`, "utf8");
         reportDependencies();
+        reportPeers();
         const manager = await detectPackageManagerIn(cwd);
         try {
             // Logged after the run, not before: `install` returns what it actually

package/dist/migrations.generated.js

@@ -3,6 +3,15 @@
 // Source: packages/codemods/src/migrations/<id>/entry.md
 /** Every migration, newest first. Bodies live in `src/migrations`. */
 export const migrations = [
+    {
+        id: "image-rounded-corners-default",
+        since: "1.3.0",
+        title: "Image: rounded corners by default, withBorder draws only the border",
+        kind: "migration",
+        action: "none",
+        remotePackage: true,
+        apply: "No code change required. To keep square corners on an `Image` without `withBorder`, pass `withRoundedCorners={false}`.",
+    },
     {
         id: "popover-open-state-props",
         since: "1.1.47",
@@ -207,7 +216,7 @@ export const migrations = [
         title: "Form: resets itself after the surrounding modal closes",
         kind: "migration",
         action: "none",
-        remotePackage: true,
+        remotePackage: false,
         apply: "No code change required. To keep the previous behaviour (the form keeping what the user entered), pass `autoReset={false}` (or `autoReset={{ onAfterModalClose: false }}`) to `Form`.",
     },
     {

package/dist/resolve/peers.d.ts

@@ -0,0 +1,64 @@
+import type { PackageVersions } from "./registry.js";
+/** One peer range, and how each Flow package that states it treats it. */
+export interface PeerRequirement {
+    /** The peer package, e.g. `react`. */
+    peer: string;
+    /** The range, exactly as the Flow packages authored it. */
+    range: string;
+    /** The declared Flow dependencies that require it, sorted. */
+    requiredBy: string[];
+    /**
+     * The declared Flow dependencies that mark it `optional`, sorted.
+     *
+     * Separate from `requiredBy` rather than a flag on the requirement, because
+     * optionality is **per package**: at 1.2.2 `react ^19.2.0` is required by
+     * `flow-react-components` and optional for `ext-bridge`. One line carrying
+     * both lists says that; a single boolean would have to pick a side, and
+     * either choice is wrong for half the readers.
+     */
+    optionalFor: string[];
+}
+export interface PeerSummary {
+    /**
+     * Everything the Flow packages peer on that is not itself a Flow package —
+     * react, react-hook-form, next, i18next and the rest.
+     */
+    external: PeerRequirement[];
+    /**
+     * Flow-internal peers the target does **not** satisfy.
+     *
+     * Flow's internal peers publish as exact pins (`@mittwald/flow-remote-core`
+     * peers on `@mittwald/flow-react-components: "1.1.52"`), so the expected case
+     * — the pin naming the version being installed — is noise. What is not noise
+     * is a pin pointing somewhere else: upgrading every declared package to one
+     * target then leaves it unsatisfied, and nothing else in the output says so.
+     *
+     * This is not hypothetical. Across the published history of the five remote
+     * packages, 2253 of 6210 Flow-internal peer entries pin a version other than
+     * the one they ship with — e.g. `flow-remote-core@0.2.0-alpha.700` peers on
+     * `ext-bridge@0.2.0-alpha.699`.
+     *
+     * What it usually is **not** is a publish hole. Lerna releases only the
+     * packages that changed, so the pin names a neighbouring release that exists:
+     * 2207 of those 2253 point at a published version, leaving 46 that are
+     * genuinely missing (#2887). The rendered warning leads with the common cause
+     * for that reason (#3204 review).
+     */
+    flowPins: PeerRequirement[];
+}
+/**
+ * What the declared Flow dependencies require of their peers at `target`.
+ *
+ * Grouped by peer **and** range, not by peer alone: two Flow packages asking
+ * for different ranges of the same peer is precisely what a consumer needs to
+ * see, and collapsing them would hide it. Optionality does **not** split a
+ * group — it is recorded per package inside it (see `optionalFor`).
+ *
+ * Ranges are reported exactly as authored — this never decides whether the
+ * project satisfies them. That is the package manager's job, it already does it
+ * during the install, and a second opinion here could only drift from the one
+ * that actually gates.
+ */
+export declare const collectPeers: (packages: PackageVersions[], target: string, flowPackages: string[]) => PeerSummary;
+/** Whether a summary has anything worth printing. */
+export declare const hasPeers: (summary: PeerSummary) => boolean;

package/dist/resolve/peers.js

@@ -0,0 +1,72 @@
+import { satisfies, validRange } from "semver";
+/**
+ * Whether a Flow-internal peer pin is the unremarkable one.
+ *
+ * `satisfies` rather than a string compare, so a genuine range (`^1.1.0`) is as
+ * expected as the exact pin the publish pipeline usually writes. An unparseable
+ * range — `workspace:*`, from a package resolved straight out of a checkout
+ * rather than the registry — is not a claim about `target` at all, so it is
+ * reported rather than silently judged.
+ *
+ * `includePrerelease` is load-bearing, not tidiness: without it a prerelease
+ * satisfies **no** non-prerelease range, `*` included. The historical
+ * Flow-internal pin _is_ `*` (2328 of 6210 published entries), and `next` and
+ * `experimental` are prerelease dist-tags — so every prerelease target reported
+ * a publish hole for a pin that accepts everything.
+ */
+const expectedFlowPin = (range, target) => validRange(range) !== null &&
+    satisfies(target, range, { includePrerelease: true });
+/**
+ * Ties break on the string, not on the locale.
+ *
+ * `localeCompare` depends on the runtime's ICU data, which differs between Node
+ * builds and would reorder hyphenated names like `react-dom` from one machine
+ * to the next — including between a developer's run and CI's.
+ */
+const byString = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
+/**
+ * What the declared Flow dependencies require of their peers at `target`.
+ *
+ * Grouped by peer **and** range, not by peer alone: two Flow packages asking
+ * for different ranges of the same peer is precisely what a consumer needs to
+ * see, and collapsing them would hide it. Optionality does **not** split a
+ * group — it is recorded per package inside it (see `optionalFor`).
+ *
+ * Ranges are reported exactly as authored — this never decides whether the
+ * project satisfies them. That is the package manager's job, it already does it
+ * during the install, and a second opinion here could only drift from the one
+ * that actually gates.
+ */
+export const collectPeers = (packages, target, flowPackages) => {
+    const grouped = new Map();
+    for (const pkg of packages) {
+        const peers = pkg.peerDependencies[target] ?? {};
+        for (const [peer, { range, optional }] of Object.entries(peers)) {
+            // Keyed on both halves, so the two sides of a disagreement survive as
+            // two entries. JSON rather than a joined string: no separator to pick
+            // that a package name or a range could contain.
+            const key = JSON.stringify([peer, range]);
+            const existing = grouped.get(key) ?? {
+                peer,
+                range,
+                requiredBy: [],
+                optionalFor: [],
+            };
+            (optional ? existing.optionalFor : existing.requiredBy).push(pkg.name);
+            grouped.set(key, existing);
+        }
+    }
+    const sorted = [...grouped.values()]
+        .map((requirement) => ({
+        ...requirement,
+        requiredBy: [...requirement.requiredBy].sort(byString),
+        optionalFor: [...requirement.optionalFor].sort(byString),
+    }))
+        .sort((a, b) => byString(a.peer, b.peer) || byString(a.range, b.range));
+    return {
+        external: sorted.filter(({ peer }) => !flowPackages.includes(peer)),
+        flowPins: sorted.filter(({ peer, range }) => flowPackages.includes(peer) && !expectedFlowPin(range, target)),
+    };
+};
+/** Whether a summary has anything worth printing. */
+export const hasPeers = (summary) => summary.external.length > 0 || summary.flowPins.length > 0;

package/dist/resolve/range.d.ts

@@ -1,4 +1,5 @@
 import { type FlowDependency, type Manifest } from "../manifest.js";
+import { type PeerSummary } from "./peers.js";
 import { fetchVersions } from "./registry.js";
 /**
  * The installed version of `name`, read from `cwd`'s `node_modules`.
@@ -23,6 +24,16 @@ export interface ResolvedRange {
     current: string;
     target: string;
     versions: string[];
+    /**
+     * What the declared Flow dependencies peer on at `target` — the answer to
+     * "which Flow package needs which peer range", which otherwise takes reading
+     * every Flow `package.json` by hand (#3059).
+     *
+     * Resolved here rather than in either command because both need it and the
+     * packuments are already fetched above: `list <revision>` can then answer it
+     * before anything is written, which is where the answer is worth most.
+     */
+    peers: PeerSummary;
 }
 export interface UnresolvedRange {
     ok: false;

package/dist/resolve/range.js

@@ -3,6 +3,7 @@ import { join } from "node:path";
 import { rsort } from "semver";
 import { flowPackages } from "../flowPackages.generated.js";
 import { detectCurrentVersion, findFlowDependencies, } from "../manifest.js";
+import { collectPeers } from "./peers.js";
 import { fetchAllVersions, fetchVersions, intersectVersions, } from "./registry.js";
 import { resolveTarget } from "./target.js";
 /**
@@ -128,7 +129,14 @@ export const resolveRange = async (revision, deps) => {
     // 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);
+    // Deduplicated, because `findFlowDependencies` returns one entry per
+    // manifest *field*: a library that wraps Flow declares it in both
+    // `peerDependencies` and `devDependencies`, and that package would otherwise
+    // be fetched twice and counted twice — once per field — in every peer line it
+    // appears in (#3204 review). `dependencies` itself keeps both entries, on
+    // purpose: the two fields are reported separately, one rewritten and one left
+    // alone.
+    const fetched = await fetchAllVersions([...new Set(dependencies.map(({ name }) => name))], deps.fetchVersions);
     const versions = intersectVersions(fetched);
     if (versions.length === 0) {
         return {
@@ -169,5 +177,6 @@ export const resolveRange = async (revision, deps) => {
         current,
         target,
         versions,
+        peers: collectPeers(fetched, target, flowPackages),
     };
 };

package/dist/resolve/registry.d.ts

@@ -1,12 +1,37 @@
+/** A peer range as a Flow package declares it. */
+export interface PeerDeclaration {
+    range: string;
+    /**
+     * Whether the declaring package marks this peer `optional`.
+     *
+     * Npm splits one declaration across two fields — the range in
+     * `peerDependencies`, the flag in `peerDependenciesMeta` — and a reader that
+     * takes only the first turns every optional peer into a hard requirement. The
+     * two are joined here, at the one place that knows the packument's encoding,
+     * so nothing downstream can read a range without its flag (#3059).
+     */
+    optional: boolean;
+}
 export interface RegistryVersions {
     versions: string[];
     distTags: Record<string, string>;
+    /**
+     * What each published version declares as peers, keyed by version.
+     *
+     * Kept rather than discarded because the abbreviated packument below carries
+     * it for free — see `fetchVersions`. A version with no peers maps to an empty
+     * object, so a lookup never has to distinguish "none" from "not fetched".
+     */
+    peerDependencies: Record<string, Record<string, PeerDeclaration>>;
 }
 /**
  * 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.
+ * with hundreds of releases is megabytes, and none of it is needed here. The
+ * abbreviated form still carries `peerDependencies` and `peerDependenciesMeta`
+ * per version, which is why the peer summary costs no request of its own
+ * (#3059).
  */
 export declare const fetchVersions: (packageName: string) => Promise<RegistryVersions>;
 export interface PackageVersions extends RegistryVersions {

package/dist/resolve/registry.js

@@ -1,4 +1,12 @@
 import registryUrl from "registry-url";
+/** One version's peers, with the optional flag folded into each range. */
+const declaredPeers = (manifest) => Object.fromEntries(Object.entries(manifest?.peerDependencies ?? {}).map(([peer, range]) => [
+    peer,
+    {
+        range,
+        optional: manifest?.peerDependenciesMeta?.[peer]?.optional === true,
+    },
+]));
 /**
  * The registry that actually serves `@mittwald`, from the consumer's npm
  * config.
@@ -18,7 +26,10 @@ const registryFor = (packageName) => {
  * 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.
+ * with hundreds of releases is megabytes, and none of it is needed here. The
+ * abbreviated form still carries `peerDependencies` and `peerDependenciesMeta`
+ * per version, which is why the peer summary costs no request of its own
+ * (#3059).
  */
 export const fetchVersions = async (packageName) => {
     // One wrapper for every failure, not just the HTTP one: `fetch` itself rejects
@@ -38,9 +49,11 @@ export const fetchVersions = async (packageName) => {
     catch (error) {
         throw new Error(`Could not read ${packageName} from the npm registry: ${error instanceof Error ? error.message : error}`, { cause: error });
     }
+    const versions = Object.entries(packument.versions ?? {});
     return {
-        versions: Object.keys(packument.versions ?? {}),
+        versions: versions.map(([version]) => version),
         distTags: packument["dist-tags"] ?? {},
+        peerDependencies: Object.fromEntries(versions.map(([version, manifest]) => [version, declaredPeers(manifest)])),
     };
 };
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mittwald/flow-codemods",
-  "version": "1.3.4",
+  "version": "1.4.0-next.0",
   "type": "module",
   "description": "Codemods and an upgrade CLI for consumers of Flow, mittwald's design system",
   "homepage": "https://flow.mittwald.de",
@@ -38,5 +38,5 @@
     "vitest": "^4.1.11",
     "yaml": "^2.8.1"
   },
-  "gitHead": "26452168e2d824f62fcb1c5d6b589229e5571d92"
+  "gitHead": "d3cf8325cc06635accd2c170750429f9c834c87c"
 }