@hominis/fireforge 0.15.1 → 0.15.3

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

@@ -0,0 +1,83 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Diff-scoping for `fireforge lint`.
+ *
+ * Pre-existing patch-state errors and errors introduced by the current task
+ * print identically today, so triaging "is the diff I just produced clean?"
+ * requires mentally subtracting the pre-existing noise. This module
+ * classifies each lint issue as either `introduced` (the file was touched
+ * since the user-supplied git revision) or `cumulative` (pre-existing
+ * drift), without changing what the underlying rules emit.
+ */
+import { toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { isMissingHeadError } from './git.js';
+import { git } from './git-base.js';
+import { getUntrackedFiles } from './git-status.js';
+/**
+ * Collects engine-relative paths that changed between `rev` and `HEAD`,
+ * plus any workdir modifications and untracked files. An empty set means
+ * "no diff we can prove" — downstream treats every issue as `cumulative`
+ * in that case (operator ran `lint --since HEAD` with no pending work).
+ * @param engineDir Path to the engine git repository.
+ * @param rev Git revision to diff against (e.g. `HEAD`, a branch, a SHA).
+ */
+export async function collectDiffFilePaths(engineDir, rev) {
+    const files = new Set();
+    try {
+        const commitDiff = await git(['diff', '--name-only', `${rev}...HEAD`], engineDir);
+        for (const line of commitDiff.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed)
+                files.add(trimmed);
+        }
+    }
+    catch (error) {
+        if (!isMissingHeadError(error)) {
+            verbose(`lint --since: could not diff against ${rev} — ${toError(error).message}`);
+        }
+    }
+    try {
+        const worktreeDiff = await git(['diff', '--name-only', 'HEAD'], engineDir);
+        for (const line of worktreeDiff.split('\n')) {
+            const trimmed = line.trim();
+            if (trimmed)
+                files.add(trimmed);
+        }
+    }
+    catch (error) {
+        verbose(`lint --since: could not enumerate workdir diff — ${toError(error).message}`);
+    }
+    try {
+        for (const file of await getUntrackedFiles(engineDir)) {
+            files.add(file);
+        }
+    }
+    catch (error) {
+        verbose(`lint --since: could not list untracked files — ${toError(error).message}`);
+    }
+    return files;
+}
+/**
+ * Annotates a list of lint issues with `introduced` / `cumulative` tags
+ * based on whether the issue's file is part of the supplied diff set.
+ * Mutates each issue in place AND returns the list for chaining.
+ *
+ * Issues with no file (`issue.file === ''`) — e.g. cross-patch rules that
+ * describe queue-wide state — are always `cumulative` under `--since`
+ * because they describe drift accumulated across many commits, not a
+ * single current-task edit.
+ * @param issues Issues returned by the lint orchestrator.
+ * @param diffFiles File paths touched since the user's revision.
+ */
+export function tagLintIssues(issues, diffFiles) {
+    for (const issue of issues) {
+        if (!issue.file) {
+            issue.tag = 'cumulative';
+            continue;
+        }
+        issue.tag = diffFiles.has(issue.file) ? 'introduced' : 'cumulative';
+    }
+    return issues;
+}
+//# sourceMappingURL=patch-lint-diff-tag.js.map

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

@@ -110,12 +110,14 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
     // Load furnace config gracefully — skip token-prefix check if unavailable
     let tokenPrefix;
     let tokenAllowlist;
+    let runtimeVariables;
     try {
         const root = join(repoDir, '..');
         const furnaceConfig = await loadFurnaceConfig(root);
         if (furnaceConfig.tokenPrefix) {
             tokenPrefix = furnaceConfig.tokenPrefix;
             tokenAllowlist = new Set(furnaceConfig.tokenAllowlist ?? []);
+            runtimeVariables = new Set(furnaceConfig.runtimeVariables ?? []);
         }
     }
     catch (error) {
@@ -154,20 +156,38 @@ export async function lintPatchedCss(repoDir, affectedFiles, diffContent, config
                 });
             }
         }
-        // Check for non-tokenized custom properties
+        // 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).
         if (tokenPrefix) {
+            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 varPattern = /var\(\s*(--[\w-]+)/g;
             let match;
             while ((match = varPattern.exec(cssContent)) !== null) {
                 const prop = match[1];
-                if (prop && !prop.startsWith(tokenPrefix) && !tokenAllowlist?.has(prop)) {
-                    issues.push({
-                        file,
-                        check: 'token-prefix-violation',
-                        message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token or add to tokenAllowlist.`,
-                        severity: 'error',
-                    });
-                }
+                if (!prop)
+                    continue;
+                if (prop.startsWith(tokenPrefix))
+                    continue;
+                if (tokenAllowlist?.has(prop))
+                    continue;
+                if (runtimeVariables?.has(prop))
+                    continue;
+                if (localDeclarations.has(prop))
+                    continue;
+                issues.push({
+                    file,
+                    check: 'token-prefix-violation',
+                    message: `CSS references var(${prop}) which does not match the required token prefix "${tokenPrefix}". Use a design token, add to tokenAllowlist, or (for runtime state channels) list the variable in runtimeVariables.`,
+                    severity: 'error',
+                });
             }
         }
     }

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

@@ -271,6 +271,31 @@ export interface FurnaceCreateOptions {
     register?: boolean;
     /** Scaffold Mochitest directory and register in moz.build */
     withTests?: boolean;
+    /**
+     * Scaffold an xpcshell test harness (headless, no tabbrowser) instead of
+     * browser-chrome. Required for forks without a `tabbrowser` (storage-only
+     * code, observer-driven modules). Implies `withTests` when set. Writes an
+     * `xpcshell.toml` + `test_<name>.js` under
+     * `engine/browser/base/content/test/<binary-name>-xpcshell/` and leaves
+     * moz.build registration to the operator (add the directory to
+     * `XPCSHELL_TESTS_MANIFESTS`).
+     */
+    xpcshell?: boolean;
+    /**
+     * Test harness style to scaffold when `--with-tests` is set.
+     *
+     * - `mochikit` (default when `--with-tests` is set alone) — a MochiKit
+     *   test at `engine/toolkit/content/tests/widgets/test_<tag>.html` that
+     *   loads the component module directly via `chrome://global/` and
+     *   asserts against `customElements`. Runs today on forks whose
+     *   top-level chrome document (e.g. `mybrowser.xhtml`) lacks a
+     *   `tabbrowser`, because it doesn't go through `URILoadingHelper`.
+     * - `browser-chrome` — today's browser-mochitest scaffold, requires a
+     *   working tabbrowser. Use for components that talk to the browser
+     *   window or open URLs.
+     * - `xpcshell` — equivalent to setting `--xpcshell`; headless, storage-only.
+     */
+    testStyle?: 'mochikit' | 'browser-chrome' | 'xpcshell';
     /** Stock component tag names composed internally by this component */
     compose?: string[];
 }

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

@@ -96,4 +96,13 @@ export interface PatchLintIssue {
     message: string;
     /** Severity: errors block export, warnings are advisory, notices are informational (not counted) */
     severity: 'error' | 'warning' | 'notice';
+    /**
+     * Diff-scoping tag populated by `lint --since <rev>`. Absent when the
+     * caller did not request diff-scoping.
+     *
+     * - `introduced` — the issue's file was touched in the diff since `<rev>`.
+     * - `cumulative` — the issue is pre-existing patch-state drift not
+     *   introduced by the current task.
+     */
+    tag?: 'introduced' | 'cumulative';
 }

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

@@ -47,7 +47,7 @@ export interface FireForgeConfig {
     /**
      * Project marker prefix appended to lines FireForge writes into
      * upstream Firefox source files (e.g. the `customElements.js` tag list).
-     * `"HOMINIS"` emits a trailing `  // HOMINIS:` on each inserted line.
+     * `"MYBROWSER"` emits a trailing `  // MYBROWSER:` on each inserted line.
      * Keeps modifications discoverable and re-applies idempotent.
      */
     markerComment?: string;

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

@@ -63,10 +63,21 @@ export interface FurnaceConfig {
     tokenPrefix?: string;
     /** Custom properties allowed even though they don't match tokenPrefix (e.g. ["--background-color-box"]) */
     tokenAllowlist?: string[];
+    /**
+     * Custom properties used as runtime state channels — written and read by the
+     * component itself (e.g. per-frame camera/tile positions) rather than
+     * consumed as design tokens. Listed names are exempt from the
+     * `token-prefix-violation` check even when they do not match `tokenPrefix`
+     * and are not in `tokenAllowlist`. Use this for cross-component runtime
+     * variables (e.g. set in JS, read in CSS of a child). Component-local
+     * variables that are both declared and consumed inside the same component's
+     * own CSS file are auto-exempted and do not need an entry here.
+     */
+    runtimeVariables?: string[];
     /**
      * Chrome documents scanned by the `missing-token-link` validator to confirm
      * the tokens CSS file is `<link>`ed. Forks with multiple chrome host
-     * documents (e.g. `hominis.xhtml` beside the stock `browser.xhtml`) should
+     * documents (e.g. `mybrowser.xhtml` beside the stock `browser.xhtml`) should
      * list every document that may own the link. When omitted, defaults to
      * `['browser/base/content/browser.xhtml']` — the upstream Firefox path.
      */
@@ -95,7 +106,7 @@ export interface FurnaceConfig {
  * state before clearing authoring markers. The string is surfaced in doctor's
  * failure message verbatim, so new entries should be self-explanatory.
  */
-export type FurnacePendingRepairOperation = 'preview-teardown' | 'apply-rollback' | 'deploy-rollback' | 'remove-rollback' | 'create-rollback' | 'override-rollback' | 'scan-rollback' | 'rename-rollback' | 'refresh-rollback';
+export type FurnacePendingRepairOperation = 'preview-teardown' | 'apply-rollback' | 'deploy-rollback' | 'remove-rollback' | 'create-rollback' | 'override-rollback' | 'scan-rollback' | 'rename-rollback' | 'refresh-rollback' | 'chrome-doc-rollback';
 /**
  * Marker persisted into `.fireforge/furnace-state.json` when a furnace
  * mutation failed to roll back cleanly. Its presence tells the next

package/package.json

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