@hominis/fireforge 0.32.0 → 0.33.0

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.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

@@ -705,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.

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

@@ -129,6 +129,19 @@ export interface TypecheckConfig {
      * built-in shim first, extraShim second — augment, don't redeclare.
      */
     extraShim?: string;
+    /**
+     * Per-project override of {@link extraShim}, keyed by the project's path
+     * exactly as it appears in {@link projects}. A string value points the
+     * project at a different `.d.ts`; `null` opts the project out of the shared
+     * extra shim entirely (it absorbs only the built-in Firefox globals shim).
+     *
+     * Needed because the shared shim is injected into every project: a shim hub
+     * that references Gecko declaration libs (`lib.gecko.dom.d.ts`, …) is wanted
+     * by projects that include it but collides with a project that narrows
+     * `lib: ["ES2024", "DOM"]` (Element/Node identity splits, nsIPrincipal
+     * mismatch). A narrowed project sets `null` here to stay clean.
+     */
+    projectOverrides?: Record<string, string | null>;
 }
 /**
  * Wire command configuration.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.32.0",
+  "version": "0.33.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -63,7 +63,7 @@
   "devDependencies": {
     "@eslint/js": "^10.0.0",
     "@types/estree": "^1.0.8",
-    "@types/node": "^25.5.2",
+    "@types/node": "^26.0.0",
     "@vitest/coverage-v8": "^4.1.2",
     "dpdm": "4.2.0",
     "eslint": "^10.0.0",
@@ -72,7 +72,7 @@
     "eslint-plugin-simple-import-sort": "^13.0.0",
     "fast-check": "^4.6.0",
     "husky": "^9.1.7",
-    "knip": "6.16.1",
+    "knip": "6.17.1",
     "lint-staged": "^17.0.4",
     "prettier": "^3.7.4",
     "tsx": "^4.7.0",