@hominis/fireforge 0.21.1 → 0.21.3

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

@@ -0,0 +1,350 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Project-specific patch queue policy evaluation.
+ *
+ * The policy is opt-in via `fireforge.json#patchPolicy`. Callers feed this
+ * module either the current manifest (`verify`, `lint --per-patch`) or a
+ * projected manifest assembled before a mutation commits (`export`,
+ * `patch reorder`, etc.).
+ */
+import { InvalidArgumentError } from '../errors/base.js';
+import { warn } from '../utils/logger.js';
+import { PATCH_CATEGORIES } from '../utils/validation.js';
+/** Default patch filename contract used when a policy omits `filenamePattern`. */
+export const DEFAULT_PATCH_POLICY_FILENAME_PATTERN = '^(?<order>\\d{3})-(?<category>[a-z][a-z0-9-]*)-(?<slug>[a-z0-9-]+)\\.patch$';
+function policy(config) {
+    return config.patchPolicy;
+}
+function mutationMode(config) {
+    return policy(config)?.mutationMode ?? 'error';
+}
+function issueSeverity(config) {
+    return mutationMode(config) === 'warn' ? 'warning' : 'error';
+}
+/** Returns true when the loaded config includes an opt-in patch policy. */
+export function hasPatchPolicy(config) {
+    return policy(config) !== undefined;
+}
+/** Returns valid categories for prompts and CLI validation under the config. */
+export function getPatchPolicyCategories(config) {
+    const cfg = policy(config);
+    if (!cfg)
+        return [...PATCH_CATEGORIES];
+    return Array.from(new Set(cfg.ranges.map((range) => range.category))).sort((a, b) => a.localeCompare(b));
+}
+/** Checks whether a category is accepted by legacy defaults or the policy ranges. */
+export function isCategoryAllowedByConfig(config, category) {
+    if (!/^[a-z][a-z0-9-]*$/.test(category))
+        return false;
+    const cfg = policy(config);
+    if (!cfg)
+        return PATCH_CATEGORIES.includes(category);
+    return cfg.ranges.some((range) => range.category === category);
+}
+function rangeLabel(range) {
+    return `${String(range.from).padStart(3, '0')}-${String(range.to).padStart(3, '0')}`;
+}
+function categoryRangeLabel(ranges, category) {
+    const matches = ranges.filter((range) => range.category === category);
+    if (matches.length === 0)
+        return '(no configured range)';
+    return matches.map(rangeLabel).join(', ');
+}
+function reservedRangeForOrder(cfg, order) {
+    return cfg.reservedRanges?.find((range) => order >= range.from && order <= range.to) ?? null;
+}
+function categoryRangeForOrder(cfg, category, order) {
+    return (cfg.ranges.find((range) => {
+        return range.category === category && order >= range.from && order <= range.to;
+    }) ?? null);
+}
+function anyRangeForOrder(cfg, order) {
+    return cfg.ranges.find((range) => order >= range.from && order <= range.to) ?? null;
+}
+function compileFilenamePattern(cfg) {
+    return new RegExp(cfg.filenamePattern ?? DEFAULT_PATCH_POLICY_FILENAME_PATTERN);
+}
+function parseFilenameWithPolicy(cfg, patch, severity) {
+    if (cfg.filenamePattern === undefined) {
+        const defaultMatch = /^(?<order>\d{3})-(?<rest>[a-z0-9-]+)\.patch$/.exec(patch.filename);
+        const orderRaw = defaultMatch?.groups?.['order'];
+        const rest = defaultMatch?.groups?.['rest'];
+        if (!orderRaw || !rest) {
+            return [
+                {
+                    code: 'filename-pattern',
+                    filename: patch.filename,
+                    severity,
+                    message: `${patch.filename} does not match the default patchPolicy filename pattern ` +
+                        '(NNN-category-slug.patch).',
+                },
+            ];
+        }
+        const categories = Array.from(new Set(cfg.ranges.map((range) => range.category))).sort((a, b) => b.length - a.length);
+        const category = categories.find((candidate) => rest.startsWith(`${candidate}-`));
+        if (!category) {
+            return [
+                {
+                    code: 'filename-captures',
+                    filename: patch.filename,
+                    severity,
+                    message: `${patch.filename} does not encode one of the configured patchPolicy categories.`,
+                },
+            ];
+        }
+        const slug = rest.slice(category.length + 1);
+        if (!/^[a-z0-9-]+$/.test(slug)) {
+            return [
+                {
+                    code: 'filename-captures',
+                    filename: patch.filename,
+                    severity,
+                    message: `${patch.filename} does not encode a lowercase slug after category "${category}".`,
+                },
+            ];
+        }
+        return { order: Number.parseInt(orderRaw, 10), category };
+    }
+    const pattern = compileFilenamePattern(cfg);
+    const match = pattern.exec(patch.filename);
+    if (!match) {
+        return [
+            {
+                code: 'filename-pattern',
+                filename: patch.filename,
+                severity,
+                message: `${patch.filename} does not match patchPolicy.filenamePattern ` +
+                    `(${cfg.filenamePattern ?? DEFAULT_PATCH_POLICY_FILENAME_PATTERN}).`,
+            },
+        ];
+    }
+    const groups = match.groups;
+    const orderRaw = groups?.['order'];
+    const category = groups?.['category'];
+    const slug = groups?.['slug'];
+    if (!orderRaw || !category || slug === undefined) {
+        return [
+            {
+                code: 'filename-captures',
+                filename: patch.filename,
+                severity,
+                message: 'patchPolicy.filenamePattern must expose named captures "order", "category", and "slug".',
+            },
+        ];
+    }
+    const order = Number.parseInt(orderRaw, 10);
+    if (!Number.isInteger(order)) {
+        return [
+            {
+                code: 'filename-captures',
+                filename: patch.filename,
+                severity,
+                message: `${patch.filename} has a non-numeric order capture "${orderRaw}".`,
+            },
+        ];
+    }
+    return { order, category };
+}
+function evaluatePatchMetadata(cfg, patch, severity) {
+    const issues = [];
+    const parsed = parseFilenameWithPolicy(cfg, patch, severity);
+    if (Array.isArray(parsed)) {
+        return parsed;
+    }
+    if (parsed.order !== patch.order || parsed.category !== patch.category) {
+        issues.push({
+            code: 'filename-metadata-mismatch',
+            filename: patch.filename,
+            severity,
+            message: `${patch.filename} encodes order/category ${parsed.order}/${parsed.category}, ` +
+                `but patches.json records ${patch.order}/${patch.category}.`,
+        });
+    }
+    if (cfg.requireDescription === true && patch.description.trim() === '') {
+        issues.push({
+            code: 'description-required',
+            filename: patch.filename,
+            severity,
+            message: `${patch.filename} has an empty description, but patchPolicy.requireDescription is true.`,
+        });
+    }
+    const reserved = reservedRangeForOrder(cfg, patch.order);
+    if (reserved) {
+        const allowed = reserved.allowed.find((entry) => entry.filename === patch.filename);
+        if (!allowed) {
+            issues.push({
+                code: 'reserved-range',
+                filename: patch.filename,
+                severity,
+                message: `${patch.filename} is in reserved range ${rangeLabel(reserved)}. ` +
+                    'Reserved ranges require an exact patchPolicy.reservedRanges[].allowed filename exception.',
+            });
+            return issues;
+        }
+        if (!allowed.adr && !allowed.documentation) {
+            issues.push({
+                code: 'reserved-documentation',
+                filename: patch.filename,
+                severity,
+                message: `${patch.filename} is allowlisted for reserved range ${rangeLabel(reserved)}, ` +
+                    'but the allowlist entry must include either "adr" or "documentation".',
+            });
+        }
+        if (allowed.files !== undefined) {
+            const allowedFiles = new Set(allowed.files);
+            const extraFiles = patch.filesAffected.filter((file) => !allowedFiles.has(file));
+            if (extraFiles.length > 0) {
+                issues.push({
+                    code: 'reserved-files',
+                    filename: patch.filename,
+                    severity,
+                    message: `${patch.filename} is allowlisted for reserved range ${rangeLabel(reserved)}, ` +
+                        `but touches file(s) outside its reserved allowlist: ${extraFiles.join(', ')}.`,
+                });
+            }
+        }
+        return issues;
+    }
+    const matchingRange = categoryRangeForOrder(cfg, patch.category, patch.order);
+    if (!matchingRange) {
+        const owner = anyRangeForOrder(cfg, patch.order);
+        const expected = categoryRangeLabel(cfg.ranges, patch.category);
+        const actual = owner !== null
+            ? `${String(patch.order).padStart(3, '0')} is configured for ${owner.category} (${rangeLabel(owner)})`
+            : `${String(patch.order).padStart(3, '0')} is outside all configured ranges`;
+        issues.push({
+            code: 'category-range',
+            filename: patch.filename,
+            severity,
+            message: `${patch.category} patches must use ${expected}; ${actual}. ` +
+                `Choose a ${patch.category} order in ${expected} or configure an explicit reserved-range exception.`,
+        });
+    }
+    return issues;
+}
+function evaluateGaps(cfg, patches, severity) {
+    if (cfg.allowGaps !== false)
+        return [];
+    const issues = [];
+    for (const range of cfg.ranges) {
+        const occupied = patches
+            .filter((patch) => {
+            return (patch.category === range.category &&
+                patch.order >= range.from &&
+                patch.order <= range.to &&
+                reservedRangeForOrder(cfg, patch.order) === null);
+        })
+            .map((patch) => patch.order)
+            .sort((a, b) => a - b);
+        if (occupied.length <= 1)
+            continue;
+        const occupiedSet = new Set(occupied);
+        const first = occupied[0];
+        const last = occupied[occupied.length - 1];
+        const missing = [];
+        for (let order = first; order <= last; order++) {
+            if (!occupiedSet.has(order) && reservedRangeForOrder(cfg, order) === null) {
+                missing.push(order);
+            }
+        }
+        if (missing.length > 0) {
+            issues.push({
+                code: 'numeric-gap',
+                filename: `${range.category}:${rangeLabel(range)}`,
+                severity,
+                message: `${range.category} range ${rangeLabel(range)} has numeric gap(s): ` +
+                    missing.map((order) => String(order).padStart(3, '0')).join(', ') +
+                    '. patchPolicy.allowGaps is false.',
+            });
+        }
+    }
+    return issues;
+}
+/** Evaluates an entire patch manifest against the configured policy. */
+export function evaluatePatchPolicy(config, manifest) {
+    const cfg = policy(config);
+    if (!cfg)
+        return [];
+    const severity = issueSeverity(config);
+    const issues = manifest.patches.flatMap((patch) => evaluatePatchMetadata(cfg, patch, severity));
+    issues.push(...evaluateGaps(cfg, manifest.patches, severity));
+    return issues;
+}
+/** Builds a sorted manifest snapshot from projected patch metadata. */
+export function buildProjectedManifest(current, patches) {
+    const next = patches
+        .map((patch) => ({ ...patch, filesAffected: [...patch.filesAffected] }))
+        .sort((a, b) => a.order - b.order || a.filename.localeCompare(b.filename));
+    return {
+        version: current?.version ?? 1,
+        patches: next,
+    };
+}
+/** Applies a filename/order rename projection to a manifest without mutating it. */
+export function applyRenameMapToManifest(manifest, renameMap) {
+    return buildProjectedManifest(manifest, manifest.patches.map((patch) => {
+        const rename = renameMap.get(patch.filename);
+        if (!rename)
+            return patch;
+        return {
+            ...patch,
+            filename: rename.newFilename,
+            order: rename.newOrder,
+        };
+    }));
+}
+/** Enforces patch policy according to the configured mutation mode. */
+export function enforcePatchPolicy(input) {
+    if (!hasPatchPolicy(input.config))
+        return;
+    const issues = evaluatePatchPolicy(input.config, input.manifest);
+    if (issues.length === 0)
+        return;
+    const mode = mutationMode(input.config);
+    const details = issues.map((issue) => `  [${issue.code}] ${issue.message}`);
+    if (mode === 'warn') {
+        warn(`${input.command}: patch policy warning(s):`);
+        for (const detail of details)
+            warn(detail);
+        return;
+    }
+    if (mode === 'force' && input.forceUnsafe === true) {
+        warn(`${input.command}: bypassing patch policy violation(s) because --force-unsafe was provided:`);
+        for (const detail of details)
+            warn(detail);
+        return;
+    }
+    const suffix = mode === 'force'
+        ? '\n\nPass --force-unsafe only if you intentionally accept this policy violation.'
+        : '';
+    throw new InvalidArgumentError(`${input.command} would violate patchPolicy:\n${details.join('\n')}${suffix}`, mode === 'force' ? '--force-unsafe' : 'patchPolicy');
+}
+/** Allocates the next available order inside the configured ranges for a category. */
+export function allocatePolicyOrder(config, patches, category) {
+    const cfg = policy(config);
+    if (!cfg)
+        return null;
+    const ranges = cfg.ranges
+        .filter((range) => range.category === category)
+        .sort((a, b) => a.from - b.from || a.to - b.to);
+    if (ranges.length === 0)
+        return null;
+    const occupied = new Set(patches.map((patch) => patch.order));
+    const highestInRanges = patches.reduce((highest, patch) => {
+        if (!ranges.some((range) => patch.order >= range.from && patch.order <= range.to)) {
+            return highest;
+        }
+        return highest === null ? patch.order : Math.max(highest, patch.order);
+    }, null);
+    const start = highestInRanges === null ? ranges[0]?.from : highestInRanges + 1;
+    if (start === undefined)
+        return null;
+    for (const range of ranges) {
+        for (let order = Math.max(start, range.from); order <= range.to; order++) {
+            if (!occupied.has(order))
+                return order;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=patch-policy.js.map

package/dist/src/types/commands/options.d.ts

@@ -530,6 +530,8 @@ export interface PatchRenameOptions {
     dryRun?: boolean;
     /** Skip the confirmation prompt (required for non-TTY). */
     yes?: boolean;
+    /** Bypass force-mode patchPolicy refusals. */
+    forceUnsafe?: boolean;
 }
 /**
  * Options for the patch reorder command.

package/dist/src/types/commands/patches.d.ts

@@ -4,7 +4,7 @@
 /**
  * Patch categories for organizational classification.
  */
-export type PatchCategory = 'branding' | 'ui' | 'privacy' | 'security' | 'infra';
+export type PatchCategory = string;
 /**
  * Information about a patch file.
  */

package/dist/src/types/config.d.ts

@@ -24,6 +24,55 @@ export interface BuildConfig {
     /** Number of parallel jobs for mach build */
     jobs?: number;
 }
+/** Enforcement mode for patch policy violations during mutating commands. */
+export type PatchPolicyMutationMode = 'error' | 'warn' | 'force';
+/** A category-owned numeric range in the patch queue. */
+export interface PatchPolicyRange {
+    /** Inclusive lower bound. */
+    from: number;
+    /** Inclusive upper bound. */
+    to: number;
+    /** Category that owns this range. */
+    category: string;
+}
+/** A single allowlisted reserved-range patch exception. */
+export interface PatchPolicyReservedAllowedPatch {
+    /** Exact patch filename allowed in the reserved range. */
+    filename: string;
+    /** Optional exact filesAffected allowlist for this reserved patch. */
+    files?: string[];
+    /** Project-relative ADR path documenting the exception. */
+    adr?: string;
+    /** Project-relative documentation path documenting the exception. */
+    documentation?: string;
+}
+/** Reserved numeric range for exceptional patches. */
+export interface PatchPolicyReservedRange {
+    /** Inclusive lower bound. */
+    from: number;
+    /** Inclusive upper bound. */
+    to: number;
+    /** Exact patch exceptions allowed in this reserved range. */
+    allowed: PatchPolicyReservedAllowedPatch[];
+}
+/**
+ * Optional project-specific patch queue policy. When absent, FireForge keeps
+ * its historical broad category + numeric ordering behaviour.
+ */
+export interface PatchPolicyConfig {
+    /** Regex with named captures: order, category, slug. */
+    filenamePattern?: string;
+    /** Require non-empty patch descriptions. Default false. */
+    requireDescription?: boolean;
+    /** Allow numeric gaps within configured category ranges. Default true. */
+    allowGaps?: boolean;
+    /** How mutating commands handle policy violations. Default "error". */
+    mutationMode?: PatchPolicyMutationMode;
+    /** Category-owned numeric ranges. */
+    ranges: PatchPolicyRange[];
+    /** Reserved exception ranges. */
+    reservedRanges?: PatchPolicyReservedRange[];
+}
 /**
  * Main fireforge.json configuration schema.
  */
@@ -46,6 +95,8 @@ export interface FireForgeConfig {
     wire?: WireConfig;
     /** Patch lint configuration */
     patchLint?: PatchLintConfig;
+    /** Optional project-specific patch queue policy. */
+    patchPolicy?: PatchPolicyConfig;
     /** Typecheck command configuration (CI-grade, whole-project) */
     typecheck?: TypecheckConfig;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.21.1",
+  "version": "0.21.3",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",