@hominis/fireforge 0.31.0 → 0.33.0

package/dist/src/core/token-manager.js

@@ -9,13 +9,13 @@ import { escapeRegex } from '../utils/regex.js';
 import { validateTokenName } from '../utils/validation.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { loadFurnaceConfig } from './furnace-config.js';
-import { findTableAfterHeading, findTableByColumns, insertRow, rewriteTableRows, updateCellByKey, } from './markdown-table.js';
 import { findDarkMediaCloseIndex, findDarkRootInsertionIndex } from './token-dark-mode.js';
+import { addTokenToDocs } from './token-docs.js';
+import { insertVariantDeclaration, validateVariantSelector, variantBlockHasToken, } from './token-variant.js';
 /** Returns the token CSS path relative to engine root for a given binary name. */
 export function getTokensCssPath(binaryName) {
     return `browser/themes/shared/${binaryName}-tokens.css`;
 }
-const TOKENS_DOC = 'docs/design/SRC_TOKENS.md';
 /**
  * Determines the mode annotation string for the CSS comment.
  */
@@ -69,6 +69,49 @@ function validateDarkValue(options) {
         throw new InvalidArgumentError('Override mode requires --dark-value to be specified.', 'darkValue');
     }
 }
+/**
+ * Validates and normalizes the `--variant` attribute selector. Returns the
+ * normalized (quoted) selector when set, or `undefined` when no variant was
+ * requested. Rejects combining `--variant` with `--mode override`: an
+ * override authors a dark `@media :root` block, which variant routing
+ * bypasses, so the combination would silently drop the dark value.
+ */
+function normalizeVariantOption(options) {
+    if (options.variant === undefined)
+        return undefined;
+    if (options.mode === 'override') {
+        throw new InvalidArgumentError('Cannot combine --variant with --mode override; author the variant declaration with ' +
+            '--mode auto/static instead.', 'variant');
+    }
+    const result = validateVariantSelector(options.variant);
+    if (!result.ok) {
+        throw new InvalidArgumentError(`--variant ${result.reason}.`, 'variant');
+    }
+    return result.value;
+}
+/** Throws when the tokens CSS file is missing (variant mode skips category checks). */
+async function assertTokensCssExists(engineDir, tokensCssPath) {
+    if (!(await pathExists(join(engineDir, tokensCssPath)))) {
+        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}`);
+    }
+}
+/**
+ * Routes a declaration into the top-level `:root<variant>` block — creating
+ * the block after the base `:root` block if absent, or appending to it if
+ * present. Idempotent within the block. Returns `{ added: false }` when the
+ * token already lives in that block.
+ */
+async function addVariantTokenToCSS(engineDir, options, tokensCssPath, variant) {
+    await assertTokensCssExists(engineDir, tokensCssPath);
+    const filePath = join(engineDir, tokensCssPath);
+    const lines = (await readText(filePath)).split('\n');
+    if (variantBlockHasToken(lines, variant, options.tokenName))
+        return { added: false };
+    const annotation = getModeAnnotation(options.mode, options.value);
+    insertVariantDeclaration(lines, variant, `  ${options.tokenName}: ${options.value}; /* ${annotation} */`);
+    await writeText(filePath, lines.join('\n'));
+    return { added: true };
+}
 /**
  * True when `lines` contain a category header (single-line or multi-line
  * banner shape) naming `category`. Shared by the pre-add assertion and the
@@ -171,6 +214,12 @@ export async function validateTokenAdd(root, options) {
     validateTokenNameSyntax(options.tokenName);
     await validateTokenPrefix(root, options);
     validateDarkValue(options);
+    // Variant mode targets a `:root<attr>` block, not a category section, so it
+    // only needs the tokens CSS file to exist — category checks do not apply.
+    if (normalizeVariantOption(options) !== undefined) {
+        await assertTokensCssExists(engineDir, tokensCssPath);
+        return;
+    }
     await assertTokenCategoryExists(engineDir, tokensCssPath, options.category, options.createCategory === true);
 }
 /**
@@ -185,10 +234,21 @@ export async function addToken(root, options) {
     validateTokenNameSyntax(options.tokenName);
     await validateTokenPrefix(root, options);
     validateDarkValue(options);
+    const normalizedVariant = normalizeVariantOption(options);
     if (options.dryRun) {
         await validateTokenAdd(root, options);
         const filePath = join(engineDir, tokensCssPath);
         const content = await readText(filePath);
+        if (normalizedVariant !== undefined) {
+            const skipped = variantBlockHasToken(content.split('\n'), normalizedVariant, options.tokenName);
+            return {
+                cssAdded: !skipped,
+                docsAdded: false,
+                unmappedAdded: false,
+                countUpdated: false,
+                skipped,
+            };
+        }
         const stripped = content.replace(/\/\*[\s\S]*?\*\//g, '');
         const skipped = stripped.includes(options.tokenName + ':');
         return {
@@ -199,6 +259,20 @@ export async function addToken(root, options) {
             skipped,
         };
     }
+    // Variant overrides are CSS-only: route the declaration into the
+    // `:root<attr>` block and leave docs untouched (the base token owns its
+    // docs row). Done before the base-CSS path so an override of an existing
+    // base token is not short-circuited by the global idempotency check.
+    if (normalizedVariant !== undefined) {
+        const { added } = await addVariantTokenToCSS(engineDir, options, tokensCssPath, normalizedVariant);
+        return {
+            cssAdded: added,
+            docsAdded: false,
+            unmappedAdded: false,
+            countUpdated: false,
+            skipped: !added,
+        };
+    }
     // --- CSS file ---
     const { added: cssAdded, categoryCreated } = await addTokenToCSS(engineDir, options, tokensCssPath);
     if (!cssAdded) {
@@ -211,7 +285,7 @@ export async function addToken(root, options) {
         };
     }
     // --- Documentation ---
-    const docsResult = await addTokenToDocs(engineDir, options);
+    const docsResult = await addTokenToDocs(engineDir, options, getModeAnnotation(options.mode, options.value));
     return {
         cssAdded,
         docsAdded: docsResult.docsAdded,
@@ -381,96 +455,4 @@ async function addTokenToCSS(engineDir, options, tokensCssPath) {
     await writeText(filePath, content);
     return { added: true, categoryCreated };
 }
-/**
- * Strips surrounding backticks from a cell, if present. Token cells are
- * usually wrapped in inline code fences (`` `--foo` ``) and the parser
- * returns them verbatim.
- */
-function stripInlineCode(cell) {
-    const trimmed = cell.trim();
-    if (trimmed.startsWith('`') && trimmed.endsWith('`') && trimmed.length >= 2) {
-        return trimmed.slice(1, -1);
-    }
-    return trimmed;
-}
-/**
- * Adds a token row to the main token table, the unmapped table (for
- * literal values), and bumps the mode count table. Each sub-update runs
- * against a freshly parsed view of the document so that splice indices
- * stay valid as rewrites are layered.
- *
- * The old implementation walked `split('\n')` by hand, detected rows by
- * literal `|`-prefix, and used a whitespace-sensitive regex to increment
- * the mode count. Switching to {@link findTableByColumns} and
- * {@link updateCellByKey} removes those formatting traps.
- */
-async function addTokenToDocs(engineDir, options) {
-    const filePath = join(engineDir, '..', TOKENS_DOC);
-    if (!(await pathExists(filePath))) {
-        // Docs file is optional
-        return { docsAdded: false, unmappedAdded: false, countUpdated: false };
-    }
-    const originalContent = await readText(filePath);
-    let lines = originalContent.split('\n');
-    let docsAdded = false;
-    let unmappedAdded = false;
-    let countUpdated = false;
-    const annotation = getModeAnnotation(options.mode, options.value);
-    const isLiteral = !options.value.startsWith('var(');
-    const mapsTo = isLiteral ? '—' : options.value.replace(/var\(([^)]+)\)/, '$1');
-    const tokenCell = `\`${options.tokenName}\``;
-    const valueCell = `\`${options.value}\``;
-    // --- Main token table: Category | Token | Value | Maps to | Mode ---
-    const mainTable = findTableByColumns(lines, ['Category', 'Token', 'Value', 'Mode']);
-    if (mainTable) {
-        // The doc convention allows the Category cell to be blank on
-        // continuation rows that belong to the previous category. Group rows
-        // by carrying the last non-empty Category value forward.
-        let lastGroupRowIndex = -1;
-        let currentCategory = '';
-        for (let i = 0; i < mainTable.rows.length; i++) {
-            const row = mainTable.rows[i];
-            if (!row)
-                continue;
-            const cell = row[0]?.trim() ?? '';
-            if (cell) {
-                currentCategory = cell;
-            }
-            if (currentCategory === options.category) {
-                lastGroupRowIndex = i;
-            }
-        }
-        if (lastGroupRowIndex !== -1) {
-            insertRow(mainTable, ['', tokenCell, valueCell, mapsTo, annotation], lastGroupRowIndex + 1);
-            lines = rewriteTableRows(lines, mainTable);
-            docsAdded = true;
-        }
-    }
-    // --- Unmapped table: populated for literal (non-var()) values only ---
-    if (isLiteral) {
-        const unmappedTable = findTableAfterHeading(lines, /not yet mapped|unmapped/i);
-        if (unmappedTable) {
-            insertRow(unmappedTable, [tokenCell, valueCell, options.description ?? ''], unmappedTable.rows.length);
-            lines = rewriteTableRows(lines, unmappedTable);
-            unmappedAdded = true;
-        }
-    }
-    // --- Mode behavior count table: Mode | Count ---
-    const modeTable = findTableByColumns(lines, ['Mode', 'Count']);
-    if (modeTable) {
-        const modeIndex = modeTable.headers.indexOf('Mode');
-        const countIndex = modeTable.headers.indexOf('Count');
-        const existing = modeTable.rows.find((row) => stripInlineCode(row[modeIndex] ?? '') === options.mode);
-        if (existing) {
-            const oldCount = parseInt(existing[countIndex] ?? '0', 10);
-            const updated = updateCellByKey(modeTable, 'Mode', existing[modeIndex] ?? options.mode, 'Count', String((Number.isNaN(oldCount) ? 0 : oldCount) + 1));
-            if (updated) {
-                lines = rewriteTableRows(lines, modeTable);
-                countUpdated = true;
-            }
-        }
-    }
-    await writeText(filePath, lines.join('\n'));
-    return { docsAdded, unmappedAdded, countUpdated };
-}
 //# sourceMappingURL=token-manager.js.map

package/dist/src/core/token-variant.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Attribute-variant block helpers for the tokens CSS scaffold.
+ *
+ * `fireforge token add --mode` can author the base `:root { }` block and the
+ * dark `@media (prefers-color-scheme: dark)` block, but there was no way to
+ * target an attribute-keyed selector such as `:root[data-skin="precision"]`
+ * or `:root[data-private]` — forcing those override blocks to be hand-edited.
+ * These helpers locate (or compute the insertion point for) a top-level
+ * `:root<variant>` block so `token-manager.ts` can splice a declaration into
+ * it, keeping all token authoring in the CLI.
+ */
+/**
+ * Outcome of {@link validateVariantSelector}. `ok: true` carries the
+ * normalized (quoted) selector fragment; `ok: false` carries a
+ * human-readable reason suitable for throwing as an `InvalidArgumentError`.
+ */
+export type VariantValidation = {
+    ok: true;
+    value: string;
+} | {
+    ok: false;
+    reason: string;
+};
+/**
+ * Validates a `--variant` attribute selector fragment and normalizes any
+ * `=value` form to the double-quoted `="value"` shape (Mozilla convention).
+ * Boolean-attribute fragments are returned unchanged.
+ *
+ * @param raw - Raw `--variant` value from the CLI / programmatic caller.
+ */
+export declare function validateVariantSelector(raw: unknown): VariantValidation;
+/** True when the `:root<variant>` block already declares `tokenName`. */
+export declare function variantBlockHasToken(lines: string[], variant: string, tokenName: string): boolean;
+/**
+ * Splices `declLine` into the `:root<variant>` block, creating the block
+ * (after the base `:root` block) when absent or appending after the last
+ * non-blank line when present. Mutates `lines` in place.
+ */
+export declare function insertVariantDeclaration(lines: string[], variant: string, declLine: string): void;

package/dist/src/core/token-variant.js

@@ -0,0 +1,141 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Attribute-variant block helpers for the tokens CSS scaffold.
+ *
+ * `fireforge token add --mode` can author the base `:root { }` block and the
+ * dark `@media (prefers-color-scheme: dark)` block, but there was no way to
+ * target an attribute-keyed selector such as `:root[data-skin="precision"]`
+ * or `:root[data-private]` — forcing those override blocks to be hand-edited.
+ * These helpers locate (or compute the insertion point for) a top-level
+ * `:root<variant>` block so `token-manager.ts` can splice a declaration into
+ * it, keeping all token authoring in the CLI.
+ */
+import { findBlockCloseIndex, stripBlockCommentsInLines } from './token-dark-mode.js';
+/**
+ * Accepts a single attribute selector fragment: `[data-private]` (boolean
+ * attribute) or `[data-skin=precision]` / `[data-skin="precision"]`
+ * (attribute with value). The value half is restricted to identifier-safe
+ * characters so the fragment can be spliced into CSS verbatim without
+ * escaping concerns.
+ */
+const VARIANT_PATTERN = /^\[[a-zA-Z][a-zA-Z0-9_-]*(?:=(?:"[a-zA-Z0-9_-]+"|'[a-zA-Z0-9_-]+'|[a-zA-Z0-9_-]+))?\]$/;
+/**
+ * Validates a `--variant` attribute selector fragment and normalizes any
+ * `=value` form to the double-quoted `="value"` shape (Mozilla convention).
+ * Boolean-attribute fragments are returned unchanged.
+ *
+ * @param raw - Raw `--variant` value from the CLI / programmatic caller.
+ */
+export function validateVariantSelector(raw) {
+    if (typeof raw !== 'string') {
+        return { ok: false, reason: 'must be a string when set' };
+    }
+    const value = raw.trim();
+    if (!VARIANT_PATTERN.test(value)) {
+        return {
+            ok: false,
+            reason: 'must be a single attribute selector like [data-private] or [data-skin=precision] ' +
+                '(identifier-safe attribute name and value only)',
+        };
+    }
+    const normalized = value
+        .replace(/='([a-zA-Z0-9_-]+)'\]$/, '="$1"]')
+        .replace(/=([a-zA-Z0-9_-]+)\]$/, '="$1"]');
+    return { ok: true, value: normalized };
+}
+/**
+ * Reduces a `:root<attr>` selector to a quote- and whitespace-insensitive
+ * canonical form so `[data-skin="precision"]`, `[data-skin='precision']`,
+ * and `[data-skin=precision]` all compare equal when matching an existing
+ * block against the requested variant.
+ */
+function canonicalSelector(selector) {
+    return selector.replace(/\s+/g, '').replace(/["']/g, '');
+}
+/**
+ * Finds the top-level `:root<variant>` block whose attribute selector
+ * matches `variant` (compared canonically). Returns the opening-brace and
+ * closing-brace line indices, or `null` when no such block exists.
+ *
+ * Scans a comment-stripped mirror of `lines` so braces inside comments do
+ * not offset the depth counter; the returned indices line up with the
+ * original array.
+ */
+function findVariantBlock(lines, variant) {
+    const stripped = stripBlockCommentsInLines(lines);
+    const want = canonicalSelector(`:root${variant}`);
+    for (let i = 0; i < stripped.length; i++) {
+        const line = stripped[i] ?? '';
+        const match = /:root\[[^{]*\]/.exec(line);
+        if (!match || canonicalSelector(match[0]) !== want)
+            continue;
+        let openLine = /\{/.test(line) ? i : -1;
+        if (openLine === -1) {
+            for (let j = i + 1; j < stripped.length; j++) {
+                const next = stripped[j] ?? '';
+                if (/\{/.test(next)) {
+                    openLine = j;
+                    break;
+                }
+                if (/[};]/.test(next))
+                    break;
+            }
+        }
+        if (openLine === -1)
+            continue;
+        const close = findBlockCloseIndex(stripped, openLine);
+        if (close === -1)
+            continue;
+        return { open: openLine, close };
+    }
+    return null;
+}
+/**
+ * Returns the line index at which a brand-new `:root<variant>` block should
+ * be spliced: immediately after the base `:root { }` block's closing brace
+ * (so attribute variants sit between the base block and any dark `@media`
+ * block). Falls back to end-of-file when no base `:root` block is found.
+ */
+function findVariantBlockInsertionPoint(lines) {
+    const stripped = stripBlockCommentsInLines(lines);
+    for (let i = 0; i < stripped.length; i++) {
+        if (/^\s*:root\s*\{/.test(stripped[i] ?? '')) {
+            const close = findBlockCloseIndex(stripped, i);
+            if (close !== -1)
+                return close + 1;
+        }
+    }
+    return lines.length;
+}
+/** True when the `:root<variant>` block already declares `tokenName`. */
+export function variantBlockHasToken(lines, variant, tokenName) {
+    const block = findVariantBlock(lines, variant);
+    if (!block)
+        return false;
+    const blockText = lines
+        .slice(block.open, block.close + 1)
+        .join('\n')
+        .replace(/\/\*[\s\S]*?\*\//g, '');
+    return blockText.includes(`${tokenName}:`);
+}
+/**
+ * Splices `declLine` into the `:root<variant>` block, creating the block
+ * (after the base `:root` block) when absent or appending after the last
+ * non-blank line when present. Mutates `lines` in place.
+ */
+export function insertVariantDeclaration(lines, variant, declLine) {
+    const block = findVariantBlock(lines, variant);
+    if (block) {
+        let insertIndex = block.close;
+        for (let i = block.close - 1; i > block.open; i--) {
+            if ((lines[i] ?? '').trim()) {
+                insertIndex = i + 1;
+                break;
+            }
+        }
+        lines.splice(insertIndex, 0, declLine);
+        return;
+    }
+    lines.splice(findVariantBlockInsertionPoint(lines), 0, '', `:root${variant} {`, declLine, '}');
+}
+//# sourceMappingURL=token-variant.js.map

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/core/typecheck.js

@@ -84,42 +84,70 @@ export async function runTypecheck(projectRoot, cfg) {
             filesChecked: 0,
         }));
     }
-    // Compose the shim once — extraShim is shared across all projects.
-    // A missing or unreadable shim is a project-wide failure, so we
-    // surface it as one issue per project rather than letting one
-    // project's read failure silently affect the others' results.
-    let shimSource;
-    try {
-        const composed = await composeShimSource(projectRoot, cfg.extraShim);
-        shimSource = composed.source;
+    // Compose the shim PER project: the effective extraShim is the per-project
+    // override (a path, or `null` to opt out) when present, else the shared
+    // top-level extraShim. A project that narrows `lib`/`types` can opt out of
+    // a Gecko-lib shim hub that another project needs, so the composed shim is
+    // no longer injected identically everywhere. Compositions are cached by the
+    // resolved extraShim path so projects sharing a shim don't recompose it.
+    const shimCache = new Map();
+    const composeForProject = async (extraShim) => {
+        const key = extraShim ?? '';
+        const cached = shimCache.get(key);
+        if (cached !== undefined)
+            return cached;
+        const composed = await composeShimSource(projectRoot, extraShim);
         if (composed.extraShimAppended) {
-            verbose(`typecheck: extra shim ${cfg.extraShim ?? ''} appended to Firefox globals shim`);
+            verbose(`typecheck: extra shim ${extraShim ?? ''} appended to Firefox globals shim`);
         }
-    }
-    catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
-        return cfg.projects.map((project) => ({
-            project,
-            issues: [
-                {
-                    file: cfg.extraShim ?? '(typecheck)',
-                    line: 1,
-                    column: 1,
-                    code: 0,
-                    category: 'error',
-                    message,
-                    project,
-                },
-            ],
-            filesChecked: 0,
-        }));
-    }
+        shimCache.set(key, composed.source);
+        return composed.source;
+    };
     const results = [];
     for (const projectPath of cfg.projects) {
+        const extraShim = resolveProjectExtraShim(cfg, projectPath);
+        let shimSource;
+        try {
+            shimSource = await composeForProject(extraShim);
+        }
+        catch (err) {
+            // A missing or unreadable shim fails only the project(s) that use it,
+            // not the whole run — projects with a different (or no) shim still run.
+            const message = err instanceof Error ? err.message : String(err);
+            results.push({
+                project: projectPath,
+                issues: [
+                    {
+                        file: extraShim ?? '(typecheck)',
+                        line: 1,
+                        column: 1,
+                        code: 0,
+                        category: 'error',
+                        message,
+                        project: projectPath,
+                    },
+                ],
+                filesChecked: 0,
+            });
+            continue;
+        }
         results.push(await runTypecheckForProject(ts, projectRoot, projectPath, shimSource));
     }
     return results;
 }
+/**
+ * Resolves the effective extra shim for a single project: a `projectOverrides`
+ * entry wins (a string path overrides; `null` opts out → `undefined`), else
+ * the shared top-level `extraShim` applies.
+ */
+function resolveProjectExtraShim(cfg, projectPath) {
+    const overrides = cfg.projectOverrides;
+    if (overrides && Object.prototype.hasOwnProperty.call(overrides, projectPath)) {
+        const value = overrides[projectPath];
+        return value === null ? undefined : value;
+    }
+    return cfg.extraShim;
+}
 /** Runs typecheck for a single jsconfig path, isolating its failures. */
 async function runTypecheckForProject(ts, projectRoot, projectPath, shimSource) {
     const absConfig = resolve(projectRoot, projectPath);

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
@@ -696,6 +705,11 @@ export interface TokenAddOptions {
     dryRun?: boolean;
     /** Declare the category banner in the tokens CSS when it does not exist yet. */
     createCategory?: boolean;
+    /**
+     * Attribute selector fragment (e.g. `[data-skin=precision]` or
+     * `[data-private]`) routing the declaration into a `:root<variant>` block.
+     */
+    variant?: string;
 }
 /**
  * Options for the doctor command.
@@ -774,6 +788,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