@hominis/fireforge 0.49.2 → 0.51.0

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`;
+}

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

@@ -4,6 +4,8 @@
  */
 import { parseObject } from '../utils/parse.js';
 import { isArray, isObject, isValidFirefoxProduct, isValidFirefoxVersion, PATCH_CATEGORIES, } from '../utils/validation.js';
+import { parseLintIgnoreEntries } from './patch-lint-ignore.js';
+import { canonicalizePatchRow } from './patch-manifest-key-order.js';
 import { checkDocumentVersion, describeNewerDocument } from './state-file.js';
 function parseForwardImports(data, label) {
     if (!isArray(data)) {
@@ -99,7 +101,11 @@ function validatePatchMetadata(data, index) {
     // `lintIgnore` to suppress a rule is quietly re-tripped the next time the
     // manifest validates. Preserve both `lintIgnore` and `tier` here. Future
     // optional fields follow the same template.
-    const lintIgnore = rec.optionalStringArray('lintIgnore');
+    // Entries are bare check IDs or `{ rule, max, reason }` ceilings.
+    const rawLintIgnore = rec.raw('lintIgnore');
+    const lintIgnore = rawLintIgnore === undefined
+        ? undefined
+        : parseLintIgnoreEntries(rawLintIgnore, `patches[${index}].lintIgnore`);
     const rawTier = rec.raw('tier');
     let tier;
     if (rawTier !== undefined) {
@@ -129,7 +135,54 @@ function validatePatchMetadata(data, index) {
     if (rawStagedDependencies !== undefined) {
         result.stagedDependencies = parseStagedDependencies(rawStagedDependencies, `patches[${index}].stagedDependencies`);
     }
-    return result;
+    return canonicalizePatchRow(result);
+}
+/**
+ * Validates the `retired` placeholders `patch retire` leaves behind. Kept on
+ * the manifest so every write that round-trips a loaded manifest carries
+ * them; dropping them would silently reopen the gaps they were retired to
+ * close.
+ */
+function parseRetiredSlots(data) {
+    if (!isArray(data)) {
+        throw new Error('patches.json field "retired" must be an array');
+    }
+    return data.map((entry, index) => {
+        const rec = parseObject(entry, `retired[${index}]`);
+        const slot = {
+            order: rec.nonNegativeInteger('order'),
+            category: rec.validatedString('category', (value) => /^[a-z][a-z0-9-]*$/.test(value), 'a lowercase category identifier (letters, numbers, hyphens)'),
+            filename: rec.string('filename'),
+            retiredAt: rec.string('retiredAt'),
+        };
+        const reason = rec.optionalString('reason');
+        if (reason !== undefined)
+            slot.reason = reason;
+        return slot;
+    });
+}
+/**
+ * Validates the `reserved` placeholders `patch reserve` writes. Same
+ * survival rule as {@link parseRetiredSlots}: dropping one on a round trip
+ * would reopen the gap a peer reserved the order to close.
+ */
+function parseReservedSlots(data) {
+    if (!isArray(data)) {
+        throw new Error('patches.json field "reserved" must be an array');
+    }
+    return data.map((entry, index) => {
+        const rec = parseObject(entry, `reserved[${index}]`);
+        const slot = {
+            order: rec.nonNegativeInteger('order'),
+            category: rec.validatedString('category', (value) => /^[a-z][a-z0-9-]*$/.test(value), 'a lowercase category identifier (letters, numbers, hyphens)'),
+            owner: rec.validatedString('owner', (value) => value.trim() !== '', 'a non-empty label'),
+            reservedAt: rec.string('reservedAt'),
+        };
+        const reason = rec.optionalString('reason');
+        if (reason !== undefined)
+            slot.reason = reason;
+        return slot;
+    });
 }
 /** Manifest schema version this build writes and understands. */
 const PATCHES_MANIFEST_VERSION = 1;
@@ -156,10 +209,15 @@ export function validatePatchesManifest(data) {
     if (!isArray(data['patches'])) {
         throw new Error('patches.json field "patches" must be an array');
     }
-    return {
+    const manifest = {
         version: 1,
         patches: data['patches'].map((patch, index) => validatePatchMetadata(patch, index)),
     };
+    if (data['retired'] !== undefined)
+        manifest.retired = parseRetiredSlots(data['retired']);
+    if (data['reserved'] !== undefined)
+        manifest.reserved = parseReservedSlots(data['reserved']);
+    return manifest;
 }
 /**
  * Infers patch metadata from a filename pattern.

package/dist/src/core/patch-order-legal.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The earliest order a new patch can take after a given order, under the
+ * queue's occupancy and `patchPolicy`.
+ *
+ * A refusal that says "export it as its own later patch" leaves the
+ * operator to find a number that is free, inside the category's range, and
+ * (with `allowGaps: false`) does not open a gap. Each wrong guess costs a
+ * full export attempt. This answers it once, with the same policy
+ * evaluation the export itself will run.
+ */
+import type { PatchesManifest } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+/**
+ * Smallest order strictly greater than `after` that no patch occupies and
+ * that adds no order-related `patchPolicy` finding (collision, category
+ * range, reserved range, numeric gap) for a `category` patch. A retired
+ * slot counts as free, since a patch may fill it; a reservation does not,
+ * since it is held for its owner's export. Returns null when no such
+ * order exists inside the category's configured ranges.
+ *
+ * @param config - Project config (only `patchPolicy` is read)
+ * @param manifest - Current manifest
+ * @param category - Category the new patch would carry
+ * @param after - The order the new patch must come after
+ */
+export declare function earliestLegalOrderAfter(config: Pick<FireForgeConfig, 'patchPolicy'>, manifest: PatchesManifest, category: string, after: number): number | null;

package/dist/src/core/patch-order-legal.js

@@ -0,0 +1,88 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * The earliest order a new patch can take after a given order, under the
+ * queue's occupancy and `patchPolicy`.
+ *
+ * A refusal that says "export it as its own later patch" leaves the
+ * operator to find a number that is free, inside the category's range, and
+ * (with `allowGaps: false`) does not open a gap. Each wrong guess costs a
+ * full export attempt. This answers it once, with the same policy
+ * evaluation the export itself will run.
+ */
+import { formatPatchOrder } from './patch-parse.js';
+import { evaluatePatchPolicy } from './patch-policy.js';
+import { reservedOrderSet } from './patch-retired.js';
+/** Policy codes an order choice alone can trip. */
+const ORDER_CODES = new Set([
+    'order-collision',
+    'category-range',
+    'reserved-range',
+    'numeric-gap',
+]);
+/** Upper bound on the search when no policy range bounds it. */
+const UNBOUNDED_SEARCH = 1000;
+const GAP_ORDERS_PATTERN = /numeric gap\(s\): (?<orders>[^.]+)\./;
+/**
+ * Order-related findings as comparable keys. A `numeric-gap` finding
+ * becomes one key per missing order, so filling one gap of several reads as
+ * removing a key rather than as a new, differently worded finding.
+ */
+function orderIssueKeys(config, manifest) {
+    const keys = new Set();
+    for (const issue of evaluatePatchPolicy(config, manifest)) {
+        if (!ORDER_CODES.has(issue.code))
+            continue;
+        const gaps = issue.code === 'numeric-gap' ? GAP_ORDERS_PATTERN.exec(issue.message) : null;
+        if (gaps?.groups?.['orders'] === undefined) {
+            keys.add(`${issue.code}|${issue.message}`);
+            continue;
+        }
+        for (const order of gaps.groups['orders'].split(',')) {
+            keys.add(`numeric-gap|${issue.filename}|${order.trim()}`);
+        }
+    }
+    return keys;
+}
+/**
+ * Smallest order strictly greater than `after` that no patch occupies and
+ * that adds no order-related `patchPolicy` finding (collision, category
+ * range, reserved range, numeric gap) for a `category` patch. A retired
+ * slot counts as free, since a patch may fill it; a reservation does not,
+ * since it is held for its owner's export. Returns null when no such
+ * order exists inside the category's configured ranges.
+ *
+ * @param config - Project config (only `patchPolicy` is read)
+ * @param manifest - Current manifest
+ * @param category - Category the new patch would carry
+ * @param after - The order the new patch must come after
+ */
+export function earliestLegalOrderAfter(config, manifest, category, after) {
+    const occupied = new Set([
+        ...manifest.patches.map((patch) => patch.order),
+        ...reservedOrderSet(manifest),
+    ]);
+    const ranges = config.patchPolicy?.ranges.filter((range) => range.category === category) ?? [];
+    const limit = ranges.length > 0 ? Math.max(...ranges.map((range) => range.to)) : after + UNBOUNDED_SEARCH;
+    const baseline = config.patchPolicy ? orderIssueKeys(config, manifest) : new Set();
+    for (let order = after + 1; order <= limit; order++) {
+        if (occupied.has(order))
+            continue;
+        if (!config.patchPolicy)
+            return order;
+        const probe = {
+            filename: `${formatPatchOrder(order)}-${category}-probe.patch`,
+            order,
+            category,
+            name: 'probe',
+            description: 'probe',
+            createdAt: '',
+            sourceEsrVersion: '',
+            filesAffected: [],
+        };
+        const projected = { ...manifest, patches: [...manifest.patches, probe] };
+        const introduced = [...orderIssueKeys(config, projected)].filter((key) => !baseline.has(key));
+        if (introduced.length === 0)
+            return order;
+    }
+    return null;
+}

package/dist/src/core/patch-policy-content.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Registration-only patch policy: the `patchPolicy` rules that need the
+ * patch bodies, not just the manifest.
+ *
+ * - `upstreamAllowlist`: which upstream files (files no patch in the queue
+ *   creates) a non-reserved patch may modify.
+ * - `addOnly` allowlist entries: for shared registration files, a patch may
+ *   only add lines, and each non-blank added line must carry the marker.
+ * - `scopeRules`: limit a class of patch (a category, or a filename pattern
+ *   such as `-tests\.patch$`) to the files its globs name.
+ * - `verifyDocumentPaths`: every reserved allowlist entry's `adr` /
+ *   `documentation` path must exist.
+ *
+ * Every rule is opt-in, and none can be evaluated from `patches.json`
+ * alone, which is why they live apart from `patch-policy.ts`: that module
+ * answers synchronously over a (possibly projected) manifest, this one reads
+ * patch bodies and the filesystem. `verify` and `lint --per-patch` run both.
+ */
+import type { PatchesManifest } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+import { type PatchQueueEntry } from './patch-lint-cross.js';
+import type { PatchPolicyIssue } from './patch-policy.js';
+/** True when the policy sets any rule this module evaluates. */
+export declare function hasPatchPolicyContentRules(config: FireForgeConfig): boolean;
+/**
+ * Evaluates the body-dependent `patchPolicy` rules over a patch queue.
+ *
+ * @param config - Project configuration
+ * @param projectRoot - Project root, for the document-path check
+ * @param manifest - Current manifest (category and order per patch)
+ * @param entries - Patch queue entries with their bodies
+ * @returns Findings, in the same shape {@link evaluatePatchPolicy} returns
+ */
+export declare function evaluatePatchPolicyContent(config: FireForgeConfig, projectRoot: string, manifest: PatchesManifest, entries: readonly PatchQueueEntry[]): Promise<PatchPolicyIssue[]>;
+/**
+ * {@link evaluatePatchPolicyContent} for a caller without a queue context
+ * in hand (`verify`): reads the patch bodies only when a body-dependent
+ * rule is configured.
+ */
+export declare function evaluatePatchPolicyContentForQueue(config: FireForgeConfig, projectRoot: string, patchesDir: string, manifest: PatchesManifest): Promise<PatchPolicyIssue[]>;

package/dist/src/core/patch-policy-content.js

@@ -0,0 +1,216 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Registration-only patch policy: the `patchPolicy` rules that need the
+ * patch bodies, not just the manifest.
+ *
+ * - `upstreamAllowlist`: which upstream files (files no patch in the queue
+ *   creates) a non-reserved patch may modify.
+ * - `addOnly` allowlist entries: for shared registration files, a patch may
+ *   only add lines, and each non-blank added line must carry the marker.
+ * - `scopeRules`: limit a class of patch (a category, or a filename pattern
+ *   such as `-tests\.patch$`) to the files its globs name.
+ * - `verifyDocumentPaths`: every reserved allowlist entry's `adr` /
+ *   `documentation` path must exist.
+ *
+ * Every rule is opt-in, and none can be evaluated from `patches.json`
+ * alone, which is why they live apart from `patch-policy.ts`: that module
+ * answers synchronously over a (possibly projected) manifest, this one reads
+ * patch bodies and the filesystem. `verify` and `lint --per-patch` run both.
+ */
+import { join } from 'node:path';
+import { pathExists } from '../utils/fs.js';
+import { matchesAnyGlob } from '../utils/path-glob.js';
+import { buildPatchQueueContext } from './patch-lint-cross.js';
+import { parseDiffSections } from './patch-parse.js';
+/** True when the policy sets any rule this module evaluates. */
+export function hasPatchPolicyContentRules(config) {
+    const cfg = config.patchPolicy;
+    return (cfg !== undefined &&
+        (cfg.upstreamAllowlist !== undefined ||
+            cfg.scopeRules !== undefined ||
+            cfg.verifyDocumentPaths === true));
+}
+function normalizeAllowEntry(entry) {
+    return typeof entry === 'string' ? { path: entry } : entry;
+}
+function isReservedOrder(cfg, order) {
+    return (cfg.reservedRanges ?? []).some((range) => order >= range.from && order <= range.to);
+}
+/**
+ * The upstream files a patch body edits, keyed by path: every section that
+ * does not create its file, minus paths some patch in the queue creates. A
+ * rename counts against both of its paths.
+ */
+function collectUpstreamEdits(diff, queueCreated) {
+    const edits = new Map();
+    for (const section of parseDiffSections(diff)) {
+        if (section.isNewFile)
+            continue;
+        const paths = new Set([section.sourcePath, section.targetPath]);
+        for (const path of paths) {
+            if (queueCreated.has(path))
+                continue;
+            const edit = edits.get(path) ?? { added: [], removed: [], deleted: false, binary: false };
+            edit.deleted ||= section.isDeletedFile;
+            edit.binary ||= section.isBinary;
+            for (const hunk of section.hunks) {
+                for (const line of hunk.lines) {
+                    if (line.startsWith('+'))
+                        edit.added.push(line.slice(1));
+                    else if (line.startsWith('-'))
+                        edit.removed.push(line.slice(1));
+                }
+            }
+            edits.set(path, edit);
+        }
+    }
+    return edits;
+}
+/**
+ * Why an add-only file's edit breaks the mode, or undefined when it holds.
+ * Blank lines are free in both directions: they carry no registration.
+ */
+function addOnlyViolation(edit, marker) {
+    if (edit.deleted)
+        return 'deletes the file';
+    if (edit.binary)
+        return 'carries a binary change';
+    const removed = edit.removed.filter((line) => line.trim() !== '');
+    if (removed.length > 0) {
+        return `removes ${String(removed.length)} line(s), first: ${JSON.stringify(removed[0])}`;
+    }
+    const needle = marker.toLowerCase();
+    const unmarked = edit.added.filter((line) => line.trim() !== '' && !line.toLowerCase().includes(needle));
+    if (unmarked.length > 0) {
+        return (`adds ${String(unmarked.length)} line(s) without the "${marker}" marker, ` +
+            `first: ${JSON.stringify(unmarked[0])}`);
+    }
+    return undefined;
+}
+function evaluateUpstreamEdits(cfg, filename, edits, severity) {
+    const allowlist = (cfg.upstreamAllowlist ?? []).map(normalizeAllowEntry);
+    const issues = [];
+    const outside = [];
+    for (const [path, edit] of [...edits].sort(([a], [b]) => a.localeCompare(b))) {
+        const matches = allowlist.filter((entry) => matchesAnyGlob(path, [entry.path]));
+        if (matches.length === 0) {
+            outside.push(path);
+            continue;
+        }
+        // Strictest wins: any add-only match makes the file add-only.
+        const addOnly = matches.find((entry) => entry.addOnly === true);
+        if (!addOnly)
+            continue;
+        const marker = addOnly.marker ?? cfg.addOnlyMarker ?? '';
+        const violation = addOnlyViolation(edit, marker);
+        if (violation !== undefined) {
+            issues.push({
+                code: 'add-only',
+                filename,
+                severity,
+                message: `${filename} edits ${path}, which patchPolicy.upstreamAllowlist marks add-only ` +
+                    `(added lines carrying "${marker}"), but ${violation}.`,
+            });
+        }
+    }
+    if (outside.length > 0) {
+        issues.push({
+            code: 'upstream-allowlist',
+            filename,
+            severity,
+            message: `${filename} modifies upstream file(s) outside patchPolicy.upstreamAllowlist: ` +
+                `${outside.join(', ')}. Move the change into a fork-owned file, or add a reviewed allowlist entry.`,
+        });
+    }
+    return issues;
+}
+function evaluateScopeRules(cfg, filename, category, files, severity) {
+    const issues = [];
+    for (const [index, rule] of (cfg.scopeRules ?? []).entries()) {
+        if (rule.category !== undefined && rule.category !== category)
+            continue;
+        if (rule.filenamePattern !== undefined && !new RegExp(rule.filenamePattern).test(filename)) {
+            continue;
+        }
+        const outside = files.filter((file) => !matchesAnyGlob(file, rule.files));
+        if (outside.length === 0)
+            continue;
+        issues.push({
+            code: 'scope',
+            filename,
+            severity,
+            message: `${filename} is scoped by patchPolicy.scopeRules[${String(index)}] to ` +
+                `${rule.files.join(', ')}, but touches: ${outside.join(', ')}. ` +
+                'Move those files to a patch of the class that owns them.',
+        });
+    }
+    return issues;
+}
+async function evaluateDocumentPaths(cfg, projectRoot, severity) {
+    if (cfg.verifyDocumentPaths !== true)
+        return [];
+    const issues = [];
+    for (const range of cfg.reservedRanges ?? []) {
+        for (const allowed of range.allowed) {
+            for (const [field, path] of [
+                ['adr', allowed.adr],
+                ['documentation', allowed.documentation],
+            ]) {
+                if (path === undefined || (await pathExists(join(projectRoot, path))))
+                    continue;
+                issues.push({
+                    code: 'reserved-document-missing',
+                    filename: allowed.filename,
+                    severity,
+                    message: `${allowed.filename}'s reserved-range allowlist entry names ${field} "${path}", ` +
+                        'which does not exist. Restore the document or correct the path.',
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Evaluates the body-dependent `patchPolicy` rules over a patch queue.
+ *
+ * @param config - Project configuration
+ * @param projectRoot - Project root, for the document-path check
+ * @param manifest - Current manifest (category and order per patch)
+ * @param entries - Patch queue entries with their bodies
+ * @returns Findings, in the same shape {@link evaluatePatchPolicy} returns
+ */
+export async function evaluatePatchPolicyContent(config, projectRoot, manifest, entries) {
+    const cfg = config.patchPolicy;
+    if (!cfg || !hasPatchPolicyContentRules(config))
+        return [];
+    const severity = cfg.mutationMode === 'warn' ? 'warning' : 'error';
+    const queueCreated = new Set();
+    for (const entry of entries)
+        for (const file of entry.createdFiles)
+            queueCreated.add(file);
+    const bodies = new Map(entries.map((entry) => [entry.filename, entry.diff]));
+    const issues = [];
+    for (const patch of manifest.patches) {
+        const diff = bodies.get(patch.filename);
+        if (cfg.upstreamAllowlist !== undefined && diff !== undefined) {
+            if (!isReservedOrder(cfg, patch.order)) {
+                const edits = collectUpstreamEdits(diff, queueCreated);
+                issues.push(...evaluateUpstreamEdits(cfg, patch.filename, edits, severity));
+            }
+        }
+        issues.push(...evaluateScopeRules(cfg, patch.filename, patch.category, patch.filesAffected, severity));
+    }
+    issues.push(...(await evaluateDocumentPaths(cfg, projectRoot, severity)));
+    return issues;
+}
+/**
+ * {@link evaluatePatchPolicyContent} for a caller without a queue context
+ * in hand (`verify`): reads the patch bodies only when a body-dependent
+ * rule is configured.
+ */
+export async function evaluatePatchPolicyContentForQueue(config, projectRoot, patchesDir, manifest) {
+    if (!hasPatchPolicyContentRules(config))
+        return [];
+    const { entries } = await buildPatchQueueContext(patchesDir);
+    return evaluatePatchPolicyContent(config, projectRoot, manifest, entries);
+}