@hominis/fireforge 0.30.0 → 0.31.0

package/dist/src/commands/lint-per-patch.js

@@ -2,7 +2,7 @@
 import { join } from 'node:path';
 import { loadConfig } from '../core/config.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
-import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/lint-cache.js';
+import { buildPerPatchLintCacheKey, getCachedPerPatchLintIssues, getPerPatchLintCacheHeadSha, loadPerPatchLintCache, savePerPatchLintCache, setCachedPerPatchLintIssues, } from '../core/lint-cache.js';
 import { buildPatchQueueContext, lintExportedPatch, lintPatchQueue, resolvePatchSizeTier, } from '../core/patch-lint.js';
 import { loadPatchesManifest } from '../core/patch-manifest.js';
 import { evaluatePatchPolicy } from '../core/patch-policy.js';
@@ -13,91 +13,75 @@ function buildPerPatchMaxWarningsMessage(count, maxWarnings, linted) {
     return (`Patch lint found ${count} warning(s) across ${linted} patch(es), exceeding --max-warnings ${maxWarnings}.` +
         ' If this is a release gate, run with --per-patch to identify the owning patch. For intentional staged imports, use patch staged-dependency; for ownership repairs, preview patch move-files, patch reorder --dry-run, or re-export --files --dry-run; add scoped lintIgnore only after review.');
 }
+function emitTierNotice(filename, files, tier) {
+    const decision = resolvePatchSizeTier(files, tier);
+    if (decision.tier !== 'branding')
+        return;
+    info(decision.source === 'explicit'
+        ? `${filename}: branding threshold tier applied via patches.json \`tier: "branding"\` opt-in.`
+        : `${filename}: branding threshold tier applied (all files under browser/branding/ plus registration siblings).`);
+}
 /**
- * Lints each patch in the queue as its own isolated diff, honouring
- * per-patch `lintIgnore` entries. Cross-patch rules still run once over
- * the whole queue so queue-level findings are not lost by the rescoping.
+ * Lints one queued patch against its own isolated diff, reusing the cache
+ * entry when the cache key matches. Pushes the patch's issues (prefixed
+ * with its filename) onto `ctx.issues`. Returns whether the patch was
+ * skipped (no files present / empty diff), served from cache, or linted
+ * fresh — and whether a fresh result was written to the cache.
  */
-export async function lintPerPatch(projectRoot, paths, options = {}) {
-    const manifest = await loadPatchesManifest(paths.patches);
-    if (!manifest || manifest.patches.length === 0) {
-        info('No patches in manifest — nothing to lint per-patch.');
-        outro('Nothing to lint');
-        return;
+async function lintQueuedPatch(patch, lintCtx) {
+    const { projectRoot, paths, config, ctx, cache, engineHeadSha, issues } = lintCtx;
+    const existing = [];
+    for (const f of patch.filesAffected) {
+        if (await pathExists(join(paths.engine, f)))
+            existing.push(f);
     }
-    const config = await loadConfig(projectRoot);
-    const ctx = await buildPatchQueueContext(paths.patches);
-    const cache = options.noCache === true ? undefined : await loadPerPatchLintCache(projectRoot);
-    let cacheDirty = false;
-    let reusedCacheEntries = 0;
-    const issues = [];
-    for (const issue of evaluatePatchPolicy(config, manifest)) {
-        issues.push({
-            file: issue.filename,
-            check: `patch-policy/${issue.code}`,
-            message: issue.message,
-            severity: issue.severity,
-        });
+    if (existing.length === 0) {
+        return { status: 'skipped', wroteCache: false };
     }
-    let linted = 0;
-    let skipped = 0;
-    for (const patch of manifest.patches) {
-        const existing = [];
-        for (const f of patch.filesAffected) {
-            if (await pathExists(join(paths.engine, f)))
-                existing.push(f);
-        }
-        if (existing.length === 0) {
-            skipped++;
-            continue;
-        }
-        const diff = await getDiffForFilesAgainstHead(paths.engine, existing);
-        if (!diff.trim()) {
-            skipped++;
-            continue;
-        }
-        const ignore = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
-        const decision = resolvePatchSizeTier(existing, patch.tier);
-        if (decision.tier === 'branding') {
-            info(decision.source === 'explicit'
-                ? `${patch.filename}: branding threshold tier applied via patches.json \`tier: "branding"\` opt-in.`
-                : `${patch.filename}: branding threshold tier applied (all files under browser/branding/ plus registration siblings).`);
-        }
-        let patchIssues;
-        if (cache) {
-            const cacheKey = await buildPerPatchLintCacheKey({
-                projectRoot,
-                engineDir: paths.engine,
-                patchesDir: paths.patches,
-                patch,
-                existingFiles: existing,
-                config,
-                queueContext: ctx,
-            });
-            patchIssues = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey);
-            if (patchIssues) {
-                reusedCacheEntries++;
-            }
-            else {
-                patchIssues = await lintExportedPatch(paths.engine, existing, diff, config, ctx, ignore, patch.tier);
-                setCachedPerPatchLintIssues(cache, patch.filename, cacheKey, patchIssues);
-                cacheDirty = true;
+    const ignore = patch.lintIgnore?.length ? new Set(patch.lintIgnore) : undefined;
+    let cacheKey;
+    if (cache) {
+        cacheKey = await buildPerPatchLintCacheKey({
+            projectRoot,
+            engineDir: paths.engine,
+            patchesDir: paths.patches,
+            patch,
+            existingFiles: existing,
+            config,
+            queueContext: ctx,
+            ...(engineHeadSha === undefined ? {} : { engineHeadSha }),
+        });
+        const cached = getCachedPerPatchLintIssues(cache, patch.filename, cacheKey);
+        if (cached) {
+            emitTierNotice(patch.filename, existing, patch.tier);
+            for (const issue of cached) {
+                issues.push({ ...issue, file: `${patch.filename} :: ${issue.file}` });
             }
+            return { status: 'cached', wroteCache: false };
         }
-        else {
-            patchIssues = await lintExportedPatch(paths.engine, existing, diff, config, ctx, ignore, patch.tier);
-        }
-        for (const issue of patchIssues) {
-            issues.push({ ...issue, file: `${patch.filename} :: ${issue.file}` });
-        }
-        linted++;
     }
-    issues.push(...lintPatchQueue(ctx));
-    if (cache && cacheDirty)
-        await savePerPatchLintCache(projectRoot, cache);
-    if (reusedCacheEntries > 0) {
-        info(`Reused lint cache for ${reusedCacheEntries} patch${reusedCacheEntries === 1 ? '' : 'es'}.`);
+    const diff = await getDiffForFilesAgainstHead(paths.engine, existing);
+    if (!diff.trim()) {
+        return { status: 'skipped', wroteCache: false };
+    }
+    emitTierNotice(patch.filename, existing, patch.tier);
+    const patchIssues = await lintExportedPatch(paths.engine, existing, diff, config, ctx, ignore, patch.tier);
+    let wroteCache = false;
+    if (cache && cacheKey) {
+        setCachedPerPatchLintIssues(cache, patch.filename, cacheKey, patchIssues);
+        wroteCache = true;
     }
+    for (const issue of patchIssues) {
+        issues.push({ ...issue, file: `${patch.filename} :: ${issue.file}` });
+    }
+    return { status: 'linted', wroteCache };
+}
+/**
+ * Reporting + exit phase of per-patch lint: renders every issue row,
+ * prints the per-patch summary, and applies the failure criteria
+ * (errors, `--max-warnings`) by throwing GeneralError.
+ */
+function reportPerPatchOutcome(issues, linted, skipped, options) {
     if (issues.length === 0) {
         if (linted === 0 && skipped > 0) {
             info(`No patches in the queue have been applied to engine/. Run "fireforge import" first if you want lint findings against the staged hunks; otherwise this is expected.`);
@@ -137,4 +121,61 @@ export async function lintPerPatch(projectRoot, paths, options = {}) {
         outro('Lint passed');
     }
 }
+/**
+ * Lints each patch in the queue as its own isolated diff, honouring
+ * per-patch `lintIgnore` entries. Cross-patch rules still run once over
+ * the whole queue so queue-level findings are not lost by the rescoping.
+ */
+export async function lintPerPatch(projectRoot, paths, options = {}) {
+    const manifest = await loadPatchesManifest(paths.patches);
+    if (!manifest || manifest.patches.length === 0) {
+        info('No patches in manifest — nothing to lint per-patch.');
+        outro('Nothing to lint');
+        return;
+    }
+    const config = await loadConfig(projectRoot);
+    const ctx = await buildPatchQueueContext(paths.patches);
+    const cache = options.noCache === true ? undefined : await loadPerPatchLintCache(projectRoot);
+    const engineHeadSha = cache ? await getPerPatchLintCacheHeadSha(paths.engine) : undefined;
+    const issues = [];
+    for (const issue of evaluatePatchPolicy(config, manifest)) {
+        issues.push({
+            file: issue.filename,
+            check: `patch-policy/${issue.code}`,
+            message: issue.message,
+            severity: issue.severity,
+        });
+    }
+    let linted = 0;
+    let skipped = 0;
+    let cacheDirty = false;
+    let reusedCacheEntries = 0;
+    for (const patch of manifest.patches) {
+        const result = await lintQueuedPatch(patch, {
+            projectRoot,
+            paths,
+            config,
+            ctx,
+            cache,
+            engineHeadSha,
+            issues,
+        });
+        if (result.status === 'skipped') {
+            skipped++;
+            continue;
+        }
+        if (result.status === 'cached')
+            reusedCacheEntries++;
+        if (result.wroteCache)
+            cacheDirty = true;
+        linted++;
+    }
+    issues.push(...lintPatchQueue(ctx));
+    if (cache && cacheDirty)
+        await savePerPatchLintCache(projectRoot, cache);
+    if (reusedCacheEntries > 0) {
+        info(`Reused lint cache for ${reusedCacheEntries} patch${reusedCacheEntries === 1 ? '' : 'es'}.`);
+    }
+    reportPerPatchOutcome(issues, linted, skipped, options);
+}
 //# sourceMappingURL=lint-per-patch.js.map

package/dist/src/commands/lint.d.ts

@@ -1,63 +1,6 @@
 import { Command } from 'commander';
 import type { CommandContext } from '../types/cli.js';
-import type { PatchLintIssue } from '../types/commands/index.js';
-/** Options controlling how the lint command filters and tags its output. */
-export interface LintCommandOptions {
-    /**
-     * When set, tag each issue as `introduced` or `cumulative` based on
-     * whether its file changed since this git revision (e.g. `HEAD`, a
-     * branch name, or a SHA). Issues are not filtered — the full set still
-     * prints — but a diff-scoped summary makes it trivial to see which
-     * errors the current task introduced.
-     */
-    since?: string;
-    /**
-     * When set together with {@link since}, scope the exit code to issues
-     * tagged `introduced`. Cumulative pre-existing errors still print (so
-     * the operator can still see the full queue state) but do not fail
-     * lint. Motivating case: a branch whose diff is clean but whose repo
-     * already carries unrelated `raw-color` / license-header errors from
-     * older patches. Without this flag, CI treats the clean branch as
-     * failing; with it, a branch "breaks the build" only when its own diff
-     * introduced a new error.
-     *
-     * Requires {@link since}: without a revision to diff against there is
-     * no distinction between introduced and cumulative, so the flag is
-     * rejected up-front rather than silently ignored.
-     */
-    onlyIntroduced?: boolean;
-    /**
-     * Lint each patch in the queue as its own isolated diff, rather than
-     * the aggregate `git diff HEAD` across all applied patches.
-     *
-     * Motivating case: running `fireforge lint` (no args) on a repo where
-     * `fireforge import` or `fireforge rebase` has just applied the full
-     * patch queue produces an aggregate diff (every patch's changes
-     * summed). The patch-size advisory rules (`large-patch-lines`,
-     * `large-patch-files`) then fire against the sum — e.g. "Patch is
-     * 37529 lines" on a queue of 22 individually-fine patches — which
-     * reads as a task-specific regression when it is really an artefact
-     * of the aggregation. `--per-patch` rescopes the diff to each patch's
-     * own `filesAffected`, honours the patch's own `lintIgnore`, and runs
-     * the cross-patch rules once over the whole queue so queue-level
-     * findings (duplicate creations, forward imports) still surface.
-     *
-     * Mutually exclusive with passing explicit file paths — the two
-     * scope contracts are different.
-     */
-    perPatch?: boolean;
-    /**
-     * Maximum warning count tolerated before lint exits non-zero. Mirrors
-     * ESLint's `--max-warnings` shape for release gates that want advisory
-     * findings to become blocking without changing default CLI behavior.
-     */
-    maxWarnings?: number;
-    /**
-     * Bypass per-patch lint cache reads and writes. Accepted in aggregate mode
-     * for CLI consistency, but only `--per-patch` currently uses the cache.
-     */
-    noCache?: boolean;
-}
+import type { LintCommandOptions, PatchLintIssue } from '../types/commands/index.js';
 /**
  * Result of {@link applyAggregateLintIgnoreSuppression}.
  */

package/dist/src/commands/lint.js

@@ -215,13 +215,12 @@ export function applyAggregateLintIgnoreSuppression(issues, ctx) {
     return { issues: filtered, dropped: issues.length - filtered.length };
 }
 /**
- * Runs the lint command to check engine changes against patch quality rules.
- * @param projectRoot - Root directory of the project
- * @param files - Optional file/directory paths to lint (relative to engine/)
- * @param options - Additional lint options such as `--since` diff-scoping
+ * Up-front flag validation for `lintCommand`: rejects `--only-introduced`
+ * without `--since`, non-integer `--max-warnings`, and `--per-patch`
+ * combined with explicit file paths — each a misconfiguration that should
+ * fail loud rather than silently narrow the result.
  */
-export async function lintCommand(projectRoot, files, options = {}) {
-    intro('FireForge Lint');
+function validateLintFlags(options, files) {
     // `--only-introduced` scopes the exit code to `--since`-tagged issues, so
     // without a revision to anchor the diff there is no "introduced" subset
     // to scope to — reject the combination up-front so a misconfigured CI
@@ -242,78 +241,16 @@ export async function lintCommand(projectRoot, files, options = {}) {
     if (options.perPatch && files.length > 0) {
         throw new GeneralError('--per-patch cannot be combined with explicit file paths. Pass either --per-patch or a file list, not both.');
     }
-    const paths = getProjectPaths(projectRoot);
-    if (!(await pathExists(paths.engine))) {
-        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
-    }
-    if (!(await isGitRepository(paths.engine))) {
-        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
-    }
-    if (options.perPatch) {
-        await lintPerPatch(projectRoot, paths, options);
-        return;
-    }
-    // Load the config before resolving the diff so we can pass
-    // `binaryName` into the aggregate-mode branding exclusion in
-    // `resolveLintDiff`. The config was previously loaded only after
-    // the diff was resolved; hoisting it is cheap and keeps the two
-    // call sites close together.
-    const config = await loadConfig(projectRoot);
-    // Pull the Furnace-managed prefix set up-front so aggregate lint can
-    // mirror the branding exclusion for Furnace material — without it,
-    // preview-generated stories under `browser/components/storybook/
-    // stories/furnace/` show up as license-header errors on every
-    // post-preview lint run.
-    const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
-    const diff = await resolveLintDiff(paths.engine, files, config.binaryName, furnacePrefixes);
-    if (diff === null)
-        return;
-    const filesAffected = extractAffectedFiles(diff);
-    // Build patch queue context once so it can be shared between the
-    // per-patch ownership resolver and the cross-patch rules.
-    let ctx;
-    if (await pathExists(paths.patches)) {
-        ctx = await buildPatchQueueContext(paths.patches);
-    }
-    let issues = [
-        ...(await lintExportedPatch(paths.engine, filesAffected, diff, config, ctx)),
-    ];
-    // Cross-patch rules operate over the whole queue, so run them whenever a
-    // patches directory exists — they surface duplicate /dev/null creations
-    // and forward-import chains that the per-patch orchestrator cannot see.
-    if (ctx) {
-        issues.push(...lintPatchQueue(ctx));
-    }
-    // Honor per-patch `lintIgnore` in aggregate mode by attributing each
-    // issue's file to its owning patches via the manifest's
-    // `filesAffected`. Per-patch mode threads `lintIgnore` directly into
-    // `lintExportedPatch`; aggregate mode previously had no patch-level
-    // scope to consult, so a check an operator had explicitly waived in
-    // `patches.json` re-surfaced on every `--since` run (CI default).
-    if (ctx) {
-        const result = applyAggregateLintIgnoreSuppression(issues, ctx);
-        issues = result.issues;
-        if (result.dropped > 0) {
-            info(`Suppressed ${result.dropped} issue(s) via per-patch lintIgnore (aggregate mode).`);
-        }
-    }
-    // When a queue manifest exists AND files were NOT scoped explicitly, the
-    // "diff" we just linted is every applied patch summed together. Patch-
-    // size rules (`large-patch-lines`, `large-patch-files`) then fire against
-    // the aggregate rather than any individual patch, producing counts like
-    // "Patch is 37529 lines" that read as a task-specific regression but are
-    // really an artefact of aggregation. Surface a one-line note pointing at
-    // `--per-patch` so the operator knows the per-patch scope exists before
-    // they read the error message as "my queue is broken".
-    //
-    // In aggregate mode over a multi-patch queue we also downgrade the two
-    // size rules from `error` to `warning`. Before this downgrade, a
-    // fresh-imported patch stack of 20+ patches hard-failed `fireforge lint`
-    // on lines-per-aggregate counts that are mathematically impossible to
-    // satisfy without splitting patches that were already split — the
-    // actionable unit is the individual patch, and `--per-patch` is the
-    // mode that matches. Per-patch mode keeps errors as errors (see
-    // `lintPerPatch` below).
+}
+/**
+ * Aggregate-mode patch-size softening: when the linted diff is every
+ * applied patch summed (no explicit file scope, multi-patch queue), the
+ * `large-patch-lines` / `large-patch-files` counts are an artefact of
+ * aggregation rather than a property of any one patch. Surface the
+ * `--per-patch` hint and downgrade those two rules to warnings; per-patch
+ * mode keeps them as errors.
+ */
+function downgradeAggregateSizeRules(issues, files, ctx) {
     const aggregateHintApplicable = files.length === 0 && ctx !== undefined && ctx.entries.length > 1;
     if (aggregateHintApplicable &&
         issues.some((i) => i.check === 'large-patch-lines' || i.check === 'large-patch-files')) {
@@ -325,18 +262,21 @@ export async function lintCommand(projectRoot, files, options = {}) {
             }
         }
     }
-    if (issues.length === 0) {
-        success('No lint issues found.');
-        outro('Lint passed');
-        return;
-    }
+}
+/**
+ * Reporting + exit phase of `lintCommand`: tags issues against `--since`,
+ * renders every notice/warning/error row, prints the summary, and applies
+ * the failure criteria (`--only-introduced` scoping, `--max-warnings`)
+ * by throwing GeneralError. Issues must be non-empty.
+ */
+async function reportLintOutcome(engineDir, issues, options) {
     // Diff-scoping: tag each issue as introduced-in-current-task vs
     // cumulative-pre-existing-drift. Never filters — full set still prints
     // and exit code semantics are unchanged — but the per-line prefix and
     // summary make triage trivial on a large patch series.
     const sinceActive = Boolean(options.since);
     if (options.since) {
-        const diffFiles = await collectDiffFilePaths(paths.engine, options.since);
+        const diffFiles = await collectDiffFilePaths(engineDir, options.since);
         tagLintIssues(issues, diffFiles);
     }
     const errors = issues.filter((i) => i.severity === 'error');
@@ -399,6 +339,78 @@ export async function lintCommand(projectRoot, files, options = {}) {
         outro('Lint passed');
     }
 }
+/**
+ * Runs the lint command to check engine changes against patch quality rules.
+ * @param projectRoot - Root directory of the project
+ * @param files - Optional file/directory paths to lint (relative to engine/)
+ * @param options - Additional lint options such as `--since` diff-scoping
+ */
+export async function lintCommand(projectRoot, files, options = {}) {
+    intro('FireForge Lint');
+    validateLintFlags(options, files);
+    const paths = getProjectPaths(projectRoot);
+    if (!(await pathExists(paths.engine))) {
+        throw new GeneralError('Firefox source not found. Run "fireforge download" first.');
+    }
+    if (!(await isGitRepository(paths.engine))) {
+        throw new GeneralError('Engine directory is not a git repository. Run "fireforge download" to initialize.');
+    }
+    if (options.perPatch) {
+        await lintPerPatch(projectRoot, paths, options);
+        return;
+    }
+    // Load the config before resolving the diff so we can pass
+    // `binaryName` into the aggregate-mode branding exclusion in
+    // `resolveLintDiff`. The config was previously loaded only after
+    // the diff was resolved; hoisting it is cheap and keeps the two
+    // call sites close together.
+    const config = await loadConfig(projectRoot);
+    // Pull the Furnace-managed prefix set up-front so aggregate lint can
+    // mirror the branding exclusion for Furnace material — without it,
+    // preview-generated stories under `browser/components/storybook/
+    // stories/furnace/` show up as license-header errors on every
+    // post-preview lint run.
+    const furnacePrefixes = await collectFurnaceManagedPrefixes(projectRoot);
+    const diff = await resolveLintDiff(paths.engine, files, config.binaryName, furnacePrefixes);
+    if (diff === null)
+        return;
+    const filesAffected = extractAffectedFiles(diff);
+    // Build patch queue context once so it can be shared between the
+    // per-patch ownership resolver and the cross-patch rules.
+    let ctx;
+    if (await pathExists(paths.patches)) {
+        ctx = await buildPatchQueueContext(paths.patches);
+    }
+    let issues = [
+        ...(await lintExportedPatch(paths.engine, filesAffected, diff, config, ctx)),
+    ];
+    // Cross-patch rules operate over the whole queue, so run them whenever a
+    // patches directory exists — they surface duplicate /dev/null creations
+    // and forward-import chains that the per-patch orchestrator cannot see.
+    if (ctx) {
+        issues.push(...lintPatchQueue(ctx));
+    }
+    // Honor per-patch `lintIgnore` in aggregate mode by attributing each
+    // issue's file to its owning patches via the manifest's
+    // `filesAffected`. Per-patch mode threads `lintIgnore` directly into
+    // `lintExportedPatch`; aggregate mode previously had no patch-level
+    // scope to consult, so a check an operator had explicitly waived in
+    // `patches.json` re-surfaced on every `--since` run (CI default).
+    if (ctx) {
+        const result = applyAggregateLintIgnoreSuppression(issues, ctx);
+        issues = result.issues;
+        if (result.dropped > 0) {
+            info(`Suppressed ${result.dropped} issue(s) via per-patch lintIgnore (aggregate mode).`);
+        }
+    }
+    downgradeAggregateSizeRules(issues, files, ctx);
+    if (issues.length === 0) {
+        success('No lint issues found.');
+        outro('Lint passed');
+        return;
+    }
+    await reportLintOutcome(paths.engine, issues, options);
+}
 /** Registers the lint command on the CLI program. */
 export function registerLint(program, { getProjectRoot, withErrorHandling }) {
     const lint = program

package/dist/src/commands/patch/compact.d.ts

@@ -2,8 +2,11 @@
  * `fireforge patch compact` — closes ordinal gaps in the patch queue.
  *
  * After deletes or splits, patch ordinals may have gaps (e.g. 1, 3, 7).
- * This command renumbers all patches to sequential ordinals (1, 2, 3, …)
- * in a single atomic operation, preserving relative order.
+ * This command renumbers patches to close those gaps in a single atomic
+ * operation, preserving relative order. Without a patch policy the whole
+ * queue is renumbered from 1; with `patchPolicy.ranges` configured the
+ * compaction is range-aware (each category range compacts independently,
+ * reserved ranges and out-of-range strays are left untouched).
  */
 import { Command } from 'commander';
 import type { CommandContext } from '../../types/cli.js';