@hominis/fireforge 0.39.0 → 0.41.0

package/dist/src/core/furnace-registration-ast.js

@@ -10,7 +10,7 @@ import { toError } from '../utils/errors.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
 import { escapeRegex } from '../utils/regex.js';
-import { detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
+import { asEstree, detectIndent, getNodeSource, parseScript, walkAST, } from './ast-utils.js';
 import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
 import { validateRegistrationPlacement, validateTagName } from './furnace-registration-validate.js';
 /**
@@ -62,7 +62,7 @@ function isInsideDOMContentLoaded(ancestors, content) {
         const ancestor = ancestors[i];
         if (!ancestor || ancestor.type !== 'CallExpression')
             continue;
-        const call = ancestor;
+        const call = asEstree(ancestor);
         if (call.callee.type === 'MemberExpression' &&
             call.callee.object.type === 'Identifier' &&
             call.callee.object.name === 'document' &&
@@ -87,18 +87,18 @@ function collectArrayDeclarations(ast) {
         enter(node) {
             if (node.type !== 'VariableDeclarator')
                 return;
-            const declarator = node;
+            const declarator = asEstree(node);
             if (declarator.id.type !== 'Identifier' || declarator.init?.type !== 'ArrayExpression') {
                 return;
             }
-            arrays.set(declarator.id.name, declarator.init);
+            arrays.set(declarator.id.name, asEstree(declarator.init));
         },
     });
     return arrays;
 }
 function resolveForOfArray(right, declaredArrays) {
     if (right.type === 'ArrayExpression') {
-        return right;
+        return asEstree(right);
     }
     if (right.type === 'Identifier') {
         return declaredArrays.get(right.name);
@@ -148,7 +148,7 @@ function addRegistrationAST(content, tagName, modulePath, isESModule, markerComm
         enter(node) {
             ancestors.push(node);
             if (node.type === 'ForOfStatement') {
-                const forOf = node;
+                const forOf = asEstree(node);
                 const array = resolveForOfArray(forOf.right, declaredArrays);
                 if (array) {
                     forOfs.push({
@@ -170,7 +170,7 @@ function addRegistrationAST(content, tagName, modulePath, isESModule, markerComm
     for (const el of array.elements) {
         if (!el || el.type !== 'ArrayExpression')
             continue;
-        const entryArr = el;
+        const entryArr = asEstree(el);
         const firstEl = entryArr.elements[0];
         if (!firstEl || firstEl.type !== 'Literal')
             continue;
@@ -181,7 +181,7 @@ function addRegistrationAST(content, tagName, modulePath, isESModule, markerComm
         const indent = detectIndent(content, entryArr.start);
         let innerIndent;
         if (isMultiLine) {
-            const firstElNode = firstEl;
+            const firstElNode = asEstree(firstEl);
             innerIndent = detectIndent(content, firstElNode.start);
         }
         entries.push({ tag, node: entryArr, isMultiLine, indent, innerIndent });

package/dist/src/core/furnace-registration-remove.js

@@ -25,7 +25,7 @@
 import { join } from 'node:path';
 import MagicString from 'magic-string';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-import { parseScript, walkAST } from './ast-utils.js';
+import { asEstree, parseScript, walkAST } from './ast-utils.js';
 import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
 /**
  * Expands `[start, end)` to consume a trailing comma and any whitespace up
@@ -147,7 +147,7 @@ function collectRemovalRanges(ast, content, tagName) {
             }
             // Standalone call: customElements.setElementCreationCallback(tag, …)
             if (node.type === 'CallExpression') {
-                const call = node;
+                const call = asEstree(node);
                 if (isStandaloneCallbackCallFor(call, tagName)) {
                     // Find the enclosing statement so we can delete `call(...);` as
                     // a unit, not just the call expression body.
@@ -158,7 +158,7 @@ function collectRemovalRanges(ast, content, tagName) {
                             continue;
                         if (ancestor.type === 'ExpressionStatement' ||
                             ancestor.type === 'VariableDeclaration') {
-                            enclosing = ancestor;
+                            enclosing = asEstree(ancestor);
                             break;
                         }
                     }
@@ -203,6 +203,9 @@ export async function removeCustomElementRegistration(engineDir, tagName) {
         ast = parseScript(content);
     }
     catch {
+        // An unparsable customElements.js is left untouched on purpose: this
+        // function only removes registrations, and editing a file it cannot parse
+        // risks corrupting it. The caller's regex fallback handles the retry.
         return;
     }
     const ranges = collectRemovalRanges(ast, content, tagName);

package/dist/src/core/furnace-registration.js

@@ -2,10 +2,6 @@
 import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
 import { pathExists, readText, writeText } from '../utils/fs.js';
-/** Escapes special regex characters in a literal string. */
-function escapeForRegex(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 /**
  * Detects the indentation used by existing `content/global/elements/` lines
  * in jar.mn. Falls back to 3 spaces (the historical Firefox convention) when
@@ -22,6 +18,7 @@ function detectJarMnIndent(lines) {
 }
 // Re-export everything from the AST module so existing imports keep working
 export { addCustomElementRegistration, removeCustomElementRegistration, validateCustomElementRegistration, } from './furnace-registration-ast.js';
+import { escapeRegex } from '../utils/regex.js';
 import { JAR_MN } from './furnace-constants.js';
 /**
  * Adds jar.mn entries that map chrome:// URIs to on-disk paths for a
@@ -66,7 +63,7 @@ export async function addJarMnEntries(engineDir, tagName, files) {
     const lines = content.split('\n');
     // Filter to files not already registered. Use a word-boundary-aware
     // check so that "moz-card.css" does not match "moz-card-group.css".
-    const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeForRegex(f)}(?:\\s|$)`, 'm').test(content));
+    const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeRegex(f)}(?:\\s|$)`, 'm').test(content));
     if (newFiles.length === 0)
         return 0;
     // Build new entry lines using the indent detected from existing entries.
@@ -141,8 +138,8 @@ export async function addLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName, c
     const content = await readText(filePath);
     const lines = content.split('\n');
     const ftlFile = `${tagName}.ftl`;
-    const escapedTag = escapeForRegex(tagName);
-    const escapedChrome = escapeForRegex(chromeSubPath);
+    const escapedTag = escapeRegex(tagName);
+    const escapedChrome = escapeRegex(chromeSubPath);
     const presencePattern = new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapedChrome}\\/${escapedTag}\\.ftl`, 'm');
     if (presencePattern.test(content)) {
         return 0;
@@ -176,7 +173,7 @@ export async function addLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName, c
 }
 /** Detects locale jar.mn indentation by sampling an existing matching entry. */
 function detectLocaleJarMnIndent(lines, chromeSubPath) {
-    const escapedChrome = escapeForRegex(chromeSubPath);
+    const escapedChrome = escapeRegex(chromeSubPath);
     const pattern = new RegExp(`^(\\s+)locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapedChrome}\\/`);
     for (const line of lines) {
         const match = pattern.exec(line);
@@ -202,7 +199,7 @@ export async function removeLocaleFtlJarMnEntry(engineDir, jarMnRelPath, tagName
     }
     const content = await readText(filePath);
     const lines = content.split('\n');
-    const pattern = new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapeForRegex(chromeSubPath)}\\/${escapeForRegex(tagName)}\\.ftl`);
+    const pattern = new RegExp(`locale\\/(?:@AB_CD@|[a-zA-Z-]+)\\/${escapeRegex(chromeSubPath)}\\/${escapeRegex(tagName)}\\.ftl`);
     const filtered = lines.filter((line) => !pattern.test(line));
     if (filtered.length === lines.length)
         return;
@@ -232,8 +229,8 @@ export async function removeJarMnEntries(engineDir, tagName) {
     // report). The legacy target-path match is kept as an OR for lines
     // written by older FireForge versions without a source mapping. Word
     // boundaries keep "moz-card" from matching "moz-card-group".
-    const sourcePattern = new RegExp(`\\(widgets/${escapeForRegex(tagName)}/`);
-    const legacyTargetPattern = new RegExp(`content/global/elements/${escapeForRegex(tagName)}\\.`);
+    const sourcePattern = new RegExp(`\\(widgets/${escapeRegex(tagName)}/`);
+    const legacyTargetPattern = new RegExp(`content/global/elements/${escapeRegex(tagName)}\\.`);
     const filtered = lines.filter((line) => !sourcePattern.test(line) && !legacyTargetPattern.test(line));
     if (filtered.length === lines.length)
         return;
@@ -296,7 +293,7 @@ export async function validateJarMnInsertionForFiles(engineDir, tagName, files)
     }
     const content = await readText(filePath);
     const lines = content.split('\n');
-    const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeForRegex(f)}(?:\\s|$)`, 'm').test(content));
+    const newFiles = files.filter((f) => !new RegExp(`content/global/elements/${escapeRegex(f)}(?:\\s|$)`, 'm').test(content));
     if (newFiles.length === 0)
         return;
     const elementLinePattern = /^\s+content\/global\/elements\/([^.]+)\./;

package/dist/src/core/furnace-rollback.js

@@ -108,7 +108,7 @@ export async function restoreRollbackJournal(journal) {
             catch (error) {
                 errors.push({
                     path: filePath,
-                    error: error instanceof Error ? error.message : String(error),
+                    error: toError(error).message,
                 });
             }
         }

package/dist/src/core/furnace-scanner.js

@@ -2,6 +2,7 @@
 import { createHash } from 'node:crypto';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
 import { asEstree, getNodeSource, parseScript, walkAST } from './ast-utils.js';
@@ -116,7 +117,7 @@ export async function scanCustomElementsRegistrations(engineDir) {
         // Best-effort scanner: if upstream syntax changes or the file is damaged,
         // fall back to the old literal callback heuristic instead of failing the
         // whole scan command.
-        const reason = parseError instanceof Error ? parseError.message : String(parseError);
+        const reason = toError(parseError).message;
         warn(`AST parsing of customElements.js failed (${reason}). Falling back to regex-based heuristic. ` +
             'Results may be incomplete — run "fireforge furnace validate" to verify registration consistency.');
         verbose(`Scanner regex fallback activated due to parse error: ${reason}`);

package/dist/src/core/furnace-stale-export.js

@@ -20,6 +20,7 @@
  * block non-furnace patch work.
  */
 import { GeneralError } from '../errors/base.js';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { verbose, warn } from '../utils/logger.js';
 import { extractComponentChecksums, hasComponentChanged } from './furnace-apply-helpers.js';
@@ -89,7 +90,7 @@ export async function findStaleFurnaceComponentsForFiles(projectRoot, files) {
         return stale;
     }
     catch (error) {
-        verbose(`Stale-furnace export gate skipped due to an error: ${error instanceof Error ? error.message : String(error)}`);
+        verbose(`Stale-furnace export gate skipped due to an error: ${toError(error).message}`);
         return [];
     }
 }

package/dist/src/core/furnace-state-persist.d.ts

@@ -21,14 +21,13 @@
  * <name>` had exactly this bug while `furnace deploy <name>` documented
  * and avoided it).
  */
-import { type applyAllComponents } from './furnace-apply.js';
+import { type ApplyAllComponentsResult } from './furnace-apply.js';
 import { type getFurnacePaths } from './furnace-config.js';
-type ApplyAllResult = Awaited<ReturnType<typeof applyAllComponents>>;
 /**
  * Counts applied entries that carry at least one BLOCKING step error
  * (advisory step errors are warnings and never fail a run).
  */
-export declare function getStepFailureCount(result: ApplyAllResult): number;
+export declare function getStepFailureCount(result: ApplyAllComponentsResult): number;
 /**
  * Decides whether a single-component apply/deploy completed cleanly enough
  * to persist its checksums into furnace-state.json.
@@ -40,7 +39,7 @@ export declare function getStepFailureCount(result: ApplyAllResult): number;
  * future refactor cannot drift them apart and accidentally persist partial
  * state.
  */
-export declare function shouldPersistSingleComponentState(result: ApplyAllResult, isDryRun: boolean): boolean;
+export declare function shouldPersistSingleComponentState(result: ApplyAllComponentsResult, isDryRun: boolean): boolean;
 /**
  * Validates and narrows the applied entry a named run should persist.
  *
@@ -52,7 +51,7 @@ export declare function shouldPersistSingleComponentState(result: ApplyAllResult
  *
  * @param commandLabel - Human label for error messages ("Deploy", "Apply")
  */
-export declare function getPersistableAppliedEntry(commandLabel: string, name: string, appliedEntry: ApplyAllResult['applied'][number] | undefined): {
+export declare function getPersistableAppliedEntry(commandLabel: string, name: string, appliedEntry: ApplyAllComponentsResult['applied'][number] | undefined): {
     name: string;
     type: 'override' | 'custom';
 };
@@ -69,4 +68,3 @@ export declare function persistSingleComponentState(projectRoot: string, applied
     name: string;
     type: 'override' | 'custom';
 }, furnacePaths: ReturnType<typeof getFurnacePaths>): Promise<void>;
-export {};

package/dist/src/core/furnace-validate-compatibility.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
-import { hasRawCssColors } from '../utils/regex.js';
+import { escapeRegex, hasRawCssColors } from '../utils/regex.js';
 import { classExtendsMozLitElement, collectCssVariableDeclarations, collectCssVariableReferences, createIssue, getTokenPrefixContext, hasCustomElementDefineCall, hasRelativeModuleImport, stripCssBlockComments, } from './furnace-validate-helpers.js';
 async function validateMjsCompatibility(mjsPath, tagName, isLibrary) {
     if (!(await pathExists(mjsPath)))
@@ -78,22 +78,19 @@ async function validateCssCompatibility(cssPath, tagName, type, config, root) {
  */
 function isReferencedAsElement(source, tagName) {
     // Match as an HTML element: <tagName or </tagName
-    const htmlPattern = new RegExp(`</?${escapeForValidation(tagName)}[\\s/>]`);
+    const htmlPattern = new RegExp(`</?${escapeRegex(tagName)}[\\s/>]`);
     if (htmlPattern.test(source))
         return true;
     // Match as a CSS tag selector: standalone word at start of line or after combinators
-    const cssPattern = new RegExp(`(?:^|[\\s,>+~])${escapeForValidation(tagName)}(?:[\\s,{:>+~.[#]|$)`, 'm');
+    const cssPattern = new RegExp(`(?:^|[\\s,>+~])${escapeRegex(tagName)}(?:[\\s,{:>+~.[#]|$)`, 'm');
     if (cssPattern.test(source))
         return true;
     // Also accept querySelector/querySelectorAll('tagName') as intentional usage
-    const querySelectorPattern = new RegExp(`querySelector(?:All)?\\(\\s*["'\`]${escapeForValidation(tagName)}(?:[\\s"'\`.,>+~:[#])`);
+    const querySelectorPattern = new RegExp(`querySelector(?:All)?\\(\\s*["'\`]${escapeRegex(tagName)}(?:[\\s"'\`.,>+~:[#])`);
     if (querySelectorPattern.test(source))
         return true;
     return false;
 }
-function escapeForValidation(str) {
-    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
-}
 /**
  * Validates that composed tags declared in furnace.json are actually referenced
  * in the component's source (.mjs and .css) in an HTML template or CSS context.

package/dist/src/core/furnace-validate-helpers.js

@@ -180,10 +180,42 @@ function isClickOnSyntheticInteractive(content, clickIndex) {
     }
     return !NATIVE_CLICK_INTERACTIVE_TAGS.has(tagName);
 }
+/** ASCII punctuation that reads as decoration rather than localizable text. */
+const SYMBOL_ONLY_ASCII = '+-*=<>|/\\^~@#&!?%';
+/**
+ * Reports whether `text` is decoration (arrows, maths, emoji, bare
+ * punctuation) rather than user-facing prose that needs localizing.
+ *
+ * The letter/number/mark test comes first and is script-agnostic. Until
+ * 0.41.0 the only non-ASCII rule was `code > 0xff`, which classified *every*
+ * code point above U+00FF as a symbol — so all CJK, Cyrillic, Greek, Arabic,
+ * Hebrew, Devanagari and Thai text was exempted from a **localization**
+ * validator, i.e. the rule was blind to precisely the strings most likely to
+ * need translating.
+ *
+ * Combining marks are deliberately NOT counted as text: the check is an
+ * `every()`, so a script's base letters already disqualify the string, and
+ * treating marks as text would flag emoji carrying a variation selector
+ * (U+FE0F is category Mn — `⚙️` is U+2699 + U+FE0F).
+ *
+ * High code points that are not letters — emoji, arrows, CJK punctuation —
+ * stay exempt, which is the rule's original intent.
+ *
+ * A handful of emoji are ALSO Unicode letters, and the letter test alone gets
+ * them wrong. U+2139 (`ℹ`, the base of the very common `ℹ️`) is category Ll, so
+ * the `\p{L}` branch classified an info badge as prose needing localization.
+ * Non-ASCII code points carrying `Emoji` are therefore read as symbols before
+ * the letter test. The ASCII guard matters: `\p{Emoji}` also covers the digits
+ * `0`-`9`, `#` and `*`, which must keep their existing classification.
+ */
 function isSymbolOnlyText(text) {
     return Array.from(text).every((character) => {
         const code = character.codePointAt(0) ?? 0;
-        return code > 0xff || '+-*=<>|/\\^~@#&!?%'.includes(character);
+        if (code > 0x7f && /\p{Emoji}/u.test(character))
+            return true;
+        if (/[\p{L}\p{N}]/u.test(character))
+            return false;
+        return code > 0xff || SYMBOL_ONLY_ASCII.includes(character);
     });
 }
 function isWithinLocalizedElement(content, matchIndex) {

package/dist/src/core/furnace-validate-registration.js

@@ -35,6 +35,18 @@ export async function validateRegistrationPatterns(root, config) {
     for (const [name, customConfig] of Object.entries(config.custom)) {
         if (!customConfig.register)
             continue;
+        // A component that is not mentioned at all is a distinct defect from one
+        // registered in the wrong block: `--fix` can repair the former (idempotent
+        // insert) but deliberately refuses the latter (moving code between blocks).
+        if (!isTagAlreadyRegistered(content, name)) {
+            issues.push({
+                component: name,
+                severity: 'error',
+                check: 'missing-custom-element-registration',
+                message: `${name} has register: true but no registration in ${CUSTOM_ELEMENTS_JS}. Run "fireforge furnace validate ${name} --fix" to add it.`,
+            });
+            continue;
+        }
         const stripped = stripJsComments(content);
         const tagPattern = new RegExp(`["']${escapeRegex(name)}["']`);
         if (tagPattern.test(stripped) && !isTagInCorrectCustomElementsPlacement(content, name, true)) {
@@ -268,6 +280,8 @@ async function autoDetectTokenHostDocuments(engineDir, tagName, already) {
         entries = await readdir(contentDir);
     }
     catch {
+        // No readable chrome-document directory means no documents reference the
+        // tag, which is the same verdict as an empty directory.
         return [];
     }
     const alreadySet = new Set(already);
@@ -284,6 +298,8 @@ async function autoDetectTokenHostDocuments(engineDir, tagName, already) {
             content = await readText(absPath);
         }
         catch {
+            // An unreadable chrome document cannot be searched for the tag; skip it and
+            // keep scanning the rest.
             continue;
         }
         if (content.includes(tagName)) {

package/dist/src/core/furnace-validate.js

@@ -1,6 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
+import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { getFurnacePaths, loadFurnaceConfig, loadFurnaceState } from './furnace-config.js';
@@ -109,7 +110,7 @@ export async function validateAllComponents(root) {
         validateComposesReferences(config.stock, config.overrides, config.custom);
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
+        const message = toError(err).message;
         // Attribute the issue to the first custom component with a bad composes reference
         for (const [name, cfg] of Object.entries(config.custom)) {
             if (cfg.composes) {
@@ -129,7 +130,7 @@ export async function validateAllComponents(root) {
         detectComposesCycles(config.custom);
     }
     catch (err) {
-        const message = err instanceof Error ? err.message : String(err);
+        const message = toError(err).message;
         // Attribute the cycle issue to the first custom component in the cycle
         for (const name of Object.keys(config.custom)) {
             if (config.custom[name]?.composes) {
@@ -274,6 +275,7 @@ async function findOrphanXpcshellScaffolds(root, config) {
         entries = dirents.filter((d) => d.isDirectory()).map((d) => d.name);
     }
     catch {
+        // An unreadable parent directory yields no sibling component dirs.
         return [];
     }
     const known = new Set([

package/dist/src/core/git-diff.js

@@ -460,6 +460,15 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
     // stage/unstage pair mutates the index, so it must not interleave with
     // another concurrent binary patch (see runWithBinaryStagingLock).
     return runWithBinaryStagingLock(async () => {
+        // Snapshot the path's exact index entry before touching it. The cleanup
+        // used to be a blanket `git reset HEAD -- <file>`, which restores the
+        // path to its HEAD state — for a path absent from HEAD that means
+        // *removing* whatever entry the index carried, so any staged state that
+        // arrived between the read-only diff above and this staging block (a
+        // concurrent writer, or a staged-add whose worktree file was deleted)
+        // was silently discarded (FORGE H1). Restoring the captured entry
+        // instead makes the cleanup exact regardless of how the entry got there.
+        const priorEntry = (await execGitWithAllowedExitCodes(repoDir, ['ls-files', '--stage', '--', filePath])).stdout;
         try {
             await execGitWithAllowedExitCodes(repoDir, ['add', '--intent-to-add', '--', filePath]);
             const diffResult = await execGitWithAllowedExitCodes(repoDir, [
@@ -471,8 +480,34 @@ export async function generateBinaryFilePatch(repoDir, filePath) {
             return diffResult.stdout;
         }
         finally {
-            // Always unstage, even if diff fails
-            await execGitWithAllowedExitCodes(repoDir, ['reset', 'HEAD', '--', filePath]);
+            await restoreIndexEntry(repoDir, filePath, priorEntry);
         }
     });
 }
+/**
+ * Restores a path's index entry to a previously captured `ls-files --stage`
+ * snapshot after a temporary `--intent-to-add` staging. No prior entry means
+ * the temporary entry is dropped via `reset HEAD` (the path's HEAD state IS
+ * "absent" — this branch only runs for files untracked in HEAD). A prior
+ * stage-0 entry is re-pointed at its recorded mode and blob. Unmerged entries
+ * (stages 1–3) cannot be rebuilt through `--cacheinfo`; that degenerate state
+ * keeps the legacy reset-to-HEAD behavior rather than corrupting the conflict.
+ * @param repoDir - Repository directory
+ * @param filePath - File path (relative to repo root)
+ * @param priorEntry - Raw `git ls-files --stage -- <file>` output from before staging
+ */
+async function restoreIndexEntry(repoDir, filePath, priorEntry) {
+    const entryMatch = /^(\d{6}) ([0-9a-f]{4,64}) 0\t/.exec(priorEntry.trim());
+    const mode = entryMatch?.[1];
+    const oid = entryMatch?.[2];
+    if (mode === undefined || oid === undefined) {
+        await execGitWithAllowedExitCodes(repoDir, ['reset', 'HEAD', '--', filePath]);
+        return;
+    }
+    await execGitWithAllowedExitCodes(repoDir, [
+        'update-index',
+        '--add',
+        '--cacheinfo',
+        `${mode},${oid},${filePath}`,
+    ]);
+}

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

@@ -1,11 +1,15 @@
 import type { PatchLintIssue, PatchMetadata } from '../types/commands/index.js';
 import type { FireForgeConfig } from '../types/config.js';
 import { type PatchQueueContext } from './patch-lint.js';
-export declare const LINT_CACHE_SCHEMA_VERSION = 1;
+export declare const LINT_CACHE_SCHEMA_VERSION = 3;
 export interface PerPatchLintCacheEntry {
     key: string;
     patchFilename: string;
     issues: PatchLintIssue[];
+    /** Issues dropped by the patch's lintIgnore waivers (FORGE G10). */
+    suppressed: PatchLintIssue[];
+    /** Non-binary diff line count measured by the cached lint run. */
+    lineCount: number;
     updatedAt: string;
 }
 export interface PerPatchLintCacheFile {
@@ -36,7 +40,13 @@ export declare function loadPerPatchLintCache(projectRoot: string): Promise<PerP
 export declare function savePerPatchLintCache(projectRoot: string, cache: PerPatchLintCacheFile): Promise<void>;
 /** Clears the per-patch lint cache by replacing it with an empty document. */
 export declare function clearPerPatchLintCache(projectRoot: string): Promise<void>;
-/** Returns cached issues for a patch when the stored key still matches. */
-export declare function getCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string): PatchLintIssue[] | undefined;
-/** Stores per-patch lint issues after a successful lint calculation. */
-export declare function setCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string, issues: PatchLintIssue[]): void;
+/** Cached per-patch lint payload returned on a key match. */
+export interface CachedPerPatchLint {
+    issues: PatchLintIssue[];
+    suppressed: PatchLintIssue[];
+    lineCount: number;
+}
+/** Returns the cached lint payload for a patch when the stored key still matches. */
+export declare function getCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string): CachedPerPatchLint | undefined;
+/** Stores the per-patch lint payload after a successful lint calculation. */
+export declare function setCachedPerPatchLintIssues(cache: PerPatchLintCacheFile, patchFilename: string, key: string, issues: PatchLintIssue[], suppressed: PatchLintIssue[], lineCount: number): void;

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

@@ -7,7 +7,15 @@ import { getPackageVersion } from '../utils/package-root.js';
 import { getFurnacePaths } from './furnace-config.js';
 import { git } from './git-base.js';
 import { collectNewFileCreatorsByPath } from './patch-lint.js';
-export const LINT_CACHE_SCHEMA_VERSION = 1;
+// Schema 2 (FORGE G10): entries additionally carry the lintIgnore-suppressed
+// issues and the measured non-binary line count, so a warm run can report
+// waived size measurements identically to a cold one (the F5-class hazard:
+// a cache hit must never surface LESS than a fresh lint).
+// Schema 3 (FORGE H2): the key additionally content-hashes the
+// `patchLint.checkJsTestShim` file exactly as `checkJsExtraShim`'s already
+// was — before this, editing the test shim in place replayed every cached
+// verdict (the same warm-run-reports-less-than-cold hazard class).
+export const LINT_CACHE_SCHEMA_VERSION = 3;
 const LINT_IMPLEMENTATION_VERSION = 1;
 const LINT_CACHE_DIRNAME = 'lint-cache';
 const PER_PATCH_CACHE_FILENAME = 'per-patch-v1.json';
@@ -81,28 +89,44 @@ function buildOwnershipFingerprint(files, ctx) {
  * The key includes source, metadata, config, engine state, and ownership inputs.
  */
 export async function buildPerPatchLintCacheKey(input) {
+    // Hash in parallel, then insert in sorted order. The sort is load-bearing:
+    // `stableHash` below serialises this record, so insertion order is part of
+    // the cache key — assigning as results land would make the key
+    // nondeterministic. Hashing was strictly sequential until 0.41.0, in the hot
+    // path of the cache whose entire purpose is making lint faster.
+    const sortedFiles = [...input.existingFiles].sort((a, b) => a.localeCompare(b));
+    const hashes = await Promise.all(sortedFiles.map((file) => fileHash(join(input.engineDir, file))));
     const engineFiles = {};
-    for (const file of [...input.existingFiles].sort((a, b) => a.localeCompare(b))) {
-        engineFiles[file] = await fileHash(join(input.engineDir, file));
-    }
+    hashes.forEach((hash, index) => {
+        const file = sortedFiles[index];
+        if (file !== undefined)
+            engineFiles[file] = hash;
+    });
     const furnaceConfigPath = getFurnacePaths(input.projectRoot).furnaceConfig;
-    const extraShimPath = input.config.patchLint?.checkJsExtraShim;
-    const extraShim = extraShimPath === undefined
+    const shimHashOf = async (shimPath) => shimPath === undefined
         ? null
-        : {
-            path: extraShimPath,
-            hash: await fileHash(resolve(input.projectRoot, extraShimPath)),
-        };
+        : { path: shimPath, hash: await fileHash(resolve(input.projectRoot, shimPath)) };
+    // Both shims feed compiled checkJs programs, so both are content-hashed —
+    // the config block alone only carries their PATHS, and an in-place edit
+    // must invalidate the programs it feeds (FORGE H2).
+    const [extraShim, testShim] = await Promise.all([
+        shimHashOf(input.config.patchLint?.checkJsExtraShim),
+        shimHashOf(input.config.patchLint?.checkJsTestShim),
+    ]);
     return stableHash({
         cacheSchemaVersion: LINT_CACHE_SCHEMA_VERSION,
         engineHeadSha: input.engineHeadSha ?? null,
         lintImplementationVersion: LINT_IMPLEMENTATION_VERSION,
+        // Deliberately the PLAIN semver, not the +g<sha> build identity
+        // (FORGE K2): identity churns every commit at the same version and
+        // would invalidate the cache for no correctness gain.
         packageVersion: input.packageVersion ?? getPackageVersion(),
         patchFile: await fileHash(join(input.patchesDir, input.patch.filename)),
         patchMetadata: normalizePatchMetadata(input.patch),
         lintConfig: normalizeLintConfig(input.config),
         furnaceConfig: await fileHash(furnaceConfigPath),
         checkJsExtraShim: extraShim,
+        checkJsTestShim: testShim,
         engineFiles,
         queueOwnership: buildOwnershipFingerprint(input.existingFiles, input.queueContext),
     });
@@ -118,6 +142,8 @@ function isCacheEntry(value) {
     return (typeof entry.key === 'string' &&
         typeof entry.patchFilename === 'string' &&
         Array.isArray(entry.issues) &&
+        Array.isArray(entry.suppressed) &&
+        typeof entry.lineCount === 'number' &&
         typeof entry.updatedAt === 'string');
 }
 /** Loads the per-patch lint cache, treating missing or invalid files as empty. */
@@ -144,6 +170,9 @@ export async function loadPerPatchLintCache(projectRoot) {
         return { schemaVersion: LINT_CACHE_SCHEMA_VERSION, entries };
     }
     catch {
+        // Any unreadable or malformed cache file is treated as a cold cache. The
+        // cache is a pure optimisation, so discarding it is always safe — the
+        // alternative is failing lint over a corrupt sidecar.
         return createEmptyPerPatchLintCache();
     }
 }
@@ -158,19 +187,25 @@ export async function savePerPatchLintCache(projectRoot, cache) {
 export async function clearPerPatchLintCache(projectRoot) {
     await writeJson(getPerPatchLintCachePath(projectRoot), createEmptyPerPatchLintCache());
 }
-/** Returns cached issues for a patch when the stored key still matches. */
+/** Returns the cached lint payload for a patch when the stored key still matches. */
 export function getCachedPerPatchLintIssues(cache, patchFilename, key) {
     const entry = cache.entries[patchFilename];
     if (!entry || entry.key !== key)
         return undefined;
-    return entry.issues.map((issue) => ({ ...issue }));
+    return {
+        issues: entry.issues.map((issue) => ({ ...issue })),
+        suppressed: entry.suppressed.map((issue) => ({ ...issue })),
+        lineCount: entry.lineCount,
+    };
 }
-/** Stores per-patch lint issues after a successful lint calculation. */
-export function setCachedPerPatchLintIssues(cache, patchFilename, key, issues) {
+/** Stores the per-patch lint payload after a successful lint calculation. */
+export function setCachedPerPatchLintIssues(cache, patchFilename, key, issues, suppressed, lineCount) {
     cache.entries[patchFilename] = {
         key,
         patchFilename,
         issues: issues.map((issue) => ({ ...issue })),
+        suppressed: suppressed.map((issue) => ({ ...issue })),
+        lineCount,
         updatedAt: new Date().toISOString(),
     };
 }