@hominis/fireforge 0.39.0 → 0.41.0

package/dist/src/core/test-stale-check.js

@@ -23,13 +23,11 @@
  * plugin, etc.) can legitimately have a fresh `dist/` with no
  * FireForge-recorded baseline update.
  */
-import { createHash } from 'node:crypto';
-import { readFile } from 'node:fs/promises';
-import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { verbose, warn } from '../utils/logger.js';
 import { isPackageablePath, isXpcomManifestPath } from './build-audit.js';
 import { readBuildBaseline } from './build-baseline.js';
+import { hashEngineFile } from './coverage-extend.js';
 import { collectChangedEnginePaths } from './engine-changes.js';
 export { isXpcomManifestPath };
 /** Cap on the number of changed paths rendered inline. */
@@ -83,23 +81,6 @@ export async function checkStaleBuildForTest(projectRoot, engineDir) {
     const truncated = Math.max(0, packageable.length - head.length);
     return { stale: true, changedPaths: head, truncated, baseline };
 }
-/**
- * Reads a file under the engine directory and returns a hex-encoded
- * SHA-256 of its contents, matching the hash the baseline writer
- * produces. Returns `undefined` on any IO error (missing file,
- * permission denied, etc.) so the caller can treat the path as still
- * stale rather than crashing the preflight.
- */
-async function hashEngineFile(engineDir, relPath) {
-    try {
-        const buffer = await readFile(join(engineDir, relPath));
-        return createHash('sha256').update(buffer).digest('hex');
-    }
-    catch (error) {
-        verbose(`Stale-build preflight: could not hash ${relPath} for baseline comparison — ${toError(error).message}`);
-        return undefined;
-    }
-}
 /**
  * Formats a human-readable warning body from a {@link StaleBuildResult}.
  * Kept separate from the probe so test code can assert on the structured

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;