@hominis/fireforge 0.35.0 → 0.36.0

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

@@ -1,5 +1,5 @@
 import type { PatchLintIssue } from '../types/commands/index.js';
-import type { FireForgeConfig } from '../types/config.js';
+import type { FireForgeConfig, ProjectLicense } from '../types/config.js';
 import { type CommentStyle } from './license-headers.js';
 import { lintPatchedCss } from './patch-lint-css.js';
 export * from './patch-lint-reexports.js';
@@ -26,7 +26,42 @@ export declare function isTestFile(file: string): boolean;
  */
 export declare function commentStyleForFile(file: string): CommentStyle | null;
 /**
- * Checks new files for required license headers.
+ * Decides whether a NEW file's leading header satisfies the
+ * `missing-license-header` rule. Single owner of the acceptance policy —
+ * `lintNewFileHeaders` (the rule) and `autoFixLicenseHeaders` (the
+ * interactive export fixer) must agree, or the fixer offers to stack a
+ * second header onto a file the lint already accepts.
+ *
+ * Accepted shapes, in order:
+ *  - the project's own header for the file's comment style;
+ *  - under `browser/branding/`, ANY recognised license header in the
+ *    matching style: the setup-generated branding directory is copied
+ *    from Firefox's `unofficial` template and arrives with Mozilla
+ *    MPL-2.0 headers — legitimate for copyright purposes (the assets are
+ *    Mozilla's) even when the fork's own code is 0BSD / EUPL-1.2 /
+ *    GPL-2.0-or-later;
+ *  - on an MPL-2.0 project, any recognised header in the matching style;
+ *  - the verbatim upstream MPL-2.0 block header (`/* … *\/`, optionally
+ *    behind a leading editor-directive comment) REGARDLESS of the
+ *    project license, on any file whose comment syntax is the block form
+ *    (JS and CSS): a file copied from the Firefox tree legitimately
+ *    keeps Mozilla's header for provenance in an EUPL/GPL/0BSD project
+ *    too. 0.35.0 accepted this on JS only; field verification showed a
+ *    derived CSS file carrying the identical three-line block header
+ *    still needed a patch-level lintIgnore. Only the block form is
+ *    accepted — the `// `-style MPL header is FireForge-generated, not
+ *    upstream provenance — and `hash`-style files (FTL) stay excluded
+ *    because `/* … *\/` is not a comment there.
+ *
+ * @param file - Engine-relative path of the new file
+ * @param content - File content
+ * @param style - Comment style resolved for the file
+ * @param license - The project license
+ */
+export declare function isAcceptableNewFileHeader(file: string, content: string, style: CommentStyle, license: ProjectLicense): boolean;
+/**
+ * Checks new files for required license headers (acceptance policy in
+ * {@link isAcceptableNewFileHeader}).
  *
  * @param repoDir - Absolute path to the engine directory
  * @param newFiles - New file paths (relative to repoDir)

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

@@ -211,7 +211,52 @@ export function commentStyleForFile(file) {
 // License header lint
 // ---------------------------------------------------------------------------
 /**
- * Checks new files for required license headers.
+ * Decides whether a NEW file's leading header satisfies the
+ * `missing-license-header` rule. Single owner of the acceptance policy —
+ * `lintNewFileHeaders` (the rule) and `autoFixLicenseHeaders` (the
+ * interactive export fixer) must agree, or the fixer offers to stack a
+ * second header onto a file the lint already accepts.
+ *
+ * Accepted shapes, in order:
+ *  - the project's own header for the file's comment style;
+ *  - under `browser/branding/`, ANY recognised license header in the
+ *    matching style: the setup-generated branding directory is copied
+ *    from Firefox's `unofficial` template and arrives with Mozilla
+ *    MPL-2.0 headers — legitimate for copyright purposes (the assets are
+ *    Mozilla's) even when the fork's own code is 0BSD / EUPL-1.2 /
+ *    GPL-2.0-or-later;
+ *  - on an MPL-2.0 project, any recognised header in the matching style;
+ *  - the verbatim upstream MPL-2.0 block header (`/* … *\/`, optionally
+ *    behind a leading editor-directive comment) REGARDLESS of the
+ *    project license, on any file whose comment syntax is the block form
+ *    (JS and CSS): a file copied from the Firefox tree legitimately
+ *    keeps Mozilla's header for provenance in an EUPL/GPL/0BSD project
+ *    too. 0.35.0 accepted this on JS only; field verification showed a
+ *    derived CSS file carrying the identical three-line block header
+ *    still needed a patch-level lintIgnore. Only the block form is
+ *    accepted — the `// `-style MPL header is FireForge-generated, not
+ *    upstream provenance — and `hash`-style files (FTL) stay excluded
+ *    because `/* … *\/` is not a comment there.
+ *
+ * @param file - Engine-relative path of the new file
+ * @param content - File content
+ * @param style - Comment style resolved for the file
+ * @param license - The project license
+ */
+export function isAcceptableNewFileHeader(file, content, style, license) {
+    if (content.startsWith(getLicenseHeader(license, style)))
+        return true;
+    if (file.startsWith('browser/branding/') && hasAnyLicenseHeader(content, style))
+        return true;
+    if (license === 'MPL-2.0' && hasAnyLicenseHeader(content, style))
+        return true;
+    if ((style === 'js' || style === 'css') && hasUpstreamMplBlockHeader(content))
+        return true;
+    return false;
+}
+/**
+ * Checks new files for required license headers (acceptance policy in
+ * {@link isAcceptableNewFileHeader}).
  *
  * @param repoDir - Absolute path to the engine directory
  * @param newFiles - New file paths (relative to repoDir)
@@ -229,38 +274,7 @@ export async function lintNewFileHeaders(repoDir, newFiles, config) {
         if (!(await pathExists(filePath)))
             continue;
         const content = await readText(filePath);
-        const expectedHeader = getLicenseHeader(license, style);
-        // Auto-exempt `browser/branding/` when the file carries ANY recognised
-        // license header in the matching comment style. The setup-generated
-        // branding directory is copied from Firefox's `unofficial` template,
-        // which arrives with Mozilla MPL-2.0 headers — those are legitimate
-        // for copyright purposes (the assets are Mozilla's) even when the
-        // fork's own code is 0BSD / EUPL-1.2 / GPL-2.0-or-later. The narrower
-        // license-match rule would force operators to either rewrite the
-        // copied headers (misrepresenting authorship) or suppress the lint
-        // with `--skip-lint` (hiding real issues elsewhere).
-        if (content.startsWith(expectedHeader))
-            continue;
-        if (file.startsWith('browser/branding/') && hasAnyLicenseHeader(content, style))
-            continue;
-        // Accept the MPL-2.0 block-comment form (`/* ... */` with leading `*`)
-        // for any JS file — that is the canonical upstream Firefox header
-        // shape, and `hasAnyLicenseHeader` above also recognises it. The
-        // explicit guard mirrors the branding carve-out so operators using the
-        // standard Mozilla header on a JS file (e.g. one copied from upstream
-        // browser/base/content) do not need `--skip-lint` to land it.
-        if (license === 'MPL-2.0' && hasAnyLicenseHeader(content, style))
-            continue;
-        // Accept the verbatim upstream MPL block header on new JS files
-        // REGARDLESS of the project license: a file copied from the Firefox
-        // tree legitimately keeps Mozilla's header for provenance in an
-        // EUPL/GPL/0BSD project too. The carve-out above is gated on the
-        // project being MPL-2.0 itself, which made this documented case dead
-        // code for every other license — consumers carried repo-side audit
-        // workarounds (recorded 2026-07-04 in the Hominis FORGE.md). Only
-        // the block-comment form is accepted; the `// `-style MPL header is
-        // FireForge-generated, not upstream provenance.
-        if (style === 'js' && hasUpstreamMplBlockHeader(content))
+        if (isAcceptableNewFileHeader(file, content, style, license))
             continue;
         issues.push({
             file,
@@ -620,4 +634,3 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     }
     return issues;
 }
-//# sourceMappingURL=patch-lint.js.map

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

@@ -27,4 +27,3 @@ export async function withPatchDirectoryLock(patchesDir, operation) {
         throw new PatchError(toError(error).message);
     });
 }
-//# sourceMappingURL=patch-lock.js.map

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

@@ -4,6 +4,7 @@
  */
 import { stat } from 'node:fs/promises';
 import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
+import { withPatchDirectoryLock } from './patch-lock.js';
 import { loadPatchesManifestState, PATCHES_MANIFEST, savePatchesManifest, } from './patch-manifest-io.js';
 import { inferPatchMetadataFromFilename } from './patch-manifest-validate.js';
 /**
@@ -89,6 +90,14 @@ export async function validatePatchesManifestConsistency(patchesDir) {
  *   plus the filenames that were reconstructed from generic defaults.
  */
 export async function rebuildPatchesManifest(patchesDir, fallbackSourceEsrVersion) {
+    // The whole read → discover → rebuild → save cycle runs under the shared
+    // patch-directory lock (invariant 2, docs/lifecycle-invariants.md):
+    // manifest writes serialize on this lock, and a repair racing a
+    // concurrent export/reorder used to be able to clobber the other
+    // writer's manifest. Not reentrant — callers must not already hold it.
+    return withPatchDirectoryLock(patchesDir, () => rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion));
+}
+async function rebuildPatchesManifestUnderLock(patchesDir, fallbackSourceEsrVersion) {
     const manifestState = await loadPatchesManifestState(patchesDir);
     const existingEntries = new Map();
     if (manifestState.manifest) {
@@ -162,4 +171,3 @@ function normalizeFiles(files) {
 function sameStringArray(left, right) {
     return left.length === right.length && left.every((value, index) => value === right[index]);
 }
-//# sourceMappingURL=patch-manifest-consistency.js.map

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

@@ -37,10 +37,26 @@ export interface PatchManifestRowMutationResult {
 export declare function loadPatchesManifestState(patchesDir: string): Promise<LoadedManifestState>;
 /**
  * Loads the patches manifest if it exists.
+ *
+ * READ-ONLY callers only: this collapses "absent" and "corrupt" into null.
+ * Any code path that will WRITE the manifest (or delete patch files based
+ * on its content) must use {@link loadPatchesManifestForWrite} instead —
+ * treating a corrupt manifest as empty and then saving destroys every
+ * existing patch's metadata.
+ *
  * @param patchesDir - Path to the patches directory
  * @returns PatchesManifest or null if not found
  */
 export declare function loadPatchesManifest(patchesDir: string): Promise<PatchesManifest | null>;
+/**
+ * Loads the patches manifest for a mutating operation.
+ *
+ * Returns null only when the manifest genuinely does not exist; a manifest
+ * that exists but fails to parse/validate throws
+ * {@link PatchManifestCorruptError} so the caller aborts instead of
+ * rebuilding an empty queue over the top of the corrupt file.
+ */
+export declare function loadPatchesManifestForWrite(patchesDir: string): Promise<PatchesManifest | null>;
 /**
  * Saves the patches manifest.
  * @param patchesDir - Path to the patches directory

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

@@ -12,6 +12,7 @@ import { rename } from 'node:fs/promises';
 import { join } from 'node:path';
 import { FireForgeError } from '../errors/base.js';
 import { ExitCode } from '../errors/codes.js';
+import { PatchManifestCorruptError } from '../errors/patch.js';
 import { toError } from '../utils/errors.js';
 import { pathExistsStrict, readJson, removeFile, writeJson } from '../utils/fs.js';
 import { warn } from '../utils/logger.js';
@@ -46,6 +47,13 @@ export async function loadPatchesManifestState(patchesDir) {
 }
 /**
  * Loads the patches manifest if it exists.
+ *
+ * READ-ONLY callers only: this collapses "absent" and "corrupt" into null.
+ * Any code path that will WRITE the manifest (or delete patch files based
+ * on its content) must use {@link loadPatchesManifestForWrite} instead —
+ * treating a corrupt manifest as empty and then saving destroys every
+ * existing patch's metadata.
+ *
  * @param patchesDir - Path to the patches directory
  * @returns PatchesManifest or null if not found
  */
@@ -53,6 +61,21 @@ export async function loadPatchesManifest(patchesDir) {
     const state = await loadPatchesManifestState(patchesDir);
     return state.manifest;
 }
+/**
+ * Loads the patches manifest for a mutating operation.
+ *
+ * Returns null only when the manifest genuinely does not exist; a manifest
+ * that exists but fails to parse/validate throws
+ * {@link PatchManifestCorruptError} so the caller aborts instead of
+ * rebuilding an empty queue over the top of the corrupt file.
+ */
+export async function loadPatchesManifestForWrite(patchesDir) {
+    const state = await loadPatchesManifestState(patchesDir);
+    if (state.exists && state.manifest === null) {
+        throw new PatchManifestCorruptError(join(patchesDir, PATCHES_MANIFEST), state.parseError);
+    }
+    return state.manifest;
+}
 /**
  * Saves the patches manifest.
  * @param patchesDir - Path to the patches directory
@@ -125,7 +148,8 @@ export async function mutatePatchRowsInManifest(patchesDir, filenames, mutator)
  * @param removeFilenames - Optional filenames to remove in the same read-modify-write cycle
  */
 export async function addPatchToManifest(patchesDir, metadata, removeFilenames) {
-    const manifest = (await loadPatchesManifest(patchesDir)) ?? {
+    // ForWrite: a corrupt manifest must abort here, not be rebuilt as empty.
+    const manifest = (await loadPatchesManifestForWrite(patchesDir)) ?? {
         version: 1,
         patches: [],
     };
@@ -156,7 +180,7 @@ export async function addPatchToManifest(patchesDir, metadata, removeFilenames)
  *   false when no matching entry existed
  */
 export async function removePatchFromManifest(patchesDir, filename) {
-    const manifest = await loadPatchesManifest(patchesDir);
+    const manifest = await loadPatchesManifestForWrite(patchesDir);
     if (!manifest)
         return false;
     const originalLength = manifest.patches.length;
@@ -240,7 +264,7 @@ export function rewriteStagedDependencyOwners(patch, renameLookup) {
 export async function renumberPatchesInManifest(patchesDir, renameMap) {
     if (renameMap.size === 0)
         return;
-    const manifest = await loadPatchesManifest(patchesDir);
+    const manifest = await loadPatchesManifestForWrite(patchesDir);
     if (!manifest) {
         throw new Error('Cannot renumber patches: patches.json is missing.');
     }
@@ -425,7 +449,9 @@ export class PatchDeleteRollbackError extends FireForgeError {
  */
 export async function removePatchFileAndManifest(patchesDir, filename) {
     const patchPath = join(patchesDir, filename);
-    const originalManifest = await loadPatchesManifest(patchesDir);
+    // ForWrite: deleting the patch FILE while a corrupt manifest still
+    // references it would strand the queue; abort on corruption instead.
+    const originalManifest = await loadPatchesManifestForWrite(patchesDir);
     const removedFromManifest = await removePatchFromManifest(patchesDir, filename);
     try {
         if (await pathExistsStrict(patchPath)) {
@@ -451,4 +477,3 @@ export async function removePatchFileAndManifest(patchesDir, filename) {
         throw deleteError;
     }
 }
-//# sourceMappingURL=patch-manifest-io.js.map

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

@@ -3,7 +3,7 @@
  * Query helpers: finding patches by file, integrity checks, version compat, stamping.
  */
 import { readText } from '../utils/fs.js';
-import { fileExistsInHead } from './git-file-ops.js';
+import { listTrackedInHead } from './git-file-ops.js';
 import { discoverPatches, getAllTargetFilesFromPatch } from './patch-files.js';
 import { withPatchDirectoryLock } from './patch-lock.js';
 import { loadPatchesManifest, mutatePatchRowsInManifest } from './patch-manifest-io.js';
@@ -79,6 +79,12 @@ export async function findPatchesAffectingFile(patchesDir, filePath) {
 export async function validatePatchIntegrity(patchesDir, engineDir) {
     const issues = [];
     const patches = await discoverPatches(patchesDir);
+    // Collect every modification target first, then resolve HEAD existence in
+    // ONE batched ls-tree pass (chunked for ARG_MAX). The per-file
+    // fileExistsInHead fan-out spawned one git process per (patch × target) on
+    // every import — a 56-file branding patch alone cost ~56 spawns before a
+    // single patch was applied.
+    const modificationTargets = [];
     for (const patch of patches) {
         // Check all files in the patch (supports multi-file patches)
         const patchContent = await readText(patch.path);
@@ -87,14 +93,17 @@ export async function validatePatchIntegrity(patchesDir, engineDir) {
             // Skip new-file sections — they don't need to exist in HEAD
             if (isNewFileInPatch(patchContent, targetFile))
                 continue;
-            const existsInHead = await fileExistsInHead(engineDir, targetFile);
-            if (!existsInHead) {
-                issues.push({
-                    filename: patch.filename,
-                    message: `Modification patch for file that doesn't exist in source. Re-export with: fireforge export ${targetFile}`,
-                    targetFile,
-                });
-            }
+            modificationTargets.push({ filename: patch.filename, targetFile });
+        }
+    }
+    const tracked = await listTrackedInHead(engineDir, modificationTargets.map((t) => t.targetFile));
+    for (const { filename, targetFile } of modificationTargets) {
+        if (!tracked.has(targetFile)) {
+            issues.push({
+                filename,
+                message: `Modification patch for file that doesn't exist in source. Re-export with: fireforge export ${targetFile}`,
+                targetFile,
+            });
         }
     }
     return issues;
@@ -128,4 +137,3 @@ export async function stampPatchVersions(patchesDir, filenames, newVersion, newP
         return null;
     }));
 }
-//# sourceMappingURL=patch-manifest-query.js.map

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

@@ -36,4 +36,3 @@ export function resolvePatchIdentifier(identifier, patches) {
     // manifest at export time. See function docstring.
     return patches.find((p) => p.name === identifier) ?? null;
 }
-//# sourceMappingURL=patch-manifest-resolve.js.map

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

@@ -144,4 +144,3 @@ export function inferPatchMetadataFromFilename(filename) {
     }
     return { category: 'infra', name: filename.replace(/\.patch$/, '') };
 }
-//# sourceMappingURL=patch-manifest-validate.js.map

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

@@ -5,7 +5,7 @@
  * is an implementation detail.
  */
 export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
-export { addPatchToManifest, loadPatchesManifest, mutatePatchRowsInManifest, PATCHES_MANIFEST, type PatchManifestRowMutation, type PatchManifestRowMutationResult, type PatchRenameEntry, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
+export { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, type PatchManifestRowMutation, type PatchManifestRowMutationResult, type PatchRenameEntry, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
 export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
 export { resolvePatchIdentifier } from './patch-manifest-resolve.js';
 export { validatePatchesManifest } from './patch-manifest-validate.js';

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

@@ -6,8 +6,7 @@
  * is an implementation detail.
  */
 export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
-export { addPatchToManifest, loadPatchesManifest, mutatePatchRowsInManifest, PATCHES_MANIFEST, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
+export { addPatchToManifest, loadPatchesManifest, loadPatchesManifestForWrite, mutatePatchRowsInManifest, PATCHES_MANIFEST, removePatchFileAndManifest, renumberPatchesInManifest, rewriteStagedDependencyOwners, savePatchesManifest, } from './patch-manifest-io.js';
 export { checkVersionCompatibility, findPatchesAffectingFile, getClaimedFiles, stampPatchVersions, validatePatchIntegrity, } from './patch-manifest-query.js';
 export { resolvePatchIdentifier } from './patch-manifest-resolve.js';
 export { validatePatchesManifest } from './patch-manifest-validate.js';
-//# sourceMappingURL=patch-manifest.js.map

package/dist/src/core/patch-parse.d.ts

@@ -1,6 +1,15 @@
 /**
  * Pure parsing functions for extracting information from patch files.
  * All functions are synchronous and operate on string content.
+ *
+ * This module is the ONE unified-diff walker in the codebase. Before
+ * {@link parseDiffSections} existed, six hand-rolled `diff --git` walkers
+ * lived across patch-parse, patch-lint-diff, patch-registration-refs, and
+ * patch-transform — with divergent CRLF handling (a CRLF-saved patch file
+ * silently failed target-file matching and `\ No newline` detection on
+ * Windows), no quoted-path support, and greedy path captures that
+ * mis-split any path containing ` b/`. New diff-shaped parsing must build
+ * on {@link parseDiffSections} rather than re-walking lines.
  */
 /**
  * Extracts the order number from a patch filename.
@@ -9,6 +18,56 @@
  * @returns Order number, or Infinity if no prefix
  */
 export declare function extractOrder(filename: string): number;
+/**
+ * A parsed `diff --git` header: both sides' paths, unquoted and with any
+ * CRLF residue stripped.
+ */
+export interface DiffGitHeader {
+    /** Old-side (`a/`) path. */
+    sourcePath: string;
+    /** New-side (`b/`) path — the file the patch produces. */
+    targetPath: string;
+}
+/**
+ * Parses a `diff --git` line into its two paths.
+ *
+ * Handles the quoted form git emits for paths with special characters
+ * (`diff --git "a/x y" "b/x y"`), and disambiguates the unquoted form for
+ * paths that themselves contain ` b/`: for the overwhelmingly common
+ * non-rename case the two paths are identical, so a symmetric split
+ * (`a/<p> b/<p>`) is tried first — the previous greedy regex
+ * (`a\/.+ b\/(.+)$`) split such lines at the LAST ` b/` and returned a
+ * truncated path. Falls back to a non-greedy split for renames.
+ *
+ * @returns null when the line is not a diff --git header.
+ */
+export declare function parseDiffGitHeader(line: string): DiffGitHeader | null;
+/**
+ * One `diff --git` section of a unified diff, fully structured.
+ */
+export interface DiffSection {
+    /** New-side (`b/`) path — the file this section produces. */
+    targetPath: string;
+    /** Old-side (`a/`) path. */
+    sourcePath: string;
+    /** True when the section carries a `new file mode` marker. */
+    isNewFile: boolean;
+    /** True when the section carries a `deleted file mode` marker. */
+    isDeletedFile: boolean;
+    /**
+     * True for binary sections (`GIT binary patch` or `Binary files … differ`).
+     * Binary sections have no parseable hunks; text-oriented consumers must
+     * refuse them rather than treat base85 lines starting with `+` as content.
+     */
+    isBinary: boolean;
+    /** Parsed hunks, in file order. Empty for binary or metadata-only sections. */
+    hunks: ParsedHunk[];
+}
+/**
+ * Parses a unified diff into structured per-file sections — the single
+ * shared walker every diff consumer builds on.
+ */
+export declare function parseDiffSections(diffContent: string): DiffSection[];
 /**
  * Checks whether a specific file is a new-file addition within a patch.
  * For multi-file patches, only inspects the section belonging to targetFile.