@fairgarden/distribution 0.1.0-0.canary.0

package/dist/extract.js

@@ -0,0 +1,177 @@
+import { execFileSync } from 'node:child_process';
+import { readFile, readdir, writeFile } from 'node:fs/promises';
+import { existsSync, statSync } from 'node:fs';
+import path from 'node:path';
+import { writeOverrides } from "./overrides.js";
+import semver from 'semver';
+import { repositoryRoot, submodules } from "./submodules.js";
+import { toHttps } from "./git-url.js";
+/**
+ * Turn a directory that grew inside a distribution into a module of its own.
+ *
+ * An app or package is easier to get working in place, where the workspace
+ * already resolves it and there is one repository to run. Once it works it
+ * wants its own history and its own version, which is what this does: the
+ * directory becomes a repository, and the distribution picks it back up as a
+ * submodule. Nothing is re-cloned, so it works before anything is pushed.
+ */
+const git = (cwd, args) => {
+    try {
+        return execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch (cause) {
+        const stderr = cause instanceof Error && 'stderr' in cause ? String(cause.stderr).trim() : '';
+        throw new Error(`git ${args[0]} failed${stderr ? `: ${stderr}` : ''}`, { cause });
+    }
+};
+const quiet = (cwd, args) => {
+    try {
+        return execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim();
+    }
+    catch {
+        return undefined;
+    }
+};
+const isDirectory = (candidate) => {
+    try {
+        return statSync(candidate).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
+const readManifest = async (root) => {
+    try {
+        return JSON.parse(await readFile(path.join(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        return {};
+    }
+};
+export const extractModule = async (cwd, target, options) => {
+    const root = repositoryRoot(cwd);
+    if (!root)
+        throw new Error(`${cwd} is not inside a git repository.`);
+    const full = path.resolve(cwd, target);
+    const relativePath = path.relative(root, full);
+    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+        throw new Error(`${target} is outside ${root}.`);
+    }
+    if (!isDirectory(full)) {
+        throw new Error(`${relativePath} is not a directory.`);
+    }
+    if (submodules(root).some((module) => module.relativePath === relativePath)) {
+        throw new Error(`${relativePath} is already a submodule.`);
+    }
+    const recorded = options.ssh ? options.url : toHttps(options.url);
+    const { name, version } = await readManifest(full);
+    // An existing repository here is kept: it may already have the history.
+    // Looking for `.git` in the directory itself, because `rev-parse` walks up
+    // and would find the distribution's repository instead.
+    const alreadyRepository = existsSync(path.join(full, '.git'));
+    const initialised = !alreadyRepository;
+    if (initialised) {
+        git(full, ['init', '--quiet', '-b', 'main']);
+    }
+    // The distribution's .gitignore stops applying the moment this is its own
+    // repository, so without one of its own the first commit would carry
+    // node_modules and build output.
+    if (!existsSync(path.join(full, '.gitignore'))) {
+        await writeFile(path.join(full, '.gitignore'), 'node_modules\n.next\n.turbo\ndist\nout\nnext-env.d.ts\n*.tsbuildinfo\n');
+    }
+    // Nested packages — a docs site, most often — were members of the
+    // distribution's workspace. Out here nothing says so, and pnpm 10 links
+    // nothing across a workspace unless told to, so this repository needs the
+    // arrangement written down for itself.
+    const nested = await nestedPackages(full);
+    if (nested.length > 0 && !existsSync(path.join(full, 'pnpm-workspace.yaml'))) {
+        await writeFile(path.join(full, 'pnpm-workspace.yaml'), workspaceFile(nested));
+    }
+    // Commit whatever is there, so the submodule has something to point at.
+    if (quiet(full, ['status', '--porcelain']) !== '') {
+        git(full, ['add', '-A']);
+        git(full, ['commit', '--quiet', '-m', 'Initial commit']);
+    }
+    if (quiet(full, ['remote', 'get-url', 'origin']) === undefined) {
+        git(full, ['remote', 'add', 'origin', recorded]);
+    }
+    // A module is versioned by tags, so give it the one its manifest declares.
+    let tagged;
+    if (options.tag !== false && version && semver.valid(version)) {
+        const tag = `v${version}`;
+        if (quiet(full, ['rev-parse', '--verify', '--quiet', `refs/tags/${tag}`]) === undefined) {
+            quiet(full, ['tag', tag]);
+            tagged = tag;
+        }
+    }
+    // Untrack the files, then let git adopt the repository that is already here.
+    // `submodule add` clones only when the path is empty, so nothing is refetched
+    // and this works before the remote exists.
+    // Tolerant, so a retry after a half-finished run still works: the files may
+    // already be untracked.
+    quiet(root, ['rm', '-r', '--quiet', '--cached', relativePath]);
+    git(root, ['submodule', 'add', recorded, relativePath]);
+    // Now that it is a submodule, the distribution resolves it from the tree
+    // rather than through whatever range its dependents declare. The repository
+    // is made and the submodule added by this point, so a workspace this cannot
+    // edit is reported rather than failing a job that is otherwise done.
+    const overridesError = await writeOverrides(root).then(() => undefined, (error) => (error instanceof Error ? error.message : String(error)));
+    return {
+        overridesError,
+        relativePath,
+        packageName: name,
+        version,
+        url: recorded,
+        rewritten: recorded !== options.url,
+        initialised,
+        tagged,
+    };
+};
+/** Directories one level down that are packages in their own right. */
+const nestedPackages = async (root) => {
+    const entries = await readdir(root, { withFileTypes: true }).catch(() => []);
+    return entries
+        .filter((entry) => entry.isDirectory() &&
+        entry.name !== 'node_modules' &&
+        !entry.name.startsWith('.') &&
+        existsSync(path.join(root, entry.name, 'package.json')))
+        .map((entry) => entry.name)
+        .sort();
+};
+/**
+ * A workspace covering this repository and the packages inside it.
+ *
+ * The settings are not decoration: pnpm 10 defaults `linkWorkspacePackages` to
+ * false, so without it a nested package resolves its dependency on this one
+ * from the registry rather than from the checkout it is sitting in.
+ */
+export const workspaceFile = (nested) => [
+    '# For when this repository is cloned on its own.',
+    '#',
+    '# pnpm uses the nearest workspace file to where it is run, so inside a',
+    '# distribution this one applies to `pnpm install` run from THIS directory —',
+    '# which would build a second workspace with its own lockfile and without the',
+    '# distribution\'s overrides. Install from the distribution root instead.',
+    'packages:',
+    '  # The workspace root — this module — is always a member; these are the',
+    '  # additions.',
+    ...nested.map((name) => `  - ${name}`),
+    '',
+    '# pnpm 10 defaults this to false, so without it the packages above resolve',
+    '# their dependency on this module from the registry instead of from the',
+    '# checkout next to them.',
+    'linkWorkspacePackages: true',
+    '# Keep plain semver ranges in package.json: the range is what a published',
+    '# module is installed by, and what a distribution reads to resolve versions.',
+    'saveWorkspaceProtocol: false',
+    '',
+].join('\n');
+//# sourceMappingURL=extract.js.map

package/dist/extract.js.map

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

package/dist/forks.d.ts

@@ -0,0 +1,116 @@
+import { type Submodule, type SubmoduleState } from './submodules.ts';
+/**
+ * The branch in a fork that holds everything this distribution pins, named
+ * after the distribution.
+ *
+ * Not the pull request's branch: GitHub deletes that once it is merged, and a
+ * pinned commit has to stay fetchable for as long as anything pins it. Not the
+ * fork's main either, which is upstream's to follow.
+ */
+export declare const distributionBranch: (root: string) => string;
+/** `https://github.com/acme/id.git` -> `acme/id`; undefined anywhere else. */
+export declare const githubRepo: (url: string) => string | undefined;
+export interface ForkOptions {
+    /** Record the url as given instead of rewriting it to https. */
+    ssh?: boolean;
+    /** Push the pinned commit to the fork, so other clones can check it out. */
+    push?: boolean;
+}
+export interface ForkResult {
+    /** The fork's url, as recorded in .gitmodules. */
+    url: string;
+    /** Where it was forked from. */
+    upstream: string;
+    /** Whether the url was rewritten from ssh. */
+    rewritten: boolean;
+    /** The branch the pinned commit was pushed to, when it was. */
+    branch: string | undefined;
+}
+/**
+ * Check a module out from a fork, keeping where it came from.
+ *
+ * The fork has to exist already — on GitHub, the Fork button — since creating
+ * repositories is not something to do behind anyone's back. Forking a fork
+ * keeps the original upstream.
+ */
+export declare const forkModule: (root: string, submodule: Submodule, url: string, { ssh, push }?: ForkOptions) => ForkResult;
+export interface ContributeOptions {
+    /** Push the branch and open the pull request. On by default. */
+    push?: boolean;
+    /** The branch the pull request goes into; defaults to the upstream's own. */
+    base?: string;
+}
+export interface ContributeResult {
+    branch: string;
+    /** The repository the pull request is against, and its branch. */
+    repository: string;
+    base: string;
+    /** The pull request, when `gh` opened one. */
+    pullRequest: string | undefined;
+    /** Where to open it by hand otherwise, on GitHub. */
+    compare: string | undefined;
+    /** The fork's distribution branch, which now holds the pinned commit too. */
+    pinnedOn: string | undefined;
+    /**
+     * The line the module's changelog check wants, when the pull request is
+     * open and has none yet: its link filled in, its words left to whoever made
+     * the change, and to review.
+     */
+    changelog?: {
+        file: string;
+        version: string;
+        line: string;
+    };
+}
+/**
+ * Offer what is on the checkout's branch upstream, as a pull request.
+ *
+ * For a fork the branch goes to the fork and the pull request to upstream; for
+ * a module you can push to, both go to its own repository. A fork also moves
+ * its distribution branch up to the commit, since that is what is pinned and
+ * the pull request's branch is gone once merged.
+ */
+export declare const contribute: (root: string, submodule: Submodule, { push, base }?: ContributeOptions) => ContributeResult;
+export interface Integration {
+    /** `moved` when upstream's release already had the fork's work, `merged` otherwise. */
+    how: 'moved' | 'merged';
+    /** What was pushed to the fork: the distribution branch, or the release's tag. */
+    pushed: string | undefined;
+}
+/**
+ * Take an upstream release into a fork: what `bump` does for one.
+ *
+ * When the release already has everything the fork adds, the fork is simply
+ * moved to it — upstream has taken the work, and the fork could be dropped.
+ * Otherwise the release is merged into the fork, keeping the fork's changes on
+ * top, and pushed to the distribution branch. A merge rather than a rebase, so
+ * every commit an older distribution pinned stays in the fork.
+ */
+export declare const integrate: (root: string, state: SubmoduleState, tag: string, { push }?: {
+    push?: boolean;
+}) => Integration;
+export interface UnforkOptions {
+    /** What to go back to: an upstream tag, branch or commit. Chosen when omitted. */
+    to?: string;
+    /** Allow going back to a release with a newer major version. */
+    major?: boolean;
+    /** Go back to `to` even when it lacks some of what the fork adds. */
+    force?: boolean;
+}
+export interface UnforkResult {
+    /** The upstream url the module is checked out from again. */
+    url: string;
+    /** The release or ref it is pinned at. */
+    to: string;
+}
+/**
+ * Check a forked module out from its upstream again.
+ *
+ * Only to something that has everything the fork adds, unless forced: going
+ * back means the fork's commits stop shipping, and that should be because
+ * upstream has them, not by accident. Without `to`, the oldest upstream release
+ * from the pinned version on that has them is chosen — going back to upstream
+ * is not the moment to upgrade as well.
+ */
+export declare const unforkModule: (root: string, state: SubmoduleState, { to, major, force }?: UnforkOptions) => UnforkResult;
+//# sourceMappingURL=forks.d.ts.map

package/dist/forks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"forks.d.ts","sourceRoot":"","sources":["../src/forks.ts"],"names":[],"mappings":"AAkBA,OAAO,EAOL,KAAK,SAAS,EACd,KAAK,cAAc,EACpB,MAAM,iBAAiB,CAAA;AAqCxB;;;;;;;GAOG;AACH,eAAO,MAAM,kBAAkB,GAAI,MAAM,MAAM,KAAG,MAUjD,CAAA;AAoBD,8EAA8E;AAC9E,eAAO,MAAM,UAAU,GAAI,KAAK,MAAM,KAAG,MAAM,GAAG,SACgC,CAAA;AAYlF,MAAM,WAAW,WAAW;IAC1B,gEAAgE;IAChE,GAAG,CAAC,EAAE,OAAO,CAAA;IACb,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAA;CACf;AAED,MAAM,WAAW,UAAU;IACzB,kDAAkD;IAClD,GAAG,EAAE,MAAM,CAAA;IACX,gCAAgC;IAChC,QAAQ,EAAE,MAAM,CAAA;IAChB,8CAA8C;IAC9C,SAAS,EAAE,OAAO,CAAA;IAClB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAC3B;AAED;;;;;;GAMG;AACH,eAAO,MAAM,UAAU,GACrB,MAAM,MAAM,EACZ,WAAW,SAAS,EACpB,KAAK,MAAM,EACX,gBAA8B,WAAgB,KAC7C,UAmCF,CAAA;AAED,MAAM,WAAW,iBAAiB;IAChC,gEAAgE;IAChE,IAAI,CAAC,EAAE,OAAO,CAAA;IACd,6EAA6E;IAC7E,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,MAAM,CAAA;IACd,kEAAkE;IAClE,UAAU,EAAE,MAAM,CAAA;IAClB,IAAI,EAAE,MAAM,CAAA;IACZ,8CAA8C;IAC9C,WAAW,EAAE,MAAM,GAAG,SAAS,CAAA;IAC/B,qDAAqD;IACrD,OAAO,EAAE,MAAM,GAAG,SAAS,CAAA;IAC3B,6EAA6E;IAC7E,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAA;IAC5B;;;;OAIG;IACH,SAAS,CAAC,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAA;CAC5D;AAwCD;;;;;;;GAOG;AACH,eAAO,MAAM,UAAU,GACrB,MAAM,MAAM,EACZ,WAAW,SAAS,EACpB,iBAAuB,iBAAsB,KAC5C,gBAmFF,CAAA;AAED,MAAM,WAAW,WAAW;IAC1B,uFAAuF;IACvF,GAAG,EAAE,OAAO,GAAG,QAAQ,CAAA;IACvB,kFAAkF;IAClF,MAAM,EAAE,MAAM,GAAG,SAAS,CAAA;CAC3B;AAED;;;;;;;;GAQG;AACH,eAAO,MAAM,SAAS,GACpB,MAAM,MAAM,EACZ,OAAO,cAAc,EACrB,KAAK,MAAM,EACX,WAAiB;IAAE,IAAI,CAAC,EAAE,OAAO,CAAA;CAAO,KACvC,WAuCF,CAAA;AAED,MAAM,WAAW,aAAa;IAC5B,kFAAkF;IAClF,EAAE,CAAC,EAAE,MAAM,CAAA;IACX,gEAAgE;IAChE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,CAAA;CAChB;AAED,MAAM,WAAW,YAAY;IAC3B,6DAA6D;IAC7D,GAAG,EAAE,MAAM,CAAA;IACX,0CAA0C;IAC1C,EAAE,EAAE,MAAM,CAAA;CACX;AAiBD;;;;;;;;GAQG;AACH,eAAO,MAAM,YAAY,GACvB,MAAM,MAAM,EACZ,OAAO,cAAc,EACrB,uBAAsC,aAAkB,KACvD,YAyEF,CAAA"}

package/dist/forks.js

@@ -0,0 +1,357 @@
+import { execFileSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import semver from 'semver';
+import { CHANGELOG, aheadEntry, bumpEntry, crossedReleases, moduleLabel, noteInDistribution, releaseNotesLinks, repositoryLink, shown, topVersion, } from "./changelog.js";
+import { existsSync } from 'node:fs';
+import { describeRemote, toHttps } from "./git-url.js";
+import { UPSTREAM, containsAll, ensureUpstreamRemote, gitmodulesSet, moveTo, setUrl, } from "./submodules.js";
+/**
+ * Forking a module, from inside a distribution.
+ *
+ * A fork is the module checked out from somewhere you can push to, with the
+ * repository it came from recorded beside it. You fix or add something there,
+ * offer it upstream as a pull request, and meanwhile ship it. Updating works
+ * as it does for any module, except that a fork takes upstream's releases by
+ * merging them in. Once upstream has everything the fork adds, you can go back
+ * to upstream, or keep the fork.
+ */
+/** Run git, throwing with what it said when it fails. */
+const run = (cwd, args) => {
+    try {
+        return execFileSync('git', args, {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe'],
+        }).trim();
+    }
+    catch (cause) {
+        const stderr = cause instanceof Error && 'stderr' in cause ? String(cause.stderr).trim() : '';
+        throw new Error(`git ${args[0]} failed in ${cwd}${stderr ? `:\n${stderr}` : ''}`, { cause });
+    }
+};
+/** Run git, returning undefined rather than throwing when it fails. */
+const attempt = (cwd, args) => {
+    try {
+        return run(cwd, args);
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The branch in a fork that holds everything this distribution pins, named
+ * after the distribution.
+ *
+ * Not the pull request's branch: GitHub deletes that once it is merged, and a
+ * pinned commit has to stay fetchable for as long as anything pins it. Not the
+ * fork's main either, which is upstream's to follow.
+ */
+export const distributionBranch = (root) => {
+    let name;
+    try {
+        name = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8')).name;
+    }
+    catch {
+        name = undefined;
+    }
+    return (typeof name === 'string' ? name : path.basename(root))
+        .replace(/^@/, '')
+        .replace(/[^A-Za-z0-9._-]+/g, '-');
+};
+/**
+ * Put the checked-out commit on the fork's distribution branch, which only
+ * moves forward. `to` is the fork's url, or `origin` once it is the fork.
+ */
+const pushPinned = (submodule, branch, to = 'origin') => {
+    try {
+        run(submodule.path, ['push', '--quiet', to, `HEAD:refs/heads/${branch}`]);
+    }
+    catch (cause) {
+        const fork = to === 'origin' ? submodule.url : to;
+        throw new Error(`${branch} on ${describeRemote(fork)} has commits that ${submodule.relativePath} does not. ` +
+            `Merge them in first, then run this again:\n` +
+            `    cd ${submodule.relativePath} && git fetch ${fork} ${branch} && git merge FETCH_HEAD`, { cause });
+    }
+};
+/** `https://github.com/acme/id.git` -> `acme/id`; undefined anywhere else. */
+export const githubRepo = (url) => /^https:\/\/github\.com\/([^/]+\/[^/]+?)(?:\.git)?\/?$/i.exec(toHttps(url))?.[1];
+/** The branch a remote's HEAD names, which is where pull requests go. */
+const defaultBranch = (cwd, remote) => {
+    const read = () => attempt(cwd, ['symbolic-ref', '--short', `refs/remotes/${remote}/HEAD`])?.replace(`${remote}/`, '');
+    const known = read();
+    if (known)
+        return known;
+    attempt(cwd, ['remote', 'set-head', remote, '--auto']);
+    return read() ?? 'main';
+};
+/**
+ * Check a module out from a fork, keeping where it came from.
+ *
+ * The fork has to exist already — on GitHub, the Fork button — since creating
+ * repositories is not something to do behind anyone's back. Forking a fork
+ * keeps the original upstream.
+ */
+export const forkModule = (root, submodule, url, { ssh = false, push = true } = {}) => {
+    const fork = ssh ? url : toHttps(url);
+    const upstream = submodule.upstream ?? submodule.url;
+    if (fork === submodule.url) {
+        throw new Error(`${submodule.relativePath} is already checked out from ${fork}.`);
+    }
+    if (fork === upstream) {
+        throw new Error(`${fork} is where ${submodule.relativePath} was forked from. ` +
+            `Run \`fg-dist unfork ${submodule.name}\` to go back to it.`);
+    }
+    // Before anything is written: a fork nobody can read is a pin nobody can fetch.
+    if (attempt(submodule.path, ['ls-remote', '--heads', fork]) === undefined) {
+        throw new Error(`Could not read ${fork}. Fork ${describeRemote(upstream)} there first, then run this again.`);
+    }
+    // Pushed before anything is recorded, so a refusal leaves the module as it was.
+    const branch = distributionBranch(root);
+    if (push)
+        pushPinned(submodule, branch, fork);
+    gitmodulesSet(root, submodule.configName, 'upstream', upstream);
+    setUrl(root, submodule, fork);
+    run(submodule.path, ['remote', 'set-url', 'origin', fork]);
+    ensureUpstreamRemote(submodule.path, upstream);
+    attempt(submodule.path, ['fetch', '--quiet', 'origin']);
+    attempt(submodule.path, ['fetch', '--quiet', '--tags', UPSTREAM]);
+    const { name } = moduleLabel(submodule.path);
+    noteInDistribution(root, `\`${name}\` forked to ${repositoryLink(fork)}, from ${repositoryLink(upstream)}`);
+    return { url: fork, upstream, rewritten: fork !== url, branch: push ? branch : undefined };
+};
+/** A pull request's title, as GitHub has it. */
+const pullRequestTitle = (cwd, url) => {
+    try {
+        return (execFileSync('gh', ['pr', 'view', url, '--json', 'title', '--jq', '.title'], {
+            cwd,
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'ignore'],
+        }).trim() || undefined);
+    }
+    catch {
+        return undefined;
+    }
+};
+/**
+ * The changelog line a pull request still needs, with its link: only the
+ * words are left, which are the author's to write. Undefined for a module
+ * without a changelog, or one that links the pull request already.
+ */
+const changelogLine = (submodule, pullRequest) => {
+    const file = path.join(submodule.path, CHANGELOG);
+    if (!existsSync(file))
+        return undefined;
+    const text = readFileSync(file, 'utf8');
+    if (text.toLowerCase().includes(pullRequest.replace(/^https?:\/\//, '').toLowerCase()))
+        return undefined;
+    const version = topVersion(text);
+    const number = /\/pull\/(\d+)/.exec(pullRequest)?.[1];
+    if (!version || !number)
+        return undefined;
+    return {
+        file: path.join(submodule.relativePath, CHANGELOG),
+        version,
+        line: `- What this changes, for someone using it ([#${number}](${pullRequest}))`,
+    };
+};
+/**
+ * Offer what is on the checkout's branch upstream, as a pull request.
+ *
+ * For a fork the branch goes to the fork and the pull request to upstream; for
+ * a module you can push to, both go to its own repository. A fork also moves
+ * its distribution branch up to the commit, since that is what is pinned and
+ * the pull request's branch is gone once merged.
+ */
+export const contribute = (root, submodule, { push = true, base } = {}) => {
+    const cwd = submodule.path;
+    const branch = attempt(cwd, ['symbolic-ref', '--short', '-q', 'HEAD']);
+    if (!branch) {
+        throw new Error(`${submodule.relativePath} is not on a branch. Start one for the change:\n` +
+            `    cd ${submodule.relativePath} && git switch -c <name>`);
+    }
+    if ((attempt(cwd, ['status', '--porcelain']) ?? '') !== '') {
+        throw new Error(`${submodule.relativePath} has uncommitted changes. Commit them first.`);
+    }
+    const fork = submodule.upstream;
+    const remote = fork ? UPSTREAM : 'origin';
+    const repository = fork ?? submodule.url;
+    if (fork) {
+        ensureUpstreamRemote(cwd, fork);
+        attempt(cwd, ['fetch', '--quiet', UPSTREAM]);
+    }
+    const into = base ?? defaultBranch(cwd, remote);
+    if (!fork && branch === into) {
+        throw new Error(`${submodule.relativePath} is on ${into} itself. A pull request needs a branch of its own:\n` +
+            `    cd ${submodule.relativePath} && git switch -c <name>`);
+    }
+    const upstreamRepo = githubRepo(repository);
+    const ownRepo = githubRepo(submodule.url);
+    const head = fork && ownRepo ? `${ownRepo.split('/')[0]}:${branch}` : branch;
+    const compare = upstreamRepo
+        ? `https://github.com/${upstreamRepo}/compare/${into}...${head}?expand=1`
+        : undefined;
+    if (!push) {
+        return { branch, repository, base: into, pullRequest: undefined, compare, pinnedOn: undefined };
+    }
+    run(cwd, ['push', '--quiet', '-u', 'origin', branch]);
+    const pinnedOn = fork ? distributionBranch(root) : undefined;
+    if (pinnedOn)
+        pushPinned(submodule, pinnedOn);
+    let pullRequest;
+    if (upstreamRepo) {
+        try {
+            const output = execFileSync('gh', ['pr', 'create', '--repo', upstreamRepo, '--base', into, '--head', head, '--fill'], { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] });
+            pullRequest = /https:\/\/\S+/.exec(output)?.[0];
+        }
+        catch {
+            // No gh, not signed in, or one already open: the compare link does the rest.
+            pullRequest = undefined;
+        }
+    }
+    // What the change is, in the distribution's changelog: the pull request's
+    // title, or without one, what its last commit says. Never the branch's name,
+    // which means nothing to anyone reading it.
+    const title = (pullRequest && pullRequestTitle(cwd, pullRequest)) ||
+        attempt(cwd, ['log', '-1', '--format=%s']) ||
+        branch;
+    // Linked where it can be read about: its pull request, or else its commit.
+    const { name } = moduleLabel(cwd);
+    const number = pullRequest && /\/pull\/(\d+)/.exec(pullRequest)?.[1];
+    const tip = attempt(cwd, ['rev-parse', 'HEAD']);
+    const link = pullRequest && upstreamRepo && number
+        ? { text: `${upstreamRepo}#${number}`, url: pullRequest }
+        : ownRepo && tip
+            ? { text: `${ownRepo}@${tip.slice(0, 7)}`, url: `https://github.com/${ownRepo}/commit/${tip}` }
+            : undefined;
+    noteInDistribution(root, aheadEntry(name, title, link));
+    // The module's own line is written by whoever made the change, and reviewed
+    // with it; only its link is known here.
+    const changelog = pullRequest ? changelogLine(submodule, pullRequest) : undefined;
+    return { branch, repository, base: into, pullRequest, compare, pinnedOn, changelog };
+};
+/**
+ * Take an upstream release into a fork: what `bump` does for one.
+ *
+ * When the release already has everything the fork adds, the fork is simply
+ * moved to it — upstream has taken the work, and the fork could be dropped.
+ * Otherwise the release is merged into the fork, keeping the fork's changes on
+ * top, and pushed to the distribution branch. A merge rather than a rebase, so
+ * every commit an older distribution pinned stays in the fork.
+ */
+export const integrate = (root, state, tag, { push = true } = {}) => {
+    const { submodule } = state;
+    const cwd = submodule.path;
+    const upstream = submodule.upstream ?? submodule.url;
+    const { name } = moduleLabel(cwd);
+    const from = state.current ?? state.head.slice(0, 7);
+    const releases = crossedReleases(state.available, tag);
+    if (containsAll(cwd, `refs/tags/${tag}`, state.head)) {
+        moveTo(submodule, tag);
+        // The fork may not have the release yet, and it is what is pinned now.
+        if (push)
+            run(cwd, ['push', '--quiet', 'origin', `refs/tags/${tag}`]);
+        noteInDistribution(root, bumpEntry(name, from, tag, upstream, releases, 'which has everything the fork added'));
+        return { how: 'moved', pushed: push ? tag : undefined };
+    }
+    try {
+        run(cwd, [
+            'merge',
+            '--no-edit',
+            '--quiet',
+            '-m',
+            `Merge ${tag} from ${describeRemote(upstream)}`,
+            `refs/tags/${tag}`,
+        ]);
+    }
+    catch (cause) {
+        attempt(cwd, ['merge', '--abort']);
+        throw new Error(`${tag} does not merge cleanly into ${submodule.relativePath}. Merge it by hand, ` +
+            `then push, and commit the new pin:\n    cd ${submodule.relativePath} && git merge ${tag}`, { cause });
+    }
+    const branch = distributionBranch(root);
+    if (push)
+        pushPinned(submodule, branch);
+    noteInDistribution(root, bumpEntry(name, from, tag, upstream, releases, 'merged into the fork'));
+    return { how: 'merged', pushed: push ? branch : undefined };
+};
+/** Commits the fork has that `base` does not, for saying what would be lost. */
+const notIn = (cwd, base) => (attempt(cwd, [
+    'log',
+    '--no-merges',
+    '--cherry-pick',
+    '--right-only',
+    '--format=%h %s',
+    `${base}...HEAD`,
+]) ?? '')
+    .split('\n')
+    .filter(Boolean);
+/**
+ * Check a forked module out from its upstream again.
+ *
+ * Only to something that has everything the fork adds, unless forced: going
+ * back means the fork's commits stop shipping, and that should be because
+ * upstream has them, not by accident. Without `to`, the oldest upstream release
+ * from the pinned version on that has them is chosen — going back to upstream
+ * is not the moment to upgrade as well.
+ */
+export const unforkModule = (root, state, { to, major = false, force = false } = {}) => {
+    const { submodule } = state;
+    const cwd = submodule.path;
+    const upstream = submodule.upstream;
+    if (!upstream) {
+        throw new Error(`${submodule.relativePath} is not a fork; it is checked out from ${submodule.url}.`);
+    }
+    if (state.dirty) {
+        throw new Error(`${submodule.relativePath} has uncommitted changes. Commit or drop them first.`);
+    }
+    let target;
+    let label;
+    if (to) {
+        const ref = [`refs/tags/${to}`, `${UPSTREAM}/${to}`, to].find((candidate) => attempt(cwd, ['rev-parse', '--verify', '--quiet', `${candidate}^{commit}`]) !== undefined);
+        if (!ref)
+            throw new Error(`${to} is not a tag, upstream branch or commit in ${submodule.relativePath}.`);
+        const lost = containsAll(cwd, ref, state.head) ? [] : notIn(cwd, ref);
+        if (lost.length > 0 && !force) {
+            throw new Error(`${to} does not have everything the fork adds:\n${lost.map((line) => `  ${line}`).join('\n')}\n` +
+                'Pass --force to go back anyway and stop shipping them.');
+        }
+        target = ref;
+        label = to;
+    }
+    else {
+        const merged = state.fork?.merged;
+        if (!merged) {
+            const tip = `${UPSTREAM}/HEAD`;
+            const lost = notIn(cwd, attempt(cwd, ['rev-parse', '--verify', '--quiet', tip]) ? tip : 'HEAD');
+            throw new Error(`Upstream has not taken everything ${submodule.relativePath} adds yet:\n` +
+                `${lost.map((line) => `  ${line}`).join('\n')}\n` +
+                'Keep the fork until it has, or pass --to <tag> --force to go back without them.');
+        }
+        if (!semver.valid(merged)) {
+            throw new Error(`Only ${merged} has everything ${submodule.relativePath} adds, and it is not a release yet. ` +
+                `Wait for one, or pass --to ${merged.replace(`${UPSTREAM}/`, '')} to go back to the branch.`);
+        }
+        if (!major && state.current && semver.major(merged) !== semver.major(state.current)) {
+            throw new Error(`The first release with everything ${submodule.relativePath} adds is ${merged}, a major ` +
+                'upgrade. Pass --major to go back to it.');
+        }
+        target = `refs/tags/${merged}`;
+        label = merged;
+    }
+    const lost = containsAll(cwd, target, state.head) ? [] : notIn(cwd, target);
+    run(cwd, ['checkout', '--quiet', `${target}^{commit}`]);
+    setUrl(root, submodule, upstream);
+    run(cwd, ['remote', 'set-url', 'origin', upstream]);
+    gitmodulesSet(root, submodule.configName, 'upstream', undefined);
+    attempt(cwd, ['remote', 'remove', UPSTREAM]);
+    const { name } = moduleLabel(cwd);
+    const notes = semver.valid(label) ? releaseNotesLinks(upstream, crossedReleases(state.available, label)) : '';
+    noteInDistribution(root, `\`${name}\` back to ${repositoryLink(upstream)} at ${shown(label)}, ` +
+        (lost.length > 0
+            ? `leaving behind ${lost.length} commit${lost.length === 1 ? '' : 's'} of the fork's that upstream does not have`
+            : 'which has everything the fork added') +
+        notes);
+    return { url: upstream, to: label };
+};
+//# sourceMappingURL=forks.js.map