@hominis/fireforge 0.31.0 → 0.32.0

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

@@ -1,13 +1,11 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { dirname, join } from 'node:path';
-import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
-import { verbose } from '../utils/logger.js';
-import { hasRawCssColors, stripJsComments } from '../utils/regex.js';
-import { loadFurnaceConfig } from './furnace-config.js';
+import { stripJsComments } from '../utils/regex.js';
 import { containsUpstreamLicenseText, getLicenseHeader, hasAnyLicenseHeader, hasAnyLicenseHeaderAnyStyle, } from './license-headers.js';
 import { invokePatchLintCheckJs } from './patch-lint-checkjs.js';
 import { lintChromeScriptJsDocForFile } from './patch-lint-chrome-jsdoc.js';
+import { lintPatchedCss } from './patch-lint-css.js';
 import { detectNewFilesInDiff, extractAddedLinesPerFile } from './patch-lint-diff.js';
 import { AGGREGATE_PATCH_FILE } from './patch-lint-diff-tag.js';
 import { hasRelativeImport } from './patch-lint-imports.js';
@@ -25,6 +23,10 @@ import { resolvePatchOwnedChromeScripts, resolvePatchOwnedSysMjs } from './patch
 // public surface from `patch-lint-reexports.ts` so callers continue to
 // import from a single module.
 export * from './patch-lint-reexports.js';
+// The CSS rule bodies live in `patch-lint-css.ts` (same per-file-budget
+// split as the other rule families); re-export the imported binding so
+// callers and tests keep importing `lintPatchedCss` from this module.
+export { lintPatchedCss };
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
@@ -205,158 +207,6 @@ export function commentStyleForFile(file) {
         return 'js';
     return null;
 }
-/**
- * Loads the furnace token-prefix lint inputs gracefully — returns
- * undefined (skipping the token-prefix check) when furnace.json cannot
- * be loaded or no tokenPrefix is configured.
- */
-async function loadCssTokenContext(repoDir) {
-    try {
-        const root = join(repoDir, '..');
-        const furnaceConfig = await loadFurnaceConfig(root);
-        if (furnaceConfig.tokenPrefix) {
-            return {
-                tokenPrefix: furnaceConfig.tokenPrefix,
-                tokenAllowlist: new Set(furnaceConfig.tokenAllowlist ?? []),
-                runtimeVariables: new Set(furnaceConfig.runtimeVariables ?? []),
-            };
-        }
-    }
-    catch (error) {
-        verbose(`Skipping furnace token-prefix lint hints because furnace.json could not be loaded: ${toError(error).message}`);
-    }
-    return undefined;
-}
-/**
- * Raw-color check for one patched CSS file, scoped to introduced lines
- * when diff context is available. Pushes onto `issues`.
- */
-function checkRawColorValues(file, rawCss, addedLinesByFile, config, issues) {
-    // Check only introduced raw color values when diff context is available.
-    // Skip files on the raw-color allowlist (exact path or basename match) and
-    // auto-exempt files under `browser/branding/` — those are the fork's
-    // visual identity assets (app-about dialogs, installer pages, branded
-    // CSS copied from Firefox's `unofficial` template) and belong to the
-    // design-decision layer the design-token system does not govern.
-    // Without this auto-exemption, every first-time setup's copied CSS
-    // failed `raw-color-value` with no actionable fix other than manually
-    // listing each path in `rawColorAllowlist`.
-    const allowlist = config?.patchLint?.rawColorAllowlist;
-    const isAllowlisted = allowlist?.some((entry) => file === entry || file.endsWith('/' + entry));
-    const isBranding = file.startsWith('browser/branding/');
-    if (!isAllowlisted && !isBranding) {
-        // 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',
-            });
-        }
-    }
-}
-/**
- * Token-prefix check for one patched CSS file: flags `var(--x)` references
- * that match neither the configured prefix, the allowlist, the runtime
- * variables, nor a same-file declaration. Pushes onto `issues`.
- */
-function checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues) {
-    // Check for non-tokenized custom properties. A variable that is both
-    // declared and consumed inside the same file is auto-exempted as a
-    // runtime state channel (see furnace.json → runtimeVariables).
-    //
-    // When diff context is available, scope the `var(...)` scan to
-    // added/modified lines only. `cssContent` (full-file) is still the
-    // source of `localDeclarations` so vars declared anywhere in the file
-    // are recognised as same-file refs regardless of where the consuming
-    // `var(...)` appears. Before this scoping change, a small edit to a
-    // Furnace override of a stock component (e.g. moz-card) produced a
-    // `token-prefix-violation` for every stock `var(--moz-card-*)` the
-    // upstream file already carried, because the scanner saw the full
-    // applied file and flagged each inherited reference as if the fork
-    // had introduced it.
-    if (tokenContext) {
-        const declarationPattern = /(?:^|[{;,\s])(--[\w-]+)\s*:/g;
-        const localDeclarations = new Set();
-        let declMatch;
-        while ((declMatch = declarationPattern.exec(cssContent)) !== null) {
-            const name = declMatch[1];
-            if (name)
-                localDeclarations.add(name);
-        }
-        const prefixScanSource = addedLinesByFile
-            ? (addedLinesByFile.get(file) ?? []).join('\n').replace(/\/\*[\s\S]*?\*\//g, '')
-            : cssContent;
-        if (prefixScanSource.length > 0) {
-            const varPattern = /var\(\s*(--[\w-]+)/g;
-            const flaggedProps = new Set();
-            let match;
-            while ((match = varPattern.exec(prefixScanSource)) !== null) {
-                const prop = match[1];
-                if (!prop)
-                    continue;
-                if (prop.startsWith(tokenContext.tokenPrefix))
-                    continue;
-                if (tokenContext.tokenAllowlist.has(prop))
-                    continue;
-                if (tokenContext.runtimeVariables.has(prop))
-                    continue;
-                if (localDeclarations.has(prop))
-                    continue;
-                // De-duplicate per (file, prop) pair so the same introduced var
-                // used five times in the added hunk doesn't produce five
-                // identical issue entries.
-                if (flaggedProps.has(prop))
-                    continue;
-                flaggedProps.add(prop);
-                issues.push({
-                    file,
-                    check: 'token-prefix-violation',
-                    message: `CSS references var(${prop}) which does not match the required token prefix "${tokenContext.tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
-                    severity: 'error',
-                });
-            }
-        }
-    }
-}
-/**
- * Lints patched CSS files for introduced raw color values and non-tokenized
- * custom properties.
- *
- * @param repoDir - Absolute path to the engine (repository) directory
- * @param affectedFiles - File paths (relative to repoDir) affected by the patch
- * @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, config) {
-    const cssFiles = affectedFiles.filter((f) => f.endsWith('.css'));
-    if (cssFiles.length === 0)
-        return [];
-    const tokenContext = await loadCssTokenContext(repoDir);
-    const issues = [];
-    const addedLinesByFile = diffContent ? extractAddedLinesPerFile(diffContent) : undefined;
-    for (const file of cssFiles) {
-        const filePath = join(repoDir, file);
-        if (!(await pathExists(filePath)))
-            continue;
-        const rawCss = await readText(filePath);
-        // Strip block comments before scanning
-        const cssContent = rawCss.replace(/\/\*[\s\S]*?\*\//g, '');
-        checkRawColorValues(file, rawCss, addedLinesByFile, config, issues);
-        checkTokenPrefixViolations(file, cssContent, addedLinesByFile, tokenContext, issues);
-    }
-    return issues;
-}
 // ---------------------------------------------------------------------------
 // License header lint
 // ---------------------------------------------------------------------------
@@ -695,9 +545,6 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
     }
     return issues;
 }
-// ---------------------------------------------------------------------------
-// Orchestrator
-// ---------------------------------------------------------------------------
 /**
  * Runs all patch lint checks and returns combined issues.
  *
@@ -717,9 +564,11 @@ export async function lintModifiedFileHeaders(repoDir, affectedFiles, newFiles)
  *   per-patch manifest context (re-export, per-patch lint) should
  *   pass this; aggregate-mode callers without a specific patch
  *   context skip it and fall through to auto-detection.
+ * @param options - Optional behaviour switches; see
+ *   {@link LintExportedPatchOptions}.
  * @returns Array of all lint issues found
  */
-export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx, ignoreChecks, patchTier) {
+export async function lintExportedPatch(repoDir, affectedFiles, diffContent, config, patchQueueCtx, ignoreChecks, patchTier, options) {
     const newFiles = detectNewFilesInDiff(diffContent);
     const { textLines: lineCount } = countNonBinaryDiffLines(diffContent);
     const patchOwnedFiles = resolvePatchOwnedSysMjs(newFiles, patchQueueCtx);
@@ -731,7 +580,9 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         lintModifiedFileHeaders(repoDir, affectedFiles, newFiles),
     ]);
     const modCommentIssues = lintModificationComments(diffContent, config);
-    const sizeIssues = lintPatchSize(affectedFiles, lineCount, patchTier);
+    const sizeIssues = options?.skipPatchSize
+        ? []
+        : lintPatchSize(affectedFiles, lineCount, patchTier);
     const issues = [
         ...sizeIssues,
         ...cssIssues,
@@ -740,8 +591,13 @@ export async function lintExportedPatch(repoDir, affectedFiles, diffContent, con
         ...jsIssues,
         ...modCommentIssues,
     ];
-    if (config.patchLint?.checkJs) {
-        issues.push(...(await invokePatchLintCheckJs(repoDir, patchOwnedFiles, config.patchLint, dirname(repoDir))));
+    if (options?.precomputedCheckJs) {
+        // Per-patch lint built one queue-wide program and already attributed
+        // this patch's findings — append them instead of rebuilding the program.
+        issues.push(...options.precomputedCheckJs);
+    }
+    else if (config.patchLint?.checkJs) {
+        issues.push(...(await invokePatchLintCheckJs(repoDir, patchOwnedFiles, config.patchLint, dirname(repoDir), options?.checkJsReportScope)));
     }
     // Filter out ignored checks last so every rule still runs (keeps the
     // implementation uniform) but suppressed rules do not surface. We do not

package/dist/src/core/test-xpcshell-retry.d.ts

@@ -3,5 +3,12 @@ export interface XpcshellRetryClassification {
     xpcshell: readonly string[];
     nonXpcshell: readonly string[];
 }
-/** Removes a stale xpcshell install symlink and retries the focused mach test once. */
-export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[], env?: Record<string, string>): Promise<MachCommandResult>;
+/** Dispatches a (possibly suite-specific) mach test run, mirroring `testWithOutput`. */
+export type TestDispatch = (engineDir: string, testPaths: string[], args: string[], env?: Record<string, string>) => Promise<MachCommandResult>;
+/**
+ * Removes a stale xpcshell install symlink and retries the focused mach test
+ * once. The retry uses the same `dispatch` (suite-specific or generic) the
+ * caller is already running on, so an xpcshell-suite run repairs and re-runs
+ * via `mach xpcshell-test` rather than falling back to the generic command.
+ */
+export declare function retryAfterXpcshellSymlinkRepair(engineDir: string, objDir: string | undefined, result: MachCommandResult, classification: XpcshellRetryClassification, normalizedPaths: string[], extraArgs: string[], env?: Record<string, string>, dispatch?: TestDispatch): Promise<MachCommandResult>;

package/dist/src/core/test-xpcshell-retry.js

@@ -1,16 +1,21 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { testWithOutput } from './mach.js';
 import { tryRepairStaleXpcshellTestSymlink } from './test-stale-symlink.js';
-/** Removes a stale xpcshell install symlink and retries the focused mach test once. */
-export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env) {
+/**
+ * Removes a stale xpcshell install symlink and retries the focused mach test
+ * once. The retry uses the same `dispatch` (suite-specific or generic) the
+ * caller is already running on, so an xpcshell-suite run repairs and re-runs
+ * via `mach xpcshell-test` rather than falling back to the generic command.
+ */
+export async function retryAfterXpcshellSymlinkRepair(engineDir, objDir, result, classification, normalizedPaths, extraArgs, env, dispatch = testWithOutput) {
     if (result.exitCode !== 0 &&
         classification.xpcshell.length > 0 &&
         classification.nonXpcshell.length === 0) {
         const repaired = await tryRepairStaleXpcshellTestSymlink(engineDir, objDir, `${result.stdout}\n${result.stderr}`);
         if (repaired) {
             return env
-                ? testWithOutput(engineDir, normalizedPaths, extraArgs, env)
-                : testWithOutput(engineDir, normalizedPaths, extraArgs);
+                ? dispatch(engineDir, normalizedPaths, extraArgs, env)
+                : dispatch(engineDir, normalizedPaths, extraArgs);
         }
     }
     return result;

package/dist/src/core/typecheck-shim.d.ts

@@ -40,7 +40,9 @@ export interface ComposedShim {
  * direction is intentional (declarations later in concat order
  * augment earlier ones), so a project that wants to refine `Services`
  * with a more specific type can do so by declaring it in the extra
- * shim.
+ * shim. Any triple-slash `/// <reference path="…">` directives inside the
+ * extra shim are inlined (resolved against the extra shim's own directory)
+ * so they are not silently dropped at the synthetic shim path.
  *
  * Missing extra-shim files raise a clear error rather than failing
  * silently with a confusing "type not found" downstream — this is the

package/dist/src/core/typecheck-shim.js

@@ -10,7 +10,7 @@
  * still fail `fireforge typecheck`, or vice versa, for reasons the
  * operator could not infer from the rule names.
  */
-import { resolve } from 'node:path';
+import { dirname, resolve } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
 /** Filename used for the synthetic Firefox-globals shim source file. */
 export const SHIM_FILENAME = '__fireforge_firefox_globals.d.ts';
@@ -110,6 +110,43 @@ export const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
     2580, // Cannot find name '{0}'. Do you need to install type definitions...
     7016, // Could not find a declaration file for module '{0}'.
 ]);
+/** Matches a lone triple-slash `/// <reference path="…" />` directive line. */
+const TRIPLE_SLASH_REFERENCE = /^\s*\/\/\/\s*<reference\s+path\s*=\s*["']([^"']+)["']\s*\/?>\s*$/;
+/**
+ * Inlines triple-slash `/// <reference path="…">` directives in shim source.
+ *
+ * Both shim consumers feed the text to the compiler at a *synthetic* path
+ * (an in-memory source file, not the extra shim's real location), so TS
+ * resolves a relative `/// <reference>` against that synthetic directory and
+ * silently drops it. Inlining the referenced file's contents (recursively,
+ * resolved against the *referencing* file's directory, deduped by absolute
+ * path) makes the directives self-contained so their declarations survive.
+ *
+ * @param source - Shim source possibly containing reference directives
+ * @param baseDir - Directory the directives' relative paths resolve against
+ * @param seen - Absolute paths already inlined (cycle / duplicate guard)
+ */
+async function inlineTripleSlashReferences(source, baseDir, seen) {
+    const out = [];
+    for (const line of source.split('\n')) {
+        const match = TRIPLE_SLASH_REFERENCE.exec(line);
+        if (!match?.[1]) {
+            out.push(line);
+            continue;
+        }
+        const absolute = resolve(baseDir, match[1]);
+        if (seen.has(absolute))
+            continue;
+        seen.add(absolute);
+        if (!(await pathExists(absolute))) {
+            out.push(`// (fireforge: unresolved /// <reference path="${match[1]}">)`);
+            continue;
+        }
+        const referenced = await readText(absolute);
+        out.push(await inlineTripleSlashReferences(referenced, dirname(absolute), seen));
+    }
+    return out.join('\n');
+}
 /**
  * Composes the synthetic shim source by concatenating the built-in
  * Firefox globals shim with the contents of an optional user-supplied
@@ -117,7 +154,9 @@ export const SUPPRESSED_DIAGNOSTIC_CODES = new Set([
  * direction is intentional (declarations later in concat order
  * augment earlier ones), so a project that wants to refine `Services`
  * with a more specific type can do so by declaring it in the extra
- * shim.
+ * shim. Any triple-slash `/// <reference path="…">` directives inside the
+ * extra shim are inlined (resolved against the extra shim's own directory)
+ * so they are not silently dropped at the synthetic shim path.
  *
  * Missing extra-shim files raise a clear error rather than failing
  * silently with a confusing "type not found" downstream — this is the
@@ -137,8 +176,9 @@ export async function composeShimSource(projectRoot, extraShimPath) {
             'Check the path in fireforge.json or create the file.');
     }
     const extra = await readText(absoluteShim);
+    const inlinedExtra = await inlineTripleSlashReferences(extra, dirname(absoluteShim), new Set([absoluteShim]));
     return {
-        source: `${FIREFOX_GLOBALS_SHIM}\n// ── extraShim: ${extraShimPath} ──\n${extra}`,
+        source: `${FIREFOX_GLOBALS_SHIM}\n// ── extraShim: ${extraShimPath} ──\n${inlinedExtra}`,
         extraShimAppended: true,
     };
 }

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

@@ -428,6 +428,15 @@ export interface TestOptions {
      * 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
@@ -774,6 +783,14 @@ export interface LintCommandOptions {
      * 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

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/package.json

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