@hominis/fireforge 0.10.1 → 0.11.0

package/dist/src/core/furnace-validate-registration.d.ts

@@ -1,4 +1,4 @@
-import type { CustomComponentConfig, FurnaceConfig, RegistrationStatus, ValidationIssue } from '../types/furnace.js';
+import type { CustomComponentConfig, FurnaceConfig, RegistrationStatus, StepError, ValidationIssue } from '../types/furnace.js';
 /**
  * Validates that all Furnace-managed .mjs components are registered in the
  * DOMContentLoaded/importESModule block (Pattern B), not the loadSubScript
@@ -20,7 +20,7 @@ export declare function validateRegistrationPatterns(root: string, config: Furna
  * @param config - Custom component configuration
  * @returns Registration status with per-check booleans and drift info
  */
-export declare function checkRegistrationConsistency(root: string, name: string, config: CustomComponentConfig): Promise<RegistrationStatus>;
+export declare function checkRegistrationConsistency(root: string, name: string, config: CustomComponentConfig, ftlDir?: string): Promise<RegistrationStatus>;
 /**
  * Validates that each custom component with `register: true` has its .mjs and
  * .css entries in jar.mn.
@@ -35,3 +35,18 @@ export declare function validateJarMnEntries(root: string, config: FurnaceConfig
  * linked in browser.xhtml. Without the link, tokens silently resolve to nothing.
  */
 export declare function validateTokenLink(componentDir: string, tagName: string, root: string, tokenPrefix?: string): Promise<ValidationIssue[]>;
+/**
+ * Post-apply registration consistency check for custom components.
+ *
+ * Detects customElements.js / jar.mn inconsistencies caused by a partial
+ * apply. Errors are surfaced as step-level warnings on the affected
+ * component rather than blocking the entire apply.
+ */
+export declare function runPostApplyConsistencyChecks(root: string, config: {
+    custom: Record<string, CustomComponentConfig>;
+}, result: {
+    applied: Array<{
+        name: string;
+        stepErrors?: StepError[];
+    }>;
+}, ftlDir: string): Promise<void>;

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

@@ -8,7 +8,7 @@ import { warn } from '../utils/logger.js';
 import { stripJsComments } from '../utils/regex.js';
 import { getProjectPaths, loadConfig } from './config.js';
 import { getFurnacePaths } from './furnace-config.js';
-import { CUSTOM_ELEMENTS_JS, JAR_MN } from './furnace-constants.js';
+import { CUSTOM_ELEMENTS_JS, FTL_DIR, JAR_MN } from './furnace-constants.js';
 import { getTokensCssPath } from './token-manager.js';
 /**
  * Validates that all Furnace-managed .mjs components are registered in the
@@ -62,7 +62,7 @@ export async function validateRegistrationPatterns(root, config) {
  * @param config - Custom component configuration
  * @returns Registration status with per-check booleans and drift info
  */
-export async function checkRegistrationConsistency(root, name, config) {
+export async function checkRegistrationConsistency(root, name, config, ftlDir) {
     const { engine: engineDir } = getProjectPaths(root);
     const furnacePaths = getFurnacePaths(root);
     const componentDir = join(furnacePaths.customDir, name);
@@ -112,6 +112,30 @@ export async function checkRegistrationConsistency(root, name, config) {
     else {
         status.filesInSync = false;
     }
+    // Localized components deploy a .ftl file outside `targetDir` (into the
+    // shared Fluent tree). The .mjs/.css loop above cannot see it, so drift
+    // there would otherwise be invisible to apply's fast-path and to `status`.
+    if (config.localized) {
+        const ftlName = `${name}.ftl`;
+        const ftlSrc = join(componentDir, ftlName);
+        if (await pathExists(ftlSrc)) {
+            const ftlDest = join(engineDir, ftlDir ?? FTL_DIR, ftlName);
+            if (!(await pathExists(ftlDest))) {
+                status.missingTargetFiles.push(ftlName);
+                status.filesInSync = false;
+            }
+            else {
+                const srcContent = await readText(ftlSrc);
+                const destContent = await readText(ftlDest);
+                const srcHash = createHash('sha256').update(srcContent).digest('hex');
+                const destHash = createHash('sha256').update(destContent).digest('hex');
+                if (srcHash !== destHash) {
+                    status.driftedFiles.push(ftlName);
+                    status.filesInSync = false;
+                }
+            }
+        }
+    }
     // Check jar.mn entries
     const jarMnPath = join(engineDir, JAR_MN);
     if (await pathExists(jarMnPath)) {
@@ -153,6 +177,7 @@ export async function validateJarMnEntries(root, config) {
         return issues;
     }
     const jarContent = await readText(jarMnPath);
+    const furnacePaths = getFurnacePaths(root);
     for (const [name, customConfig] of Object.entries(config.custom)) {
         if (!customConfig.register)
             continue;
@@ -164,7 +189,13 @@ export async function validateJarMnEntries(root, config) {
                 message: `${name}.mjs is not registered in jar.mn. Run "fireforge furnace deploy" to register.`,
             });
         }
-        if (!jarContent.includes(`content/global/elements/${name}.css`)) {
+        // Only complain about a missing CSS entry when the source actually
+        // ships a CSS file. Components that intentionally have no CSS would
+        // otherwise generate a permanent false-positive that trains developers
+        // to ignore validator output.
+        const cssSourcePath = join(furnacePaths.customDir, name, `${name}.css`);
+        if ((await pathExists(cssSourcePath)) &&
+            !jarContent.includes(`content/global/elements/${name}.css`)) {
             issues.push({
                 component: name,
                 severity: 'warning',
@@ -217,4 +248,43 @@ export async function validateTokenLink(componentDir, tagName, root, tokenPrefix
     }
     return issues;
 }
+/**
+ * Post-apply registration consistency check for custom components.
+ *
+ * Detects customElements.js / jar.mn inconsistencies caused by a partial
+ * apply. Errors are surfaced as step-level warnings on the affected
+ * component rather than blocking the entire apply.
+ */
+export async function runPostApplyConsistencyChecks(root, config, result, ftlDir) {
+    for (const [name, customConfig] of Object.entries(config.custom)) {
+        if (!customConfig.register)
+            continue;
+        if (!result.applied.some((a) => a.name === name))
+            continue;
+        try {
+            const status = await checkRegistrationConsistency(root, name, customConfig, ftlDir);
+            const issues = [];
+            if (!status.customElementsPresent) {
+                issues.push('missing customElements.js registration');
+            }
+            if (!status.jarMnMjs && status.sourceExists) {
+                issues.push('missing jar.mn .mjs entry');
+            }
+            if (issues.length > 0) {
+                const entry = result.applied.find((a) => a.name === name);
+                if (entry) {
+                    const stepErrors = entry.stepErrors ?? [];
+                    stepErrors.push({
+                        step: 'post-apply consistency',
+                        error: `Registration inconsistency: ${issues.join(', ')}`,
+                    });
+                    entry.stepErrors = stepErrors;
+                }
+            }
+        }
+        catch {
+            // Consistency check is best-effort; failures here should not block apply
+        }
+    }
+}
 //# sourceMappingURL=furnace-validate-registration.js.map

package/dist/src/core/furnace-validate-structure.d.ts

@@ -1,6 +1,14 @@
-import type { ComponentType, ValidationIssue } from '../types/furnace.js';
+import type { ComponentType, CustomComponentConfig, ValidationIssue } from '../types/furnace.js';
 /**
  * Validates the file structure of a component directory.
  * Checks for required files and naming conventions.
+ *
+ * @param componentDir - Component source directory
+ * @param tagName - Component tag name
+ * @param type - Component type (stock, override, custom)
+ * @param customConfig - When `type === 'custom'`, the matching config from
+ *   furnace.json. Used to derive `localized`, which gates the `.ftl`
+ *   requirement. Optional so existing callers without config in scope (e.g.
+ *   the structure-only test fixtures) can keep calling without changes.
  */
-export declare function validateStructure(componentDir: string, tagName: string, type: ComponentType): Promise<ValidationIssue[]>;
+export declare function validateStructure(componentDir: string, tagName: string, type: ComponentType, customConfig?: CustomComponentConfig): Promise<ValidationIssue[]>;

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

@@ -1,12 +1,20 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
-import { pathExists } from '../utils/fs.js';
+import { pathExists, readText } from '../utils/fs.js';
 /**
  * Validates the file structure of a component directory.
  * Checks for required files and naming conventions.
+ *
+ * @param componentDir - Component source directory
+ * @param tagName - Component tag name
+ * @param type - Component type (stock, override, custom)
+ * @param customConfig - When `type === 'custom'`, the matching config from
+ *   furnace.json. Used to derive `localized`, which gates the `.ftl`
+ *   requirement. Optional so existing callers without config in scope (e.g.
+ *   the structure-only test fixtures) can keep calling without changes.
  */
-export async function validateStructure(componentDir, tagName, type) {
+export async function validateStructure(componentDir, tagName, type, customConfig) {
     const issues = [];
     const mjsPath = join(componentDir, `${tagName}.mjs`);
     const cssPath = join(componentDir, `${tagName}.css`);
@@ -28,8 +36,42 @@ export async function validateStructure(componentDir, tagName, type) {
             message: `No ${tagName}.css found. Consider adding styles.`,
         });
     }
+    // Localized custom components must have a {tag}.ftl file. Without one,
+    // apply silently deploys nothing for the locale and the runtime
+    // localization payload is empty, which is hard to spot in review.
+    if (type === 'custom' && customConfig?.localized) {
+        const ftlPath = join(componentDir, `${tagName}.ftl`);
+        if (!(await pathExists(ftlPath))) {
+            issues.push({
+                component: tagName,
+                severity: 'error',
+                check: 'missing-ftl',
+                message: `Component is marked localized: true but ${tagName}.ftl is missing. Create the file or set localized: false in furnace.json.`,
+            });
+        }
+    }
+    // Conflict markers left by furnace refresh (three-way merge) must be
+    // resolved before the component can be applied or deployed.
+    const dirEntries = await readdir(componentDir, { withFileTypes: true });
+    for (const entry of dirEntries) {
+        if (!entry.isFile())
+            continue;
+        if (!entry.name.endsWith('.mjs') &&
+            !entry.name.endsWith('.css') &&
+            !entry.name.endsWith('.ftl'))
+            continue;
+        const content = await readText(join(componentDir, entry.name));
+        if (/^<{7}\s/m.test(content) || /^>{7}\s/m.test(content) || /^={7}$/m.test(content)) {
+            issues.push({
+                component: tagName,
+                severity: 'error',
+                check: 'conflict-markers',
+                message: `File "${entry.name}" contains unresolved merge conflict markers. Resolve conflicts before applying.`,
+            });
+        }
+    }
     // File names should match tag name
-    const entries = await readdir(componentDir, { withFileTypes: true });
+    const entries = dirEntries;
     for (const entry of entries) {
         if (!entry.isFile())
             continue;

package/dist/src/core/furnace-validate.d.ts

@@ -1,12 +1,21 @@
 import type { ComponentType, FurnaceConfig, ValidationIssue } from '../types/furnace.js';
 /**
  * Runs all validation checks on a single component.
+ *
  * @param componentDir - Path to the component directory
  * @param tagName - Component tag name
  * @param type - Component type (stock, override, custom)
+ * @param config - Optional furnace config for cross-component checks
+ * @param root - Optional project root for checks that read outside componentDir
+ * @param options - Optional behavior flags. `skipAggregateChecks` suppresses the
+ *        per-component registration/jar.mn scan so that an outer caller
+ *        (e.g. validateAllComponents) can run the aggregate versions once
+ *        without double-reporting the same issues.
  * @returns Combined list of validation issues
  */
-export declare function validateComponent(componentDir: string, tagName: string, type: ComponentType, config?: FurnaceConfig, root?: string): Promise<ValidationIssue[]>;
+export declare function validateComponent(componentDir: string, tagName: string, type: ComponentType, config?: FurnaceConfig, root?: string, options?: {
+    skipAggregateChecks?: boolean;
+}): Promise<ValidationIssue[]>;
 /**
  * Validates all components registered in furnace.json.
  * Stock components are skipped (no local files to validate).

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

@@ -1,30 +1,60 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { pathExists } from '../utils/fs.js';
+import { loadConfig } from './config.js';
 import { getFurnacePaths, loadFurnaceConfig } from './furnace-config.js';
+import { detectComposesCycles, validateComposesReferences } from './furnace-graph-utils.js';
 import { validateAccessibility, validateCompatibility, validateJarMnEntries, validateRegistrationPatterns, validateStructure, validateTokenLink, } from './furnace-validate-checks.js';
+import { findOverrideBaseVersionDrift, } from './furnace-version-drift.js';
+function buildOverrideVersionDriftIssues(config, currentVersion, tagName) {
+    return findOverrideBaseVersionDrift(config, currentVersion)
+        .filter((entry) => tagName === undefined || entry.name === tagName)
+        .map((entry) => ({
+        component: entry.name,
+        severity: 'error',
+        check: 'override-base-version-drift',
+        message: `Override targets Firefox ${entry.baseVersion}, but fireforge.json records ${entry.currentVersion}. ` +
+            'Refresh the override if upstream changed, or update baseVersion in furnace.json to acknowledge the new baseline.',
+    }));
+}
 // ---------------------------------------------------------------------------
 // Aggregate validators
 // ---------------------------------------------------------------------------
 /**
  * Runs all validation checks on a single component.
+ *
  * @param componentDir - Path to the component directory
  * @param tagName - Component tag name
  * @param type - Component type (stock, override, custom)
+ * @param config - Optional furnace config for cross-component checks
+ * @param root - Optional project root for checks that read outside componentDir
+ * @param options - Optional behavior flags. `skipAggregateChecks` suppresses the
+ *        per-component registration/jar.mn scan so that an outer caller
+ *        (e.g. validateAllComponents) can run the aggregate versions once
+ *        without double-reporting the same issues.
  * @returns Combined list of validation issues
  */
-export async function validateComponent(componentDir, tagName, type, config, root) {
+export async function validateComponent(componentDir, tagName, type, config, root, options) {
     const issues = [];
-    issues.push(...(await validateStructure(componentDir, tagName, type)));
+    // Pass the matching custom config so structure validation can enforce
+    // the .ftl-when-localized invariant. Non-custom validations ignore the
+    // parameter, so this is a no-op for stock and override components.
+    issues.push(...(await validateStructure(componentDir, tagName, type, type === 'custom' ? config?.custom[tagName] : undefined)));
     issues.push(...(await validateAccessibility(componentDir, tagName)));
     issues.push(...(await validateCompatibility(componentDir, tagName, type, config, root)));
+    if (root && config && type === 'override') {
+        const forgeConfig = await loadConfig(root);
+        issues.push(...buildOverrideVersionDriftIssues(config, forgeConfig.firefox.version, tagName));
+    }
     // Check for missing token link in browser.xhtml
     if (root) {
         issues.push(...(await validateTokenLink(componentDir, tagName, root, config?.tokenPrefix)));
     }
     // When root is provided and this is a custom component with registration,
     // also run registration pattern and jar.mn validation for this component.
-    if (root && config && type === 'custom') {
+    // Skipped when an outer orchestrator (validateAllComponents) will run the
+    // aggregate versions itself; otherwise the same issues are reported twice.
+    if (root && config && type === 'custom' && !options?.skipAggregateChecks) {
         const customConfig = config.custom[tagName];
         if (customConfig?.register) {
             const singleConfig = {
@@ -47,6 +77,47 @@ export async function validateAllComponents(root) {
     const config = await loadFurnaceConfig(root);
     const furnacePaths = getFurnacePaths(root);
     const results = new Map();
+    // Validate composition graph integrity (dangling references and cycles)
+    try {
+        validateComposesReferences(config.stock, config.overrides, config.custom);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // 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) {
+                const existing = results.get(name) ?? [];
+                existing.push({
+                    component: name,
+                    severity: 'error',
+                    check: 'composes-dangling-reference',
+                    message,
+                });
+                results.set(name, existing);
+                break;
+            }
+        }
+    }
+    try {
+        detectComposesCycles(config.custom);
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        // 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) {
+                const existing = results.get(name) ?? [];
+                existing.push({
+                    component: name,
+                    severity: 'error',
+                    check: 'composes-cycle',
+                    message,
+                });
+                results.set(name, existing);
+                break;
+            }
+        }
+    }
     // Override components
     for (const name of Object.keys(config.overrides)) {
         const componentDir = join(furnacePaths.overridesDir, name);
@@ -79,9 +150,12 @@ export async function validateAllComponents(root) {
             continue;
         }
         // Pass root so that per-component token link validation runs.
-        // Per-component registration/jar.mn checks are also included, but that's
-        // acceptable as the aggregate validators below deduplicate by component name.
-        const issues = await validateComponent(componentDir, name, 'custom', config, root);
+        // Skip registration/jar.mn checks inside validateComponent — the aggregate
+        // validators below run them exactly once across all components, which both
+        // surfaces cross-component issues and avoids double-counting.
+        const issues = await validateComponent(componentDir, name, 'custom', config, root, {
+            skipAggregateChecks: true,
+        });
         results.set(name, issues);
     }
     // Registration pattern validation (customElements.js Pattern A vs B)

package/dist/src/core/furnace-version-drift.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Detects drift between an override's stored `baseVersion` and the current
+ * Firefox version recorded in `fireforge.json`.
+ *
+ * Overrides are forks of Firefox source files taken at a specific point in
+ * time. If Firefox moves forward and the override's `baseVersion` is not
+ * refreshed, the override may apply against a file whose upstream shape has
+ * changed — which is the single biggest silent failure mode for furnace.
+ *
+ * This module is deliberately pure and string-only: it does no I/O and does
+ * not parse Firefox version components. Comparing by string equality is
+ * sufficient because `fireforge.json` stores a canonical version string
+ * (e.g. `"146.0esr"`) and overrides are created with exactly that string
+ * copied from `forgeConfig.firefox.version`. Any string mismatch is worth
+ * surfacing — even "140.0" vs "146.0esr" is a real drift signal.
+ *
+ * The result is advisory: apply/deploy emit warnings but do not fail, and
+ * status reports drift alongside the component overview. Nothing here
+ * should be wired into a blocking code path without an operator prompt.
+ */
+import type { FurnaceConfig } from '../types/furnace.js';
+/** Severity of the version drift between an override's base and the current Firefox version. */
+export type DriftSeverity = 'major' | 'minor' | 'patch';
+export interface OverrideVersionDrift {
+    name: string;
+    /** The version the override was originally created against. */
+    baseVersion: string;
+    /** The Firefox version currently recorded in `fireforge.json`. */
+    currentVersion: string;
+    /** How severe the drift is, based on comparing version components. */
+    severity: DriftSeverity;
+}
+/**
+ * Classifies how severe a version drift is by comparing the numeric
+ * components of the two version strings. Falls back to `'major'` when
+ * either version is unparseable — this ensures that unusual version
+ * formats surface with the highest visibility rather than being silently
+ * downgraded.
+ */
+export declare function classifyDriftSeverity(baseVersion: string, currentVersion: string): DriftSeverity;
+/**
+ * Returns every override whose recorded `baseVersion` does not match the
+ * current Firefox version. Returns an empty array when everything is in
+ * sync, when there are no overrides, or when `currentVersion` is empty
+ * (the caller should surface config problems via a different path).
+ */
+export declare function findOverrideBaseVersionDrift(config: FurnaceConfig, currentVersion: string): OverrideVersionDrift[];
+/**
+ * Formats a single drift entry into a one-line human-readable warning.
+ * Kept alongside the detector so the same wording is reused by every
+ * command that surfaces drift.
+ */
+export declare function formatOverrideBaseVersionDriftWarning(entry: OverrideVersionDrift): string;
+/** Formats a blocking preflight error for one or more stale overrides. */
+export declare function formatOverrideBaseVersionDriftError(entries: OverrideVersionDrift[]): string;

package/dist/src/core/furnace-version-drift.js

@@ -0,0 +1,101 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Detects drift between an override's stored `baseVersion` and the current
+ * Firefox version recorded in `fireforge.json`.
+ *
+ * Overrides are forks of Firefox source files taken at a specific point in
+ * time. If Firefox moves forward and the override's `baseVersion` is not
+ * refreshed, the override may apply against a file whose upstream shape has
+ * changed — which is the single biggest silent failure mode for furnace.
+ *
+ * This module is deliberately pure and string-only: it does no I/O and does
+ * not parse Firefox version components. Comparing by string equality is
+ * sufficient because `fireforge.json` stores a canonical version string
+ * (e.g. `"146.0esr"`) and overrides are created with exactly that string
+ * copied from `forgeConfig.firefox.version`. Any string mismatch is worth
+ * surfacing — even "140.0" vs "146.0esr" is a real drift signal.
+ *
+ * The result is advisory: apply/deploy emit warnings but do not fail, and
+ * status reports drift alongside the component overview. Nothing here
+ * should be wired into a blocking code path without an operator prompt.
+ */
+/**
+ * Parses a version string into its major, minor, and patch numeric
+ * components. Non-numeric suffixes (e.g. "esr") are stripped. Returns
+ * `[NaN, NaN, NaN]` for unparseable strings.
+ */
+function parseVersionComponents(version) {
+    const match = /^(\d+)(?:\.(\d+))?(?:\.(\d+))?/.exec(version);
+    if (!match)
+        return [NaN, NaN, NaN];
+    return [
+        Number(match[1]),
+        match[2] !== undefined ? Number(match[2]) : 0,
+        match[3] !== undefined ? Number(match[3]) : 0,
+    ];
+}
+/**
+ * Classifies how severe a version drift is by comparing the numeric
+ * components of the two version strings. Falls back to `'major'` when
+ * either version is unparseable — this ensures that unusual version
+ * formats surface with the highest visibility rather than being silently
+ * downgraded.
+ */
+export function classifyDriftSeverity(baseVersion, currentVersion) {
+    const [baseMajor, baseMinor] = parseVersionComponents(baseVersion);
+    const [curMajor, curMinor] = parseVersionComponents(currentVersion);
+    if (isNaN(baseMajor) || isNaN(curMajor))
+        return 'major';
+    if (baseMajor !== curMajor)
+        return 'major';
+    if (baseMinor !== curMinor)
+        return 'minor';
+    return 'patch';
+}
+/**
+ * Returns every override whose recorded `baseVersion` does not match the
+ * current Firefox version. Returns an empty array when everything is in
+ * sync, when there are no overrides, or when `currentVersion` is empty
+ * (the caller should surface config problems via a different path).
+ */
+export function findOverrideBaseVersionDrift(config, currentVersion) {
+    if (!currentVersion)
+        return [];
+    const drift = [];
+    for (const [name, override] of Object.entries(config.overrides)) {
+        if (override.baseVersion && override.baseVersion !== currentVersion) {
+            drift.push({
+                name,
+                baseVersion: override.baseVersion,
+                currentVersion,
+                severity: classifyDriftSeverity(override.baseVersion, currentVersion),
+            });
+        }
+    }
+    return drift;
+}
+/**
+ * Formats a single drift entry into a one-line human-readable warning.
+ * Kept alongside the detector so the same wording is reused by every
+ * command that surfaces drift.
+ */
+export function formatOverrideBaseVersionDriftWarning(entry) {
+    const severityLabel = entry.severity === 'major'
+        ? ' (major version jump)'
+        : entry.severity === 'minor'
+            ? ' (minor version change)'
+            : ' (patch-level change)';
+    return `Override "${entry.name}" was created against Firefox ${entry.baseVersion}, but fireforge.json records ${entry.currentVersion}${severityLabel}. The upstream component may have changed — re-run "fireforge furnace validate ${entry.name}" and refresh the override if needed.`;
+}
+/** Formats a blocking preflight error for one or more stale overrides. */
+export function formatOverrideBaseVersionDriftError(entries) {
+    const names = entries.map((entry) => entry.name).sort();
+    const summary = entries.length === 1
+        ? `Override "${names[0]}" is stale against the Firefox version recorded in fireforge.json.`
+        : `${entries.length} overrides are stale against the Firefox version recorded in fireforge.json (${names.join(', ')}).`;
+    return (`${summary}\n\n` +
+        'Run "fireforge furnace refresh <name>" to merge upstream changes, ' +
+        'update baseVersion in furnace.json to acknowledge the new baseline, ' +
+        'or pass --force to proceed despite the drift.');
+}
+//# sourceMappingURL=furnace-version-drift.js.map

package/dist/src/core/git-file-ops.d.ts

@@ -48,6 +48,14 @@ export declare function unstageFiles(repoDir: string, files: string[]): Promise<
  * @returns true if file exists in HEAD
  */
 export declare function fileExistsInHead(repoDir: string, filePath: string): Promise<boolean>;
+/**
+ * Gets the content of a file at a specific git ref (HEAD by default).
+ * @param repoDir - Repository directory
+ * @param filePath - Path to the file (relative to repo)
+ * @param ref - Git ref to read from (commit hash, branch, tag). Defaults to HEAD.
+ * @returns File content or null if file doesn't exist at that ref
+ */
+export declare function getFileContentAtRef(repoDir: string, filePath: string, ref?: string): Promise<string | null>;
 /**
  * Gets the content of a file from HEAD commit.
  * @param repoDir - Repository directory

package/dist/src/core/git-file-ops.js

@@ -96,23 +96,36 @@ export async function fileExistsInHead(repoDir, filePath) {
     return (await git(['ls-tree', 'HEAD', '--', filePath], repoDir)).trim().length > 0;
 }
 /**
- * Gets the content of a file from HEAD commit.
+ * Gets the content of a file at a specific git ref (HEAD by default).
  * @param repoDir - Repository directory
  * @param filePath - Path to the file (relative to repo)
- * @returns File content or null if file doesn't exist in HEAD
+ * @param ref - Git ref to read from (commit hash, branch, tag). Defaults to HEAD.
+ * @returns File content or null if file doesn't exist at that ref
  */
-export async function getFileContentFromHead(repoDir, filePath) {
+export async function getFileContentAtRef(repoDir, filePath, ref = 'HEAD') {
     await ensureGit();
-    const result = await exec('git', ['show', `HEAD:${filePath}`], { cwd: repoDir });
+    const result = await exec('git', ['show', `${ref}:${filePath}`], { cwd: repoDir });
     if (result.exitCode !== 0) {
         const stderr = result.stderr.trim();
-        if (/exists on disk, but not in 'HEAD'|path '.*' exists, but not '.*'|path '.*' does not exist in 'HEAD'/i.test(stderr)) {
+        // Recognise the "file does not exist at this ref" variants across git versions.
+        // The ref name in quotes varies with what was passed (HEAD, a SHA, a tag), so
+        // match loosely rather than interpolating ref into a regex.
+        if (/exists on disk, but not in '[^']*'|path '[^']*' exists, but not '[^']*'|path '[^']*' does not exist in '[^']*'/i.test(stderr)) {
             return null;
         }
-        throw new GitError(stderr || 'Git command failed', `show HEAD:${filePath}`);
+        throw new GitError(stderr || 'Git command failed', `show ${ref}:${filePath}`);
     }
     return result.stdout;
 }
+/**
+ * Gets the content of a file from HEAD commit.
+ * @param repoDir - Repository directory
+ * @param filePath - Path to the file (relative to repo)
+ * @returns File content or null if file doesn't exist in HEAD
+ */
+export async function getFileContentFromHead(repoDir, filePath) {
+    return getFileContentAtRef(repoDir, filePath, 'HEAD');
+}
 /**
  * Checks if a file is binary by looking for NUL bytes in the first 8KB.
  * Uses the same heuristic as git.

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

@@ -0,0 +1,25 @@
+import type { PatchLintIssue } from '../types/commands/index.js';
+/**
+ * Diffs projected lint issues against the baseline and returns those
+ * considered "new" regressions.
+ *
+ * The equality key is the issue fingerprint when present, otherwise the
+ * full `(check, file, message)` triple. Fingerprints are emitted by rules
+ * whose message text can drift between otherwise-equivalent runs (for
+ * example because the message embeds later-owner filenames or positional
+ * detail). Falling back to the full tuple keeps the helper conservative
+ * for older/non-fingerprinted rules: if their message changes, we would
+ * rather surface a potential regression than silently swallow it.
+ *
+ * Consumption order within the projected list is stable (the input
+ * order is preserved), so when baseline has N issues for a key and
+ * projected has N+M for the same key, the *last* M projected issues on
+ * that key are reported as regressions. That keeps the reporting
+ * deterministic and gives the operator at least one concrete message
+ * per regression even when only counts differ.
+ *
+ * @param baseline - Error-severity issues from the current queue
+ * @param projected - Error-severity issues from the projected queue
+ * @returns Subset of `projected` not matched by a baseline counterpart
+ */
+export declare function computeProjectedLintRegressions(baseline: PatchLintIssue[], projected: PatchLintIssue[]): PatchLintIssue[];