@fairgarden/distribution 0.1.0-0.canary.0

package/dist/policy.js

@@ -0,0 +1,269 @@
+import { spawnSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { copyFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import path from 'node:path';
+/**
+ * A distribution's policy: the organization's rules for every service it
+ * ships, kept in `policies/` beside `apps/` and `packages/`, and marked by the
+ * `.manifest` that says whose they are.
+ *
+ * It is built in layers — each module's own `policies/`, then the policy of
+ * any distribution this one extends, then its own — into one bundle, named
+ * after the distribution's version and what is in it. `policies/` is a
+ * workspace package, so turbo builds it once, and every service's build
+ * takes a copy (`fg-dist policy use`) to run. Upgrading a module brings its
+ * rules; the organization's stay as they were.
+ *
+ * Compiling is `@fairgarden/policy`'s: this finds the layers and hands them
+ * to whichever `fg-policy` the distribution installed.
+ */
+export const POLICIES = 'policies';
+/** Where the bundle is built, inside `policies/`. */
+export const BUILT = path.join('dist', 'policies.tar.gz');
+/** Where a service runs it from, inside the service; `@fairgarden/policy` looks there. */
+export const USED = path.join('.policy', 'policies.tar.gz');
+/** What marks a project as running the policy, in its build script. */
+const USES = 'fg-dist policy use';
+const readJson = (file) => JSON.parse(readFileSync(file, 'utf8'));
+/** A `policies/` with a `.manifest` is an organization's; a module's own has none. */
+const isOrganizations = (dir) => existsSync(path.join(dir, '.manifest'));
+/** The published policy of what `root` extends, and of what that extends, the furthest first. */
+const parentsOf = (root, seen = new Set()) => {
+    const parent = readJson(path.join(root, 'package.json')).distribution?.extends;
+    if (!parent || seen.has(parent))
+        return [];
+    seen.add(parent);
+    let parentRoot;
+    try {
+        parentRoot = path.dirname(createRequire(path.join(root, 'package.json')).resolve(`${parent}/package.json`));
+    }
+    catch {
+        // Not installed: `fg-dist check` says so; there is nothing to build on.
+        return [];
+    }
+    const dir = path.join(parentRoot, POLICIES);
+    return [...parentsOf(parentRoot, seen), ...(isOrganizations(dir) ? [dir] : [])];
+};
+const describe = (root) => {
+    const bases = [];
+    for (const group of ['apps', 'packages']) {
+        const entries = existsSync(path.join(root, group)) ? readdirSync(path.join(root, group)).sort() : [];
+        for (const name of entries) {
+            const dir = path.join(root, group, name, POLICIES);
+            if (existsSync(dir) && statSync(dir).isDirectory() && !isOrganizations(dir))
+                bases.push(dir);
+        }
+    }
+    const dir = path.join(root, POLICIES);
+    return {
+        root,
+        dir,
+        version: readJson(path.join(root, 'package.json')).version,
+        bases,
+        parents: parentsOf(root),
+        built: path.join(dir, BUILT),
+    };
+};
+/**
+ * The distribution around `from`, if it has a policy: the nearest directory
+ * above with an organization's `policies/`. Found on disk rather than by
+ * git, which a build host may not have, and which stops at a submodule.
+ */
+export const findPolicy = (from) => {
+    for (let dir = path.resolve(from);; dir = path.dirname(dir)) {
+        if (path.basename(dir) === POLICIES && isOrganizations(dir))
+            return describe(path.dirname(dir));
+        if (isOrganizations(path.join(dir, POLICIES)))
+            return describe(dir);
+        if (path.dirname(dir) === dir)
+            return undefined;
+    }
+};
+/** Where a package is installed, seen from `base`, whether or not it exports its package.json. */
+const packageDir = (base, name) => {
+    const require = createRequire(path.join(base, 'package.json'));
+    try {
+        return path.dirname(require.resolve(`${name}/package.json`));
+    }
+    catch {
+        // Not exported: find it from its entry point instead.
+    }
+    try {
+        for (let dir = path.dirname(require.resolve(name)); path.dirname(dir) !== dir; dir = path.dirname(dir)) {
+            const file = path.join(dir, 'package.json');
+            if (existsSync(file) && readJson(file).name === name)
+                return dir;
+        }
+    }
+    catch {
+        // Not installed here.
+    }
+    return undefined;
+};
+/** The `fg-policy` the distribution installed, from `from` or its root. */
+const fgPolicy = (policy, from) => {
+    for (const base of [from, policy.dir, policy.root]) {
+        const dir = packageDir(base, '@fairgarden/policy');
+        if (!dir)
+            continue;
+        const { bin } = readJson(path.join(dir, 'package.json'));
+        return path.join(dir, bin['fg-policy']);
+    }
+    throw new Error('@fairgarden/policy is not installed here; add it to policies/package.json.');
+};
+const layerArgs = (policy) => {
+    const relative = (dir) => path.relative(policy.root, dir);
+    return [
+        '--dir',
+        relative(policy.dir),
+        ...policy.bases.flatMap((dir) => ['--base', relative(dir)]),
+        ...policy.parents.flatMap((dir) => ['--parent', relative(dir)]),
+    ];
+};
+const run = (policy, from, args) => {
+    const result = spawnSync(process.execPath, [fgPolicy(policy, from), ...args], { cwd: policy.root, stdio: 'inherit' });
+    if (result.error)
+        throw result.error;
+    return result.status ?? 1;
+};
+/**
+ * What the bundle is built from, as a digest: every rule, setting and
+ * manifest in every layer, and the version it is named after. A bundle built
+ * from anything else — a rule since changed, added or deleted — is out of date.
+ */
+export const inputsDigest = (policy) => {
+    const hash = createHash('sha256').update(`${policy.version ?? ''}\0`);
+    for (const dir of [...policy.bases, ...policy.parents, policy.dir]) {
+        const files = readdirSync(dir, { recursive: true, encoding: 'utf8' })
+            .filter((file) => !file.split(path.sep).some((part) => part === 'node_modules' || part === 'dist'))
+            .filter((file) => /(\.rego|data\.json|\.manifest)$/.test(file))
+            .sort();
+        for (const file of files) {
+            hash.update(`${path.relative(policy.root, path.join(dir, file)).split(path.sep).join('/')}\0`);
+            hash.update(readFileSync(path.join(dir, file))).update('\0');
+        }
+    }
+    return hash.digest('hex');
+};
+/** Beside the bundle: the digest of what it was built from. */
+const inputsFile = (built) => `${built}.inputs`;
+/** Build the bundle, named after the distribution's version. */
+export const buildPolicy = (policy, from = policy.root, out = policy.built) => {
+    const digest = inputsDigest(policy);
+    const status = run(policy, from, [
+        'build',
+        ...layerArgs(policy),
+        ...(policy.version ? ['--release', policy.version] : []),
+        '--out',
+        out,
+    ]);
+    if (status === 0)
+        writeFileSync(inputsFile(out), `${digest}\n`);
+    return status;
+};
+/** Each module's tests on its own rules, then the organization's on them all. */
+export const testPolicy = (policy, from = policy.root) => run(policy, from, ['test', ...layerArgs(policy)]);
+/**
+ * Put the distribution's policy beside the service in `project`, for it to
+ * run: the bundle turbo already built, or one built now if there is none, or
+ * it was built from anything other than the rules as they are. Outside a
+ * distribution, nothing — and no copy left from before: the service's
+ * built-in rules decide.
+ */
+export const usePolicy = (project) => {
+    const used = path.join(project, USED);
+    const policy = findPolicy(project);
+    if (!policy) {
+        rmSync(used, { force: true });
+        return { status: 0 };
+    }
+    const built = existsSync(inputsFile(policy.built)) ? readFileSync(inputsFile(policy.built), 'utf8').trim() : undefined;
+    if (!existsSync(policy.built) || built !== inputsDigest(policy)) {
+        const status = buildPolicy(policy, project);
+        if (status !== 0)
+            return { policy, status };
+    }
+    mkdirSync(path.dirname(used), { recursive: true });
+    // Whole or not at all, for a server reading it meanwhile.
+    const partial = `${used}.${process.pid}.partial`;
+    copyFileSync(policy.built, partial);
+    renameSync(partial, used);
+    return { policy, status: 0 };
+};
+/** `list` with `entry` at the end, unless it has it already. */
+const including = (list, entry) => list?.includes(entry) ? list : [...(list ?? []), entry];
+/**
+ * What turbo needs, so the policy is built once however many services run
+ * it: the policy's own tasks, which read every module's rules as well as its
+ * own, and each project whose build uses it waiting for it to be built.
+ *
+ * A project's task is the generic one plus the policy, unless `existing`
+ * already has one for it: that is kept as it is — a monolith's waits for its
+ * apps' libraries rather than their builds, say — and only gains the policy.
+ */
+export const turboTasks = (policy, generic, genericDev = { persistent: true, cache: false }, existing = {}) => {
+    const name = readJson(path.join(policy.dir, 'package.json')).name;
+    if (!name)
+        throw new Error(`${path.join(POLICIES, 'package.json')} needs a name.`);
+    const inputs = [
+        '$TURBO_DEFAULT$',
+        '$TURBO_ROOT$/apps/*/policies/**',
+        '$TURBO_ROOT$/packages/*/policies/**',
+        // The distribution's version names every revision.
+        '$TURBO_ROOT$/package.json',
+        // What it extends is installed, so its policy changes with the lockfile.
+        ...(policy.parents.length > 0 ? ['$TURBO_ROOT$/pnpm-lock.yaml'] : []),
+    ];
+    // Not hashed: which opa compiles it changes nothing, and the commit is only
+    // where a revision was first built — the same rules are the same revision.
+    // A signing key is hashed, so adding one does not bring back an unsigned build.
+    const passThroughEnv = ['OPA', 'VERCEL_GIT_COMMIT_SHA', 'GITHUB_SHA'];
+    const tasks = {
+        [`${name}#build`]: { dependsOn: ['^build'], inputs, outputs: ['dist/**'], env: ['FG_POLICY_SIGNING_KEY'], passThroughEnv },
+        [`${name}#test`]: { dependsOn: ['^build'], inputs, passThroughEnv: ['OPA'] },
+    };
+    for (const group of ['apps', 'packages']) {
+        const entries = existsSync(path.join(policy.root, group)) ? readdirSync(path.join(policy.root, group)).sort() : [];
+        for (const entry of entries) {
+            const file = path.join(policy.root, group, entry, 'package.json');
+            if (!existsSync(file))
+                continue;
+            const pkg = readJson(file);
+            if (!pkg.name)
+                continue;
+            if (pkg.scripts?.build?.includes(USES)) {
+                const base = existing[`${pkg.name}#build`] ?? generic;
+                tasks[`${pkg.name}#build`] = {
+                    ...base,
+                    dependsOn: including(base.dependsOn, `${name}#build`),
+                    // The copy it runs is part of what it built: a cached build brings it back.
+                    outputs: including(base.outputs, `${path.dirname(USED)}/**`),
+                };
+            }
+            // A fresh checkout has built neither the policy nor the tools that build it.
+            if (pkg.scripts?.dev?.includes(USES)) {
+                const base = existing[`${pkg.name}#dev`] ?? genericDev;
+                tasks[`${pkg.name}#dev`] = { ...base, dependsOn: including(base.dependsOn, `${name}#build`) };
+            }
+        }
+    }
+    return tasks;
+};
+/**
+ * Write the policy's tasks into turbo.json, or with `check`, say which are
+ * missing or out of date. Returns what differed.
+ */
+export const setupTurbo = (policy, { check = false } = {}) => {
+    const file = path.join(policy.root, 'turbo.json');
+    const turbo = readJson(file);
+    const tasks = turbo.tasks ?? {};
+    const wanted = turboTasks(policy, tasks.build ?? { dependsOn: ['^build'] }, tasks.dev, tasks);
+    const differ = Object.keys(wanted).filter((key) => JSON.stringify(tasks[key]) !== JSON.stringify(wanted[key]));
+    if (!check && differ.length > 0) {
+        turbo.tasks = { ...tasks, ...wanted };
+        writeFileSync(file, `${JSON.stringify(turbo, null, 2)}\n`);
+    }
+    return differ;
+};
+//# sourceMappingURL=policy.js.map

package/dist/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../src/policy.ts"],"names":[],"mappings":"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"}

package/dist/readme.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Replace the block a marker delimits, or add one.
+ *
+ * A new block goes after the first heading, which is where someone looking for
+ * a version would look first.
+ */
+export declare const updateSection: (source: string, marker: string, body: string, 
+/**
+ * Marker whose block this one belongs under, when it has to be inserted.
+ * Without it a new block goes straight after the first heading, which means
+ * whichever block is written last ends up on top.
+ */
+after?: string) => string;
+export interface ModuleVersion {
+    name: string;
+    /** The version its own package.json declares. */
+    version: string;
+    relativePath: string;
+    /** The commit the distribution pins. */
+    pinned: string;
+    /** The version tag at that commit, or the newest one behind it. */
+    tag: string | undefined;
+    /** Whether the tag is the pinned commit rather than an ancestor of it. */
+    released: boolean;
+    /** Where the repository can be browsed, when it has a web address. */
+    url: string | undefined;
+    /** For a fork, where the repository it was forked from can be browsed, or its url. */
+    upstream: string | undefined;
+    /** What the module is, from its own package.json. */
+    description: string | undefined;
+}
+/** What a distribution ships, read from the checkouts. */
+export declare const moduleVersions: (root: string) => Promise<ModuleVersion[]>;
+/**
+ * How to release this module, written into the module's own readme.
+ *
+ * The same words in every module, with this one's version and branch names
+ * filled in — so "how do I release this" is answered where someone is already
+ * standing, rather than in a document they have to know exists.
+ */
+export declare const releasingSection: (name: string, version: string) => string;
+export interface ReadmeUpdate {
+    file: string;
+    changed: boolean;
+}
+export interface ReadmeResult {
+    updates: ReadmeUpdate[];
+    modules: ModuleVersion[];
+    /** What was found here: a distribution listing modules, or a module itself. */
+    kind: 'distribution' | 'module';
+}
+/**
+ * Write the versions into the distribution's readme and each module's.
+ *
+ * Idempotent: running it again when nothing has moved rewrites nothing.
+ */
+export declare const writeReadmes: (root: string, { check }?: {
+    check?: boolean;
+}) => Promise<ReadmeResult>;
+//# sourceMappingURL=readme.d.ts.map

package/dist/readme.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"readme.d.ts","sourceRoot":"","sources":["../src/readme.ts"],"names":[],"mappings":"AA2CA;;;;;GAKG;AACH,eAAO,MAAM,aAAa,GACxB,QAAQ,MAAM,EACd,QAAQ,MAAM,EACd,MAAM,MAAM;AACZ;;;;GAIG;AACH,QAAQ,MAAM,KACb,MA2BF,CAAA;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAA;IACZ,iDAAiD;IACjD,OAAO,EAAE,MAAM,CAAA;IACf,YAAY,EAAE,MAAM,CAAA;IACpB,wCAAwC;IACxC,MAAM,EAAE,MAAM,CAAA;IACd,mEAAmE;IACnE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IACvB,0EAA0E;IAC1E,QAAQ,EAAE,OAAO,CAAA;IACjB,sEAAsE;IACtE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAA;IACvB,sFAAsF;IACtF,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B,qDAAqD;IACrD,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;CAChC;AAqCD,0DAA0D;AAC1D,eAAO,MAAM,cAAc,GAAU,MAAM,MAAM,KAAG,OAAO,CAAC,aAAa,EAAE,CAS1E,CAAA;AAuED;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,EAAE,SAAS,MAAM,KAAG,MA4DhE,CAAA;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,OAAO,CAAA;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,YAAY,EAAE,CAAA;IACvB,OAAO,EAAE,aAAa,EAAE,CAAA;IACxB,+EAA+E;IAC/E,IAAI,EAAE,cAAc,GAAG,QAAQ,CAAA;CAChC;AA8BD;;;;GAIG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,MAAM,EACZ,YAAmB;IAAE,KAAK,CAAC,EAAE,OAAO,CAAA;CAAO,KAC1C,OAAO,CAAC,YAAY,CA6FtB,CAAA"}

package/dist/readme.js

@@ -0,0 +1,304 @@
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import semver from 'semver';
+import { fromMarkdown } from 'mdast-util-from-markdown';
+import { inspect, isDistribution, submodules, uninitialised, } from "./submodules.js";
+import { readDistribution } from "./extends.js";
+import { toHttps } from "./git-url.js";
+const open = (marker) => `<!-- fg:${marker} -->`;
+const close = (marker) => `<!-- /fg:${marker} -->`;
+const offsets = (node) => [
+    node.position?.start.offset ?? 0,
+    node.position?.end.offset ?? 0,
+];
+/**
+ * Replace the block a marker delimits, or add one.
+ *
+ * A new block goes after the first heading, which is where someone looking for
+ * a version would look first.
+ */
+export const updateSection = (source, marker, body, 
+/**
+ * Marker whose block this one belongs under, when it has to be inserted.
+ * Without it a new block goes straight after the first heading, which means
+ * whichever block is written last ends up on top.
+ */
+after) => {
+    const tree = fromMarkdown(source);
+    const comments = tree.children.filter((node) => node.type === 'html' && typeof node.value === 'string');
+    const start = comments.find((node) => node.value?.trim() === open(marker));
+    const end = comments.find((node) => node.value?.trim() === close(marker));
+    if (start && end) {
+        const [, from] = offsets(start);
+        const [to] = offsets(end);
+        return `${source.slice(0, from)}\n\n${body}\n\n${source.slice(to)}`;
+    }
+    const block = `${open(marker)}\n\n${body}\n\n${close(marker)}`;
+    // Under the block it belongs to if that is already here, otherwise under the
+    // heading — the top of the file is where a reader starts.
+    const anchor = (after && comments.find((node) => node.value?.trim() === close(after))) ??
+        tree.children.find((node) => node.type === 'heading');
+    if (!anchor)
+        return `${block}\n\n${source}`;
+    const [, at] = offsets(anchor);
+    return `${source.slice(0, at)}\n\n${block}${source.slice(at)}`;
+};
+/**
+ * A remote as somewhere to browse, or undefined when there is nowhere.
+ *
+ * A local path is a real remote and has no web address, so linking to one
+ * would be worse than not linking at all.
+ */
+const browsableAt = (remote) => {
+    const https = toHttps(remote);
+    if (!/^https?:\/\//i.test(https))
+        return undefined;
+    return https.replace(/\.git$/, '');
+};
+const link = (text, href) => href ? `[${text}](${href})` : text;
+/**
+ * What the distribution is actually pinned at.
+ *
+ * A tagged commit is a released version and links to the tag. Anything else is
+ * a commit after the last release, which is worth saying: the version in the
+ * manifest is not what is being shipped.
+ */
+const pinnedAs = (module) => {
+    const short = module.pinned.slice(0, 7);
+    if (module.released && module.tag) {
+        return link(module.tag, module.url && `${module.url}/tree/${module.tag}`);
+    }
+    const commit = link(short, module.url && `${module.url}/commit/${module.pinned}`);
+    return module.tag
+        ? `${commit} — unreleased, after ${module.tag}`
+        : `${commit} — untagged`;
+};
+/** What a distribution ships, read from the checkouts. */
+export const moduleVersions = async (root) => {
+    const found = [];
+    for (const submodule of submodules(root)) {
+        const manifest = await readManifest(submodule);
+        if (manifest)
+            found.push(manifest);
+    }
+    return found.sort((a, b) => a.relativePath.localeCompare(b.relativePath));
+};
+const readManifest = async (submodule) => {
+    try {
+        const pkg = JSON.parse(await readFile(path.join(submodule.path, 'package.json'), 'utf8'));
+        if (!pkg.name || !pkg.version)
+            return undefined;
+        // Never fetches: this reads what is checked out, and writing a readme
+        // should not depend on the network.
+        const state = inspect(submodule, { fetch: false });
+        return {
+            name: pkg.name,
+            version: pkg.version,
+            description: typeof pkg.description === 'string' ? pkg.description : undefined,
+            relativePath: submodule.relativePath,
+            pinned: state.head,
+            tag: state.current,
+            released: state.exact,
+            url: browsableAt(submodule.url),
+            upstream: submodule.upstream && (browsableAt(submodule.upstream) ?? submodule.upstream),
+        };
+    }
+    catch {
+        return undefined;
+    }
+};
+const modulesTable = (modules) => {
+    const rows = [
+        '| Module | Version | Pinned at | Path |',
+        '| --- | --- | --- | --- |',
+        ...modules.map((module) => {
+            // Linked by name, so the table is also the index of where each lives.
+            const name = link(`\`${module.name}\``, module.url);
+            // An empty cell is honest: it shows which modules have yet to say what
+            // they are, rather than hiding it.
+            const what = module.description ? `<br>${module.description}` : '';
+            // A fork is shipped from somewhere other than where the module lives.
+            const fork = module.upstream
+                ? `<br>Fork of ${/^https?:/.test(module.upstream) ? link(module.upstream.replace(/^https?:\/\//, ''), module.upstream) : module.upstream}`
+                : '';
+            return `| ${name}${what}${fork} | ${module.version} | ${pinnedAs(module)} | \`${module.relativePath}\` |`;
+        }),
+    ];
+    // Only worth explaining when something is actually unreleased.
+    if (modules.some((module) => !module.released)) {
+        rows.push('', 'A module pinned at a commit rather than a tag is being shipped ahead of', 'its last release, so its stated version is not what is deployed.');
+    }
+    return rows.join('\n');
+};
+/**
+ * A module states its own version and nothing else.
+ *
+ * Naming a distribution here would be a claim the module cannot make: the same
+ * module is shipped in several, which is the point of extending one. The
+ * distribution's readme is where the relationship belongs.
+ */
+const versionLine = (module) => `Version **${module.version}**`;
+/**
+ * How to release this module, written into the module's own readme.
+ *
+ * The same words in every module, with this one's version and branch names
+ * filled in — so "how do I release this" is answered where someone is already
+ * standing, rather than in a document they have to know exists.
+ */
+export const releasingSection = (name, version) => {
+    const parsed = semver.parse(version);
+    // A prerelease has no line to maintain — there is no 2.0.0-alpha.0 that
+    // someone is still running and needs a fix for — so `release` only moves it
+    // forward, and saying otherwise here would contradict the command.
+    const prerelease = (parsed?.prerelease.length ?? 0) > 0;
+    const after = (bump) => (parsed && semver.inc(version, bump)) ?? '…';
+    const moveOn = prerelease
+        ? [
+            '2. **Move it on.** `pnpm release` — opens a pull request bumping this branch',
+            `   to \`${(parsed && semver.inc(version, 'prerelease')) ?? '…'}\`, or \`pnpm release --id rc\` to change`,
+            '   identifier. A prerelease gets no maintenance branch; there is no released',
+            '   line behind it yet.',
+        ]
+        : [
+            '2. **Decide which way main moves on.** `pnpm release` on its own prints the',
+            '   three and stops — it will not choose for you:',
+            '',
+            '   | | Next | Leaves behind |',
+            '   | --- | --- | --- |',
+            `   | \`pnpm release --patch\` | \`${after('patch')}\` | nothing; this branch is the line |`,
+            `   | \`pnpm release --minor\` | \`${after('minor')}\` | \`v${parsed?.major ?? 'x'}-${parsed?.minor ?? 'y'}\` at \`${after('patch')}\` |`,
+            `   | \`pnpm release --major\` | \`${after('major')}\` | \`v${parsed?.major ?? 'x'}-${parsed?.minor ?? 'y'}\` at \`${after('patch')}\` |`,
+            '',
+            '   The branch it leaves behind is where fixes to what you just released go.',
+            '3. **Fixing an older release.** Land it on main first, cherry-pick it onto that',
+            "   release's `v<major>-<minor>` branch, then publish from there under its own",
+            '   dist tag — never as `latest` unless that line is still the newest.',
+        ];
+    const early = prerelease
+        ? []
+        : [
+            '',
+            '### Starting the next line early',
+            '',
+            `\`pnpm exec fg-dist prerelease --major\` cuts \`v${(parsed?.major ?? 0) + 1}\` at`,
+            `\`${(parsed && semver.inc(version, 'premajor', 'alpha')) ?? '…'}\` and leaves main exactly where it is, so the next`,
+            'line can be worked on while this one goes on shipping. Release from that branch',
+            'under a dist tag of its own — `next`, say — so `latest` goes on meaning the line',
+            'main is shipping. `--minor` does the same for the next minor.',
+        ];
+    return [
+        '## Releasing',
+        '',
+        `This module releases on its own. \`${version}\` is what main is working towards,`,
+        'not what is published — the version here is always the next one.',
+        '',
+        '1. **Publish it.** Run the *Publish* workflow from the Actions tab, picking the',
+        '   dist tag. It refuses if that version is already on npm.',
+        ...moveOn,
+        ...early,
+        '',
+        `Every push to main publishes \`${name}@canary\`. A canary is not a release and`,
+        'carries no promise; it is there so main can be tried without a checkout.',
+    ].join('\n');
+};
+/** The name and version of the repository this is run in. */
+const ownManifest = async (root) => {
+    try {
+        const pkg = JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+        if (!pkg.name || !pkg.version)
+            return undefined;
+        return { name: pkg.name, version: pkg.version };
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The readme this repository has, or what to call one if it has none.
+ *
+ * Hard-coding `Readme.md` writes a second file next to an existing `README.md`
+ * on Linux and edits the real one on macOS, so the same command passes locally
+ * and fails in CI.
+ */
+const readmeIn = async (dir) => {
+    const found = (await readdir(dir).catch(() => []))
+        .filter((entry) => /^readme\.md$/i.test(entry))
+        .sort();
+    return path.join(dir, found[0] ?? 'Readme.md');
+};
+/**
+ * Write the versions into the distribution's readme and each module's.
+ *
+ * Idempotent: running it again when nothing has moved rewrites nothing.
+ */
+export const writeReadmes = async (root, { check = false } = {}) => {
+    const modules = await moduleVersions(root);
+    // Read from .gitmodules rather than from the checkouts: a clone made without
+    // --recurse-submodules has none of them, and calling that a module would
+    // write a module's readme over the distribution's.
+    const kind = isDistribution(root) ? 'distribution' : 'module';
+    if (kind === 'distribution') {
+        const absent = uninitialised(root);
+        if (absent.length > 0) {
+            throw new Error(`These submodules are not checked out, so their versions cannot be read: ` +
+                `${absent.join(', ')}.\nRun \`git submodule update --init\` first.`);
+        }
+    }
+    const planned = [];
+    if (kind === 'module') {
+        const own = await ownManifest(root);
+        if (!own) {
+            throw new Error(`${root} has no submodules and no package.json version, so there is ` +
+                'nothing to record.');
+        }
+        const file = await readmeIn(root);
+        planned.push({ file, marker: 'version', body: `Version **${own.version}**`, heading: own.name }, {
+            file,
+            marker: 'releasing',
+            body: releasingSection(own.name, own.version),
+            heading: own.name,
+            after: 'version',
+        });
+    }
+    else {
+        const distribution = readDistribution(root);
+        planned.push({
+            file: await readmeIn(root),
+            marker: 'modules',
+            body: modulesTable(modules),
+            heading: distribution.name,
+        });
+        for (const module of modules) {
+            const file = await readmeIn(path.join(root, module.relativePath));
+            planned.push({ file, marker: 'version', body: versionLine(module), heading: module.name }, {
+                file,
+                marker: 'releasing',
+                body: releasingSection(module.name, module.version),
+                heading: module.name,
+                after: 'version',
+            });
+        }
+    }
+    // Grouped, because a file carries more than one block and reporting it once
+    // per block doubles both the listing and the count of what changed.
+    const byFile = new Map();
+    for (const entry of planned) {
+        byFile.set(entry.file, [...(byFile.get(entry.file) ?? []), entry]);
+    }
+    const updates = [];
+    for (const [file, blocks] of byFile) {
+        const original = await readFile(file, 'utf8').catch(() => undefined);
+        // Applied in order to the same text: a block that has to be inserted is
+        // placed relative to the ones before it.
+        let updated = original ?? `# ${blocks[0].heading}\n`;
+        for (const { marker, body, after } of blocks) {
+            updated = updateSection(updated, marker, body, after);
+        }
+        const changed = updated !== original;
+        if (changed && !check)
+            await writeFile(file, updated);
+        updates.push({ file, changed });
+    }
+    return { updates, modules, kind };
+};
+//# sourceMappingURL=readme.js.map