@fairgarden/distribution 0.1.0-alpha.0

package/dist/readme.js

@@ -0,0 +1,299 @@
+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),
+        };
+    }
+    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}` : '';
+            return `| ${name}${what} | ${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

package/dist/readme.js.map

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

package/dist/release.d.ts

@@ -0,0 +1,140 @@
+export declare class ReleaseError extends Error {
+}
+export interface Branch {
+    branch: string;
+    version: string;
+}
+export interface ReleasePlan {
+    /** The version that has just been released, read from the manifest. */
+    released: string;
+    /**
+     * Where fixes to the released version go. Undefined for a prerelease, which
+     * has nothing to maintain.
+     */
+    maintenance: Branch | undefined;
+    /** The bump that main takes, opened as a pull request. */
+    next: Branch;
+    /** What the maintenance branch is cut from: the release tag, or HEAD. */
+    base: string;
+    /** Whether {@link base} is the release tag rather than wherever HEAD is. */
+    tagged: boolean;
+}
+/**
+ * Work out the two branches a release leaves behind.
+ *
+ * Main always carries the next unreleased version, so the release is the
+ * moment main moves on: once 1.6.0 is published, main becomes 1.7.0 and 1.6.x
+ * continues on its own branch, starting at the patch nobody has written yet.
+ */
+export type Bump = 'patch' | 'minor' | 'major';
+/**
+ * Work out what a release leaves behind.
+ *
+ * Main always carries the next unreleased version, so the release is the moment
+ * main moves on. Which way it moves is a decision nobody else can make: a minor
+ * is the usual answer, a major says something was removed or changed meaning,
+ * and a patch says this branch *is* the line and stays on it.
+ */
+export declare const planRelease: (released: string, { bump, id }?: {
+    bump?: Bump;
+    id?: string;
+}) => Omit<ReleasePlan, "base" | "tagged">;
+export interface PrereleasePlan {
+    /** The version the branch is cut to carry. */
+    version: string;
+    /** The branch it lives on, which becomes that line's branch if it ships. */
+    branch: string;
+    /** The version on the branch this was cut from, which keeps going. */
+    from: string;
+}
+/**
+ * Start the next line early, without main leaving the current one.
+ *
+ * Main is at 1.6.0 and still has 1.6.x and 1.7.0 to ship; 2.0.0 can be worked
+ * on anyway, on a branch of its own, published under a dist tag of its own.
+ * Nothing here touches main — that is the point.
+ */
+export declare const planPrerelease: (current: string, { bump, id }: {
+    bump: Exclude<Bump, "patch">;
+    id?: string;
+}) => PrereleasePlan;
+/**
+ * Set the version in package.json, leaving the rest of the file untouched.
+ *
+ * Spliced rather than re-serialised: a manifest carries key order, comments in
+ * some tools, and whatever indentation the repository settled on, and a
+ * release is no occasion to reformat it.
+ */
+export declare const setVersion: (source: string, version: string) => string;
+/** Read the release the repository is standing on, without changing anything. */
+export declare const readRelease: (root: string, { bump, id }?: {
+    bump?: Bump;
+    id?: string;
+}) => Promise<ReleasePlan>;
+export interface ReleaseOptions {
+    /** Which way main moves on. Required, unless this is a prerelease. */
+    bump?: Bump;
+    /** Prerelease identifier, for moving alpha to beta to rc. */
+    id?: string;
+    dryRun?: boolean;
+    /** Push the branches and open the pull request. On by default. */
+    push?: boolean;
+}
+export interface ReleaseOutcome {
+    plan: ReleasePlan;
+    /** The branch this was released from, which the pull request is against. */
+    base: string;
+    /** Branches that were created, in the order they were created. */
+    created: string[];
+    pushed: boolean;
+    /** The pull request, when `gh` was there to open one. */
+    pullRequest: string | undefined;
+}
+/**
+ * Move a module on from the release it has just published.
+ *
+ * Two branches come out of it: `v1-6` where 1.6.x is maintained, and a pull
+ * request moving main to 1.7.0. The pull request is where main's bump gets
+ * reviewed like any other change; the maintenance branch is not a proposal, so
+ * it is just pushed.
+ */
+export declare const release: (root: string, { bump, id, dryRun, push }?: ReleaseOptions) => Promise<ReleaseOutcome>;
+export interface Releasable {
+    name: string;
+    version: string;
+    tag: string;
+    /** Whether npm will generate provenance; it refuses for restricted packages. */
+    provenance: boolean;
+}
+/**
+ * Check that the version in the manifest is one that can be released.
+ *
+ * Main is meant to carry the next unreleased version, so finding that version
+ * already on npm means {@link release} has not run since the last one — and
+ * publishing would either fail or, worse, succeed as a republish.
+ */
+export declare const checkReleasable: (root: string, { published }?: {
+    published?: (spec: string) => string | undefined;
+}) => Promise<Releasable>;
+/** Hand the version to the workflow steps that tag and publish it. */
+export declare const reportToActions: (releasable: Releasable) => Promise<void>;
+export interface PrereleaseOutcome {
+    plan: PrereleasePlan;
+    created: boolean;
+    pushed: boolean;
+}
+/**
+ * Cut a branch carrying the next line, and leave main where it is.
+ *
+ * No pull request: this is not a change to the branch you are on, it is a
+ * second line starting beside it. Main goes on releasing what it was
+ * releasing, and this one publishes under a dist tag of its own until it is
+ * ready to become `latest`.
+ */
+export declare const startPrerelease: (root: string, { bump, id, dryRun, push, }: {
+    bump: Exclude<Bump, "patch">;
+    id?: string;
+    dryRun?: boolean;
+    push?: boolean;
+}) => Promise<PrereleaseOutcome>;
+//# sourceMappingURL=release.d.ts.map

package/dist/release.d.ts.map

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