@hominis/fireforge 0.50.0 → 0.51.0

package/dist/src/core/patch-lint-token-scale.d.ts

@@ -6,20 +6,29 @@
  * or referencing foreign custom properties, but say nothing about
  * `gap: 7px`, `font-size: 13px` or `z-index: 9999`. Those are the values a
  * design scale exists to remove, and without a rule they drift back one
- * literal at a time. A scale names its properties, the token prefix that
- * defines its steps, and the literals that are not steps at all (`0`,
- * `auto`, a percentage).
+ * literal at a time. A scale names its properties, the token prefix (or
+ * prefixes) that defines its steps, and the literals that are not steps at
+ * all (`0`, `auto`, a percentage).
  *
  * Judged per value atom, after peeling `var()` innermost-first so a fallback
  * is held to the same scale as the token it backs: `var(--x-gap, 7px)` is a
  * literal in disguise. `calc()`, `min()`, `max()` and `clamp()` are
  * transparent, so a value built from tokens passes and one that adds a raw
- * length does not. Unitless multipliers inside them are literals too and
- * need an `allowLiterals` entry.
+ * length does not. Inside them, `allowInCalc` names literals legal only
+ * there (a unitless multiplier), and `offsetCap` lets a declaration
+ * subtract a few px from a token (a border inset) without allowing the px
+ * value anywhere else.
+ *
+ * Declarations inside descriptor at-rules (`@font-face`, `@counter-style`,
+ * `@property`, `@page`, …) are not property declarations and are not
+ * judged: `font-weight` in `@font-face` names a face, not a type step.
  *
  * Runs over CSS files the patch creates, not files it modifies: an upstream
- * stylesheet is not the fork's to put on a scale. A line carrying
- * `fireforge-ignore: token-scale` is skipped.
+ * stylesheet is not the fork's to put on a scale. A file a scale `exclude`s
+ * is not judged against that scale. A line carrying
+ * `fireforge-ignore: token-scale` is skipped. A scale with `minFiles` also
+ * fails the queue (`token-scale-vacuous`) when fewer created files carry
+ * its properties, so an emptied scan set cannot pass by judging nothing.
  */
 import type { PatchLintIssue } from '../types/commands/index.js';
 import type { PatchLintTokenScale } from '../types/config.js';
@@ -31,9 +40,18 @@ export declare function findOffScaleAtom(value: string, scale: PatchLintTokenSca
 /**
  * Lints one patch-created CSS file against the configured scales.
  *
- * @param file - Engine-relative path, for the issue
+ * @param file - Engine-relative path, for the issue and the `exclude` globs
  * @param css - The file's full content
  * @param scales - `patchLint.tokenScales`
  * @returns One `token-scale` error per off-scale declaration
  */
 export declare function lintTokenScales(file: string, css: string, scales: readonly PatchLintTokenScale[]): PatchLintIssue[];
+/**
+ * The `minFiles` floor of every scale over the queue's created stylesheets:
+ * one `token-scale-vacuous` error per scale that fewer created CSS files
+ * (outside its `exclude`) carry a declaration of.
+ *
+ * @param createdFiles - Every patch-created file's path and content
+ * @param scales - `patchLint.tokenScales`
+ */
+export declare function lintTokenScaleFloors(createdFiles: Iterable<readonly [string, string]>, scales: readonly PatchLintTokenScale[]): PatchLintIssue[];

package/dist/src/core/patch-lint-token-scale.js

@@ -7,26 +7,44 @@
  * or referencing foreign custom properties, but say nothing about
  * `gap: 7px`, `font-size: 13px` or `z-index: 9999`. Those are the values a
  * design scale exists to remove, and without a rule they drift back one
- * literal at a time. A scale names its properties, the token prefix that
- * defines its steps, and the literals that are not steps at all (`0`,
- * `auto`, a percentage).
+ * literal at a time. A scale names its properties, the token prefix (or
+ * prefixes) that defines its steps, and the literals that are not steps at
+ * all (`0`, `auto`, a percentage).
  *
  * Judged per value atom, after peeling `var()` innermost-first so a fallback
  * is held to the same scale as the token it backs: `var(--x-gap, 7px)` is a
  * literal in disguise. `calc()`, `min()`, `max()` and `clamp()` are
  * transparent, so a value built from tokens passes and one that adds a raw
- * length does not. Unitless multipliers inside them are literals too and
- * need an `allowLiterals` entry.
+ * length does not. Inside them, `allowInCalc` names literals legal only
+ * there (a unitless multiplier), and `offsetCap` lets a declaration
+ * subtract a few px from a token (a border inset) without allowing the px
+ * value anywhere else.
+ *
+ * Declarations inside descriptor at-rules (`@font-face`, `@counter-style`,
+ * `@property`, `@page`, …) are not property declarations and are not
+ * judged: `font-weight` in `@font-face` names a face, not a type step.
  *
  * Runs over CSS files the patch creates, not files it modifies: an upstream
- * stylesheet is not the fork's to put on a scale. A line carrying
- * `fireforge-ignore: token-scale` is skipped.
+ * stylesheet is not the fork's to put on a scale. A file a scale `exclude`s
+ * is not judged against that scale. A line carrying
+ * `fireforge-ignore: token-scale` is skipped. A scale with `minFiles` also
+ * fails the queue (`token-scale-vacuous`) when fewer created files carry
+ * its properties, so an emptied scan set cannot pass by judging nothing.
  */
+import { matchesAnyGlob } from '../utils/path-glob.js';
 import { escapeRegex } from '../utils/regex.js';
 const IGNORE_MARKER = 'fireforge-ignore: token-scale';
 /** CSS-wide keywords: never a step on any scale, always legal. */
 const CSS_WIDE_KEYWORDS = new Set(['inherit', 'initial', 'unset', 'revert', 'revert-layer']);
 const TOKEN_PLACEHOLDER = '\u0000token\u0000';
+const MATH_FUNCTION = /^(?:calc|min|max|clamp)$/i;
+const OPERATORS = new Set(['+', '-', '*', '/']);
+/**
+ * At-rules whose blocks hold descriptors, not property declarations. A
+ * block nested in one (an `@page` margin box, a `@font-feature-values`
+ * feature block) is a descriptor block too.
+ */
+const DESCRIPTOR_AT_RULE = /^@(?:font-face|counter-style|property|font-feature-values|font-palette-values|page|view-transition)\b/i;
 /** Exact name, or a `*`-suffixed prefix. */
 function matchesName(name, patterns) {
     return patterns.some((pattern) => pattern.endsWith('*') ? name.startsWith(pattern.slice(0, -1)) : name === pattern);
@@ -34,16 +52,70 @@ function matchesName(name, patterns) {
 function matchesLiteral(atom, patterns) {
     return patterns.some((pattern) => new RegExp(`^${pattern.split('*').map(escapeRegex).join('.*')}$`).test(atom));
 }
+/** The scale's token prefixes, whether configured as one or a list. */
+function scalePrefixes(scale) {
+    return typeof scale.prefix === 'string' ? [scale.prefix] : scale.prefix;
+}
+/** The scale as a message names it: `--x-space-*`, or `--x-space-* / --x-gap-*`. */
+function scaleLabel(scale) {
+    return scalePrefixes(scale)
+        .map((prefix) => `${prefix}*`)
+        .join(' / ');
+}
+/**
+ * Splits a value into atoms, keeping operators as atoms and noting which
+ * atoms sit inside a math function. A math function's name is dropped; any
+ * other function's name stays an atom, judged like a literal.
+ */
+function valueAtoms(value) {
+    const atoms = [];
+    const mathStack = [];
+    let current = '';
+    const flush = () => {
+        if (current !== '')
+            atoms.push({ text: current, inMath: mathStack.includes(true) });
+        current = '';
+    };
+    for (const char of value) {
+        if (char === '(') {
+            const isMath = MATH_FUNCTION.test(current);
+            if (isMath)
+                current = '';
+            else
+                flush();
+            mathStack.push(isMath);
+        }
+        else if (char === ')') {
+            flush();
+            mathStack.pop();
+        }
+        else if (char === '*' || char === '/') {
+            flush();
+            atoms.push({ text: char, inMath: mathStack.includes(true) });
+        }
+        else if (char === ',' || /\s/.test(char)) {
+            flush();
+        }
+        else {
+            current += char;
+        }
+    }
+    flush();
+    return atoms;
+}
+const PX_LITERAL = /^(\d*\.?\d+)px$/;
 /**
  * Returns the first atom of `value` that is off `scale`, or undefined when
  * every atom resolves to the scale.
  */
 export function findOffScaleAtom(value, scale) {
     let rest = value.replace(/!\s*important\s*$/i, '');
+    const prefixes = scalePrefixes(scale);
     const varPattern = /var\(\s*(--[\w-]+)\s*(?:,([^()]*))?\)/;
     for (let match = varPattern.exec(rest); match !== null; match = varPattern.exec(rest)) {
         const name = match[1] ?? '';
-        if (!name.startsWith(scale.prefix) && !matchesName(name, scale.allow ?? [])) {
+        const onScale = prefixes.some((prefix) => name.startsWith(prefix));
+        if (!onScale && !matchesName(name, scale.allow ?? [])) {
             return `var(${name})`;
         }
         const fallback = match[2];
@@ -54,54 +126,159 @@ export function findOffScaleAtom(value, scale) {
         }
         rest = `${rest.slice(0, match.index)} ${TOKEN_PLACEHOLDER} ${rest.slice(match.index + match[0].length)}`;
     }
-    const atoms = rest
-        .replace(/\b(?:calc|min|max|clamp)\(/gi, ' ')
-        .replace(/[(),]/g, ' ')
-        .split(/\s+/)
-        .filter((atom) => atom !== '' && !['+', '-', '*', '/'].includes(atom));
-    return atoms.find((atom) => atom !== TOKEN_PLACEHOLDER &&
-        !CSS_WIDE_KEYWORDS.has(atom.toLowerCase()) &&
-        !matchesLiteral(atom, scale.allowLiterals ?? []));
+    const atoms = valueAtoms(rest);
+    // A px offset subtracted from a token (`token - 1px`, `token - 1px - 1px`)
+    // counts toward `offsetCap`, summed over the declaration.
+    let offsetTotal = 0;
+    let lastOffsetIndex = -1;
+    for (const [index, atom] of atoms.entries()) {
+        if (OPERATORS.has(atom.text) || atom.text === TOKEN_PLACEHOLDER)
+            continue;
+        if (CSS_WIDE_KEYWORDS.has(atom.text.toLowerCase()))
+            continue;
+        if (matchesLiteral(atom.text, scale.allowLiterals ?? []))
+            continue;
+        if (atom.inMath && matchesLiteral(atom.text, scale.allowInCalc ?? []))
+            continue;
+        const px = PX_LITERAL.exec(atom.text);
+        if (atom.inMath && px !== null && scale.offsetCap !== undefined) {
+            const subtrahendOf = atoms[index - 2]?.text;
+            const subtracted = atoms[index - 1]?.text === '-' &&
+                (subtrahendOf === TOKEN_PLACEHOLDER || lastOffsetIndex === index - 2);
+            if (subtracted) {
+                offsetTotal += Number(px[1]);
+                lastOffsetIndex = index;
+                if (offsetTotal <= scale.offsetCap)
+                    continue;
+            }
+        }
+        return atom.text;
+    }
+    return undefined;
 }
 /** Blanks block comments, keeping newlines so offsets map to lines. */
 function maskComments(css) {
     return css.replace(/\/\*[\s\S]*?\*\//g, (comment) => comment.replace(/[^\n]/g, ' '));
 }
+/**
+ * Blanks the contents of descriptor at-rule blocks (keeping braces and
+ * newlines), so the declaration scan never sees their descriptors.
+ */
+function maskDescriptorBlocks(css) {
+    const out = css.split('');
+    const stack = [];
+    let preludeStart = 0;
+    for (let i = 0; i < css.length; i++) {
+        const char = css.charAt(i);
+        const inDescriptor = stack[stack.length - 1] === true;
+        if (char === '{') {
+            const prelude = css.slice(preludeStart, i).trim();
+            stack.push(inDescriptor || DESCRIPTOR_AT_RULE.test(prelude));
+            preludeStart = i + 1;
+        }
+        else if (char === '}') {
+            stack.pop();
+            preludeStart = i + 1;
+        }
+        else if (char === ';') {
+            preludeStart = i + 1;
+        }
+        if (inDescriptor && char !== '\n' && char !== '{' && char !== '}')
+            out[i] = ' ';
+    }
+    return out.join('');
+}
+/** Every property declaration of a stylesheet, descriptors and comments left out. */
+function scanDeclarations(css) {
+    const masked = maskDescriptorBlocks(maskComments(css));
+    const declarations = [];
+    const pattern = /(^|[{;\s])([a-zA-Z][a-zA-Z-]*)\s*:\s*([^;{}]*)/g;
+    for (let match = pattern.exec(masked); match !== null; match = pattern.exec(masked)) {
+        const start = match.index + (match[1] ?? '').length;
+        declarations.push({
+            property: (match[2] ?? '').toLowerCase(),
+            value: (match[3] ?? '').trim(),
+            line: masked.slice(0, start).split('\n').length,
+        });
+    }
+    return declarations;
+}
+/** The scales that govern `file`: those that do not `exclude` it. */
+function scalesFor(file, scales) {
+    return scales.filter((scale) => !matchesAnyGlob(file, scale.exclude ?? []));
+}
 /**
  * Lints one patch-created CSS file against the configured scales.
  *
- * @param file - Engine-relative path, for the issue
+ * @param file - Engine-relative path, for the issue and the `exclude` globs
  * @param css - The file's full content
  * @param scales - `patchLint.tokenScales`
  * @returns One `token-scale` error per off-scale declaration
  */
 export function lintTokenScales(file, css, scales) {
-    if (scales.length === 0)
+    const governing = scalesFor(file, scales);
+    if (governing.length === 0)
         return [];
     const rawLines = css.split('\n');
-    const masked = maskComments(css);
     const issues = [];
-    const declaration = /(^|[{;\s])([a-zA-Z][a-zA-Z-]*)\s*:\s*([^;{}]*)/g;
-    for (let match = declaration.exec(masked); match !== null; match = declaration.exec(masked)) {
-        const property = (match[2] ?? '').toLowerCase();
-        const value = (match[3] ?? '').trim();
-        const scale = scales.find((candidate) => matchesName(property, candidate.properties));
+    for (const { property, value, line } of scanDeclarations(css)) {
+        const scale = governing.find((candidate) => matchesName(property, candidate.properties));
         if (scale === undefined || value === '')
             continue;
-        const start = match.index + (match[1] ?? '').length;
-        const line = masked.slice(0, start).split('\n').length;
         if ((rawLines[line - 1] ?? '').includes(IGNORE_MARKER))
             continue;
         const atom = findOffScaleAtom(value, scale);
         if (atom === undefined)
             continue;
+        const label = scaleLabel(scale);
         issues.push({
             file,
             check: 'token-scale',
             fingerprint: `token-scale:${file}:${property}:${value}`,
-            message: `Line ${String(line)}: ${property}: ${value} is off the ${scale.prefix}* scale ` +
-                `("${atom}"). Use a ${scale.prefix}* token, or list a reviewed exception in ` +
-                `patchLint.tokenScales (allowLiterals / allow) or mark the line "${IGNORE_MARKER}".`,
+            message: `Line ${String(line)}: ${property}: ${value} is off the ${label} scale ` +
+                `("${atom}"). Use a ${label} token, or list a reviewed exception in ` +
+                `patchLint.tokenScales (allowLiterals / allowInCalc / allow) or mark the line "${IGNORE_MARKER}".`,
+            severity: 'error',
+        });
+    }
+    return issues;
+}
+/**
+ * The `minFiles` floor of every scale over the queue's created stylesheets:
+ * one `token-scale-vacuous` error per scale that fewer created CSS files
+ * (outside its `exclude`) carry a declaration of.
+ *
+ * @param createdFiles - Every patch-created file's path and content
+ * @param scales - `patchLint.tokenScales`
+ */
+export function lintTokenScaleFloors(createdFiles, scales) {
+    const floored = scales.filter((scale) => scale.minFiles !== undefined);
+    if (floored.length === 0)
+        return [];
+    const counts = new Map(floored.map((scale) => [scale, 0]));
+    for (const [file, content] of createdFiles) {
+        if (!file.endsWith('.css'))
+            continue;
+        const properties = new Set(scanDeclarations(content).map((entry) => entry.property));
+        for (const scale of scalesFor(file, floored)) {
+            if ([...properties].some((property) => matchesName(property, scale.properties))) {
+                counts.set(scale, (counts.get(scale) ?? 0) + 1);
+            }
+        }
+    }
+    const issues = [];
+    for (const [scale, count] of counts) {
+        const floor = scale.minFiles ?? 0;
+        if (count >= floor)
+            continue;
+        const label = scaleLabel(scale);
+        issues.push({
+            file: 'fireforge.json',
+            check: 'token-scale-vacuous',
+            fingerprint: `token-scale-vacuous:${label}`,
+            message: `The ${label} scale governs ${String(count)} patch-created stylesheet(s), under its ` +
+                `minFiles ${String(floor)}. A scale that judges nothing passes vacuously: check its ` +
+                'properties and exclude globs, or lower minFiles after a reviewed move.',
             severity: 'error',
         });
     }

package/dist/src/core/patch-lint.js

@@ -14,7 +14,7 @@ import { hasRelativeImport } from './patch-lint-imports.js';
 import { validateExportJsDoc } from './patch-lint-jsdoc.js';
 import { lintMozBuildSortedLists } from './patch-lint-mozbuild.js';
 import { lintObserverTopics } from './patch-lint-observer.js';
-import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs, resolvePatchOwnedTestScripts, } from './patch-lint-ownership.js';
+import { resolvableModulesForTests, resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs, resolvePatchOwnedTestScripts, } from './patch-lint-ownership.js';
 import { invokePatchLintPrettier } from './patch-lint-prettier.js';
 import { isTestFile, lintPatchSize, measurePatchSize, } from './patch-lint-size.js';
 // ---------------------------------------------------------------------------
@@ -495,7 +495,7 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         // Export-time twin of per-patch lint's test-file pass, so
         // export/re-export and `lint --per-patch` agree on the checked surface.
         if (config.patchLint.checkJsTestFiles === true) {
-            const testGrouped = await runCheckJsTestFilesGrouped(repoDir, resolvePatchOwnedTestScripts(newFiles, patchQueueCtx), config.patchLint, dirname(repoDir));
+            const testGrouped = await runCheckJsTestFilesGrouped(repoDir, resolvePatchOwnedTestScripts(newFiles, patchQueueCtx), config.patchLint, dirname(repoDir), undefined, patchQueueCtx ? resolvableModulesForTests(patchQueueCtx) : undefined);
             issues.push(...testGrouped.global);
             for (const [rel, list] of testGrouped.byFile) {
                 if (options?.checkJsReportScope && !options.checkJsReportScope.has(rel))

package/dist/src/core/patch-manifest-io.js

@@ -19,6 +19,7 @@ import { pathExistsStrict, readJson, removeFile, writeJson } from '../utils/fs.j
 import { warn } from '../utils/logger.js';
 import { isArray, isObject } from '../utils/validation.js';
 import { assertPatchDirectoryLockHeld } from './patch-lock.js';
+import { canonicalizeManifest, canonicalizePatchRow } from './patch-manifest-key-order.js';
 import { validatePatchesManifest } from './patch-manifest-validate.js';
 import { manifestWithRetiredSlots } from './patch-retired.js';
 /** Filename for the patches manifest */
@@ -86,7 +87,7 @@ export async function loadPatchesManifestForWrite(patchesDir) {
  */
 export async function savePatchesManifest(patchesDir, manifest) {
     const manifestPath = join(patchesDir, PATCHES_MANIFEST);
-    await writeJson(manifestPath, manifest);
+    await writeJson(manifestPath, canonicalizeManifest(manifest));
 }
 /**
  * Mutates selected manifest rows while preserving the raw JSON shape of every
@@ -139,6 +140,12 @@ export async function mutatePatchRowsInManifest(patchesDir, filenames, mutator)
     }
     if (changedIndexes.length === 0)
         return [];
+    // Only the rows this call changed are put in canonical order, so a key
+    // it sets lands where every other writer puts it; untouched rows keep
+    // their raw shape.
+    for (const index of changedIndexes) {
+        rawPatches[index] = canonicalizePatchRow(rawPatches[index]);
+    }
     const nextRawManifest = {
         ...rawManifest,
         patches: rawPatches,

package/dist/src/core/patch-manifest-key-order.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The one key order every `patches.json` writer uses for a patch row and
+ * for the manifest itself. Writers used to disagree: `export` spread
+ * `sourceProduct` before `sourceVersion` while a full-manifest save put it
+ * after `filesAffected`, so a no-op rewrite left a key-order-only hunk in
+ * the manifest.
+ */
+/**
+ * Returns a copy of a patch row with its keys in canonical order.
+ *
+ * @param row - A `PatchMetadata` row, typed or raw
+ * @returns The same fields in canonical key order
+ */
+export declare function canonicalizePatchRow<T extends object>(row: T): T;
+/**
+ * Returns a copy of a manifest with its top-level keys and every row in
+ * canonical order.
+ *
+ * @param manifest - A `PatchesManifest`, typed or raw
+ * @returns The manifest in canonical key order
+ */
+export declare function canonicalizeManifest<T extends {
+    patches: readonly object[];
+}>(manifest: T): T;

package/dist/src/core/patch-manifest-key-order.js

@@ -0,0 +1,61 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The one key order every `patches.json` writer uses for a patch row and
+ * for the manifest itself. Writers used to disagree: `export` spread
+ * `sourceProduct` before `sourceVersion` while a full-manifest save put it
+ * after `filesAffected`, so a no-op rewrite left a key-order-only hunk in
+ * the manifest.
+ */
+/** Patch-row keys in the order of the `PatchMetadata` interface. */
+const PATCH_ROW_KEY_ORDER = [
+    'filename',
+    'order',
+    'category',
+    'name',
+    'description',
+    'createdAt',
+    'sourceEsrVersion',
+    'sourceProduct',
+    'sourceVersion',
+    'filesAffected',
+    'lintIgnore',
+    'tier',
+    'stagedDependencies',
+];
+/** Manifest keys in the order of the `PatchesManifest` interface. */
+const MANIFEST_KEY_ORDER = ['version', 'patches', 'retired', 'reserved'];
+function reorder(value, order) {
+    const source = value;
+    const out = {};
+    for (const key of order) {
+        if (Object.hasOwn(source, key))
+            out[key] = source[key];
+    }
+    // Keys this build does not know keep their relative order after the
+    // known ones, so a newer writer's fields survive an older rewrite.
+    for (const key of Object.keys(source)) {
+        if (!Object.hasOwn(out, key))
+            out[key] = source[key];
+    }
+    return out;
+}
+/**
+ * Returns a copy of a patch row with its keys in canonical order.
+ *
+ * @param row - A `PatchMetadata` row, typed or raw
+ * @returns The same fields in canonical key order
+ */
+export function canonicalizePatchRow(row) {
+    return reorder(row, PATCH_ROW_KEY_ORDER);
+}
+/**
+ * Returns a copy of a manifest with its top-level keys and every row in
+ * canonical order.
+ *
+ * @param manifest - A `PatchesManifest`, typed or raw
+ * @returns The manifest in canonical key order
+ */
+export function canonicalizeManifest(manifest) {
+    const ordered = reorder(manifest, MANIFEST_KEY_ORDER);
+    return { ...ordered, patches: manifest.patches.map((row) => canonicalizePatchRow(row)) };
+}

package/dist/src/core/patch-manifest-stage.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The manifest `patch stage` writes into the git index: HEAD's
+ * `patches.json` with only the named patches' rows (and their retired and
+ * reserved slots) taken from the working copy.
+ *
+ * Sessions sharing one checkout each touch their own rows of the shared
+ * manifest. Staging the whole file commits every session's rows under one
+ * message; staging hunks with `git apply --cached --unidiff-zero` lands a
+ * kept insertion at its new-side line number once a dropped hunk above it
+ * shifted the file, and committed invalid JSON. Merging rows from the
+ * parsed manifests has neither failure: the result is built from structure,
+ * then validated before anything is staged.
+ */
+import type { PatchesManifest } from '../types/commands/index.js';
+/** What staging does to one named patch's row. */
+export type StagedRowChange = 'added' | 'updated' | 'removed' | 'unchanged';
+/** The staged manifest and the per-patch row changes it carries. */
+export interface StagedManifest {
+    manifest: PatchesManifest;
+    changes: Array<{
+        filename: string;
+        change: StagedRowChange;
+    }>;
+}
+/**
+ * Merges the named rows of `working` into `head`.
+ *
+ * Rows: every unnamed row comes from HEAD; a named row comes from the
+ * working copy, or leaves when the working copy no longer has it.
+ * Retired slots: a slot whose `filename` is named follows the working
+ * copy, the rest follow HEAD. Reserved slots follow HEAD. A slot whose
+ * order a staged row now fills is dropped, as every manifest write does.
+ *
+ * @param head - HEAD's manifest, or null when HEAD has none
+ * @param working - The working-copy manifest
+ * @param filenames - Patch filenames whose rows to take from the working copy
+ * @returns The validated manifest and the row changes
+ * @throws Error when two rows would hold one order, or the merge does not
+ *   validate
+ */
+export declare function mergeStagedManifest(head: PatchesManifest | null, working: PatchesManifest, filenames: ReadonlySet<string>): StagedManifest;
+/**
+ * Serializes a staged manifest exactly as the manifest writers do, so the
+ * staged blob and a later full save of the same content are byte-identical.
+ */
+export declare function serializeStagedManifest(manifest: PatchesManifest): string;

package/dist/src/core/patch-manifest-stage.js

@@ -0,0 +1,96 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The manifest `patch stage` writes into the git index: HEAD's
+ * `patches.json` with only the named patches' rows (and their retired and
+ * reserved slots) taken from the working copy.
+ *
+ * Sessions sharing one checkout each touch their own rows of the shared
+ * manifest. Staging the whole file commits every session's rows under one
+ * message; staging hunks with `git apply --cached --unidiff-zero` lands a
+ * kept insertion at its new-side line number once a dropped hunk above it
+ * shifted the file, and committed invalid JSON. Merging rows from the
+ * parsed manifests has neither failure: the result is built from structure,
+ * then validated before anything is staged.
+ */
+import { toError } from '../utils/errors.js';
+import { canonicalizeManifest } from './patch-manifest-key-order.js';
+import { validatePatchesManifest } from './patch-manifest-validate.js';
+import { carryReservedSlots, carryRetiredSlots } from './patch-retired.js';
+/**
+ * Merges the named rows of `working` into `head`.
+ *
+ * Rows: every unnamed row comes from HEAD; a named row comes from the
+ * working copy, or leaves when the working copy no longer has it.
+ * Retired slots: a slot whose `filename` is named follows the working
+ * copy, the rest follow HEAD. Reserved slots follow HEAD. A slot whose
+ * order a staged row now fills is dropped, as every manifest write does.
+ *
+ * @param head - HEAD's manifest, or null when HEAD has none
+ * @param working - The working-copy manifest
+ * @param filenames - Patch filenames whose rows to take from the working copy
+ * @returns The validated manifest and the row changes
+ * @throws Error when two rows would hold one order, or the merge does not
+ *   validate
+ */
+export function mergeStagedManifest(head, working, filenames) {
+    const headRows = head?.patches ?? [];
+    const changes = [...filenames].sort().map((filename) => {
+        const before = headRows.find((row) => row.filename === filename);
+        const after = working.patches.find((row) => row.filename === filename);
+        const change = before === undefined
+            ? 'added'
+            : after === undefined
+                ? 'removed'
+                : JSON.stringify(canonicalRow(before)) === JSON.stringify(canonicalRow(after))
+                    ? 'unchanged'
+                    : 'updated';
+        return { filename, change };
+    });
+    const rows = [
+        ...headRows.filter((row) => !filenames.has(row.filename)),
+        ...working.patches.filter((row) => filenames.has(row.filename)),
+    ].sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
+    assertNoCollision(rows);
+    const retiredSource = [
+        ...(head?.retired ?? []).filter((slot) => !filenames.has(slot.filename)),
+        ...(working.retired ?? []).filter((slot) => filenames.has(slot.filename)),
+    ];
+    const retired = carryRetiredSlots({ retired: retiredSource }, rows);
+    const reserved = carryReservedSlots(head, rows);
+    const merged = {
+        version: 1,
+        patches: rows,
+        ...(retired !== undefined ? { retired } : {}),
+        ...(reserved !== undefined ? { reserved } : {}),
+    };
+    try {
+        validatePatchesManifest(JSON.parse(JSON.stringify(merged)));
+    }
+    catch (error) {
+        throw new Error(`the staged manifest would not validate: ${toError(error).message}`, {
+            cause: error,
+        });
+    }
+    return { manifest: canonicalizeManifest(merged), changes };
+}
+function canonicalRow(row) {
+    return canonicalizeManifest({ patches: [row] }).patches[0];
+}
+function assertNoCollision(rows) {
+    const seen = new Map();
+    for (const row of rows) {
+        const holder = seen.get(row.order);
+        if (holder !== undefined) {
+            throw new Error(`order ${String(row.order)} would be held by both ${holder} and ${row.filename}; ` +
+                'stage the patch that moved off that order as well');
+        }
+        seen.set(row.order, row.filename);
+    }
+}
+/**
+ * Serializes a staged manifest exactly as the manifest writers do, so the
+ * staged blob and a later full save of the same content are byte-identical.
+ */
+export function serializeStagedManifest(manifest) {
+    return `${JSON.stringify(manifest, null, 2)}\n`;
+}