@hominis/fireforge 0.31.0 → 0.33.0

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

@@ -343,27 +343,8 @@ function findMatchingStagedDependency(entry, sitePath, specifier, laterOwners) {
         laterOwners.some((owner) => owner.fullPath === dependency.creates &&
             (dependency.owner === undefined || dependency.owner === owner.filename)));
 }
-/**
- * Cross-patch lint rule: a patch imports a module that a later patch is
- * responsible for creating.
- *
- * Approach is deliberately conservative — we do not resolve `resource://`
- * URLs to engine file paths. Instead we build a cross-queue index of
- * newly-created files keyed by their basename, and flag imports whose leaf
- * matches an entry owned by a later-ordered patch. False positives from
- * unrelated basename collisions (two different directories happening to
- * create files named `Helper.sys.mjs`) are possible; the README documents
- * the limitation and the inline ignore marker above provides an escape
- * hatch.
- *
- * Rules out:
- * - Imports whose leaf matches a newly-created file in the *same* or an
- *   *earlier* patch (legitimate use).
- * - Imports whose leaf is not in the new-file index at all (pre-existing
- *   engine file — not our concern).
- * - Imports on a line suppressed by the ignore marker.
- */
-export function lintPatchQueueForwardImports(ctx) {
+/** Builds the basename → later-creators index used by the forward-import scan. */
+function buildNewFileIndex(ctx) {
     const newFileIndex = new Map();
     for (const entry of ctx.entries) {
         for (const fullPath of entry.newFiles.keys()) {
@@ -376,23 +357,24 @@ export function lintPatchQueueForwardImports(ctx) {
             owners.push({ filename: entry.filename, order: entry.order, fullPath });
         }
     }
-    const issues = [];
-    const usedStagedDeclarations = new Set();
-    // Runs the forward-import check against one source site — either a file
-    // the patch creates (`content` = full file) or a file the patch modifies
-    // (`content` = concatenated added lines only). We deliberately scan added
-    // lines rather than the full resulting file for modifications: we only
-    // want to flag imports *this patch introduces*, not imports that already
-    // exist on HEAD and happen to match a later-created file by coincidence.
+    return newFileIndex;
+}
+/**
+ * Visits every forward-import site (an import whose leaf is created by a
+ * later-ordered patch). Shared by {@link lintPatchQueueForwardImports} (which
+ * resolves/reports each) and {@link collectForwardImportEdges} (which returns
+ * them structurally). We scan a created file's full body and a modified
+ * file's added lines only — flagging imports *this patch introduces*, not
+ * pre-existing HEAD imports that happen to collide with a later-created file.
+ */
+function eachForwardImportSite(ctx, newFileIndex, visit) {
     const checkSite = (entry, sitePath, content) => {
         if (!isForwardImportableFile(sitePath))
             return;
         const ignoreLines = findForwardImportIgnoreLines(content);
-        const extracted = extractImportSpecifiersWithLines(content);
-        for (const { specifier, line } of extracted) {
+        for (const { specifier, line } of extractImportSpecifiersWithLines(content)) {
             if (ignoreLines.has(line))
                 continue;
-            // Take the leaf and strip query/hash if any.
             const cleaned = specifier.split(/[?#]/)[0] ?? specifier;
             const leaf = basename(cleaned);
             if (!leaf || !isForwardImportableFile(leaf))
@@ -400,41 +382,11 @@ export function lintPatchQueueForwardImports(ctx) {
             const owners = newFileIndex.get(leaf);
             if (!owners)
                 continue;
-            // Is the owner a later-ordered patch (or one ordered equal but
-            // lexicographically later as a tiebreaker)?
             const laterOwners = owners.filter((owner) => owner.order > entry.order ||
                 (owner.order === entry.order && owner.filename > entry.filename));
             if (laterOwners.length === 0)
                 continue;
-            const stagedDependency = findMatchingStagedDependency(entry, sitePath, specifier, laterOwners);
-            if (stagedDependency) {
-                usedStagedDeclarations.add(stagedDependencyKey(entry, stagedDependency));
-                continue;
-            }
-            const ownersSummary = laterOwners
-                .map((o) => `${o.filename} (creates ${o.fullPath})`)
-                .join(', ');
-            const fingerprintOwners = [...laterOwners]
-                .map((o) => `${o.filename}:${o.fullPath}`)
-                .sort((a, b) => a.localeCompare(b))
-                .join(',');
-            // Lowest ordinal that lands AFTER every later-ordered creator —
-            // turns the operator's "guess and re-run" loop into a single shot
-            // when the only fix is reordering.
-            const suggestedOrder = Math.max(...laterOwners.map((o) => o.order)) + 1;
-            issues.push({
-                file: sitePath,
-                check: 'forward-import',
-                fingerprint: `forward-import|${sitePath}|${cleaned}|${fingerprintOwners}`,
-                message: `${sitePath} in ${entry.filename} imports "${specifier}", ` +
-                    `but the matching new file is created by a later patch: ${ownersSummary}. ` +
-                    'Reorder the patches so the dependency is created first, move the import ' +
-                    'into the later patch, declare the intentional staged dependency with ' +
-                    '"fireforge patch staged-dependency --add", or mark the import with ' +
-                    `"// ${FORWARD_IMPORT_IGNORE_MARKER}" if the basename collision is a false positive. ` +
-                    `Closest legal ordinal that satisfies this dependency: ${suggestedOrder}.`,
-                severity: 'error',
-            });
+            visit(entry, sitePath, specifier, cleaned, laterOwners);
         }
     };
     for (const entry of ctx.entries) {
@@ -443,6 +395,74 @@ export function lintPatchQueueForwardImports(ctx) {
         for (const [path, added] of entry.modifiedFileAdditions)
             checkSite(entry, path, added);
     }
+}
+/**
+ * Returns every forward-import edge in the queue, one per (site, later
+ * creator) pair, regardless of any staged-dependency declarations. Used by
+ * `patch split` to discover the forward edges it introduces into the new
+ * patch so it can auto-declare them (and so its projected lint matches the
+ * real per-patch gate).
+ */
+export function collectForwardImportEdges(ctx) {
+    const newFileIndex = buildNewFileIndex(ctx);
+    const edges = [];
+    eachForwardImportSite(ctx, newFileIndex, (entry, sitePath, specifier, cleaned, laterOwners) => {
+        for (const owner of laterOwners) {
+            edges.push({
+                entry: entry.filename,
+                sitePath,
+                specifier,
+                cleaned,
+                owner: owner.filename,
+                creates: owner.fullPath,
+            });
+        }
+    });
+    return edges;
+}
+/**
+ * Cross-patch lint rule: flag imports of a module a later-ordered patch is
+ * responsible for creating, unless the patch declares an exact staged
+ * forward-import for it. Also warns on staged-dependency declarations that
+ * never matched (stale). Matching is conservative — by basename, not by
+ * resolving `resource://`/`chrome://` URLs — with an inline ignore marker as
+ * an escape hatch for unrelated basename collisions.
+ */
+export function lintPatchQueueForwardImports(ctx) {
+    const newFileIndex = buildNewFileIndex(ctx);
+    const issues = [];
+    const usedStagedDeclarations = new Set();
+    eachForwardImportSite(ctx, newFileIndex, (entry, sitePath, specifier, cleaned, laterOwners) => {
+        const stagedDependency = findMatchingStagedDependency(entry, sitePath, specifier, laterOwners);
+        if (stagedDependency) {
+            usedStagedDeclarations.add(stagedDependencyKey(entry, stagedDependency));
+            return;
+        }
+        const ownersSummary = laterOwners
+            .map((o) => `${o.filename} (creates ${o.fullPath})`)
+            .join(', ');
+        const fingerprintOwners = [...laterOwners]
+            .map((o) => `${o.filename}:${o.fullPath}`)
+            .sort((a, b) => a.localeCompare(b))
+            .join(',');
+        // Lowest ordinal that lands AFTER every later-ordered creator —
+        // turns the operator's "guess and re-run" loop into a single shot
+        // when the only fix is reordering.
+        const suggestedOrder = Math.max(...laterOwners.map((o) => o.order)) + 1;
+        issues.push({
+            file: sitePath,
+            check: 'forward-import',
+            fingerprint: `forward-import|${sitePath}|${cleaned}|${fingerprintOwners}`,
+            message: `${sitePath} in ${entry.filename} imports "${specifier}", ` +
+                `but the matching new file is created by a later patch: ${ownersSummary}. ` +
+                'Reorder the patches so the dependency is created first, move the import ' +
+                'into the later patch, declare the intentional staged dependency with ' +
+                '"fireforge patch staged-dependency --add", or mark the import with ' +
+                `"// ${FORWARD_IMPORT_IGNORE_MARKER}" if the basename collision is a false positive. ` +
+                `Closest legal ordinal that satisfies this dependency: ${suggestedOrder}.`,
+            severity: 'error',
+        });
+    });
     for (const entry of ctx.entries) {
         for (const dependency of entry.metadata?.stagedDependencies?.forwardImports ?? []) {
             if (usedStagedDeclarations.has(stagedDependencyKey(entry, dependency)))

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

@@ -0,0 +1,23 @@
+/**
+ * CSS patch-lint rules: introduced raw color values and non-tokenized
+ * custom-property references.
+ *
+ * Split out of `patch-lint.ts` so the per-patch and CSS rule bodies each
+ * stay within the project's per-file line budget — the same separation
+ * already applied to the JSDoc, observer, import, ownership, checkJs, and
+ * cross-patch rule families. `patch-lint.ts` re-exports `lintPatchedCss`
+ * so existing callers keep importing from the single module.
+ */
+import type { PatchLintIssue } from '../types/commands/index.js';
+import type { FireForgeConfig } from '../types/config.js';
+/**
+ * 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
+ * @param config - Project configuration
+ * @returns Array of lint issues found
+ */
+export declare function lintPatchedCss(repoDir: string, affectedFiles: string[], diffContent?: string, config?: FireForgeConfig): Promise<PatchLintIssue[]>;

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

@@ -0,0 +1,172 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * CSS patch-lint rules: introduced raw color values and non-tokenized
+ * custom-property references.
+ *
+ * Split out of `patch-lint.ts` so the per-patch and CSS rule bodies each
+ * stay within the project's per-file line budget — the same separation
+ * already applied to the JSDoc, observer, import, ownership, checkJs, and
+ * cross-patch rule families. `patch-lint.ts` re-exports `lintPatchedCss`
+ * so existing callers keep importing from the single module.
+ */
+import { 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 } from '../utils/regex.js';
+import { loadFurnaceConfig } from './furnace-config.js';
+import { extractAddedLinesPerFile } from './patch-lint-diff.js';
+/**
+ * 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
+ * @param config - Project configuration
+ * @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;
+}
+//# sourceMappingURL=patch-lint-css.js.map

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

@@ -2,5 +2,5 @@
  * Public re-exports for {@link ./patch-lint.ts}. Split out so the
  * orchestrator stays within the ESLint `max-lines` budget.
  */
-export { buildPatchQueueContext, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, type PatchQueueContext, type PatchQueueEntry, } from './patch-lint-cross.js';
+export { buildPatchQueueContext, collectForwardImportEdges, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, type ForwardImportEdge, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, type PatchQueueContext, type PatchQueueEntry, } from './patch-lint-cross.js';
 export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';

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

@@ -3,6 +3,6 @@
  * Public re-exports for {@link ./patch-lint.ts}. Split out so the
  * orchestrator stays within the ESLint `max-lines` budget.
  */
-export { buildPatchQueueContext, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, } from './patch-lint-cross.js';
+export { buildPatchQueueContext, collectForwardImportEdges, collectNewFileCreatorsByPath, extractImportSpecifiers, extractImportSpecifiersWithLines, findForwardImportIgnoreLines, FORWARD_IMPORT_IGNORE_MARKER, isForwardImportableFile, lintPatchQueue, lintPatchQueueDuplicateCreations, lintPatchQueueForwardImports, } from './patch-lint-cross.js';
 export { buildModifiedFileAdditionsFromDiff, detectNewFilesInDiff } from './patch-lint-diff.js';
 //# sourceMappingURL=patch-lint-reexports.js.map

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

@@ -1,7 +1,9 @@
 import type { PatchLintIssue } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import { type CommentStyle } from './license-headers.js';
+import { lintPatchedCss } from './patch-lint-css.js';
 export * from './patch-lint-reexports.js';
+export { lintPatchedCss };
 /**
  * Counts the total lines in a unified diff and the number of non-binary
  * text lines, so binary hunks do not inflate patch size checks.
@@ -23,16 +25,6 @@ export declare function isTestFile(file: string): boolean;
  * Detects comment style from file extension for license header checks.
  */
 export declare function commentStyleForFile(file: string): CommentStyle | null;
-/**
- * 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 declare function lintPatchedCss(repoDir: string, affectedFiles: string[], diffContent?: string, config?: FireForgeConfig): Promise<PatchLintIssue[]>;
 /**
  * Checks new files for required license headers.
  *
@@ -121,6 +113,35 @@ export declare function lintPatchSize(filesAffected: string[], lineCount: number
  * @returns Warning-level lint issues for files missing any recognized header
  */
 export declare function lintModifiedFileHeaders(repoDir: string, affectedFiles: string[], newFiles: Set<string>): Promise<PatchLintIssue[]>;
+/**
+ * Optional behaviour switches for {@link lintExportedPatch}.
+ */
+export interface LintExportedPatchOptions {
+    /**
+     * Skip the patch-size rules (`large-patch-files` / `large-patch-lines`).
+     * The ad-hoc `fireforge lint <files>` path passes a cross-patch file
+     * list that does not correspond to a single patch, so it suppresses the
+     * synthetic combined-list size check here and re-evaluates the size
+     * rules per owning patch instead — never synthesising a phantom
+     * oversized patch from the operator's file selection.
+     */
+    skipPatchSize?: boolean;
+    /**
+     * Restrict checkJs diagnostics to these repo-relative files; module
+     * resolution still spans every owned file in `patchQueueCtx`. Export and
+     * re-export pass the patch under export so cross-patch `resource:///`
+     * imports resolve against the whole queue while only that patch's
+     * findings surface.
+     */
+    checkJsReportScope?: ReadonlySet<string>;
+    /**
+     * Pre-computed checkJs issues for this patch. When provided, the internal
+     * checkJs invocation is skipped and these are appended verbatim — the
+     * per-patch lint path builds one queue-wide checkJs program and
+     * attributes findings per patch instead of rebuilding per patch.
+     */
+    precomputedCheckJs?: readonly PatchLintIssue[];
+}
 /**
  * Runs all patch lint checks and returns combined issues.
  *
@@ -140,6 +161,8 @@ export declare function lintModifiedFileHeaders(repoDir: string, affectedFiles:
  *   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 declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>, patchTier?: 'branding'): Promise<PatchLintIssue[]>;
+export declare function lintExportedPatch(repoDir: string, affectedFiles: string[], diffContent: string, config: FireForgeConfig, patchQueueCtx?: import('./patch-lint-cross.js').PatchQueueContext, ignoreChecks?: ReadonlySet<string>, patchTier?: 'branding', options?: LintExportedPatchOptions): Promise<PatchLintIssue[]>;