@hominis/fireforge 0.31.0 → 0.32.0

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

@@ -16,6 +16,14 @@
  * `patchLint.checkJsStrict` only tightens `strict` / `noImplicitAny`
  * and optional allowlisted `checkJsCompilerOptions`; it does not change
  * shim composition or suppressed diagnostic codes.
+ *
+ * Resolution scope vs reporting scope: the TS program is built over a
+ * *resolution* set (every patch-owned `.sys.mjs` the run cares about, so
+ * cross-patch `resource:///` imports resolve to their real sources), while
+ * diagnostics are emitted only for files in the *report* scope. Splitting
+ * the two lets per-patch lint build one queue-wide program and attribute
+ * findings per patch, and lets export/re-export resolve cross-patch imports
+ * while reporting only the patch under export.
  */
 import { basename, resolve } from 'node:path';
 import { pathExists } from '../utils/fs.js';
@@ -62,57 +70,121 @@ function createOwnedSpecifierResolver(ts, ownedAbsolute) {
         };
     };
 }
+/** Maps a resolved file path to the TS extension enum the host must report. */
+function extensionForFile(ts, file) {
+    if (file.endsWith('.d.ts'))
+        return ts.Extension.Dts;
+    if (file.endsWith('.ts'))
+        return ts.Extension.Ts;
+    if (file.endsWith('.tsx'))
+        return ts.Extension.Tsx;
+    if (file.endsWith('.cjs'))
+        return ts.Extension.Cjs;
+    if (file.endsWith('.jsx'))
+        return ts.Extension.Jsx;
+    if (file.endsWith('.json'))
+        return ts.Extension.Json;
+    return ts.Extension.Mjs;
+}
 /**
- * Runs TypeScript's checkJs pass on patch-owned `.sys.mjs` files.
+ * Builds a resolver for a reviewed `paths` mapping (route 2 of the
+ * cross-patch resolution work). Each pattern may contain a single `*`;
+ * matching targets are resolved relative to `baseDir` (the engine dir, like
+ * the rest of `patchLint` which is engine-relative). Resolved files are
+ * recorded via `onResolved` so the compiler host knows to read them from
+ * disk rather than returning empty content. No `baseUrl` is set, so this is
+ * TS5090-safe: `paths` resolution is host-driven here, not config-driven.
+ */
+function createPathsResolver(ts, paths, baseDir, fileExists, onResolved) {
+    const entries = Object.entries(paths);
+    return (specifier) => {
+        for (const [pattern, targets] of entries) {
+            const star = pattern.indexOf('*');
+            let captured;
+            if (star === -1) {
+                if (specifier !== pattern)
+                    continue;
+                captured = '';
+            }
+            else {
+                const prefix = pattern.slice(0, star);
+                const suffix = pattern.slice(star + 1);
+                if (specifier.length < prefix.length + suffix.length)
+                    continue;
+                if (!specifier.startsWith(prefix) || !specifier.endsWith(suffix))
+                    continue;
+                captured = specifier.slice(prefix.length, specifier.length - suffix.length);
+            }
+            for (const target of targets) {
+                const rel = target.includes('*') ? target.replace('*', captured) : target;
+                const abs = resolve(baseDir, rel);
+                if (!fileExists(abs))
+                    continue;
+                onResolved(abs);
+                return {
+                    resolvedFileName: abs,
+                    extension: extensionForFile(ts, abs),
+                    isExternalLibraryImport: false,
+                };
+            }
+        }
+        return undefined;
+    };
+}
+/**
+ * Builds the checkJs program **once** over `resolutionOwned` and returns its
+ * diagnostics grouped by originating file. Callers slice the result by their
+ * own report scope — per-patch lint attributes each file to its owning
+ * patch, export/re-export keeps only the patch under export. Resolution
+ * always spans every file in `resolutionOwned`, so cross-patch
+ * `resource:///`/`chrome://` imports resolve to real sources.
  *
- * @param repoDir - Absolute path to the engine (repository) directory
- * @param patchOwnedFiles - Set of patch-owned `.sys.mjs` file paths (relative to repoDir)
- * @param extraShimPath - Optional project-relative path to an additional
- *   `.d.ts` file whose contents are concatenated to the built-in
- *   Firefox-globals shim. Sourced from `patchLint.checkJsExtraShim`.
- *   Resolved against `projectRoot` (one level up from `repoDir` is the
- *   wrong root — patches sit inside `engine/` while the shim lives at
- *   the project root, so the caller passes both).
- * @param projectRoot - Absolute project root for resolving `extraShimPath`.
- *   Defaults to `repoDir` for back-compat with callers that don't
- *   pass an extra shim (no resolution actually happens in that case).
- * @param mode - When `strict` is true, enables `strict` and `noImplicitAny`
- *   (CI-style). Optional `compilerOptions` merges allowlisted boolean
- *   overrides after that preset (from `patchLint.checkJsCompilerOptions`).
- *   Omitted or `{ strict: false }` preserves the historical loose preset.
- * @returns Array of lint issues from TS diagnostics
+ * @param repoDir - Absolute engine (repository) directory
+ * @param resolutionOwned - Patch-owned `.sys.mjs` paths (relative to repoDir)
+ *   the program should see and resolve against
+ * @param extraShimPath - Optional project-relative extra `.d.ts` appended to
+ *   the built-in Firefox-globals shim (from `patchLint.checkJsExtraShim`)
+ * @param projectRoot - Absolute project root for resolving `extraShimPath`
+ * @param mode - Strictness preset plus allowlisted compiler-option overrides
+ * @returns Diagnostics grouped per owning file plus run-level errors
  */
-export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projectRoot, mode) {
-    if (patchOwnedFiles.size === 0)
-        return [];
+export async function runCheckJsGrouped(repoDir, resolutionOwned, extraShimPath, projectRoot, mode) {
+    const empty = { byFile: new Map(), global: [] };
+    if (resolutionOwned.size === 0)
+        return empty;
     // Dynamic import — typescript stays as a dev dependency
     let ts;
     try {
         ts = await import('typescript');
     }
     catch {
-        return [
-            {
-                file: '(checkJs)',
-                check: 'checkjs-type-error',
-                message: 'patchLint.checkJs is enabled but the "typescript" package is not installed. ' +
-                    'Run "npm install typescript" to enable type checking.',
-                severity: 'error',
-            },
-        ];
+        return {
+            byFile: new Map(),
+            global: [
+                {
+                    file: '(checkJs)',
+                    check: 'checkjs-type-error',
+                    message: 'patchLint.checkJs is enabled but the "typescript" package is not installed. ' +
+                        'Run "npm install typescript" to enable type checking.',
+                    severity: 'error',
+                },
+            ],
+        };
     }
     // Resolve absolute paths for root files, filtering to files that exist
     const rootFiles = [];
     const ownedAbsolute = new Set();
-    for (const rel of patchOwnedFiles) {
+    const relByAbsolute = new Map();
+    for (const rel of resolutionOwned) {
         const abs = resolve(repoDir, rel);
         if (await pathExists(abs)) {
             rootFiles.push(abs);
             ownedAbsolute.add(abs);
+            relByAbsolute.set(abs, rel);
         }
     }
     if (rootFiles.length === 0)
-        return [];
+        return empty;
     // Compose the shim. `extraShimPath` is project-relative (validated
     // by config-validate); resolve it against `projectRoot`. When the
     // caller passes neither, fall back to `repoDir` — the only way the
@@ -127,14 +199,17 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
         }
     }
     catch (err) {
-        return [
-            {
-                file: extraShimPath ?? '(checkJs)',
-                check: 'checkjs-type-error',
-                message: err instanceof Error ? err.message : String(err),
-                severity: 'error',
-            },
-        ];
+        return {
+            byFile: new Map(),
+            global: [
+                {
+                    file: extraShimPath ?? '(checkJs)',
+                    check: 'checkjs-type-error',
+                    message: err instanceof Error ? err.message : String(err),
+                    severity: 'error',
+                },
+            ],
+        };
     }
     const shimPath = resolve(repoDir, SHIM_FILENAME);
     rootFiles.push(shimPath);
@@ -146,12 +221,23 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
             strict: false,
             noImplicitAny: false,
         };
+    // Allowlisted overrides. Booleans merge directly; a reviewed `paths`
+    // mapping is applied to the compiler options AND wired into the host
+    // resolver below so patch-owned modules can be typed from their real
+    // sources without a hand-generated ambient stub shim.
     const overrides = {};
+    let pathsMapping;
     const co = mode?.compilerOptions;
     if (co) {
         for (const key of Object.keys(co)) {
             const v = co[key];
-            if (v !== undefined) {
+            if (v === undefined)
+                continue;
+            if (key === 'paths') {
+                pathsMapping = v;
+                overrides.paths = pathsMapping;
+            }
+            else {
                 overrides[key] = v;
             }
         }
@@ -180,13 +266,19 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
     // the shim for the shim path, and returns empty content for
     // anything else to avoid reading the full Firefox tree.
     const defaultHost = ts.createCompilerHost(options);
+    // Files pulled in via a reviewed `paths` mapping — outside the owned set
+    // but read from disk so the resolver's targets actually type-check.
+    const pathsResolved = new Set();
+    const resolveViaPaths = pathsMapping
+        ? createPathsResolver(ts, pathsMapping, repoDir, (f) => defaultHost.fileExists(f), (abs) => pathsResolved.add(abs))
+        : undefined;
     const host = {
         ...defaultHost,
         getSourceFile(fileName, languageVersion, onError) {
             if (fileName === shimPath) {
                 return ts.createSourceFile(fileName, shimSource, languageVersion, true);
             }
-            if (ownedAbsolute.has(fileName)) {
+            if (ownedAbsolute.has(fileName) || pathsResolved.has(fileName)) {
                 return defaultHost.getSourceFile(fileName, languageVersion, onError);
             }
             // For lib files (lib.es*.d.ts) delegate to the default host
@@ -201,7 +293,7 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
         fileExists(fileName) {
             if (fileName === shimPath)
                 return true;
-            if (ownedAbsolute.has(fileName))
+            if (ownedAbsolute.has(fileName) || pathsResolved.has(fileName))
                 return true;
             return defaultHost.fileExists(fileName);
         },
@@ -211,61 +303,115 @@ export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projec
             return defaultHost.readFile(fileName);
         },
         resolveModuleNameLiterals(moduleLiterals) {
-            return moduleLiterals.map((literal) => ({
-                resolvedModule: resolveOwnedSpecifier(literal.text),
-            }));
+            return moduleLiterals.map((literal) => {
+                const owned = resolveOwnedSpecifier(literal.text);
+                if (owned)
+                    return { resolvedModule: owned };
+                return { resolvedModule: resolveViaPaths?.(literal.text) };
+            });
         },
     };
     const program = ts.createProgram(rootFiles, options, host);
-    const allDiagnostics = [
-        ...program.getSemanticDiagnostics(),
-        ...program.getSyntacticDiagnostics(),
-    ];
-    // Filter to diagnostics originating in patch-owned files only,
-    // and suppress module-resolution / unknown-name noise that is
-    // inherent to checking Firefox JS outside Mozilla's build system.
-    const issues = [];
-    for (const diag of allDiagnostics) {
+    const byFile = groupOwnedDiagnostics(ts, [...program.getSemanticDiagnostics(), ...program.getSyntacticDiagnostics()], relByAbsolute);
+    verbose(`checkJs: analyzed ${rootFiles.length - 1} file(s) across ${byFile.size} owning file(s)`);
+    return { byFile, global: [] };
+}
+/**
+ * Groups TS diagnostics by the patch-owned file they originate in,
+ * suppressing module-resolution / unknown-name noise inherent to checking
+ * Firefox JS outside Mozilla's build system. Diagnostics from `paths`-resolved
+ * or shim files are dropped — only owned files (in `relByAbsolute`) carry
+ * findings.
+ */
+function groupOwnedDiagnostics(ts, diagnostics, relByAbsolute) {
+    const byFile = new Map();
+    for (const diag of diagnostics) {
         if (SUPPRESSED_DIAGNOSTIC_CODES.has(diag.code))
             continue;
         const sourceFile = diag.file;
         if (!sourceFile)
             continue;
-        if (!ownedAbsolute.has(sourceFile.fileName))
+        const relPath = relByAbsolute.get(sourceFile.fileName);
+        if (relPath === undefined)
             continue;
         const lineInfo = sourceFile.getLineAndCharacterOfPosition(diag.start ?? 0);
         const line = lineInfo.line + 1;
         const messageText = typeof diag.messageText === 'string'
             ? diag.messageText
             : ts.flattenDiagnosticMessageText(diag.messageText, '\n');
-        // Find the relative path for the issue
-        let relPath = sourceFile.fileName;
-        for (const [rel, abs] of [...patchOwnedFiles].map((r) => [r, resolve(repoDir, r)])) {
-            if (abs === sourceFile.fileName) {
-                relPath = rel;
-                break;
-            }
-        }
         const severity = diag.category === ts.DiagnosticCategory.Error ? 'error' : 'warning';
-        issues.push({
+        const bucket = byFile.get(relPath) ?? [];
+        bucket.push({
             file: relPath,
             check: 'checkjs-type-error',
             message: `Line ${line}: ${messageText}`,
             severity,
         });
+        byFile.set(relPath, bucket);
+    }
+    return byFile;
+}
+/**
+ * Flattens a {@link runCheckJsGrouped} run into a single issue list. When
+ * `reportScope` is supplied, only diagnostics from files in that set are
+ * returned (resolution still spans every owned file); omitting it reports
+ * every owned file's diagnostics — the historical whole-set behaviour.
+ *
+ * @param repoDir - Absolute engine (repository) directory
+ * @param patchOwnedFiles - Patch-owned `.sys.mjs` paths to resolve against
+ * @param extraShimPath - Optional project-relative extra `.d.ts`
+ * @param projectRoot - Absolute project root for resolving `extraShimPath`
+ * @param mode - Strictness preset plus allowlisted compiler-option overrides
+ * @param reportScope - When set, restrict reported diagnostics to these
+ *   repo-relative files
+ * @returns Array of lint issues from TS diagnostics
+ */
+export async function runCheckJs(repoDir, patchOwnedFiles, extraShimPath, projectRoot, mode, reportScope) {
+    const { byFile, global } = await runCheckJsGrouped(repoDir, patchOwnedFiles, extraShimPath, projectRoot, mode);
+    const issues = [...global];
+    for (const [rel, list] of byFile) {
+        if (reportScope && !reportScope.has(rel))
+            continue;
+        issues.push(...list);
     }
-    verbose(`checkJs: analyzed ${rootFiles.length - 1} file(s), found ${issues.length} issue(s)`);
     return issues;
 }
 /**
  * Invokes {@link runCheckJs} for a `patchLint` block with `checkJs: true`.
  * `projectRoot` is the FireForge project root (`dirname(engine)`).
+ *
+ * @param repoDir - Absolute engine (repository) directory
+ * @param patchOwnedFiles - Patch-owned `.sys.mjs` paths to resolve against
+ * @param patchLint - The resolved `patchLint` config block
+ * @param projectRoot - FireForge project root for shim resolution
+ * @param reportScope - Optional repo-relative files to report on (export /
+ *   re-export passes the patch under export so cross-patch resolution does
+ *   not surface other patches' diagnostics)
+ */
+export async function invokePatchLintCheckJs(repoDir, patchOwnedFiles, patchLint, projectRoot, reportScope) {
+    const strict = patchLint.checkJsStrict === true;
+    const mode = strict && patchLint.checkJsCompilerOptions
+        ? { strict, compilerOptions: patchLint.checkJsCompilerOptions }
+        : { strict };
+    return runCheckJs(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, mode, reportScope);
+}
+/**
+ * Grouped variant of {@link invokePatchLintCheckJs}: builds one queue-wide
+ * checkJs program over `patchOwnedFiles` and returns its findings grouped by
+ * owning file. The per-patch lint orchestrator calls this **once per run**
+ * and attributes each file's findings to its owning patch, instead of
+ * rebuilding the same program for every patch in the queue.
+ *
+ * @param repoDir - Absolute engine (repository) directory
+ * @param patchOwnedFiles - Every patch-owned `.sys.mjs` in the queue
+ * @param patchLint - The resolved `patchLint` config block
+ * @param projectRoot - FireForge project root for shim resolution
  */
-export async function invokePatchLintCheckJs(repoDir, patchOwnedFiles, patchLint, projectRoot) {
+export async function invokePatchLintCheckJsGrouped(repoDir, patchOwnedFiles, patchLint, projectRoot) {
     const strict = patchLint.checkJsStrict === true;
     const mode = strict && patchLint.checkJsCompilerOptions
         ? { strict, compilerOptions: patchLint.checkJsCompilerOptions }
         : { strict };
-    return runCheckJs(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, mode);
+    return runCheckJsGrouped(repoDir, patchOwnedFiles, patchLint.checkJsExtraShim, projectRoot, mode);
 }
 //# sourceMappingURL=patch-lint-checkjs.js.map

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.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[]>;