@fairgarden/distribution 0.1.0-alpha.1 → 0.1.0-alpha.3

package/dist/cli.js

@@ -1,19 +1,23 @@
 #!/usr/bin/env node
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { mkdir } from 'node:fs/promises';
+import { mkdir, readFile } from 'node:fs/promises';
 import { addModule } from "./add-module.js";
 import { extractModule } from "./extract.js";
 import { writeReadmes } from "./readme.js";
-import { writeWorkflows } from "./workflows.js";
+import { writeDistributionChangelogCheck, writeDistributionWorkflow, writeWorkflows } from "./workflows.js";
 import { writeOverrides } from "./overrides.js";
-import { checkReleasable, planRelease, readRelease, release, reportToActions as reportRelease, startPrerelease, } from "./release.js";
+import { checkReleasable, planRelease, readRelease, release, releaseDistribution, reportToActions as reportRelease, startPrerelease, } from "./release.js";
 import { reportToActions as reportCanary, stampCanary } from "./canary.js";
 import { describeRemote, isSsh, toHttps } from "./git-url.js";
 import { distributionRepo, isEmpty, moduleRepo, monolithRepo, write, } from "./scaffold.js";
 import { describeViolations, inspectExtends } from "./extends.js";
+import { contribute, forkModule, integrate, unforkModule } from "./forks.js";
+import { inherit } from "./inherit.js";
+import { bumpEntry, checkChangelog, crossedReleases, holdPullRequests, CHANGELOG, moduleLabel, noteInDistribution, notesFor, pullRequestFromActions, } from "./changelog.js";
 import { buildPolicy, findPolicy, POLICIES, setupTurbo, testPolicy, usePolicy } from "./policy.js";
-import { inspect, isPublic, moveTo, repositoryRoot, setUrl, submodules, target, } from "./submodules.js";
+import { stampModules } from "./manifest.js";
+import { containsAll, inspect, isDistribution, isPublic, moveTo, repositoryRoot, setUrl, submodules, target, } from "./submodules.js";
 // Piping into `head` closes stdout early; that is ordinary use, not a failure.
 for (const stream of [process.stdout, process.stderr]) {
     stream.on('error', (error) => {
@@ -30,14 +34,22 @@ Commands:
   extract <path>       Turn a directory here into its own repository and submodule
   use-https [name...]  Rewrite submodule urls from ssh to https
   readme               Record versions in the readmes; run in a distribution or a module
-  workflows            Give every module a publishing workflow
+  workflows [name...]  Give every module a publishing workflow and a changelog check;
+                       --distribution, this one a publishing workflow too
   overrides            Point the workspace at this distribution's own checkouts
   canary               Stamp a canary version into the manifest, for CI
   release              Move a module on from the release it just published
   prerelease           Start the next line on a branch, leaving main where it is
   check                Fail when this ships anything older than what it extends
+  inherit              Add the modules the distribution this extends ships, and this does not
   sync                 Report which modules have newer versions available
-  bump [name...]       Move modules to their newest non-major version
+  bump [name...]       Move modules to their newest non-major version; a fork merges it
+  fork <name> <url>    Check a module out from your fork, keeping where it came from
+  contribute <name>    Push the module's branch and open a pull request upstream
+  unfork <name>        Go back to the upstream a fork came from, once it has the fork's work
+  changelog check      Fail a pull request that adds no changelog line linking itself (CI)
+  changelog notes [v]  Print a version's changelog section, for its release notes
+  changelog hold       Hold open pull requests until the next version starts (CI, after a release)
   policy build         Build the organization's policy: policies/, on every module's own
   policy test          Test each module's rules, then the organization's on top of them
   policy use           Put the built policy beside this service, for it to run
@@ -49,6 +61,9 @@ Options:
   --minor              Release the next minor, or branch one (release, prerelease)
   --patch              Release the next patch, staying on this line (release)
   --id <name>          Prerelease identifier: alpha, beta, rc (release, prerelease)
+  --stable             A distribution's release leaves its prerelease stages (release)
+  --next <how>         prerelease, alpha, beta, rc, patch, minor, major or stable (release)
+  --direct             Commit main's move on where this runs and push it, no pull request (release)
   --no-fetch           Use the refs already fetched (sync, bump)
   --dry-run            Report what would change without changing it
   --check              Verify instead of writing (readme, release, overrides)
@@ -63,7 +78,12 @@ Options:
   --no-verify          Skip checking whether the https urls can be cloned
   --no-tag             Do not tag the extracted module with its declared version
   --force              Overwrite workflows that are already there (workflows)
-  --no-push            Leave the release branches local, and open no pull request
+  --distribution       Publish the distribution itself, for others to extend (workflows)
+  --no-push            Push nothing and open no pull request (release, fork, contribute, bump)
+  --to <ref>           Upstream tag, branch or commit to go back to (unfork)
+  --base <branch>      Branch the pull request goes into (contribute); what it merges into (changelog check)
+  --pr <number>        The pull request to check, outside GitHub Actions (changelog check)
+  --repo <owner/name>  The repository its link names, outside GitHub Actions (changelog check)
   --out <file>         Where policy build writes the bundle (default: policies/dist/)
 `;
 const parseArgs = (argv) => {
@@ -89,6 +109,13 @@ const parseArgs = (argv) => {
         bump: undefined,
         id: undefined,
         out: undefined,
+        to: undefined,
+        base: undefined,
+        distribution: false,
+        stable: false,
+        pr: undefined,
+        repo: undefined,
+        direct: false,
     };
     for (let index = 0; index < argv.length; index += 1) {
         const arg = argv[index];
@@ -150,6 +177,47 @@ const parseArgs = (argv) => {
         else if (arg === '--no-push') {
             args.push = false;
         }
+        else if (arg === '--direct') {
+            args.direct = true;
+        }
+        else if (arg === '--next') {
+            // How main moves on after a release, as the publish workflow is told:
+            // carry on the prerelease, change its stage, or bump.
+            const next = argv[++index];
+            if (next === 'prerelease') {
+                // as it is
+            }
+            else if (next === 'alpha' || next === 'beta' || next === 'rc') {
+                args.id = next;
+            }
+            else if (next === 'patch' || next === 'minor' || next === 'major') {
+                args.bump = next;
+            }
+            else if (next === 'stable') {
+                args.stable = true;
+            }
+            else {
+                throw new Error(`--next is prerelease, alpha, beta, rc, patch, minor, major or stable; not ${next}.`);
+            }
+        }
+        else if (arg === '--pr') {
+            args.pr = Number(argv[++index]);
+        }
+        else if (arg === '--repo') {
+            args.repo = argv[++index];
+        }
+        else if (arg === '--stable') {
+            args.stable = true;
+        }
+        else if (arg === '--distribution') {
+            args.distribution = true;
+        }
+        else if (arg === '--to') {
+            args.to = argv[++index];
+        }
+        else if (arg === '--base') {
+            args.base = argv[++index];
+        }
         else if (arg === '--out') {
             args.out = path.resolve(argv[++index] ?? '.');
         }
@@ -166,6 +234,19 @@ const parseArgs = (argv) => {
     return args;
 };
 /** One line per module, aligned, saying what is available. */
+/**
+ * Where a fork could go back to upstream, when upstream has taken what it
+ * added: a release past the pinned one, or its branch. Not a fork that has
+ * added nothing yet, which is where every fork starts.
+ */
+const canReturn = (state) => {
+    const merged = state.fork?.merged;
+    if (!merged)
+        return undefined;
+    if (merged === state.current && state.fork?.ahead === 0)
+        return undefined;
+    return merged.replace(/^upstream\//, '');
+};
 const describeState = (state) => {
     const { current, available, untagged, dirty } = state;
     const parts = [];
@@ -185,6 +266,18 @@ const describeState = (state) => {
     }
     if (untagged > 0)
         parts.push(`${untagged} untagged commit${untagged === 1 ? '' : 's'}`);
+    if (state.fork) {
+        const { upstream, ahead } = state.fork;
+        const from = `fork of ${describeRemote(upstream)}`;
+        const returnTo = canReturn(state);
+        parts.push(returnTo
+            ? `${from}, all in upstream ${returnTo}`
+            : ahead === 0
+                ? `${from}, nothing of its own`
+                : `${from}, ${ahead} commit${ahead === 1 ? '' : 's'} not upstream`);
+    }
+    if (state.pushed === false)
+        parts.push('not pushed');
     if (dirty)
         parts.push('uncommitted changes');
     if (state.fetched === false)
@@ -269,7 +362,9 @@ const main = async () => {
         }
         process.stdout.write(kind === 'module'
             ? 'Next: pnpm install, then commit and push so a distribution can add it.\n'
-            : 'Next: pnpm install, then `fg-dist add-module <url>` to ship a module.\n');
+            : args.extends && kind === 'distribution'
+                ? `Next: pnpm install, then \`fg-dist inherit\` to ship what ${args.extends} ships.\n`
+                : 'Next: pnpm install, then `fg-dist add-module <url>` to ship a module.\n');
         return 0;
     }
     if (args.command === 'add-module') {
@@ -328,6 +423,9 @@ const main = async () => {
         else if (result.monolithConfig) {
             process.stdout.write(`Already mounted at /${result.mount}.\n`);
         }
+        if (result.turbo) {
+            process.stdout.write("turbo.json: the monolith's build waits for its libraries, not its own build\n");
+        }
         process.stdout.write(result.monolithPackageJson
             ? '\nRun pnpm install and `fg-monolith merge-package-json`.\n'
             : '\nRun pnpm install.\n');
@@ -365,10 +463,34 @@ const main = async () => {
         const root = repositoryRoot(args.cwd);
         if (!root)
             throw new Error(`${args.cwd} is not inside a git repository.`);
+        if (args.distribution) {
+            const update = await writeDistributionWorkflow(root, { force: args.force, dryRun: args.dryRun });
+            if (update.skipped) {
+                process.stdout.write('The distribution has a publishing workflow already. Pass --force to overwrite it.\n');
+                return 0;
+            }
+            process.stdout.write(`${update.files.join(', ')}\n`);
+            if (update.unprivated) {
+                process.stdout.write('\nTook "private": true off package.json — a private package cannot publish.\n');
+            }
+            if (update.missingAccess) {
+                process.stdout.write('Nothing says whether it publishes publicly. For others to extend it, add\n' +
+                    '  "publishConfig": { "access": "public" }\n');
+            }
+            process.stdout.write('\nIt publishes the manifest, recording every module it ships, and its policy. ' +
+                'Version it with `fg-dist release`, then run the workflow.\n');
+            return 0;
+        }
         const updates = await writeWorkflows(root, {
             force: args.force,
             dryRun: args.dryRun,
+            names: args.names,
         });
+        // The distribution checks its own changelog too, for policy changes —
+        // unless only some modules were named.
+        if (isDistribution(root) && args.names.length === 0) {
+            updates.push(await writeDistributionChangelogCheck(root, { force: args.force, dryRun: args.dryRun }));
+        }
         if (updates.length === 0) {
             process.stdout.write('No modules here. Run this in a distribution, which is where the modules are.\n');
             return 0;
@@ -463,11 +585,40 @@ const main = async () => {
             throw new Error(`${args.cwd} is not inside a git repository.`);
         if (args.check) {
             const releasable = await checkReleasable(root);
+            // A distribution records what it ships in what it publishes.
+            if (isDistribution(root))
+                await stampModules(root, { version: releasable.version });
             await reportRelease(releasable);
             process.stdout.write(`${releasable.name}@${releasable.version} is not on npm; ready to release as ` +
                 `${releasable.tag}.\n`);
             return 0;
         }
+        if (isDistribution(root)) {
+            if (args.bump) {
+                process.stderr.write("A distribution's version is its month and its release: move it with " +
+                    '--id <alpha|beta|rc> or --stable, or neither to carry on as it is.\n');
+                return 1;
+            }
+            const next = await releaseDistribution(root, {
+                dryRun: args.dryRun,
+                id: args.id,
+                stable: args.stable,
+                direct: args.direct,
+                push: args.push,
+            });
+            const verb = args.dryRun ? 'Would move' : 'Moved';
+            process.stdout.write(next.version === next.from
+                ? `${next.name} ${next.from} is not published yet; it is what the publish workflow releases next.\n`
+                : `${next.published ? `${next.from} is published. ` : `${next.from} was never published. `}` +
+                    `${verb} ${next.name} to ${next.version}.\n`);
+            if (next.pushed) {
+                process.stdout.write('Committed and pushed.\n');
+            }
+            else if (!args.dryRun && next.version !== next.from) {
+                process.stdout.write(`Commit it, then run the publish workflow, which publishes it and tags v${next.version}.\n`);
+            }
+            return 0;
+        }
         // Which way main moves on is a judgement about what changed, so it is asked
         // for rather than guessed at. Showing all three is the cheapest way to ask.
         if (!args.bump) {
@@ -492,8 +643,16 @@ const main = async () => {
             id: args.id,
             dryRun: args.dryRun,
             push: args.push,
+            direct: args.direct,
         });
         const { plan } = outcome;
+        // Straight onto the branch this runs on: what the publish workflow does.
+        if (args.direct && !args.dryRun) {
+            process.stdout.write(`Released ${plan.released}. ${outcome.base} starts ${plan.next.version}` +
+                (plan.maintenance ? `; ${plan.maintenance.branch} maintains ${plan.maintenance.version}` : '') +
+                (outcome.pushed ? '. Pushed.\n' : '. Left local.\n'));
+            return 0;
+        }
         process.stdout.write(`Released ${plan.released}, ` +
             `${plan.tagged ? `tagged ${plan.base}` : 'which is not tagged here'}\n\n`);
         const width = pad([plan.maintenance?.branch ?? '', plan.next.branch]);
@@ -707,6 +866,25 @@ const main = async () => {
             process.stdout.write('Run `fg-dist use-https` to rewrite them. They also have to be ' +
                 'readable without credentials, which means public.\n');
         }
+        // A pin the remote does not have breaks every other clone, a build host's first.
+        const unpushed = states.filter((state) => state.pushed === false);
+        if (unpushed.length > 0) {
+            process.stdout.write(`\n${unpushed.length} module(s) are pinned at a commit their remote does not have, ` +
+                'so no other clone can check them out:\n');
+            for (const state of unpushed) {
+                process.stdout.write(`  ${state.submodule.relativePath}  ${state.head.slice(0, 7)}\n`);
+            }
+            process.stdout.write('Push them — `fg-dist contribute <name>` does, for a change on its way upstream.\n');
+        }
+        // A fork whose work upstream has taken can go back to upstream.
+        const returnable = states.filter((state) => canReturn(state));
+        if (returnable.length > 0) {
+            process.stdout.write('\nUpstream has everything these forks add:\n');
+            for (const state of returnable) {
+                process.stdout.write(`  ${state.submodule.relativePath}  in ${canReturn(state)}\n`);
+            }
+            process.stdout.write('Keep them, or `fg-dist unfork <name>` to go back to upstream.\n');
+        }
         // An extension may move ahead of what it extends, never behind it.
         const extendsReport = inspectExtends(root);
         if (extendsReport.violations.length > 0) {
@@ -742,7 +920,7 @@ const main = async () => {
         return 0;
     }
     if (args.command === 'bump') {
-        const { modules } = modulesFor(args.cwd, args.names);
+        const { root, modules } = modulesFor(args.cwd, args.names);
         const states = modules.map((module) => inspect(module, { fetch: args.fetch }));
         const moves = states
             .map((state) => ({ state, to: target(state, { major: args.major }) }))
@@ -763,18 +941,184 @@ const main = async () => {
                 .join('\n')}\n`);
             return 1;
         }
+        let failed = 0;
         for (const { state, to } of moves) {
             const from = state.current ?? state.head.slice(0, 7);
+            const line = `${state.submodule.relativePath}  ${from} -> ${to}`;
             if (args.dryRun) {
-                process.stdout.write(`${state.submodule.relativePath}  ${from} -> ${to}\n`);
+                const how = !state.fork
+                    ? ''
+                    : containsAll(state.submodule.path, `refs/tags/${to}`, state.head)
+                        ? '  (fork: upstream has all of it; would move to it)'
+                        : '  (fork: would merge it in)';
+                process.stdout.write(`${line}${how}\n`);
                 continue;
             }
-            moveTo(state.submodule, to);
-            process.stdout.write(`${state.submodule.relativePath}  ${from} -> ${to}\n`);
+            if (!state.fork) {
+                moveTo(state.submodule, to);
+                noteInDistribution(root, bumpEntry(moduleLabel(state.submodule.path).name, from, to, state.submodule.url, crossedReleases(state.available, to)));
+                process.stdout.write(`${line}\n`);
+                continue;
+            }
+            // A fork takes upstream's release by merging it, keeping its own work on top.
+            try {
+                const done = integrate(root, state, to, { push: args.push });
+                process.stdout.write(done.how === 'moved'
+                    ? `${line}  (fork: upstream has all of it; \`fg-dist unfork ${state.submodule.name}\` goes back)\n`
+                    : `${line}  (fork: merged${done.pushed ? `, pushed to ${done.pushed}` : ', not pushed'})\n`);
+            }
+            catch (error) {
+                failed += 1;
+                process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            }
         }
         process.stdout.write(args.dryRun
             ? '\nDry run; nothing moved.\n'
             : '\nSubmodule pointers moved. Commit them to record the new versions.\n');
+        return failed > 0 ? 1 : 0;
+    }
+    if (args.command === 'inherit') {
+        const root = repositoryRoot(args.cwd);
+        if (!root)
+            throw new Error(`${args.cwd} is not inside a git repository.`);
+        const result = await inherit(root, { dryRun: args.dryRun });
+        const width = pad(result.added.map((module) => module.path));
+        for (const module of result.added) {
+            process.stdout.write(`${module.path.padEnd(width)}  ${module.name} ${module.version} at ${module.commit.slice(0, 7)}, ` +
+                `from ${describeRemote(module.repository)}` +
+                `${module.upstream ? ` (a fork of ${describeRemote(module.upstream)})` : ''}\n`);
+        }
+        for (const module of result.blocked) {
+            process.stderr.write(`${module.path} has something in it already, so ${module.name} was not added there.\n`);
+        }
+        if (result.added.length === 0 && result.blocked.length === 0) {
+            process.stdout.write(`Ships everything ${result.parent}@${result.parentVersion} ships already.\n`);
+            return 0;
+        }
+        process.stdout.write(args.dryRun
+            ? '\nDry run; nothing added.\n'
+            : `\nShips what ${result.parent}@${result.parentVersion} ships. Run pnpm install, then commit.\n`);
+        return result.blocked.length > 0 ? 1 : 0;
+    }
+    if (args.command === 'changelog') {
+        const [action, version] = args.names;
+        const root = repositoryRoot(args.cwd) ?? args.cwd;
+        if (action === 'check') {
+            const actions = pullRequestFromActions();
+            const pullRequest = args.pr ?? actions.pullRequest;
+            const base = args.base ?? actions.base;
+            const repository = args.repo ?? actions.repository;
+            if (!pullRequest || !base || !repository) {
+                process.stderr.write('changelog check runs on a pull request: in GitHub Actions, or given ' +
+                    '--pr <number> --base <ref> --repo <owner/name>.\n');
+                return 1;
+            }
+            const result = checkChangelog(root, {
+                pullRequest,
+                base,
+                repository,
+                distribution: isDistribution(root),
+                labels: actions.labels,
+                server: actions.server,
+            });
+            (result.ok ? process.stdout : process.stderr).write(`${result.message}\n`);
+            return result.ok ? 0 : 1;
+        }
+        if (action === 'hold') {
+            // The branch just released from: main, or a maintenance branch.
+            const base = args.base ??
+                process.env.GITHUB_REF_NAME ??
+                execFileSync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: root, encoding: 'utf8' }).trim();
+            const holds = holdPullRequests(root, { base });
+            if (holds.length === 0) {
+                process.stdout.write(`No pull requests are open into ${base}.\n`);
+                return 0;
+            }
+            for (const hold of holds) {
+                process.stdout.write(hold.held
+                    ? `#${hold.pullRequest}  held${hold.run === undefined ? ', its first check will see the release' : ''}\n`
+                    : `#${hold.pullRequest}  could not be held: ${hold.problem}\n`);
+            }
+            return holds.every((hold) => hold.held) ? 0 : 1;
+        }
+        if (action === 'notes') {
+            const wanted = version ?? JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8')).version;
+            const text = await readFile(path.join(root, CHANGELOG), 'utf8').catch(() => '');
+            const notes = notesFor(text, wanted);
+            if (!notes) {
+                process.stderr.write(`${CHANGELOG} says nothing for ${wanted}.\n`);
+                return 1;
+            }
+            process.stdout.write(notes);
+            return 0;
+        }
+        process.stderr.write('changelog needs `check`, `hold` or `notes`.\n');
+        return 1;
+    }
+    if (args.command === 'fork') {
+        const [name, url] = args.names;
+        if (!name || !url) {
+            process.stderr.write('fork needs a module and the url of your fork: fg-dist fork <name> <url>\n');
+            return 1;
+        }
+        const { root, modules } = modulesFor(args.cwd, [name]);
+        const result = forkModule(root, modules[0], url, { ssh: args.ssh, push: args.push });
+        process.stdout.write(`${modules[0].relativePath} is checked out from ${result.url}\n` +
+            `forked from ${result.upstream}, which .gitmodules records as its upstream\n`);
+        if (result.rewritten) {
+            process.stdout.write(`(rewritten from ${url}; a submodule is cloned without an SSH key)\n`);
+        }
+        process.stdout.write(result.branch
+            ? `Pinned commit pushed to ${result.branch}, where everything this distribution pins in the fork lives.\n`
+            : 'Nothing pushed. The pinned commit has to be on the fork before anyone else can check it out.\n');
+        process.stdout.write(`\nNext: make the change on a branch in ${modules[0].relativePath}, then ` +
+            `\`fg-dist contribute ${modules[0].name}\`.\nCommit .gitmodules and ${modules[0].relativePath} here.\n`);
+        return 0;
+    }
+    if (args.command === 'contribute') {
+        const [name] = args.names;
+        if (!name) {
+            process.stderr.write('contribute needs a module: fg-dist contribute <name>\n');
+            return 1;
+        }
+        const { root, modules } = modulesFor(args.cwd, [name]);
+        const result = contribute(root, modules[0], { push: args.push, base: args.base });
+        if (!args.push) {
+            process.stdout.write(`Would push ${result.branch} and open a pull request into ${describeRemote(result.repository)} ${result.base}.\n`);
+            return 0;
+        }
+        process.stdout.write(`Pushed ${result.branch}.\n`);
+        if (result.pinnedOn)
+            process.stdout.write(`Pinned commit kept on ${result.pinnedOn}, which outlives the pull request's branch.\n`);
+        if (result.pullRequest) {
+            process.stdout.write(`Opened ${result.pullRequest}\n`);
+        }
+        else if (result.compare) {
+            process.stdout.write(`Open the pull request at\n  ${result.compare}\n`);
+        }
+        else {
+            process.stdout.write(`Open a pull request from ${result.branch} into ${result.base} on ${describeRemote(result.repository)}.\n`);
+        }
+        if (result.changelog) {
+            process.stdout.write(`\nIts changelog check wants a line in ${result.changelog.file}, under ${result.changelog.version}. ` +
+                'The words are yours:\n' +
+                `  ${result.changelog.line}\n` +
+                'Commit it on the branch and push, then run this again to keep the pin current.\n');
+        }
+        process.stdout.write(`\nCommit ${modules[0].relativePath} here to ship the change meanwhile.\n`);
+        return 0;
+    }
+    if (args.command === 'unfork') {
+        const [name] = args.names;
+        if (!name) {
+            process.stderr.write('unfork needs a module: fg-dist unfork <name>\n');
+            return 1;
+        }
+        const { root, modules } = modulesFor(args.cwd, [name]);
+        const state = inspect(modules[0], { fetch: args.fetch });
+        const result = unforkModule(root, state, { to: args.to, major: args.major, force: args.force });
+        process.stdout.write(`${modules[0].relativePath} is checked out from ${result.url} again, at ${result.to}.\n` +
+            `Commit .gitmodules and ${modules[0].relativePath} here. The fork itself is left as it is.\n`);
         return 0;
     }
     process.stderr.write(`Unknown command: ${args.command}\n\n${USAGE}`);