@hominis/fireforge 0.12.0 → 0.13.0

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # Changelog
 
+## 0.13.0
+
+### Setup
+
+- **`fireforge bootstrap` now runs targeted post-bootstrap checks** instead of pattern-matching output text. When `mach bootstrap` exits successfully but sub-downloads fail (e.g. HTTP 403 from Apple's CDN), FireForge validates actual system state — checking whether a macOS SDK is available via Xcode — and reports actionable results using the same `✓`/`!`/`✗` severity rendering as `fireforge doctor`. Non-critical issues (SDK download failed but Xcode provides one) are reported as warnings rather than alarming "did not complete successfully" errors.
+
+### Lint fixes
+
+- **`file-too-large` now uses tiered severity thresholds.** The old single 650-line warning is replaced with a three-tier system (notice / warning / error) that distinguishes general files from test files. General files: 500–749 lines notice, 750–899 warning, 900+ error. Test files (paths containing `/test/`, or filenames matching `browser_*.js`, `test_*.js`, `xpcshell_*.js`): 1200–1399 notice, 1400–1599 warning, 1600+ error. Messages include the applicable thresholds so users know where they stand. The new `notice` severity is displayed but does not count toward warning or error totals and does not block export.
+- **`observer-topic-naming` no longer matches across newlines.** The regex that extracts topic strings from `notifyObservers`/`addObserver`/`removeObserver` calls now anchors to a single line, preventing false positives when the call spans multiple lines and an unrelated string literal appears later.
+- **`raw-color-value` now supports a file allowlist and inline suppression.** New `patchLint.rawColorAllowlist` config array in `fireforge.json` exempts file paths (exact or basename match) from the raw-color check — intended for design token files that must contain raw color values. Individual declarations can also be suppressed with an inline `/* fireforge-ignore: raw-color-value */` comment.
+- **`large-patch-lines` now uses tiered severity thresholds.** The old single >300-line warning is replaced with a three-tier system matching the `file-too-large` pattern. General patches: 800+ lines notice, 1500+ warning, 3000+ error. Test-only patches (all files match test patterns): 1500+ notice, 3000+ warning, 6000+ error. The previous threshold was too restrictive relative to file LOC limits — creating a single new file at the `file-too-large` notice tier (500 LOC) already exceeded it. Messages now include the applicable soft and hard limits.
+
+### General Improvements
+
+- **Minor Refactor**
+
 ## 0.12.0
 
 ### JSDoc validation (breaking)

package/README.md

@@ -8,7 +8,7 @@
 
 **Build and maintain your own Firefox-based browser with a patch-first workflow**
 
-FireForge gives you a toolkit for forking Firefox: download a specific ESR release, manage your customisations as a series of patches, survive version upgrades with semi-automated rebase, wire custom code into Mozilla's startup paths, and build the result. It also ships **Furnace**, a component system for creating and overriding Firefox custom elements under `toolkit/content/widgets`.
+FireForge gives you a toolkit for forking Firefox: download a specific ESR release, manage your customisations as a series of patches, survive version upgrades with semi-automated rebase, wire custom code into Mozilla's startup paths and build the result. It also ships **Furnace**, a component system for creating and overriding Firefox custom elements under `toolkit/content/widgets`.
 
 Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon](https://github.com/dothq/melon).
 
@@ -18,7 +18,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 
 - **Semi-automated ESR rebase** `fireforge rebase` replays your patch stack onto new Firefox source with escalating fuzz matching. When a patch fails, you fix it manually and `--continue`. The full stack gets re-exported with updated version stamps.
 
-- **Wiring and registration** `fireforge wire` and `fireforge register` inject your code into Mozilla's startup paths, build manifests, and JAR files with a single command. The injection is AST-based (via Acorn), so it survives formatting changes applied between versions.
+- **Wiring and registration** `fireforge wire` and `fireforge register` inject your code into Mozilla's startup paths, build manifests and JAR files with a single command. The injection is AST-based (via Acorn), so it survives formatting changes applied between versions.
 
 - **Furnace component system** Override existing Firefox custom elements or create new ones under `toolkit/content/widgets` (CSS-only restyles, full behavioural forks, or entirely new widgets).
 
@@ -26,7 +26,7 @@ Inspired by [fern.js](https://github.com/ghostery/user-agent-desktop) and [Melon
 
 - **Quality checks** `fireforge lint` catches fork-specific issues (raw colours, missing licence headers, relative imports, large patches, cross-patch ordering problems) before you export. `fireforge verify` runs a read-only integrity check over the whole patch queue. `fireforge doctor` diagnoses project health including Furnace component validation.
 
-- **Built and validated against real Firefox code** Developed by editing a real Firefox ESR codebase, learning from existing patch tools, observing the breakages and edge cases that surfaced, and turning those findings into a realistic test suite. In-repo tests are thus grounded in actual development scenarios. Yes, we mock quite a bit, but when building a tool that modifies a separate code base, I think it's a solid compromise for the time being. Full end-to-end runs are currently run locally, as they require about 30 GB of disk and significant compute for multiple full builds. Full end-to-end via Github Actions will be added soonishlyTM.
+- **Built and validated against real Firefox code** Developed by editing a real Firefox ESR codebase, learning from existing patch tools, observing the breakages and edge cases that surfaced and turning those findings into a realistic test suite. In-repo tests are thus grounded in actual development scenarios. Yes, we mock quite a bit, but when building a tool that modifies a separate code base, I think it's a solid compromise for the time being. Full end-to-end runs are currently run locally, as they require about 30 GB of disk and significant compute for multiple full builds. Full end-to-end via Github Actions will be added soonishlyTM.
 
 ## Quick Start
 
@@ -52,7 +52,7 @@ npx fireforge build               # build the browser
 npx fireforge run                 # launch it
 ```
 
-Your project now has `fireforge.json`, an `engine/` directory with Firefox source, and a `patches/` directory with an empty `patches.json` manifest ready for your first customisation.
+Your project now has `fireforge.json`, an `engine/` directory with Firefox source and a `patches/` directory with an empty `patches.json` manifest ready for your first customisation.
 
 ### Workflow Overview
 
@@ -71,14 +71,14 @@ npx fireforge export browser/base/content/browser.js \
 npx fireforge reset --yes
 npx fireforge import              # --dry-run to preview without applying
 
-# 5. When Firefox releases a new ESR, update fireforge.json, re-download, and rebase
+# 5. When Firefox releases a new ESR, update fireforge.json, re-download and rebase
 npx fireforge download --force
 npx fireforge rebase
 ```
 
 ## Patch Workflow
 
-Patches live in `patches/`, applied by numeric filename prefix, and tracked in `patches/patches.json`:
+Patches live in `patches/`, applied by numeric filename prefix and tracked in `patches/patches.json`:
 
 ```
 patches/
@@ -186,30 +186,30 @@ If the manifest drifts after an interrupted export or manual edits, `fireforge i
 <details>
 <summary>Patch lint checks</summary>
 
-`fireforge lint` runs automatically during export, export-all, and re-export. Use `--skip-lint` to downgrade errors to warnings. Errors block the export; warnings are printed but do not block.
-
-| Check                          | Scope                                 | Severity |
-| ------------------------------ | ------------------------------------- | -------- |
-| `missing-license-header`       | New files (JS/CSS/FTL)                | error    |
-| `relative-import`              | JS/MJS files                          | error    |
-| `token-prefix-violation`       | CSS files (with furnace)              | error    |
-| `raw-color-value`              | Introduced CSS color values           | error    |
-| `duplicate-new-file-creation`  | Same path created by multiple patches | error    |
-| `forward-import`               | Patch imports from a later-patch file | error    |
-| `missing-jsdoc`                | Exports in patch-owned `.sys.mjs`     | error    |
-| `jsdoc-param-mismatch`         | Exports in patch-owned `.sys.mjs`     | error    |
-| `jsdoc-missing-returns`        | Exports in patch-owned `.sys.mjs`     | error    |
-| `checkjs-type-error`           | Patch-owned `.sys.mjs` (opt-in)       | error    |
-| `missing-modification-comment` | Modified upstream JS/MJS              | warning  |
-| `modified-file-missing-header` | Modified upstream files (JS/CSS/FTL)  | warning  |
-| `file-too-large`               | New files >650 lines                  | warning  |
-| `observer-topic-naming`        | Observer topics with binaryName       | warning  |
-| `large-patch-files`            | Patches affecting >5 files            | warning  |
-| `large-patch-lines`            | Patches >300 lines                    | warning  |
+`fireforge lint` runs automatically during export, export-all and re-export. Use `--skip-lint` to downgrade errors to warnings. Errors block the export; warnings are printed but do not block.
+
+| Check                          | Scope                                                                 | Severity                 |
+| ------------------------------ | --------------------------------------------------------------------- | ------------------------ |
+| `missing-license-header`       | New files (JS/CSS/FTL)                                                | error                    |
+| `relative-import`              | JS/MJS files                                                          | error                    |
+| `token-prefix-violation`       | CSS files (with furnace)                                              | error                    |
+| `raw-color-value`              | Introduced CSS color values                                           | error                    |
+| `duplicate-new-file-creation`  | Same path created by multiple patches                                 | error                    |
+| `forward-import`               | Patch imports from a later-patch file                                 | error                    |
+| `missing-jsdoc`                | Exports in patch-owned `.sys.mjs`                                     | error                    |
+| `jsdoc-param-mismatch`         | Exports in patch-owned `.sys.mjs`                                     | error                    |
+| `jsdoc-missing-returns`        | Exports in patch-owned `.sys.mjs`                                     | error                    |
+| `checkjs-type-error`           | Patch-owned `.sys.mjs` (opt-in)                                       | error                    |
+| `missing-modification-comment` | Modified upstream JS/MJS                                              | warning                  |
+| `modified-file-missing-header` | Modified upstream files (JS/CSS/FTL)                                  | warning                  |
+| `file-too-large`               | New files (tiered: 500/750/900 general, 1200/1400/1600 test)          | notice / warning / error |
+| `observer-topic-naming`        | Observer topics with binaryName                                       | warning                  |
+| `large-patch-files`            | Patches affecting >5 files                                            | warning                  |
+| `large-patch-lines`            | Patch line count (tiered: 800/1500/3000 general, 1500/3000/6000 test) | notice / warning / error |
 
 **JSDoc validation** uses AST-based analysis (Acorn) to validate exported APIs in patch-owned `.sys.mjs` files. A file is "patch-owned" if it was newly created by the current diff or by an existing patch in the queue. Functions must document every `@param` (names must match) and include `@returns` when the function returns a value. Exported constants and classes require a JSDoc block.
 
-**Optional `checkJs` pass.** Enable TypeScript-based type checking for patch-owned `.sys.mjs` files by adding `"patchLint": { "checkJs": true }` to `fireforge.json`. This uses the TypeScript compiler API with `allowJs + checkJs + noEmit`, scoped only to patch-owned files. Firefox globals (`Services`, `ChromeUtils`, `lazy`, etc.) are shimmed automatically. Module-resolution errors from Firefox's `resource://` and `chrome://` URL schemes are suppressed since TypeScript cannot follow these — the pass focuses on type errors within the patch-owned code itself (mismatched JSDoc types, wrong argument counts, unreachable code, etc.).
+**Optional `checkJs` pass.** Enable a TypeScript-esque bastardization of type checking for patch-owned `.sys.mjs` files by adding `"patchLint": { "checkJs": true }` to `fireforge.json`. This uses the TypeScript compiler API with `allowJs + checkJs + noEmit`, scoped only to patch-owned files. Firefox globals (`Services`, `ChromeUtils`, `lazy`, etc.) are shimmed automatically. Module-resolution errors from Firefox's `resource://` and `chrome://` URL schemes are suppressed since TypeScript cannot follow these. This pass solely focuses on type errors within the patch-owned code itself (mismatched JSDoc types, wrong argument counts, unreachable code, etc.).
 
 The two cross-patch rules (`duplicate-new-file-creation` and `forward-import`) run over the whole patch queue rather than a single diff, catching ordering issues that only surface during `import`. Forward-import detection compares leaf filenames, so a false positive is theoretically possible when two patches create files with the same basename in different directories. Suppress with an inline `// fireforge-ignore: forward-import` comment on or above the import line. This is currently the only lint rule that supports inline suppression.
 
@@ -217,7 +217,7 @@ The two cross-patch rules (`duplicate-new-file-creation` and `forward-import`) r
 
 ### Repairing a broken patch queue
 
-When a patch queue drifts — overlapping new-file creations, forward imports, manifest desync — start with diagnosis:
+When a patch queue drifts, e.g. due to overlapping new-file creations, forward imports, manifest desync, etc. start with diagnosing the root cause:
 
 ```bash
 fireforge verify                    # fsck: manifest + cross-patch lint
@@ -237,7 +237,7 @@ Then fix with the appropriate primitive:
 | Manifest references a missing patch file       | `fireforge doctor --repair-patches-manifest`                          |
 | Unmanaged changes you want to discard          | `fireforge discard <file>` or `fireforge reset`                       |
 
-Every destructive command defaults to an interactive confirmation with a change summary. `--dry-run` previews without writing; `--yes` skips the prompt for CI; `--force-unsafe` bypasses structural refusals when you have context the linter cannot see. Do not hand-edit `patches.json` — it is owned by FireForge.
+Every destructive command defaults to an interactive confirmation with a change summary. `--dry-run` previews without writing; `--yes` skips the prompt for CI; `--force-unsafe` bypasses structural refusals when you have context the linter cannot see. Do not hand-edit `patches.json` as the file is owned by FireForge.
 
 ## Wiring Custom Code
 
@@ -278,7 +278,7 @@ fireforge register browser/modules/mybrowser/MyStore.sys.mjs
 
 ## Furnace (UI Component System)
 
-Furnace manages Firefox custom elements (`MozLitElement`) under `toolkit/content/widgets`. You can override existing components or create new ones. Changes feed into the same patch workflow as everything else — Furnace is not a separate persistence layer.
+Furnace manages Firefox custom elements (`MozLitElement`) under `toolkit/content/widgets`. You can override existing components or create new ones. Changes feed into the same patch workflow as everything else, Furnace is not a separate persistence layer.
 
 There are three component types:
 
@@ -297,11 +297,11 @@ fireforge furnace status                           # workspace vs engine drift
 fireforge furnace diff moz-button                  # unified diff against baseline
 ```
 
-`furnace deploy` validates components before applying — errors block, warnings are advisory. `fireforge build` and `fireforge test --build` run apply automatically. Use `fireforge doctor --repair-furnace` if the engine gets out of sync.
+`furnace deploy` validates components before applying. As always, errors block, warnings are advisory. `fireforge build` and `fireforge test --build` run apply automatically. Use `fireforge doctor --repair-furnace` if the engine gets out of sync.
 
 ## Additional Commands
 
-The commands below cover project configuration, patch queue management, build packaging, and development utilities. Run `fireforge <command> --help` for full option details.
+The commands below cover project configuration, patch queue management, build packaging and development utilities. Run `fireforge <command> --help` for full option details.
 
 ### Configuration
 

package/dist/src/commands/bootstrap-checks.d.ts

@@ -0,0 +1,16 @@
+import type { DoctorCheck } from '../types/commands/index.js';
+/** Tags representing distinct issues detected in bootstrap output. */
+export type BootstrapIssue = 'sdk-fetch-403' | 'python-traceback' | 'missing-origin-remote';
+/**
+ * Scans bootstrap output for known failure patterns and returns structured
+ * issue tags. A Python traceback paired with an HTTP 403 is collapsed into
+ * a single `sdk-fetch-403` tag since the traceback is just the stack trace
+ * from the HTTP error.
+ */
+export declare function detectBootstrapIssues(output: string): BootstrapIssue[];
+/**
+ * Runs targeted post-bootstrap checks based on the detected issues.
+ * Returns doctor-compatible check results so the caller can render them
+ * with the standard `reportDoctorResults` display.
+ */
+export declare function runPostBootstrapChecks(issues: BootstrapIssue[]): Promise<DoctorCheck[]>;

package/dist/src/commands/bootstrap-checks.js

@@ -0,0 +1,66 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { execFile } from 'node:child_process';
+import { failure, warning } from './doctor.js';
+/**
+ * Scans bootstrap output for known failure patterns and returns structured
+ * issue tags. A Python traceback paired with an HTTP 403 is collapsed into
+ * a single `sdk-fetch-403` tag since the traceback is just the stack trace
+ * from the HTTP error.
+ */
+export function detectBootstrapIssues(output) {
+    const normalized = output.replace(/\r\n/g, '\n');
+    const issues = [];
+    const hasTraceback = /traceback \(most recent call last\):/i.test(normalized);
+    const has403 = /\bhttp(?:\s+error)?\s*403\b/i.test(normalized) || /\b403\b.*forbidden/i.test(normalized);
+    if (has403) {
+        // The traceback is just the stack trace from the HTTP error — report once.
+        issues.push('sdk-fetch-403');
+    }
+    else if (hasTraceback) {
+        issues.push('python-traceback');
+    }
+    if (/no such remote ['"]origin['"]/i.test(normalized) ||
+        /remote ['"]origin['"] does not exist/i.test(normalized) ||
+        /missing git remote ['"]origin['"]/i.test(normalized)) {
+        issues.push('missing-origin-remote');
+    }
+    return issues;
+}
+/** Checks whether `xcrun --show-sdk-path` returns a valid macOS SDK path. */
+async function hasMacOsSdk() {
+    return new Promise((resolve) => {
+        execFile('xcrun', ['--show-sdk-path'], { timeout: 10_000 }, (err, stdout) => {
+            resolve(!err && stdout.trim().length > 0);
+        });
+    });
+}
+/**
+ * Runs targeted post-bootstrap checks based on the detected issues.
+ * Returns doctor-compatible check results so the caller can render them
+ * with the standard `reportDoctorResults` display.
+ */
+export async function runPostBootstrapChecks(issues) {
+    const checks = [];
+    for (const issue of issues) {
+        switch (issue) {
+            case 'sdk-fetch-403': {
+                const sdkAvailable = await hasMacOsSdk();
+                if (sdkAvailable) {
+                    checks.push(warning('macOS SDK download', "SDK download from Apple's CDN failed (HTTP 403), but a macOS SDK was found via Xcode. This is safe to ignore."));
+                }
+                else {
+                    checks.push(failure('macOS SDK', 'SDK download failed and no macOS SDK found on your system.', 'Install Xcode Command Line Tools with "xcode-select --install"'));
+                }
+                break;
+            }
+            case 'python-traceback':
+                checks.push(warning('Python traceback', 'Bootstrap emitted a Python traceback. This may indicate a non-critical issue.', 'Review the bootstrap output above for details.'));
+                break;
+            case 'missing-origin-remote':
+                checks.push(failure('Git remote', 'Bootstrap expected an "origin" git remote in the Firefox source checkout.', 'Run "git remote add origin <url>" in the engine directory.'));
+                break;
+        }
+    }
+    return checks;
+}
+//# sourceMappingURL=bootstrap-checks.js.map

package/dist/src/commands/bootstrap.js

@@ -4,7 +4,13 @@ import { bootstrapWithOutput } from '../core/mach.js';
 import { GeneralError } from '../errors/base.js';
 import { BootstrapError } from '../errors/build.js';
 import { pathExists } from '../utils/fs.js';
-import { error, info, intro, outro } from '../utils/logger.js';
+import { error, info, intro, outro, warn } from '../utils/logger.js';
+import { detectBootstrapIssues, runPostBootstrapChecks } from './bootstrap-checks.js';
+import { reportDoctorResults } from './doctor.js';
+/**
+ * Builds a human-readable failure message for hard failures (non-zero exit).
+ * Used only when mach bootstrap itself reports failure.
+ */
 function buildBootstrapFailureMessage(output) {
     const normalized = output.replace(/\r\n/g, '\n');
     const issues = [];
@@ -52,15 +58,27 @@ export async function bootstrapCommand(projectRoot) {
         throw new BootstrapError();
     }
     // mach bootstrap may exit 0 even when sub-downloads fail (e.g. HTTP 403).
-    // Scan output for known failure patterns and surface them prominently.
-    const softFailure = buildBootstrapFailureMessage(`${result.stdout}\n${result.stderr}`);
-    if (softFailure) {
+    // Instead of guessing from output text, detect what went wrong and run
+    // targeted checks to determine whether the issues are actually actionable.
+    const output = `${result.stdout}\n${result.stderr}`;
+    const issues = detectBootstrapIssues(output);
+    if (issues.length > 0) {
+        const checks = await runPostBootstrapChecks(issues);
+        const hasErrors = checks.some((c) => c.severity === 'error' || (!c.passed && !c.warning));
         info('');
-        error('Bootstrap completed with issues:');
-        info(softFailure);
-        info('Run "fireforge doctor" to verify your build environment. ' +
-            'These issues may cause build failures if not resolved.');
-        outro('Build dependencies installed with warnings');
+        if (hasErrors) {
+            warn('Bootstrap completed with issues:');
+        }
+        else {
+            warn('Bootstrap completed with warnings:');
+        }
+        reportDoctorResults(checks);
+        if (hasErrors) {
+            outro('Build dependencies installed with errors');
+        }
+        else {
+            outro('Build dependencies installed with warnings');
+        }
         return;
     }
     outro('Build dependencies installed successfully!');

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

@@ -1,4 +1,5 @@
 import { Command } from 'commander';
+import { ExitCode } from '../errors/codes.js';
 import type { CommandContext } from '../types/cli.js';
 import type { DoctorCheck, DoctorOptions } from '../types/commands/index.js';
 import type { FireForgeConfig, FireForgeState, ProjectPaths } from '../types/config.js';
@@ -116,6 +117,13 @@ export declare function failure(name: string, message: string, fix?: string): Do
  * think through the consequences.
  */
 export declare const DOCTOR_CHECK_ORDER: readonly string[];
+/**
+ * Renders a list of doctor checks to the console and returns the
+ * appropriate exit code (success when no errors, general error otherwise).
+ * @param checks - The check results to display
+ * @returns The exit code reflecting the overall result
+ */
+export declare function reportDoctorResults(checks: DoctorCheck[]): ExitCode;
 /**
  * Result of the doctor command, carrying the exit code so the caller
  * (or test) can inspect it without relying on process.exitCode.

package/dist/src/commands/doctor.js

@@ -342,7 +342,13 @@ validateCheckDependencies(DOCTOR_CHECKS);
  * think through the consequences.
  */
 export const DOCTOR_CHECK_ORDER = DOCTOR_CHECKS.map((check) => check.name);
-function reportDoctorResults(checks) {
+/**
+ * Renders a list of doctor checks to the console and returns the
+ * appropriate exit code (success when no errors, general error otherwise).
+ * @param checks - The check results to display
+ * @returns The exit code reflecting the overall result
+ */
+export function reportDoctorResults(checks) {
     info('');
     let passedCount = 0;
     let warningCount = 0;

package/dist/src/commands/export-flow.js

@@ -11,7 +11,7 @@ import { join } from 'node:path';
 import { findAllPatchesForFilesWithDetails, planExport } from '../core/patch-export.js';
 import { buildModifiedFileAdditionsFromDiff, buildPatchQueueContext, detectNewFilesInDiff, lintPatchQueue, } from '../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../core/patch-lock.js';
-import { addPatchToManifest, loadPatchesManifest, renumberPatchesInManifest, savePatchesManifest, } from '../core/patch-manifest.js';
+import { addPatchToManifest, loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, savePatchesManifest, } from '../core/patch-manifest.js';
 import { extractNewFileContentFromDiff } from '../core/patch-transform.js';
 import { InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
@@ -32,14 +32,6 @@ function buildFilenameForPlacement(category, name, order, width) {
     const padded = String(order).padStart(Math.max(3, width), '0');
     return `${padded}-${category}-${sanitizeExportName(name)}.patch`;
 }
-function resolvePatchByIdentifier(identifier, patches) {
-    if (/^\d+$/.test(identifier)) {
-        const order = parseInt(identifier, 10);
-        return patches.find((p) => p.order === order) ?? null;
-    }
-    const normalized = identifier.endsWith('.patch') ? identifier : `${identifier}.patch`;
-    return patches.find((p) => p.filename === normalized) ?? null;
-}
 function getSortedRenameEntries(renameMap) {
     return Array.from(renameMap.entries()).sort((a, b) => a[1].newOrder - b[1].newOrder);
 }
@@ -115,7 +107,7 @@ export async function resolvePlacementPlan(patchesDir, options, category, name)
         targetOrder = options.order;
     }
     else if (options.before !== undefined) {
-        const anchor = resolvePatchByIdentifier(options.before, existingPatches);
+        const anchor = resolvePatchIdentifier(options.before, existingPatches);
         if (!anchor) {
             throw new InvalidArgumentError(`--before anchor "${options.before}" not found.`, '--before');
         }
@@ -126,7 +118,7 @@ export async function resolvePlacementPlan(patchesDir, options, category, name)
         if (afterAnchorId === undefined) {
             throw new InvalidArgumentError('Placement flag resolver reached --after branch with no value set.', '--after');
         }
-        const anchor = resolvePatchByIdentifier(afterAnchorId, existingPatches);
+        const anchor = resolvePatchIdentifier(afterAnchorId, existingPatches);
         if (!anchor) {
             throw new InvalidArgumentError(`--after anchor "${afterAnchorId}" not found.`, '--after');
         }

package/dist/src/commands/export-shared.js

@@ -25,6 +25,10 @@ export async function runPatchLint(engineDir, filesAffected, diffContent, config
         return;
     const errors = issues.filter((i) => i.severity === 'error');
     const warnings = issues.filter((i) => i.severity === 'warning');
+    const notices = issues.filter((i) => i.severity === 'notice');
+    for (const issue of notices) {
+        info(`NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
+    }
     for (const issue of warnings) {
         warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
     }

package/dist/src/commands/lint.js

@@ -107,6 +107,10 @@ export async function lintCommand(projectRoot, files) {
     }
     const errors = issues.filter((i) => i.severity === 'error');
     const warnings = issues.filter((i) => i.severity === 'warning');
+    const notices = issues.filter((i) => i.severity === 'notice');
+    for (const issue of notices) {
+        info(`NOTICE [${issue.check}] ${issue.file}: ${issue.message}`);
+    }
     for (const issue of warnings) {
         warn(`[${issue.check}] ${issue.file}: ${issue.message}`);
     }

package/dist/src/commands/patch/delete.js

@@ -12,26 +12,12 @@ import { getProjectPaths } from '../../core/config.js';
 import { appendHistory, confirmDestructive } from '../../core/destructive.js';
 import { buildPatchQueueContext, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, isForwardImportableFile, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
-import { loadPatchesManifest, removePatchFileAndManifest } from '../../core/patch-manifest.js';
+import { loadPatchesManifest, removePatchFileAndManifest, resolvePatchIdentifier, } from '../../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { pickDefined } from '../../utils/options.js';
-/**
- * Resolves `<name>` (ordinal number or filename) to a manifest entry.
- * Mirrors re-export's `resolvePatchIdentifier` so the two resolvers behave
- * consistently — future work can lift this into a shared helper once a
- * third consumer appears.
- */
-function resolvePatchIdentifier(identifier, patches) {
-    if (/^\d+$/.test(identifier)) {
-        const order = parseInt(identifier, 10);
-        return patches.find((p) => p.order === order) ?? null;
-    }
-    const normalized = identifier.endsWith('.patch') ? identifier : `${identifier}.patch`;
-    return patches.find((p) => p.filename === normalized) ?? null;
-}
 /**
  * Runs the `patch delete` command: removes a patch file and its manifest
  * row atomically, refusing when a later patch imports a leaf owned by the

package/dist/src/commands/patch/reorder.js

@@ -13,21 +13,13 @@ import { getProjectPaths } from '../../core/config.js';
 import { appendHistory, confirmDestructive, } from '../../core/destructive.js';
 import { buildPatchQueueContext, lintPatchQueue, } from '../../core/patch-lint.js';
 import { withPatchDirectoryLock } from '../../core/patch-lock.js';
-import { loadPatchesManifest, renumberPatchesInManifest, } from '../../core/patch-manifest.js';
+import { loadPatchesManifest, renumberPatchesInManifest, resolvePatchIdentifier, } from '../../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../../errors/base.js';
 import { toError } from '../../utils/errors.js';
 import { pathExists } from '../../utils/fs.js';
 import { info, intro, outro, warn } from '../../utils/logger.js';
 import { pickDefined } from '../../utils/options.js';
 import { parsePositiveIntegerFlag } from '../../utils/validation.js';
-function resolvePatchIdentifier(identifier, patches) {
-    if (/^\d+$/.test(identifier)) {
-        const order = parseInt(identifier, 10);
-        return patches.find((p) => p.order === order) ?? null;
-    }
-    const normalized = identifier.endsWith('.patch') ? identifier : `${identifier}.patch`;
-    return patches.find((p) => p.filename === normalized) ?? null;
-}
 function padOrder(value, width) {
     return String(value).padStart(width, '0');
 }

package/dist/src/commands/re-export.js

@@ -6,7 +6,7 @@ import { isGitRepository } from '../core/git.js';
 import { getDiffForFilesAgainstHead } from '../core/git-diff.js';
 import { getModifiedFilesInDir, getUntrackedFilesInDir } from '../core/git-status.js';
 import { updatePatch, updatePatchMetadata } from '../core/patch-export.js';
-import { getClaimedFiles, loadPatchesManifest } from '../core/patch-manifest.js';
+import { getClaimedFiles, loadPatchesManifest, resolvePatchIdentifier, } from '../core/patch-manifest.js';
 import { GeneralError, InvalidArgumentError } from '../errors/base.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
@@ -14,22 +14,6 @@ import { cancel, info, intro, isCancel, outro, spinner, success, warn } from '..
 import { pickDefined } from '../utils/options.js';
 import { runPatchLint } from './export-shared.js';
 import { reExportFilesInPlace } from './re-export-files.js';
-/**
- * Resolves patch identifiers (numbers or filenames) to manifest entries.
- * @param identifier - Patch number (e.g. "005") or filename (e.g. "005-ui-storage-modules.patch")
- * @param patches - All patches from the manifest
- * @returns Matching patch metadata
- */
-function resolvePatchIdentifier(identifier, patches) {
-    // If all digits, match by order number
-    if (/^\d+$/.test(identifier)) {
-        const order = parseInt(identifier, 10);
-        return patches.find((p) => p.order === order) ?? null;
-    }
-    // Match by filename (with or without .patch suffix)
-    const normalized = identifier.endsWith('.patch') ? identifier : `${identifier}.patch`;
-    return patches.find((p) => p.filename === normalized) ?? null;
-}
 async function scanPatchFiles(currentFilesAffected, engineDir, manifest, patchFilename, isDryRun) {
     const parentDirs = [...new Set(currentFilesAffected.map((f) => dirname(f)))];
     const claimedByOthers = getClaimedFiles(manifest, patchFilename);

package/dist/src/commands/verify.js

@@ -89,11 +89,11 @@ export async function verifyCommand(projectRoot) {
     if (lintIssues.length > 0) {
         warn(`Cross-patch lint issues (${lintIssues.length}):`);
         for (const issue of lintIssues) {
-            const label = issue.severity === 'error' ? 'ERROR' : 'WARN';
+            const label = issue.severity === 'error' ? 'ERROR' : issue.severity === 'warning' ? 'WARN' : 'NOTICE';
             warn(`  ${label} [${issue.check}] ${issue.file}: ${issue.message}`);
             if (issue.severity === 'error')
                 errorCount += 1;
-            else
+            else if (issue.severity === 'warning')
                 warningCount += 1;
         }
     }

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

@@ -6,6 +6,12 @@ export { buildPatchQueueContext, collectNewFileCreatorsByPath, type ExtractedSpe
 export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
 export { type JsDocCheck, type JsDocIssue, validateExportJsDoc } from './patch-lint-jsdoc.js';
 export { resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
+/**
+ * Returns true if the file path looks like a test file.
+ * Matches paths containing `/test/` or filenames starting with
+ * `browser_`, `test_`, or `xpcshell_` (all `.js`).
+ */
+export declare function isTestFile(file: string): boolean;
 /**
  * Detects comment style from file extension for license header checks.
  */
@@ -19,7 +25,7 @@ export declare function commentStyleForFile(file: string): CommentStyle | null;
  * @param diffContent - Optional unified diff used to scope raw color checks to introduced lines
  * @returns Array of lint issues found
  */
-export declare function lintPatchedCss(repoDir: string, affectedFiles: string[], diffContent?: string): Promise<PatchLintIssue[]>;
+export declare function lintPatchedCss(repoDir: string, affectedFiles: string[], diffContent?: string, config?: FireForgeConfig): Promise<PatchLintIssue[]>;
 /**
  * Checks new files for required license headers.
  *

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

@@ -28,6 +28,14 @@ export { resolvePatchOwnedSysMjs } from './patch-lint-ownership.js';
 // Helpers
 // ---------------------------------------------------------------------------
 const JS_EXTENSIONS = ['.js', '.mjs', '.jsm'];
+const FILE_SIZE_THRESHOLDS = {
+    general: { notice: 500, warning: 750, error: 900 },
+    test: { notice: 1200, warning: 1400, error: 1600 },
+};
+const PATCH_LINE_THRESHOLDS = {
+    general: { notice: 800, warning: 1500, error: 3000 },
+    test: { notice: 1500, warning: 3000, error: 6000 },
+};
 /**
  * Returns true if the filename looks like a JS/MJS/JSM file.
  * Handles `.sys.mjs` as well.
@@ -35,6 +43,17 @@ const JS_EXTENSIONS = ['.js', '.mjs', '.jsm'];
 function isJsFile(file) {
     return JS_EXTENSIONS.some((ext) => file.endsWith(ext));
 }
+/**
+ * Returns true if the file path looks like a test file.
+ * Matches paths containing `/test/` or filenames starting with
+ * `browser_`, `test_`, or `xpcshell_` (all `.js`).
+ */
+export function isTestFile(file) {
+    if (file.includes('/test/'))
+        return true;
+    const basename = file.split('/').pop() ?? '';
+    return /^(?:browser_|test_|xpcshell_).*\.js$/.test(basename);
+}
 /**
  * Detects comment style from file extension for license header checks.
  */
@@ -59,7 +78,7 @@ export function commentStyleForFile(file) {
  * @param diffContent - Optional unified diff used to scope raw color checks to introduced lines
  * @returns Array of lint issues found
  */
-export async function lintPatchedCss(repoDir, affectedFiles, diffContent) {
+export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config) {
     const cssFiles = affectedFiles.filter((f) => f.endsWith('.css'));
     if (cssFiles.length === 0)
         return [];
@@ -86,17 +105,29 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent) {
         const rawCss = await readText(filePath);
         // Strip block comments before scanning
         const cssContent = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
-        const rawColorContent = addedLinesByFile
-            ? (addedLinesByFile.get(file) ?? []).join('\n').replace(/\/\*[\s\S]*?\*\//g, '')
-            : cssContent;
         // Check only introduced raw color values when diff context is available.
-        if (hasRawCssColors(rawColorContent)) {
-            issues.push({
-                file,
-                check: 'raw-color-value',
-                message: 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.',
-                severity: 'error',
-            });
+        // Skip files on the raw-color allowlist (exact path or basename match).
+        const allowlist = config?.patchLint?.rawColorAllowlist;
+        const isAllowlisted = allowlist?.some((entry) => file === entry || file.endsWith('/' + entry));
+        if (!isAllowlisted) {
+            // Strip lines with inline fireforge-ignore: raw-color-value suppression.
+            // Check against rawCss (before comment stripping) so the CSS comment marker is still present.
+            const sourceForSuppression = addedLinesByFile
+                ? (addedLinesByFile.get(file) ?? []).join('\n')
+                : rawCss;
+            const suppressedContent = sourceForSuppression
+                .split('\n')
+                .filter((line) => !line.includes('fireforge-ignore: raw-color-value'))
+                .join('\n')
+                .replace(/\/\*[\s\S]*?\*\//g, '');
+            if (hasRawCssColors(suppressedContent)) {
+                issues.push({
+                    file,
+                    check: 'raw-color-value',
+                    message: 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.',
+                    severity: 'error',
+                });
+            }
         }
         // Check for non-tokenized custom properties
         if (tokenPrefix) {
@@ -193,14 +224,34 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
         // 2. File size check (new files only)
         if (isNew) {
             const lineCount = content.split('\n').length;
-            if (lineCount > 650) {
+            const isTest = isTestFile(file);
+            const thresholds = isTest ? FILE_SIZE_THRESHOLDS.test : FILE_SIZE_THRESHOLDS.general;
+            const label = isTest ? 'Test file' : 'New file';
+            const verb = isTest ? 'splitting' : 'decomposing';
+            if (lineCount >= thresholds.error) {
                 issues.push({
                     file,
                     check: 'file-too-large',
-                    message: `New file has ${lineCount} lines (recommended max: 650). Consider decomposing.`,
+                    message: `${label} has ${lineCount} lines (hard limit: ${thresholds.error}). Consider ${verb}.`,
+                    severity: 'error',
+                });
+            }
+            else if (lineCount >= thresholds.warning) {
+                issues.push({
+                    file,
+                    check: 'file-too-large',
+                    message: `${label} has ${lineCount} lines (soft limit: ${thresholds.warning}, hard limit: ${thresholds.error}). Consider ${verb}.`,
                     severity: 'warning',
                 });
             }
+            else if (lineCount >= thresholds.notice) {
+                issues.push({
+                    file,
+                    check: 'file-too-large',
+                    message: `${label} has ${lineCount} lines (soft limit: ${thresholds.warning}, hard limit: ${thresholds.error}). Consider ${verb}.`,
+                    severity: 'notice',
+                });
+            }
         }
         // 3. JSDoc on exports (patch-owned .sys.mjs files)
         const isOwned = patchOwnedFiles ? patchOwnedFiles.has(file) : isNew;
@@ -216,7 +267,7 @@ export async function lintPatchedJs(repoDir, affectedFiles, newFiles, config, pa
             }
         }
         // 4. Observer topic naming
-        const topicPattern = /(?:addObserver|removeObserver|notifyObservers)\s*\([^)]*["']([^"']+)["']/g;
+        const topicPattern = /(?:addObserver|removeObserver|notifyObservers)\s*\([^)\n]*["']([^"']+)["']/g;
         let topicMatch;
         while ((topicMatch = topicPattern.exec(strippedContent)) !== null) {
             const topic = topicMatch[1];
@@ -283,14 +334,32 @@ export function lintPatchSize(filesAffected, lineCount) {
             severity: 'warning',
         });
     }
-    if (lineCount > 300) {
+    const allTests = filesAffected.length > 0 && filesAffected.every(isTestFile);
+    const thresholds = allTests ? PATCH_LINE_THRESHOLDS.test : PATCH_LINE_THRESHOLDS.general;
+    if (lineCount >= thresholds.error) {
+        issues.push({
+            file: '(patch)',
+            check: 'large-patch-lines',
+            message: `Patch is ${lineCount} lines (hard limit: ${thresholds.error}). Consider splitting into smaller, focused patches.`,
+            severity: 'error',
+        });
+    }
+    else if (lineCount >= thresholds.warning) {
         issues.push({
             file: '(patch)',
             check: 'large-patch-lines',
-            message: `Patch is ${lineCount} lines (recommended: ≤300). Consider splitting into smaller, focused patches.`,
+            message: `Patch is ${lineCount} lines (soft limit: ${thresholds.warning}, hard limit: ${thresholds.error}). Consider splitting into smaller, focused patches.`,
             severity: 'warning',
         });
     }
+    else if (lineCount >= thresholds.notice) {
+        issues.push({
+            file: '(patch)',
+            check: 'large-patch-lines',
+            message: `Patch is ${lineCount} lines (soft limit: ${thresholds.warning}, hard limit: ${thresholds.error}). Consider splitting into smaller, focused patches.`,
+            severity: 'notice',
+        });
+    }
     return issues;
 }
 // ---------------------------------------------------------------------------
@@ -346,7 +415,7 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
     const lineCount = diffContent.split('\n').length;
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);
     const [cssIssues, headerIssues, jsIssues, modifiedHeaderIssues] = await Promise.all([
-        lintPatchedCss(repoDir, affectedFiles, diffContent),
+        lintPatchedCss(repoDir, affectedFiles, diffContent, config),
         lintNewFileHeaders(repoDir, [...newFiles], config),
         lintPatchedJs(repoDir, affectedFiles, newFiles, config, patchOwnedFiles),
         lintModifiedFileHeaders(repoDir, affectedFiles, newFiles),

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

@@ -0,0 +1,5 @@
+import type { PatchMetadata } from '../types/commands/index.js';
+/**
+ * Resolves a patch identifier (ordinal number or filename) to its manifest entry.
+ */
+export declare function resolvePatchIdentifier(identifier: string, patches: PatchMetadata[]): PatchMetadata | null;

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

@@ -0,0 +1,12 @@
+/**
+ * Resolves a patch identifier (ordinal number or filename) to its manifest entry.
+ */
+export function resolvePatchIdentifier(identifier, patches) {
+    if (/^\d+$/.test(identifier)) {
+        const order = parseInt(identifier, 10);
+        return patches.find((p) => p.order === order) ?? null;
+    }
+    const normalized = identifier.endsWith('.patch') ? identifier : `${identifier}.patch`;
+    return patches.find((p) => p.filename === normalized) ?? null;
+}
+//# sourceMappingURL=patch-manifest-resolve.js.map

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

@@ -8,4 +8,5 @@ export type { PatchManifestConsistencyIssue } from './patch-manifest-consistency
 export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
 export { addPatchToManifest, loadPatchesManifest, PatchDeleteRollbackError, PATCHES_MANIFEST, type PatchRenameEntry, removePatchFileAndManifest, removePatchFromManifest, renumberPatchesInManifest, 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

@@ -8,5 +8,6 @@
 export { rebuildPatchesManifest, validatePatchesManifestConsistency, } from './patch-manifest-consistency.js';
 export { addPatchToManifest, loadPatchesManifest, PatchDeleteRollbackError, PATCHES_MANIFEST, removePatchFileAndManifest, removePatchFromManifest, renumberPatchesInManifest, 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/types/commands/patches.d.ts

@@ -94,6 +94,6 @@ export interface PatchLintIssue {
     fingerprint?: string;
     /** Human-readable description of the issue */
     message: string;
-    /** Severity: errors block export, warnings are advisory */
-    severity: 'error' | 'warning';
+    /** Severity: errors block export, warnings are advisory, notices are informational (not counted) */
+    severity: 'error' | 'warning' | 'notice';
 }

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

@@ -58,6 +58,8 @@ export interface WireConfig {
 export interface PatchLintConfig {
     /** Enable TypeScript checkJs pass on patch-owned .sys.mjs files */
     checkJs?: boolean;
+    /** File paths exempt from the raw-color-value check (exact or basename match) */
+    rawColorAllowlist?: string[];
 }
 /**
  * Build mode for mach.

package/package.json

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