canopycms 0.12.0 → 0.13.0

package/dist/worker/branch-merge.d.ts

@@ -1,14 +1,30 @@
 import type { SimpleGit } from 'simple-git';
-import { type ContentId } from '../paths/types.js';
-import type { ConflictStatus } from '../types.js';
+import type { KeyRemap } from '../merge/entry-merge.js';
+import type { FoundEntryConflict } from '../merge-conflicts.js';
 import type { WorkerContext } from './worker-context.js';
-/** What {@link buildMergeCommit} made of the two commits. */
-export type BuiltMerge = 
-/** `sha` is the merge, reachable from no ref yet. `conflicted` kept the branch's version. */
-{
-    kind: 'built';
-    sha: string;
-    conflicted: string[];
+/** What {@link planMerge} made of the two commits. */
+export type MergePlan = {
+    kind: 'planned';
+    /** The merge's tree. */
+    tree: string;
+    /** The tree git's own merge wrote, conflict markers and all. */
+    gitTree: string;
+    /** Paths git could not merge, whoever settled them. */
+    gitConflicted: string[];
+    /** What a person must still decide, entry by entry. */
+    conflicts: FoundEntryConflict[];
+    /** Paths where the branch's version stands over the other side's change, whole or in part. */
+    keptPaths: string[];
+    /** Git's own merge with nothing for a person: no conflict, and every file as git merged it. */
+    asGitDoes: boolean;
+    /** Item keys the merge changed, by the entry path the branch's comment threads name. */
+    keyRemaps: Array<{
+        entryPath: string;
+        contentId?: string;
+        remaps: KeyRemap[];
+    }>;
+    /** Where each entry the merge decided stands in it. */
+    paths: Map<string, string>;
 }
 /** Git met conflicts no rule settles safely. Nothing was built. */
  | {
@@ -16,24 +32,69 @@ export type BuiltMerge =
     conflicts: string[];
     paths: string[];
 };
+/** {@link commitMerge}'s commit of a planned merge; `sha` is reachable from no ref yet. */
+export type BuiltMerge = Omit<Extract<MergePlan, {
+    kind: 'planned';
+}>, 'kind' | 'tree' | 'gitTree'> & {
+    kind: 'built';
+    sha: string;
+};
 /**
- * The merge of `other` into `head`, as a commit no ref names, with `head` the first parent. A path
- * git cannot merge keeps `head`'s side, stage 2, at the path git reports, or stays deleted when
- * `head` has no such stage: the rule the rebase loop applies to a conflict, since `head` has the
- * editor's work. The commit takes its identity from the clone's `user.*`, written when the clone
- * is provisioned.
+ * The merge of `other` into `head`, as a tree. Every entry and `.collection.json` both sides
+ * changed is merged field by field (field-merge.ts), which settles git's conflicts there, whatever
+ * their kind. A path git cannot merge that is no entry keeps `head`'s side, stage 2, at the path
+ * git reports, or stays deleted when `head` has no such stage: `head` has the editor's work. With
+ * no single merge base, git's merge stands as that rule leaves it, since a field merge needs one
+ * version both sides started from.
  */
-export declare function buildMergeCommit(git: SimpleGit, clonePath: string, args: {
+export declare function planMerge(git: SimpleGit, clonePath: string, args: {
     head: string;
     other: string;
-    message: string;
+    contentRoot: string;
     timeoutMs: number;
+}): Promise<MergePlan>;
+/**
+ * {@link planMerge}'s merge as a commit no ref names, with `head` the first parent. The commit takes
+ * its identity from the clone's `user.*`, written when the clone is provisioned.
+ */
+export declare function commitMerge(git: SimpleGit, plan: Extract<MergePlan, {
+    kind: 'planned';
+}>, { head, other, message }: {
+    head: string;
+    other: string;
+    message: string;
 }): Promise<BuiltMerge>;
+/** Whether `plan` is git's own merge with nothing for a person. */
+export declare const mergesAsGitDoes: (plan: MergePlan) => boolean;
+/**
+ * Whether `merged` holds exactly what `from` and `other` merge to cleanly, and so nothing else, the
+ * item keys of entries under `contentRoot` aside: a re-key ({@link buildRekey}) changes no content.
+ * A conflict counts as no: whoever settled it chose what `merged` holds.
+ */
+export declare function isCleanMergeOf(git: SimpleGit, merged: string, from: string, other: string, contentRoot: string): Promise<boolean>;
 /**
- * Whether `merged` holds exactly what `from` and `other` merge to cleanly, and so nothing else. A
- * conflict counts as no: whoever settled it chose what `merged` holds.
+ * A commit on `tip` that gives the items of every entry a merge on the branch's own line in
+ * `from..tip` (first parents: never the base's history) brought in the keys the field merge of
+ * that merge's two parents gives them, where it holds what git merged
+ * (field-merge.ts `rekeyOnly`) and `tip` still holds the merge's version. Git keeps each item under
+ * the key its side's copy held, which can name another item once the other side changed it; the
+ * field merge's are the keys a later merge reads correctly. Null when no item needs a new key.
  */
-export declare function isCleanMergeOf(git: SimpleGit, merged: string, from: string, other: string): Promise<boolean>;
+export declare function buildRekey(git: SimpleGit, clonePath: string, args: {
+    from: string;
+    tip: string;
+    contentRoot: string;
+    timeoutMs: number;
+    message: string;
+    /**
+     * Only entries `head` holds as `since` held them: a merge of `head` with the re-key reads an
+     * entry `head` changed against `since`'s keys, which git's merge keeps and a re-key would not.
+     */
+    unchangedIn?: {
+        head: string;
+        since: string;
+    };
+}): Promise<BuiltMerge | null>;
 /**
  * Move `refs/heads/<branchRef>` in remote.git to `sha` as a plain push, so it can only ever
  * fast-forward. Resolves false when it would not: under the caller's locks, the only writers left
@@ -45,24 +106,3 @@ export declare function commitsApart(git: SimpleGit, a: string, b: string): Prom
     onlyA: number;
     onlyB: number;
 }>;
-/**
- * Map the file paths a rebase or merge kept the branch's version of onto the ContentIds the
- * editor shows as conflicted, deduplicated. IDs rather than paths because they are
- * immutable: a later slug rename must not orphan a conflict marker. Paths that
- * carry no recoverable ID are dropped rather than guessed at.
- *
- * Pure.
- */
-export declare function conflictFilesToContentIds(conflictedFiles: readonly string[], contentRoot: string): ContentId[];
-/**
- * The conflict record after a rebase or merge: the IDs already recorded plus
- * its own. A conflict means this branch's version replaced base's change to
- * that entry, which a later clean rebase does not undo, so the record only
- * grows until the branch merges (buildMergedBranchUpdate clears it).
- *
- * Pure.
- */
-export declare function recordConflicts(recorded: readonly ContentId[] | undefined, found: readonly ContentId[]): {
-    conflictStatus: ConflictStatus;
-    conflictFiles: ContentId[];
-};

package/dist/worker/branch-merge.js

@@ -1,11 +1,14 @@
 import { randomUUID } from 'node:crypto';
 import fs from 'node:fs/promises';
 import path from 'node:path';
+import { readSchemaSnapshot } from '../branch-schema-cache.js';
 import { extractIdFromFilename } from '../content-id-index.js';
 import { normalizeFilesystemPath } from '../paths/normalize.js';
 import { ROOT_COLLECTION_ID } from '../paths/types.js';
 import { isNonFastForwardRejection } from '../utils/git.js';
 import { getErrorMessage, redactCredentials } from '../utils/error.js';
+import { parseTypedFilename } from '../utils/typed-filename.js';
+import { changedFiles, resolveFieldMerge, differsInItemKeysOnly, } from './field-merge.js';
 import { runGit } from './git-process.js';
 import { pinnedReceivePack, sharedRepoGit, sharedRepoProcessOptions } from './shared-repo-git.js';
 /**
@@ -16,10 +19,12 @@ import { pinnedReceivePack, sharedRepoGit, sharedRepoProcessOptions } from './sh
  */
 const OBJECT_ID = /^[0-9a-f]{40}([0-9a-f]{24})?$/;
 /**
- * The conflicts {@link buildMergeCommit} settles by keeping `head`'s side of one path. Every other
- * kind (a rename colliding with another, a file meeting a directory, a directory rename) moves or
- * joins paths, so no one side of one path is the branch's version, and settling it by rule loses a
- * file. Messages that are not `CONFLICT` are git's notes, such as `Auto-merging`.
+ * The conflicts {@link planMerge} settles by keeping `head`'s side of one path. Every other kind (a
+ * rename colliding with another, a file meeting a directory, a directory rename) moves or joins
+ * paths, so no one side of one path is the branch's version, and settling it by rule loses a file;
+ * only the field merge, which pairs entries by content ID, settles those, and only where it decides
+ * every path the conflict names. Messages that are not `CONFLICT` are git's notes, such as
+ * `Auto-merging`.
  */
 const SETTLED_BY_KEEPING_HEAD = new Set([
     'CONFLICT (contents)',
@@ -46,27 +51,44 @@ function parseMergeTree(output, head, other) {
         const [, mode, oid, stage, path] = match;
         stages.push({ mode, oid, stage, path });
     }
-    const unsettled = new Set();
+    const unsettled = [];
     for (i++; i < fields.length && fields[i] !== '';) {
-        const kind = fields[i + parseInt(fields[i], 10) + 1];
-        if (kind?.startsWith('CONFLICT') && !SETTLED_BY_KEEPING_HEAD.has(kind))
-            unsettled.add(kind);
-        i += parseInt(fields[i], 10) + 3;
+        const count = parseInt(fields[i], 10);
+        const kind = fields[i + count + 1];
+        if (kind?.startsWith('CONFLICT') && !SETTLED_BY_KEEPING_HEAD.has(kind)) {
+            unsettled.push({ kind, paths: fields.slice(i + 1, i + 1 + count) });
+        }
+        i += count + 3;
     }
     // A path git could not decode as UTF-8 reads back as U+FFFD, which names no file.
-    if (stages.some(({ path }) => path.includes('\ufffd')))
-        unsettled.add('an unreadable file name');
-    return { tree, stages, unsettled: [...unsettled] };
+    const undecodable = stages.filter(({ path }) => path.includes('\ufffd')).map(({ path }) => path);
+    if (undecodable.length > 0)
+        unsettled.push({ kind: 'an unreadable file name', paths: [] });
+    return { tree, stages, unsettled };
 }
+const NO_FIELD_MERGE = {
+    updates: new Map(),
+    covered: new Set(),
+    conflicts: [],
+    keyRemaps: [],
+    paths: new Map(),
+};
 /**
- * The merge of `other` into `head`, as a commit no ref names, with `head` the first parent. A path
- * git cannot merge keeps `head`'s side, stage 2, at the path git reports, or stays deleted when
- * `head` has no such stage: the rule the rebase loop applies to a conflict, since `head` has the
- * editor's work. The commit takes its identity from the clone's `user.*`, written when the clone
- * is provisioned.
+ * The merge of `other` into `head`, as a tree. Every entry and `.collection.json` both sides
+ * changed is merged field by field (field-merge.ts), which settles git's conflicts there, whatever
+ * their kind. A path git cannot merge that is no entry keeps `head`'s side, stage 2, at the path
+ * git reports, or stays deleted when `head` has no such stage: `head` has the editor's work. With
+ * no single merge base, git's merge stands as that rule leaves it, since a field merge needs one
+ * version both sides started from.
  */
-export async function buildMergeCommit(git, clonePath, args) {
-    const { head, other, message, timeoutMs } = args;
+export async function planMerge(git, clonePath, args) {
+    const { head, other, contentRoot, timeoutMs } = args;
+    const bases = (await git.raw(['merge-base', '--all', '--end-of-options', head, other]))
+        .split('\n')
+        .filter((line) => OBJECT_ID.test(line));
+    if (bases.length === 0) {
+        return { kind: 'unsettled', conflicts: ['no history in common with it'], paths: [] };
+    }
     const output = await git.raw([
         'merge-tree',
         '--write-tree',
@@ -75,21 +97,105 @@ export async function buildMergeCommit(git, clonePath, args) {
         head,
         other,
     ]);
-    const { tree: mergedTree, stages, unsettled } = parseMergeTree(output, head, other);
-    const conflicted = [...new Set(stages.map(({ path }) => path))];
-    if (unsettled.length > 0)
-        return { kind: 'unsettled', conflicts: unsettled, paths: conflicted };
-    const tree = stages.length === 0
-        ? mergedTree
-        : await keepHeadStages(clonePath, { mergedTree, stages, conflicted, timeoutMs });
+    const { tree: gitTree, stages, unsettled } = parseMergeTree(output, head, other);
+    const gitConflicted = [...new Set(stages.map(({ path }) => path))];
+    const field = bases.length === 1
+        ? await resolveFieldMerge({
+            git,
+            clonePath,
+            ancestor: bases[0],
+            head,
+            other,
+            mergedTree: gitTree,
+            conflicted: new Set(gitConflicted),
+            contentRoot,
+            flatSchema: await readSchemaSnapshot(clonePath),
+            collectionIdOf: (file) => conflictFilesToContentIds([file], contentRoot)[0],
+            timeoutMs,
+        })
+        : NO_FIELD_MERGE;
+    const unsettledLeft = unsettled.filter(({ paths }) => paths.length === 0 || paths.some((p) => !field.covered.has(p)));
+    if (field.unsettled)
+        unsettledLeft.push({ kind: field.unsettled, paths: [] });
+    if (unsettledLeft.length > 0) {
+        return {
+            kind: 'unsettled',
+            conflicts: [...new Set(unsettledLeft.map(({ kind }) => kind))],
+            paths: gitConflicted,
+        };
+    }
+    const updates = new Map(field.updates);
+    const kept = gitConflicted.filter((file) => !field.covered.has(file));
+    const headStages = new Map(stages.filter((s) => s.stage === '2').map((s) => [s.path, s]));
+    for (const file of kept) {
+        const stage = headStages.get(file);
+        updates.set(file, stage ? { path: file, mode: stage.mode, oid: stage.oid } : null);
+    }
+    const tree = updates.size === 0 ? gitTree : await withUpdates(clonePath, { gitTree, updates, timeoutMs });
+    const conflicts = [
+        ...field.conflicts,
+        ...keptVersions(kept, stages, contentRoot, field.conflicts),
+    ];
+    return {
+        kind: 'planned',
+        tree,
+        gitTree,
+        gitConflicted,
+        conflicts,
+        keptPaths: [...new Set([...field.conflicts.map(({ path }) => path), ...kept])],
+        keyRemaps: field.keyRemaps,
+        paths: field.paths,
+        asGitDoes: gitConflicted.length === 0 &&
+            conflicts.length === 0 &&
+            field.keyRemaps.length === 0 &&
+            tree === gitTree,
+    };
+}
+/**
+ * The files the merge kept `head`'s side of as entry-level conflicts, by the content ID their path
+ * carries, one per ID and none for an ID the field merge already names. A path with none is
+ * dropped rather than guessed at.
+ */
+function keptVersions(kept, stages, contentRoot, named) {
+    const seen = new Set(named.map(({ contentId }) => contentId));
+    const found = [];
+    for (const file of kept) {
+        const [contentId] = conflictFilesToContentIds([file], contentRoot);
+        if (!contentId || seen.has(contentId))
+            continue;
+        seen.add(contentId);
+        const oid = (stage) => stages.find((s) => s.path === file && s.stage === stage)?.oid;
+        const [ancestor, branch, base] = [oid('1'), oid('2'), oid('3')];
+        found.push({
+            contentId,
+            path: file,
+            kind: 'unreadable',
+            sides: {
+                ...(ancestor && { ancestor }),
+                ...(base && { base }),
+                ...(branch && { branch }),
+            },
+        });
+    }
+    return found;
+}
+/**
+ * {@link planMerge}'s merge as a commit no ref names, with `head` the first parent. The commit takes
+ * its identity from the clone's `user.*`, written when the clone is provisioned.
+ */
+export async function commitMerge(git, plan, { head, other, message }) {
+    const { tree, gitTree: _gitTree, kind: _kind, ...rest } = plan;
     const sha = (await git.raw(['commit-tree', '-p', head, '-p', other, '-m', message, '--end-of-options', tree])).trim();
-    return { kind: 'built', sha, conflicted };
+    return { kind: 'built', sha, ...rest };
 }
+/** Whether `plan` is git's own merge with nothing for a person. */
+export const mergesAsGitDoes = (plan) => plan.kind === 'planned' && plan.asGitDoes;
 /**
- * Whether `merged` holds exactly what `from` and `other` merge to cleanly, and so nothing else. A
- * conflict counts as no: whoever settled it chose what `merged` holds.
+ * Whether `merged` holds exactly what `from` and `other` merge to cleanly, and so nothing else, the
+ * item keys of entries under `contentRoot` aside: a re-key ({@link buildRekey}) changes no content.
+ * A conflict counts as no: whoever settled it chose what `merged` holds.
  */
-export async function isCleanMergeOf(git, merged, from, other) {
+export async function isCleanMergeOf(git, merged, from, other, contentRoot) {
     const output = await git.raw([
         'merge-tree',
         '--write-tree',
@@ -101,11 +207,110 @@ export async function isCleanMergeOf(git, merged, from, other) {
     const { tree, stages } = parseMergeTree(output, from, other);
     if (stages.length > 0)
         return false;
-    return (await git.revparse(['--verify', '--end-of-options', `${merged}^{tree}`])).trim() === tree;
+    const mergedTree = (await git.revparse(['--verify', '--end-of-options', `${merged}^{tree}`])).trim();
+    if (mergedTree === tree)
+        return true;
+    for (const { before, after } of await changedFiles(git, tree, mergedTree)) {
+        if (!before || !after || !(await differsInItemKeysOnly(git, before, after, contentRoot))) {
+            return false;
+        }
+    }
+    return true;
 }
-/** `mergedTree` with each of `conflicted` as `head` has it, through a throwaway index. */
-async function keepHeadStages(clonePath, args) {
-    const { mergedTree, stages, conflicted, timeoutMs } = args;
+/**
+ * A commit on `tip` that gives the items of every entry a merge on the branch's own line in
+ * `from..tip` (first parents: never the base's history) brought in the keys the field merge of
+ * that merge's two parents gives them, where it holds what git merged
+ * (field-merge.ts `rekeyOnly`) and `tip` still holds the merge's version. Git keeps each item under
+ * the key its side's copy held, which can name another item once the other side changed it; the
+ * field merge's are the keys a later merge reads correctly. Null when no item needs a new key.
+ */
+export async function buildRekey(git, clonePath, args) {
+    const { from, tip, contentRoot, timeoutMs, message, unchangedIn } = args;
+    const merges = (await git.raw([
+        'rev-list',
+        '--first-parent',
+        '--merges',
+        '--reverse',
+        '--end-of-options',
+        `${from}..${tip}`,
+    ]))
+        .split('\n')
+        .filter((line) => OBJECT_ID.test(line));
+    if (merges.length === 0)
+        return null;
+    const flatSchema = await readSchemaSnapshot(clonePath);
+    const updates = new Map();
+    const keyRemaps = [];
+    for (const merge of merges) {
+        const parents = (await git.raw(['rev-list', '--parents', '-n', '1', '--end-of-options', merge]))
+            .trim()
+            .split(' ')
+            .slice(1);
+        if (parents.length !== 2)
+            continue;
+        const bases = (await git.raw(['merge-base', '--all', '--end-of-options', ...parents]))
+            .split('\n')
+            .filter((line) => OBJECT_ID.test(line));
+        if (bases.length !== 1)
+            continue;
+        const field = await resolveFieldMerge({
+            git,
+            clonePath,
+            ancestor: bases[0],
+            head: parents[0],
+            other: parents[1],
+            mergedTree: (await git.revparse(['--verify', '--end-of-options', `${merge}^{tree}`])).trim(),
+            conflicted: new Set(),
+            contentRoot,
+            flatSchema,
+            collectionIdOf: (file) => conflictFilesToContentIds([file], contentRoot)[0],
+            timeoutMs,
+            rekeyOnly: true,
+        });
+        const applied = new Set();
+        for (const [file, blob] of field.updates) {
+            // A later commit that changed the entry again decided its keys itself.
+            if (!blob || (await blobAt(git, merge, file)) !== (await blobAt(git, tip, file)))
+                continue;
+            if (unchangedIn &&
+                (await blobAt(git, unchangedIn.head, file)) !== (await blobAt(git, unchangedIn.since, file))) {
+                continue;
+            }
+            updates.set(file, blob);
+            const id = parseTypedFilename(path.posix.basename(file))?.id;
+            if (id !== undefined)
+                applied.add(id);
+        }
+        keyRemaps.push(...field.keyRemaps.filter((r) => r.contentId !== undefined && applied.has(r.contentId)));
+    }
+    if (updates.size === 0)
+        return null;
+    const tipTree = (await git.revparse(['--verify', '--end-of-options', `${tip}^{tree}`])).trim();
+    const tree = await withUpdates(clonePath, { gitTree: tipTree, updates, timeoutMs });
+    const sha = (await git.raw(['commit-tree', '-p', tip, '-m', message, '--end-of-options', tree])).trim();
+    return {
+        kind: 'built',
+        sha,
+        gitConflicted: [],
+        conflicts: [],
+        keptPaths: [],
+        asGitDoes: false,
+        keyRemaps,
+        paths: new Map(),
+    };
+}
+/** The blob `commit` holds at `file`, or null for none. */
+async function blobAt(git, commit, file) {
+    const out = await git
+        .raw(['rev-parse', '--verify', '--quiet', '--end-of-options', `${commit}:${file}`])
+        .catch(() => '');
+    const oid = out.trim();
+    return OBJECT_ID.test(oid) ? oid : null;
+}
+/** `gitTree` with each of `updates` in place, through a throwaway index. */
+async function withUpdates(clonePath, args) {
+    const { gitTree, updates, timeoutMs } = args;
     const shared = sharedRepoProcessOptions(clonePath, 'worktree');
     const indexFile = path.join(clonePath, '.git', `canopy-merge-index-${randomUUID()}`);
     const options = {
@@ -113,15 +318,11 @@ async function keepHeadStages(clonePath, args) {
         env: { ...shared.env, GIT_INDEX_FILE: indexFile },
         inactivityTimeoutMs: timeoutMs,
     };
-    const kept = new Map(stages.filter((s) => s.stage === '2').map((s) => [s.path, s]));
-    // Mode 0 removes a path: what is left when `head` has no side of it.
-    const zeros = '0'.repeat(mergedTree.length);
-    const entries = conflicted.map((file) => {
-        const entry = kept.get(file);
-        return `${entry?.mode ?? '0'} ${entry?.oid ?? zeros}\t${file}\0`;
-    });
+    // Mode 0 removes a path.
+    const zeros = '0'.repeat(gitTree.length);
+    const entries = [...updates].map(([file, blob]) => `${blob?.mode ?? '0'} ${blob?.oid ?? zeros}\t${file}\0`);
     try {
-        await runGit(['read-tree', '--end-of-options', mergedTree], options);
+        await runGit(['read-tree', '--end-of-options', gitTree], options);
         await runGit(['update-index', '-z', '--index-info'], { ...options, stdin: entries.join('') });
         return (await runGit(['write-tree'], options)).trim();
     }
@@ -170,7 +371,7 @@ export async function commitsApart(git, a, b) {
  *
  * Pure.
  */
-export function conflictFilesToContentIds(conflictedFiles, contentRoot) {
+function conflictFilesToContentIds(conflictedFiles, contentRoot) {
     // Entry files carry their ID in the filename. A `.collection.json` has none
     // of its own (extractIdFromFilename returns null for dot-prefixed files), so
     // the ID comes from the parent directory; the root content directory has no
@@ -211,18 +412,3 @@ export function conflictFilesToContentIds(conflictedFiles, contentRoot) {
         .filter((id) => id !== null);
     return [...new Set(conflictIds)];
 }
-/**
- * The conflict record after a rebase or merge: the IDs already recorded plus
- * its own. A conflict means this branch's version replaced base's change to
- * that entry, which a later clean rebase does not undo, so the record only
- * grows until the branch merges (buildMergedBranchUpdate clears it).
- *
- * Pure.
- */
-export function recordConflicts(recorded, found) {
-    const conflictFiles = [...new Set([...(recorded ?? []), ...found])];
-    return {
-        conflictStatus: conflictFiles.length > 0 ? 'conflicts-detected' : 'clean',
-        conflictFiles,
-    };
-}

package/dist/worker/branch-policy.d.ts

@@ -15,8 +15,8 @@ export declare const MAX_PULL_REQUEST_TITLE_LENGTH = 1024;
  * @internal Exported for tests.
  */
 export declare const MAX_PULL_REQUEST_BODY_LENGTH = 65536;
-export type GatewayOperation = 'push' | 'delete' | 'pull-request';
-export type RefusalReason = 'invalid' | 'protected' | 'settings' | 'other-settings' | 'outside-namespace' | 'not-a-commit' | 'too-long';
+export type GatewayOperation = 'push' | 'delete' | 'pull-request' | 'commit-status';
+export type RefusalReason = 'invalid' | 'protected' | 'settings' | 'other-settings' | 'outside-namespace' | 'not-a-commit' | 'too-long' | 'not-head';
 /** The refusals {@link BranchPolicy.assertPushAllowed} makes. */
 export type PushPolicyRefusal = 'protected' | 'settings' | 'other-settings' | 'outside-namespace';
 /**
@@ -217,3 +217,19 @@ export declare function assertPullRequestText(refusing: string, branch: string,
     title?: string;
     body?: string;
 }): void;
+/**
+ * The longest commit status description the gateway sends, the length GitHub documents for a
+ * deployment status's; its own descriptions are far shorter.
+ * @internal Exported for tests.
+ */
+export declare const MAX_COMMIT_STATUS_DESCRIPTION_LENGTH = 140;
+/** The longest commit status target URL the gateway sends, as the editor URL is capped. */
+export declare const MAX_COMMIT_STATUS_URL_LENGTH = 2048;
+/**
+ * Refuse a commit status description over the cap or holding a control character, and a target
+ * URL that is not plain http(s) or carries credentials. `branch` names the pull request's head.
+ */
+export declare function assertCommitStatusText(refusing: string, branch: string, text: {
+    description: string;
+    targetUrl?: string;
+}): void;

package/dist/worker/branch-policy.js

@@ -442,6 +442,42 @@ export function assertPullRequestText(refusing, branch, text) {
         throw new GatewayRefusalError('pull-request', branch, 'too-long', `${refusing}: ${over}`);
     }
 }
+/**
+ * The longest commit status description the gateway sends, the length GitHub documents for a
+ * deployment status's; its own descriptions are far shorter.
+ * @internal Exported for tests.
+ */
+export const MAX_COMMIT_STATUS_DESCRIPTION_LENGTH = 140;
+/** The longest commit status target URL the gateway sends, as the editor URL is capped. */
+export const MAX_COMMIT_STATUS_URL_LENGTH = 2048;
+/**
+ * Refuse a commit status description over the cap or holding a control character, and a target
+ * URL that is not plain http(s) or carries credentials. `branch` names the pull request's head.
+ */
+export function assertCommitStatusText(refusing, branch, text) {
+    if (text.description.length > MAX_COMMIT_STATUS_DESCRIPTION_LENGTH) {
+        throw new GatewayRefusalError('commit-status', branch, 'too-long', `${refusing}: its description is longer than ${MAX_COMMIT_STATUS_DESCRIPTION_LENGTH} characters`);
+    }
+    // eslint-disable-next-line no-control-regex -- the control characters are what it refuses
+    if (/[\u0000-\u001f\u007f]/.test(text.description)) {
+        throw new GatewayRefusalError('commit-status', branch, 'invalid', `${refusing}: its description holds a control character`);
+    }
+    if (text.targetUrl !== undefined && !isPlainWebUrl(text.targetUrl)) {
+        throw new GatewayRefusalError('commit-status', branch, 'invalid', `${refusing}: its target URL is not a plain http(s) URL of at most ${MAX_COMMIT_STATUS_URL_LENGTH} characters`);
+    }
+}
+function isPlainWebUrl(raw) {
+    if (raw.length > MAX_COMMIT_STATUS_URL_LENGTH)
+        return false;
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        return false;
+    }
+    return (url.protocol === 'https:' || url.protocol === 'http:') && !url.username && !url.password;
+}
 /** Equal, or naming the same workspace directory. */
 function sameBranch(a, b) {
     return a === b || sanitizeBranchName(a) === sanitizeBranchName(b);