@hominis/fireforge 0.39.0 → 0.40.0

package/dist/src/core/status-classify.js

@@ -47,7 +47,14 @@ export function getPrimaryStatusCode(status) {
     }
     return status;
 }
-function isGeneratedBrandingPath(file, binaryName) {
+/**
+ * True for the branding paths whose content FireForge generates itself
+ * (configure.sh, brand.properties/ftl, browser/moz.configure). Unlike the
+ * broader branding-root test, a brand-new unowned file under the branding
+ * directory is NOT generated — it is a patch candidate and must stay
+ * visible as unmanaged (the Assets.car precedent).
+ */
+export function isGeneratedBrandingPath(file, binaryName) {
     const normalized = file.replace(/\\/g, '/');
     const brandingRoot = `browser/branding/${binaryName}`;
     return (normalized === 'browser/moz.configure' ||
@@ -64,13 +71,14 @@ function isGeneratedBrandingPath(file, binaryName) {
  * deletion the patch does not expect, or a failed comparison) reports
  * `patch-owned-drift`.
  */
-async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassification) {
+async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassification, owner) {
     if (getPrimaryStatusCode(entry.status) === 'D') {
         // Deleted file: content matches only if the patch expects deletion
         const expected = await computePatchedContent(patchesDir, engineDir, entry.file);
         return {
             ...entry,
             classification: expected === null ? matchClassification : 'patch-owned-drift',
+            owner,
         };
     }
     // File exists on disk — compare actual vs expected
@@ -82,11 +90,12 @@ async function classifySingleOwnerFile(entry, engineDir, patchesDir, matchClassi
         return {
             ...entry,
             classification: actual === expected ? matchClassification : 'patch-owned-drift',
+            owner,
         };
     }
     catch (error) {
         verbose(`Treating ${entry.file} as patch-owned drift because patch-backed classification failed: ${toError(error).message}`);
-        return { ...entry, classification: 'patch-owned-drift' };
+        return { ...entry, classification: 'patch-owned-drift', owner };
     }
 }
 /**
@@ -146,8 +155,8 @@ export async function classifyFiles(files, engineDir, patchesDir, binaryName, fu
                 // `furnace`. Multi-owner and unowned furnace paths keep the
                 // short-circuit — the ownership table independently flags
                 // filesAffected conflicts.
-                if (owners && owners.length === 1) {
-                    results.push(await classifySingleOwnerFile(entry, engineDir, patchesDir, 'furnace'));
+                if (owners && owners.length === 1 && owners[0] !== undefined) {
+                    results.push(await classifySingleOwnerFile(entry, engineDir, patchesDir, 'furnace', owners[0]));
                 }
                 else {
                     results.push({ ...entry, classification: 'furnace' });
@@ -174,7 +183,12 @@ export async function classifyFiles(files, engineDir, patchesDir, binaryName, fu
             continue;
         }
         // File is claimed by exactly one patch — compare content.
-        results.push(await classifySingleOwnerFile(entry, engineDir, patchesDir, 'patch-backed'));
+        const owner = owners[0];
+        if (owner === undefined) {
+            results.push({ ...entry, classification: 'unmanaged' });
+            continue;
+        }
+        results.push(await classifySingleOwnerFile(entry, engineDir, patchesDir, 'patch-backed', owner));
     }
     return results;
 }

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

@@ -0,0 +1,40 @@
+/**
+ * True when `lines` contain a category header (single-line or multi-line
+ * banner shape) whose name EQUALS `category`. Shared by the pre-add
+ * assertion, the banner creation path, and the section finder so all
+ * agree on what "exists" means.
+ */
+export declare function categoryHeaderExists(lines: string[], category: string): boolean;
+/**
+ * Asserts the category banner exists (or that creation was requested).
+ * Throws a GeneralError naming the available categories and the
+ * `--create-category` remedy otherwise.
+ */
+export declare function assertTokenCategoryExists(engineDir: string, tokensCssPath: string, category: string, createCategory?: boolean): Promise<void>;
+/**
+ * Splices a new single-line category banner ("= Name =" comment shape, the
+ * same format `discoverCategoryHeaders` recognises) just before the closing
+ * brace of the `:root` block, making the new category the last section.
+ * Mutates `lines` in place.
+ */
+export declare function declareCategoryBanner(lines: string[], category: string, tokensCssPath: string): void;
+/** Locates and bounds the named category section. Throws when absent. */
+export declare function findCategorySection(lines: string[], category: string, tokensCssPath: string): {
+    categoryLine: number;
+    sectionEnd: number;
+};
+/** Location of an existing base-`:root` token declaration. */
+export interface TokenDeclarationLocation {
+    /** 1-based line number in the tokens CSS file. */
+    line: number;
+    /** Nearest enclosing category banner name, when one precedes the declaration. */
+    category?: string;
+}
+/**
+ * Finds an existing declaration of `tokenName` inside the base `:root`
+ * block. Dark `@media` and `:root[variant]` companion blocks are
+ * deliberately excluded — they mirror the base declaration, they do not
+ * own the token. Comment content never matches, and the name match is
+ * exact (`--foo-bar` does not match `--x-foo-bar`).
+ */
+export declare function findTokenDeclarationInRoot(lines: string[], tokenName: string): TokenDeclarationLocation | undefined;

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

@@ -0,0 +1,264 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Category banner and token-declaration helpers for the tokens CSS file
+ * (FORGE G3). Split out of `token-manager.ts` to stay inside the per-file
+ * line budget.
+ *
+ * Banner matching is EXACT: the text between the `=` runs (single-line
+ * shape) or on the block line (multi-line shape) must equal the category
+ * after trimming. The pre-0.40.0 substring match let a TOC comment or a
+ * longer banner (`Colors — Canvas` for `Colors`) satisfy the lookup, so
+ * `token add` wrote into the wrong section — or no-oped for 19
+ * consecutive calls — with exit 0.
+ */
+import { join } from 'node:path';
+import { GeneralError } from '../errors/base.js';
+import { pathExists, readText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
+function singleLineBannerPattern(category) {
+    return new RegExp(`\\/\\*\\s*=+\\s*${escapeRegex(category)}\\s*=+\\s*\\*\\/`);
+}
+function multiLineBlockNameMatches(blockLine, category) {
+    return blockLine.replace(/^\s*\*\s*/, '').trim() === category;
+}
+/**
+ * True when `lines` contain a category header (single-line or multi-line
+ * banner shape) whose name EQUALS `category`. Shared by the pre-add
+ * assertion, the banner creation path, and the section finder so all
+ * agree on what "exists" means.
+ */
+export function categoryHeaderExists(lines, category) {
+    const singleLinePattern = singleLineBannerPattern(category);
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (singleLinePattern.test(line)) {
+            return true;
+        }
+        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                const blockLine = lines[j] ?? '';
+                if (multiLineBlockNameMatches(blockLine, category)) {
+                    return true;
+                }
+                if (/\*\//.test(blockLine))
+                    break;
+            }
+        }
+    }
+    return false;
+}
+/**
+ * Scans a tokens CSS file for category header comments and returns the
+ * category names in document order. Used to enrich the "category not
+ * found" error body with concrete alternatives the operator can copy.
+ *
+ * Mirrors the shapes `findCategorySection` recognises:
+ * - Single-line: `/* = Foo = *\/`
+ * - Multi-line: `/* =====` opening, `Foo` on any of the next ~5 lines,
+ *   closing `*\/`.
+ *
+ * This helper exists as a pure inspector; it never throws on malformed
+ * headers and silently skips shapes it cannot parse.
+ */
+function discoverCategoryHeaders(lines) {
+    const categories = new Set();
+    const singleLinePattern = /\/\*\s*=+\s*(.+?)\s*=+\s*\*\//;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        const singleMatch = singleLinePattern.exec(line);
+        if (singleMatch?.[1]) {
+            const extracted = singleMatch[1].trim();
+            if (extracted.length > 0)
+                categories.add(extracted);
+            continue;
+        }
+        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                const blockLine = lines[j] ?? '';
+                if (/\*\//.test(blockLine))
+                    break;
+                const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
+                if (trimmed.length === 0)
+                    continue;
+                if (/^=+$/.test(trimmed))
+                    continue;
+                categories.add(trimmed);
+                break;
+            }
+        }
+    }
+    return [...categories];
+}
+/**
+ * Asserts the category banner exists (or that creation was requested).
+ * Throws a GeneralError naming the available categories and the
+ * `--create-category` remedy otherwise.
+ */
+export async function assertTokenCategoryExists(engineDir, tokensCssPath, category, createCategory = false) {
+    const filePath = join(engineDir, tokensCssPath);
+    if (!(await pathExists(filePath))) {
+        throw new GeneralError(`Token CSS file not found: ${tokensCssPath}`);
+    }
+    const content = await readText(filePath);
+    const lines = content.split('\n');
+    if (categoryHeaderExists(lines, category))
+        return;
+    // The write path declares the banner in the same edit as the token
+    // insertion, so a missing category is fine when creation was requested.
+    if (createCategory)
+        return;
+    const discoveredCategories = discoverCategoryHeaders(lines);
+    const available = discoveredCategories.length > 0
+        ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
+        : 'The file currently has no category headers.';
+    throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
+        `${available}\n\n` +
+        'Categories are declared by comment headers. Single-line shape: /* = My Category = */. ' +
+        'Multi-line shape: /* =============\\n * My Category\\n * ============= */.\n\n' +
+        'Re-run with --create-category to declare the banner and insert the token in one step.');
+}
+/**
+ * Splices a new single-line category banner ("= Name =" comment shape, the
+ * same format `discoverCategoryHeaders` recognises) just before the closing
+ * brace of the `:root` block, making the new category the last section.
+ * Mutates `lines` in place.
+ */
+export function declareCategoryBanner(lines, category, tokensCssPath) {
+    const bounds = findBaseRootBounds(lines);
+    if (bounds === null) {
+        throw new GeneralError(`Cannot create category "${category}": no :root block found in ${tokensCssPath}. ` +
+            'Run "fireforge furnace init --force" to re-scaffold the tokens CSS file.');
+    }
+    if (bounds.close === -1) {
+        throw new GeneralError(`Cannot create category "${category}": the :root block in ${tokensCssPath} never closes.`);
+    }
+    lines.splice(bounds.close, 0, '', `  /* = ${category} = */`);
+}
+/** Locates and bounds the named category section. Throws when absent. */
+export function findCategorySection(lines, category, tokensCssPath) {
+    const singleLinePattern = singleLineBannerPattern(category);
+    let categoryLine = -1;
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        // Check single-line format: /* = Category = */
+        if (singleLinePattern.test(line)) {
+            categoryLine = i;
+            break;
+        }
+        // Check multi-line format: line opens a block comment with === but does NOT close it
+        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                const blockLine = lines[j] ?? '';
+                if (multiLineBlockNameMatches(blockLine, category)) {
+                    categoryLine = i;
+                    break;
+                }
+                if (/\*\//.test(blockLine))
+                    break;
+            }
+            if (categoryLine !== -1)
+                break;
+        }
+    }
+    if (categoryLine === -1) {
+        const discoveredCategories = discoverCategoryHeaders(lines);
+        const available = discoveredCategories.length > 0
+            ? `Available categories in the file: ${discoveredCategories.map((name) => `"${name}"`).join(', ')}.`
+            : 'The file currently has no category headers.';
+        throw new GeneralError(`Category "${category}" not found in ${tokensCssPath}.\n\n` +
+            `${available}\n\n` +
+            'Add a header by hand inside the :root block (format: "/* = My Category = */") or re-run "fireforge furnace init --force" to re-seed the default categories.');
+    }
+    // Find the end of this category section (next section header or closing })
+    // Skip past the current header block first
+    let scanStart = categoryLine + 1;
+    for (let i = categoryLine + 1; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (/^\s*\/\*\s*=/.test(line) || /^\s*\*\s*=/.test(line) || /^\s*\*\//.test(line)) {
+            scanStart = i + 1;
+            continue;
+        }
+        break;
+    }
+    let sectionEnd = lines.length;
+    for (let i = scanStart; i < lines.length; i++) {
+        const line = lines[i] ?? '';
+        if (/\/\*\s*=.*=\s*\*\//.test(line) ||
+            (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) ||
+            /^\s*\}/.test(line)) {
+            sectionEnd = i;
+            break;
+        }
+    }
+    return { categoryLine, sectionEnd };
+}
+/** 0-based open/close line indices of the base `:root {` block. */
+function findBaseRootBounds(lines) {
+    let open = -1;
+    for (let i = 0; i < lines.length; i++) {
+        if (/:root\s*\{/.test(lines[i] ?? '')) {
+            open = i;
+            break;
+        }
+    }
+    if (open === -1)
+        return null;
+    for (let i = open + 1; i < lines.length; i++) {
+        if (/^\s*\}/.test(lines[i] ?? '')) {
+            return { open, close: i };
+        }
+    }
+    return { open, close: -1 };
+}
+/** Masks block-comment content per line so declarations inside comments never match. */
+function maskCommentLines(lines) {
+    const masked = lines.join('\n').replace(/\/\*[\s\S]*?\*\//g, (m) => m.replace(/[^\n]/g, ' '));
+    return masked.split('\n');
+}
+/**
+ * Finds an existing declaration of `tokenName` inside the base `:root`
+ * block. Dark `@media` and `:root[variant]` companion blocks are
+ * deliberately excluded — they mirror the base declaration, they do not
+ * own the token. Comment content never matches, and the name match is
+ * exact (`--foo-bar` does not match `--x-foo-bar`).
+ */
+export function findTokenDeclarationInRoot(lines, tokenName) {
+    const bounds = findBaseRootBounds(lines);
+    if (bounds === null || bounds.close === -1)
+        return undefined;
+    const masked = maskCommentLines(lines);
+    const declPattern = new RegExp(`^\\s*${escapeRegex(tokenName)}\\s*:`);
+    for (let i = bounds.open + 1; i < bounds.close; i++) {
+        if (!declPattern.test(masked[i] ?? ''))
+            continue;
+        const category = findSectionNameAbove(lines, i);
+        return category === undefined ? { line: i + 1 } : { line: i + 1, category };
+    }
+    return undefined;
+}
+/** Nearest category banner name above `lineIndex`, if any. */
+function findSectionNameAbove(lines, lineIndex) {
+    const singleLinePattern = /\/\*\s*=+\s*(.+?)\s*=+\s*\*\//;
+    for (let i = lineIndex - 1; i >= 0; i--) {
+        const line = lines[i] ?? '';
+        const singleMatch = singleLinePattern.exec(line);
+        if (singleMatch?.[1]) {
+            const extracted = singleMatch[1].trim();
+            if (extracted.length > 0 && !/^=+$/.test(extracted))
+                return extracted;
+            continue;
+        }
+        if (/^\s*\/\*\s*=+/.test(line) && !/\*\//.test(line)) {
+            for (let j = i + 1; j < Math.min(i + 6, lines.length); j++) {
+                const blockLine = lines[j] ?? '';
+                if (/\*\//.test(blockLine))
+                    break;
+                const trimmed = blockLine.replace(/^\s*\*\s*/, '').trim();
+                if (trimmed.length === 0 || /^=+$/.test(trimmed))
+                    continue;
+                return trimmed;
+            }
+        }
+    }
+    return undefined;
+}

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

@@ -1,3 +1,4 @@
+import { type TokenDeclarationLocation } from './token-category.js';
 /**
  * Dark mode behavior for a token.
  */
@@ -47,6 +48,12 @@ export interface AddTokenResult {
     skipped: boolean;
     /** Whether a new category banner was declared by this add. */
     categoryCreated?: boolean;
+    /**
+     * When the add skipped because the token already lives in the TARGET
+     * category, names where the existing base-`:root` declaration sits so
+     * the skip message can point at it (FORGE G3).
+     */
+    skippedExisting?: TokenDeclarationLocation;
 }
 /** Returns the token CSS path relative to engine root for a given binary name. */
 export declare function getTokensCssPath(binaryName: string): string;