@hominis/fireforge 0.30.1 → 0.32.0

package/dist/src/core/wire-utils.js

@@ -60,9 +60,7 @@ export function coerceToCall(expression) {
  */
 export function countBraceDepth(line, inBlockComment) {
     let depth = 0;
-    let inSingle = false;
-    let inDouble = false;
-    let inTemplate = false;
+    let quote = null;
     let inLine = false;
     let inBlock = inBlockComment;
     for (let i = 0; i < line.length; i++) {
@@ -77,23 +75,13 @@ export function countBraceDepth(line, inBlockComment) {
             }
             continue;
         }
-        if (ch === '\\' && (inSingle || inDouble || inTemplate)) {
+        if (ch === '\\' && quote !== null) {
             i++;
             continue;
         }
-        if (inSingle) {
-            if (ch === "'")
-                inSingle = false;
-            continue;
-        }
-        if (inDouble) {
-            if (ch === '"')
-                inDouble = false;
-            continue;
-        }
-        if (inTemplate) {
-            if (ch === '`')
-                inTemplate = false;
+        if (quote !== null) {
+            if (ch === quote)
+                quote = null;
             continue;
         }
         if (ch === '/' && next === '/') {
@@ -105,35 +93,12 @@ export function countBraceDepth(line, inBlockComment) {
             i++;
             continue;
         }
-        // Heuristic for regex literals: if / follows an operator or keyword boundary,
-        // treat it as a regex start and skip to the closing /
-        if (ch === '/' && next !== undefined) {
-            const prev = i > 0 ? line[i - 1] : undefined;
-            if (prev === undefined || /[=(:,!|&?;~^{[\n+\-*%<>]/.test(prev)) {
-                // Skip to closing /
-                i++;
-                while (i < line.length) {
-                    if (line[i] === '\\') {
-                        i++; // skip escaped character
-                    }
-                    else if (line[i] === '/') {
-                        break;
-                    }
-                    i++;
-                }
-                continue;
-            }
-        }
-        if (ch === "'") {
-            inSingle = true;
-            continue;
-        }
-        if (ch === '"') {
-            inDouble = true;
+        if (ch === '/' && next !== undefined && isRegexLiteralStart(line, i)) {
+            i = scanToRegexLiteralEnd(line, i);
             continue;
         }
-        if (ch === '`') {
-            inTemplate = true;
+        if (ch === "'" || ch === '"' || ch === '`') {
+            quote = ch;
             continue;
         }
         if (ch === '{')
@@ -143,6 +108,34 @@ export function countBraceDepth(line, inBlockComment) {
     }
     return { depth, inBlockComment: inBlock };
 }
+/**
+ * Regex-literal opener heuristic for the fallback scanner: a `/` is
+ * treated as starting a regex when it follows an operator or
+ * keyword-boundary character (or starts the line). See the misfire notes
+ * on {@link countBraceDepth}.
+ */
+function isRegexLiteralStart(line, i) {
+    const prev = i > 0 ? line[i - 1] : undefined;
+    return prev === undefined || /[=(:,!|&?;~^{[\n+\-*%<>]/.test(prev);
+}
+/**
+ * Scans from the opening `/` of a regex literal to its closing `/`
+ * (honouring escapes), returning the index of the closing slash — or the
+ * end of the line when the literal never closes.
+ */
+function scanToRegexLiteralEnd(line, start) {
+    let i = start + 1;
+    while (i < line.length) {
+        if (line[i] === '\\') {
+            i++; // skip escaped character
+        }
+        else if (line[i] === '/') {
+            break;
+        }
+        i++;
+    }
+    return i;
+}
 /**
  * Extracts the class/object name from an expression like "MyComponent.init()".
  */

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

@@ -1,6 +1,6 @@
 /**
  * Re-exports all command-related types from focused sub-modules.
  */
-export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchStagedDependencyOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, SourceSetOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
+export type { BuildOptions, DiscardOptions, DoctorOptions, DownloadOptions, ExportOptions, FurnaceApplyOptions, FurnaceCreateOptions, FurnaceDeployOptions, FurnaceOverrideOptions, FurnacePreviewOptions, FurnaceRefreshOptions, FurnaceRemoveOptions, FurnaceSyncOptions, FurnaceValidateOptions, GlobalOptions, ImportOptions, LintCommandOptions, PackageOptions, PatchCompactOptions, PatchDeleteOptions, PatchLintIgnoreOptions, PatchMoveFilesOptions, PatchRenameOptions, PatchReorderOptions, PatchSplitOptions, PatchStagedDependencyOptions, PatchTierOptions, RebaseOptions, ReExportOptions, RegisterOptions, ResetOptions, RunOptions, SetupOptions, SourceSetOptions, StatusOptions, TestOptions, TokenAddOptions, WireOptions, } from './options.js';
 export type { ImportSummary, PatchCategory, PatchesManifest, PatchInfo, PatchLintIssue, PatchMetadata, PatchResult, PatchStagedDependencies, PatchStagedForwardImport, } from './patches.js';
 export type { DoctorCheck, ProjectStatus, TokenCoverageFileEntry, TokenCoverageReport, } from './project.js';

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

@@ -304,6 +304,33 @@ export interface PatchStagedDependencyOptions {
  * It validates an ownership transfer and prints the explicit
  * `re-export --files` commands needed to perform it.
  */
+/**
+ * Options for the `patch split` command.
+ */
+export interface PatchSplitOptions {
+    /** Files to move out of the source patch (engine-relative). */
+    files: string[];
+    /** Name for the new patch (used in its filename slug). */
+    name: string;
+    /** Category for the new patch; defaults to the source patch's category. */
+    category?: string;
+    /** Description for the new patch. */
+    description?: string;
+    /** Exact sparse order for the new patch (mutually exclusive with before/after). */
+    order?: number;
+    /** Place the new patch before this patch identifier. */
+    before?: string;
+    /** Place the new patch after this patch identifier (default: the source). */
+    after?: string;
+    /** Preview without writing. */
+    dryRun?: boolean;
+    /** Skip interactive confirmation (required for non-TTY). */
+    yes?: boolean;
+    /** Bypass projected-lint refusals. */
+    forceUnsafe?: boolean;
+    /** Skip per-patch lint of the projected bodies. */
+    skipLint?: boolean;
+}
 export interface PatchMoveFilesOptions {
     /** File paths relative to engine/ to move from the source patch to the target patch. */
     file?: string[];
@@ -394,6 +421,34 @@ export interface TestOptions {
      * stale process holds the default port or CI uses another port.
      */
     marionettePort?: number;
+    /**
+     * Retry budget for recognized harness crashes (resource-monitor
+     * tracebacks, pre-test no-output hangs, post-green shutdown re-entry).
+     * 0 disables retries. Defaults to {@link DEFAULT_HARNESS_RETRIES} at the
+     * command layer.
+     */
+    harnessRetries?: number;
+    /**
+     * Force dispatch through the generic `mach test` command instead of the
+     * suite-specific `mach xpcshell-test` / `mach mochitest` commands a
+     * single-suite run auto-selects. Escape hatch for the rare case where a
+     * suite-specific command misbehaves; on a healthy host the generic command
+     * is equivalent. The default (auto suite dispatch) skips the mozlog
+     * resource monitor that crashes `mach test` on a broken host (E1).
+     */
+    genericMachTest?: boolean;
+    /**
+     * Commander negation flag for `--no-shard`. When false, multiple test
+     * paths run in one combined mach invocation; by default they shard into
+     * sequential single-file harness runs with an aggregate report.
+     */
+    shard?: boolean;
+    /**
+     * Project-relative (or absolute) artifact path published to the harness
+     * run as `<BINARYNAME>_PERF_SAMPLE_JSON`, for downstream perf-budget
+     * checkers that consume a sample artifact after the run.
+     */
+    perfSamples?: string;
 }
 /**
  * Options for the furnace apply command.
@@ -648,6 +703,8 @@ export interface TokenAddOptions {
     description?: string;
     darkValue?: string;
     dryRun?: boolean;
+    /** Declare the category banner in the tokens CSS when it does not exist yet. */
+    createCategory?: boolean;
 }
 /**
  * Options for the doctor command.
@@ -681,3 +738,68 @@ export interface GlobalOptions {
     /** Enable verbose/debug output */
     verbose?: boolean;
 }
+/** 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;
+    /**
+     * Restrict `--per-patch` to a named subset of the queue (by filename,
+     * filename ± `.patch`, or manifest `name`). Lets a change that touches a
+     * handful of patches run the per-patch gate over just those instead of
+     * the full ~90-patch queue. Only valid with {@link perPatch}; queue-level
+     * findings (policy, cross-patch) are scoped to files the subset touches.
+     */
+    patches?: string[];
+    /**
+     * 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;
+}

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

@@ -145,8 +145,15 @@ export type PatchLintSeverityGate = 'off' | 'warning' | 'error';
 /**
  * Allowlisted TypeScript `compilerOptions` overrides for the patch
  * `checkJs` pass when {@link PatchLintConfig.checkJsStrict} is true.
- * Merged after the strict preset; only boolean flags — no `paths`,
- * `rootDir`, or other options that would fight the synthetic program.
+ * Merged after the strict preset.
+ *
+ * Boolean flags tighten the strict preset. The optional `paths` mapping
+ * (each pattern may carry a single `*`) lets patch-owned modules be typed
+ * from their real sources — e.g. `"resource:///modules/foo/*": ["./*"]` —
+ * resolved host-side against the engine directory, so no `baseUrl` is set
+ * (TS5090-safe) and no hand-generated ambient stub shim is needed. Other
+ * options (`rootDir`, etc.) stay disallowed: they would fight the
+ * synthetic program.
  */
 export interface PatchLintCheckJsCompilerOptions {
     strictNullChecks?: boolean;
@@ -157,6 +164,8 @@ export interface PatchLintCheckJsCompilerOptions {
     strictPropertyInitialization?: boolean;
     noUnusedLocals?: boolean;
     noUnusedParameters?: boolean;
+    /** Module-resolution `paths` mapping (pattern → targets, engine-relative). */
+    paths?: Record<string, string[]>;
 }
 /**
  * Configuration for patch lint rules.

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

@@ -140,6 +140,15 @@ export interface FurnaceConfig {
      * Always includes `toolkit/content/widgets` by default.
      */
     scanPaths?: string[];
+    /**
+     * Project-relative path to a consumer-owned jsconfig/tsconfig whose
+     * `compilerOptions.paths` entries for deployed component modules
+     * (`chrome://global/content/elements/<file>.mjs`) Furnace keeps in sync
+     * on deploy. Only entries under that chrome prefix that map into
+     * `components/custom/` are managed; everything else is preserved.
+     * Unset disables jsconfig maintenance.
+     */
+    typecheckJsconfig?: string;
     /** Stock components tracked for preview */
     stock: string[];
     /** Override components */
@@ -234,7 +243,7 @@ export interface ApplyResult {
  */
 export interface DryRunAction {
     component: string;
-    action: 'copy' | 'register-ce' | 'register-jar' | 'copy-ftl' | 'undeploy-remove' | 'undeploy-restore' | 'unregister-ce' | 'unregister-jar';
+    action: 'copy' | 'expand-fragments' | 'register-ce' | 'register-jar' | 'copy-ftl' | 'undeploy-remove' | 'undeploy-restore' | 'unregister-ce' | 'unregister-jar';
     source?: string;
     target?: string;
     description: string;
@@ -277,3 +286,5 @@ export interface ValidationIssue {
     /** Human-readable description of the issue */
     message: string;
 }
+/** Resolved test-harness selection for a `furnace create` run. */
+export type ResolvedTestStyle = 'mochikit' | 'browser-chrome' | 'xpcshell' | 'none';

package/dist/src/utils/elapsed.d.ts

@@ -1,4 +1,2 @@
-/** Formats elapsed milliseconds for progress messages. */
-export declare function formatElapsed(ms: number): string;
 /** Returns formatted elapsed time since a start timestamp from Date.now(). */
 export declare function elapsedSince(startedAt: number): string;

package/dist/src/utils/elapsed.js

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
 /** Formats elapsed milliseconds for progress messages. */
-export function formatElapsed(ms) {
+function formatElapsed(ms) {
     const totalSeconds = Math.max(0, Math.round(ms / 1000));
     const minutes = Math.floor(totalSeconds / 60);
     const seconds = totalSeconds % 60;

package/dist/src/utils/fs.d.ts

@@ -13,11 +13,6 @@ export declare function pathExistsStrict(path: string): Promise<boolean>;
  * @param path - Directory path to ensure
  */
 export declare function ensureDir(path: string): Promise<void>;
-/**
- * Ensures the parent directory of a file exists.
- * @param filePath - Path to a file
- */
-export declare function ensureParentDir(filePath: string): Promise<void>;
 /**
  * Removes a directory recursively.
  * @param path - Directory path to remove

package/dist/src/utils/fs.js

@@ -52,7 +52,7 @@ export async function ensureDir(path) {
  * Ensures the parent directory of a file exists.
  * @param filePath - Path to a file
  */
-export async function ensureParentDir(filePath) {
+async function ensureParentDir(filePath) {
     const parent = dirname(filePath);
     await ensureDir(parent);
 }

package/dist/src/utils/regex.d.ts

@@ -2,12 +2,6 @@
  * Escapes special regex characters in a string.
  */
 export declare function escapeRegex(str: string): string;
-/** Matches hex color values like #fff, #ff00ff, #ff00ff80 (longest-first alternation) */
-export declare const CSS_HEX_COLOR: RegExp;
-/** Matches rgb() or rgba() function calls */
-export declare const CSS_RGB_COLOR: RegExp;
-/** Matches hsl() or hsla() function calls */
-export declare const CSS_HSL_COLOR: RegExp;
 /**
  * Returns true if the content contains any raw CSS color values (hex, rgb, hsl).
  */

package/dist/src/utils/regex.js

@@ -6,11 +6,11 @@ export function escapeRegex(str) {
     return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 /** Matches hex color values like #fff, #ff00ff, #ff00ff80 (longest-first alternation) */
-export const CSS_HEX_COLOR = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b/;
+const CSS_HEX_COLOR = /#(?:[0-9a-fA-F]{8}|[0-9a-fA-F]{6}|[0-9a-fA-F]{3,4})\b/;
 /** Matches rgb() or rgba() function calls */
-export const CSS_RGB_COLOR = /\brgba?\s*\(/;
+const CSS_RGB_COLOR = /\brgba?\s*\(/;
 /** Matches hsl() or hsla() function calls */
-export const CSS_HSL_COLOR = /\bhsla?\s*\(/;
+const CSS_HSL_COLOR = /\bhsla?\s*\(/;
 // Global variants for counting (cached to avoid re-creation per call)
 const CSS_HEX_COLOR_G = new RegExp(CSS_HEX_COLOR.source, 'g');
 const CSS_RGB_COLOR_G = new RegExp(CSS_RGB_COLOR.source, 'g');

package/dist/src/utils/validation.d.ts

@@ -90,14 +90,6 @@ export declare const PATCH_CATEGORIES: readonly ["branding", "ui", "privacy", "s
  * Validates a patch category string.
  */
 export declare function isValidPatchCategory(category: string): category is (typeof PATCH_CATEGORIES)[number];
-/**
- * Checks whether a Firefox version string has an ESR suffix.
- */
-export declare function isEsrVersion(version: string): boolean;
-/**
- * Checks whether a Firefox version string is a beta version (e.g. "147.0b1").
- */
-export declare function isBetaVersion(version: string): boolean;
 /**
  * Infers the Firefox product type from a version string.
  * Returns undefined if no clear inference can be made.

package/dist/src/utils/validation.js

@@ -134,13 +134,13 @@ export function isValidPatchCategory(category) {
 /**
  * Checks whether a Firefox version string has an ESR suffix.
  */
-export function isEsrVersion(version) {
+function isEsrVersion(version) {
     return /esr$/i.test(version);
 }
 /**
  * Checks whether a Firefox version string is a beta version (e.g. "147.0b1").
  */
-export function isBetaVersion(version) {
+function isBetaVersion(version) {
     return /b\d+$/.test(version);
 }
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.30.1",
+  "version": "0.32.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -24,6 +24,8 @@
     "lint:ci": "eslint src/ bin/ scripts/ eslint.config.js vitest.config.ts --max-warnings 0",
     "lint:fix": "eslint src/ bin/ scripts/ eslint.config.js vitest.config.ts --fix",
     "typecheck": "tsc --noEmit -p tsconfig.json",
+    "deadcode:check": "knip",
+    "cycles:check": "dpdm --no-output --no-tree --no-warning --exit-code circular:1 src/index.ts bin/fireforge.ts",
     "test": "vitest run",
     "test:package": "npm run pack:verify",
     "test:watch": "vitest",
@@ -36,7 +38,7 @@
     "format:check": "prettier --check --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\"",
     "prepare": "node -e \"import('./scripts/prepare.mjs').catch((error) => { if (error && typeof error === 'object' && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND') process.exit(0); throw error; })\"",
     "prepack": "npm run build",
-    "release:check": "npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run test:coverage && npm run pack:verify && npm run pack:dry-run",
+    "release:check": "npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run deadcode:check && npm run cycles:check && npm run test:coverage && npm run pack:verify && npm run pack:dry-run",
     "prepublishOnly": "npm run release:check"
   },
   "files": [
@@ -62,15 +64,15 @@
     "@eslint/js": "^10.0.0",
     "@types/estree": "^1.0.8",
     "@types/node": "^25.5.2",
-    "@typescript-eslint/eslint-plugin": "^8.0.0",
-    "@typescript-eslint/parser": "^8.0.0",
     "@vitest/coverage-v8": "^4.1.2",
+    "dpdm": "4.2.0",
     "eslint": "^10.0.0",
     "eslint-config-prettier": "^10.1.8",
     "eslint-plugin-jsdoc": "^63.0.0",
     "eslint-plugin-simple-import-sort": "^13.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
+    "knip": "6.16.1",
     "lint-staged": "^17.0.4",
     "prettier": "^3.7.4",
     "tsx": "^4.7.0",