@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/furnace-state-persist.js

@@ -1,116 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Single-component furnace state persistence.
- *
- * There are exactly two sanctioned ways checksums land in
- * furnace-state.json:
- *
- *  1. The batch path inside `applyAllComponents` (persistState: true), which
- *     replaces `appliedChecksums` wholesale. That is correct only when the
- *     run covered every component.
- *  2. The per-component merge in this module, which rewrites only the
- *     `<type>/<name>/…` keys of the component that was applied.
- *
- * Every targeted (named) apply/deploy must use path 2 with
- * `persistState: false`. Routing a named run through the batch path wipes
- * every other component's checksum state: the batch loops filter to the
- * named component, so the wholesale replace persists a state file containing
- * only that component. Downstream, `diffDeletedFiles` and
- * `findOrphanedEngineFiles` both key on `appliedChecksums`, so the wiped
- * components' stale engine files become undetectable by apply and by
- * `furnace validate`.
- */
-import { join } from 'node:path';
-import { FurnaceError } from '../errors/furnace.js';
-import { computeComponentChecksums, prefixChecksums, } from './furnace-apply.js';
-import { updateFurnaceState } from './furnace-config.js';
-import { countEntriesWithBlockingStepErrors } from './furnace-step-errors.js';
-/**
- * Counts applied entries that carry at least one blocking step error
- * (advisory step errors are warnings and never fail a run).
- */
-export function getStepFailureCount(result) {
-    return countEntriesWithBlockingStepErrors(result.applied);
-}
-/**
- * Decides whether a single-component apply/deploy completed cleanly enough
- * to persist its checksums into furnace-state.json.
- *
- * Named runs are atomic: if any apply step fails, the rollback journal
- * restores the engine to its pre-run state and this helper returns `false`
- * so state is not touched. The conditions must stay in lock-step with the
- * rollback trigger in `applyAllComponents`: both read step errors, so a
- * future refactor cannot drift them apart and accidentally persist partial
- * state.
- */
-export function shouldPersistSingleComponentState(result, isDryRun) {
-    if (isDryRun)
-        return false;
-    if (result.errors.length > 0)
-        return false;
-    if (getStepFailureCount(result) > 0)
-        return false;
-    return result.applied.length > 0;
-}
-/**
- * Validates and narrows the applied entry a named run should persist.
- *
- * Guards against future refactors that might reorder or misroute the
- * applied[] array: a named run persists state under a single component
- * name, so the first applied entry must be that component. Persisting a
- * different component's checksums would cause the next status/apply run to
- * mis-report health for both components involved.
- *
- * @param commandLabel - Human label for error messages ("Deploy", "Apply")
- */
-export function getPersistableAppliedEntry(commandLabel, name, appliedEntry) {
-    if (!appliedEntry) {
-        throw new FurnaceError(`${commandLabel} for "${name}" finished without producing an applied component entry; ` +
-            `furnace state was not modified. Run "fireforge doctor --repair-furnace" to ` +
-            `reconcile state, then retry. If this persists, file a bug with the ` +
-            `output of "fireforge doctor".`);
-    }
-    if (appliedEntry.type !== 'override' && appliedEntry.type !== 'custom') {
-        throw new FurnaceError(`${commandLabel} for "${name}" returned an unsupported component type "${appliedEntry.type}"; ` +
-            `furnace state was not modified. Run "fireforge doctor --repair-furnace" to reconcile, ` +
-            `then verify the component with "fireforge furnace validate" before retrying.`);
-    }
-    if (appliedEntry.name !== name) {
-        throw new FurnaceError(`${commandLabel} for "${name}" returned an applied entry for a different component ` +
-            `("${appliedEntry.name}"); refusing to persist mismatched state. ` +
-            `Run "fireforge doctor --repair-furnace" to reconcile, then retry.`);
-    }
-    return {
-        name: appliedEntry.name,
-        type: appliedEntry.type,
-    };
-}
-/**
- * Persists checksum state for a successfully applied named component by
- * merging its `<type>/<name>/…` keys into the existing state rather than
- * replacing the whole map.
- *
- * @param projectRoot - Root directory of the project
- * @param appliedEntry - Applied component descriptor
- * @param furnacePaths - Resolved Furnace workspace paths
- */
-export async function persistSingleComponentState(projectRoot, appliedEntry, furnacePaths) {
-    const componentDir = appliedEntry.type === 'override'
-        ? join(furnacePaths.overridesDir, appliedEntry.name)
-        : join(furnacePaths.customDir, appliedEntry.name);
-    const checksums = await computeComponentChecksums(componentDir);
-    const prefixed = prefixChecksums(checksums, appliedEntry.type, appliedEntry.name);
-    const componentPrefix = `${appliedEntry.type}/${appliedEntry.name}/`;
-    await updateFurnaceState(projectRoot, (current) => ({
-        ...current,
-        appliedChecksums: {
-            ...Object.fromEntries(Object.entries(current.appliedChecksums ?? {}).filter(([key]) => !key.startsWith(componentPrefix))),
-            ...prefixed,
-        },
-        engineChecksums: {
-            ...Object.fromEntries(Object.entries(current.engineChecksums ?? {}).filter(([key]) => !key.startsWith(componentPrefix))),
-            ...prefixed,
-        },
-        lastApply: new Date().toISOString(),
-    }));
-}

package/dist/src/core/furnace-step-errors.d.ts

@@ -1,23 +0,0 @@
-/**
- * Shared predicates over {@link StepError} lists.
- *
- * Step errors come in two severities: blocking (the default: the apply is
- * considered failed, triggers rollback and a non-zero exit) and advisory
- * (`advisory: true`, which is reported as a warning, never blocks, and is
- * used by the `.ftl` helpers whose contract is graceful degradation). Every
- * gate that decides rollback/failure must count only blocking errors, and
- * every reporter should still surface advisory ones. This module is a leaf (types-only
- * imports) so both `furnace-apply.ts` and its callers can share the
- * predicates without import cycles.
- */
-import type { StepError } from '../types/furnace.js';
-/** Narrow shape shared by applied-component entries carrying step errors. */
-export interface HasStepErrors {
-    stepErrors?: StepError[];
-}
-/** Returns only the blocking (non-advisory) step errors. */
-export declare function blockingStepErrors(stepErrors: StepError[] | undefined): StepError[];
-/** True when the entry carries at least one blocking step error. */
-export declare function hasBlockingStepErrors(entry: HasStepErrors): boolean;
-/** Counts applied entries that carry at least one blocking step error. */
-export declare function countEntriesWithBlockingStepErrors(entries: readonly HasStepErrors[]): number;

package/dist/src/core/furnace-step-errors.js

@@ -1,25 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Shared predicates over {@link StepError} lists.
- *
- * Step errors come in two severities: blocking (the default: the apply is
- * considered failed, triggers rollback and a non-zero exit) and advisory
- * (`advisory: true`, which is reported as a warning, never blocks, and is
- * used by the `.ftl` helpers whose contract is graceful degradation). Every
- * gate that decides rollback/failure must count only blocking errors, and
- * every reporter should still surface advisory ones. This module is a leaf (types-only
- * imports) so both `furnace-apply.ts` and its callers can share the
- * predicates without import cycles.
- */
-/** Returns only the blocking (non-advisory) step errors. */
-export function blockingStepErrors(stepErrors) {
-    return (stepErrors ?? []).filter((e) => e.advisory !== true);
-}
-/** True when the entry carries at least one blocking step error. */
-export function hasBlockingStepErrors(entry) {
-    return blockingStepErrors(entry.stepErrors).length > 0;
-}
-/** Counts applied entries that carry at least one blocking step error. */
-export function countEntriesWithBlockingStepErrors(entries) {
-    return entries.filter((entry) => hasBlockingStepErrors(entry)).length;
-}

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

@@ -1,37 +0,0 @@
-import type { ComponentType, SyncResult } from '../types/furnace.js';
-/**
- * Generates the full content of a Storybook `.stories.mjs` file for a
- * Furnace component.
- *
- * @param tagName - Component tag name (e.g. "moz-button")
- * @param displayName - Human-readable name (e.g. "Button")
- * @param type - Component classification (stock, override, custom)
- * @returns Complete story file content
- */
-export declare function generateStoryContent(tagName: string, displayName: string, type: ComponentType, licenseHeader?: string, modulePath?: string): string;
-/**
- * Returns the path to the Storybook stories directory in the engine.
- *
- * @param engineDir - Path to the Firefox engine source root
- * @returns Absolute path to `browser/components/storybook/stories/`
- */
-export declare function getStoriesDir(engineDir: string): string;
-/**
- * Synchronises Storybook story files for all Furnace-managed components.
- *
- * - Stock components: story created only if not already present.
- * - Override components: story always regenerated.
- * - Custom components: story always regenerated.
- * - Stale story files (for components no longer in furnace.json) are removed.
- *
- * @param root - Root directory of the project
- * @returns Summary of created, updated, and removed story files
- */
-export declare function syncStories(root: string): Promise<SyncResult>;
-/**
- * Removes the entire `stories/furnace/` directory from the engine.
- *
- * @param engineDir - Path to the Firefox engine source root
- * @returns Number of files that were removed
- */
-export declare function cleanStories(engineDir: string): Promise<number>;

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

@@ -1,186 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { ensureDir, pathExists, removeDir, removeFile, writeText } from '../utils/fs.js';
-import { getProjectPaths, loadConfig } from './config.js';
-import { loadFurnaceConfig } from './furnace-config.js';
-import { stripComponentPrefix } from './furnace-constants.js';
-import { DEFAULT_LICENSE, getLicenseHeader } from './license-headers.js';
-/** MPL-2.0 license header used in generated story files for Firefox-derived components */
-const MPL_LICENSE_HEADER = getLicenseHeader('MPL-2.0', 'js');
-/** Title category for each component type */
-const TITLE_CATEGORIES = {
-    stock: 'Design System/Stock',
-    override: 'Design System/Overrides',
-    custom: 'Design System/Custom',
-};
-/**
- * Derives a human-readable display name from a component tag name.
- *
- * Removes the `moz-` prefix, splits on hyphens, capitalises each word,
- * and joins with spaces.
- *
- * @example
- * generateDisplayName("moz-button")      // "Button"
- * generateDisplayName("moz-message-bar") // "Message Bar"
- *
- * @param tagName - Component tag name (e.g. "moz-button")
- * @returns Display name (e.g. "Button")
- */
-function generateDisplayName(tagName, componentPrefix) {
-    const withoutPrefix = stripComponentPrefix(tagName, componentPrefix);
-    return withoutPrefix
-        .split('-')
-        .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
-        .join(' ');
-}
-/**
- * Generates the full content of a Storybook `.stories.mjs` file for a
- * Furnace component.
- *
- * @param tagName - Component tag name (e.g. "moz-button")
- * @param displayName - Human-readable name (e.g. "Button")
- * @param type - Component classification (stock, override, custom)
- * @returns Complete story file content
- */
-export function generateStoryContent(tagName, displayName, type, licenseHeader = MPL_LICENSE_HEADER, modulePath) {
-    const category = TITLE_CATEGORIES[type];
-    // Derive chrome:// URI from modulePath if provided, otherwise default to elements/ path
-    let chromeUri;
-    if (modulePath) {
-        if (modulePath.startsWith('toolkit/content/')) {
-            chromeUri = modulePath.replace(/^toolkit\/content\//, 'chrome://global/content/');
-        }
-        else if (modulePath.startsWith('browser/base/content/')) {
-            chromeUri = modulePath.replace(/^browser\/base\/content\//, 'chrome://browser/content/');
-        }
-        else {
-            chromeUri = `chrome://global/content/${modulePath}`;
-        }
-    }
-    else {
-        chromeUri = `chrome://global/content/elements/${tagName}.mjs`;
-    }
-    return `${licenseHeader}
-
-import { html } from "chrome://global/content/vendor/lit.all.mjs";
-// The component import triggers customElements.define
-import "${chromeUri}";
-
-export default {
-  title: "${category}/${displayName}",
-  component: "${tagName}",
-  argTypes: {},
-};
-
-const Template = (args) => html\`<${tagName}></${tagName}>\`;
-
-export const Default = Template.bind({});
-Default.args = {};
-`;
-}
-/**
- * Returns the path to the Storybook stories directory in the engine.
- *
- * @param engineDir - Path to the Firefox engine source root
- * @returns Absolute path to `browser/components/storybook/stories/`
- */
-export function getStoriesDir(engineDir) {
-    return join(engineDir, 'browser', 'components', 'storybook', 'stories');
-}
-/**
- * Synchronises Storybook story files for all Furnace-managed components.
- *
- * - Stock components: story created only if not already present.
- * - Override components: story always regenerated.
- * - Custom components: story always regenerated.
- * - Stale story files (for components no longer in furnace.json) are removed.
- *
- * @param root - Root directory of the project
- * @returns Summary of created, updated, and removed story files
- */
-export async function syncStories(root) {
-    const config = await loadFurnaceConfig(root);
-    const forgeConfig = await loadConfig(root);
-    const license = forgeConfig.license ?? DEFAULT_LICENSE;
-    const customLicenseHeader = getLicenseHeader(license, 'js');
-    const { engine: engineDir } = getProjectPaths(root);
-    const storiesDir = join(getStoriesDir(engineDir), 'furnace');
-    await ensureDir(storiesDir);
-    const result = { created: [], updated: [], removed: [] };
-    const expectedFiles = new Set();
-    const componentPrefix = config.componentPrefix;
-    // --- Stock components (only create if missing) ---
-    for (const tagName of config.stock) {
-        const filename = `${tagName}.stories.mjs`;
-        expectedFiles.add(filename);
-        const filePath = join(storiesDir, filename);
-        if (await pathExists(filePath)) {
-            continue;
-        }
-        const displayName = generateDisplayName(tagName, componentPrefix);
-        const content = generateStoryContent(tagName, displayName, 'stock');
-        await writeText(filePath, content);
-        result.created.push(filename);
-    }
-    // --- Override components (always regenerate) ---
-    for (const name of Object.keys(config.overrides)) {
-        const filename = `${name}.stories.mjs`;
-        expectedFiles.add(filename);
-        const filePath = join(storiesDir, filename);
-        const existed = await pathExists(filePath);
-        const displayName = generateDisplayName(name, componentPrefix);
-        const content = generateStoryContent(name, displayName, 'override', customLicenseHeader);
-        await writeText(filePath, content);
-        if (existed) {
-            result.updated.push(filename);
-        }
-        else {
-            result.created.push(filename);
-        }
-    }
-    // --- Custom components (always regenerate, use project license) ---
-    for (const name of Object.keys(config.custom)) {
-        const filename = `${name}.stories.mjs`;
-        expectedFiles.add(filename);
-        const filePath = join(storiesDir, filename);
-        const existed = await pathExists(filePath);
-        const displayName = generateDisplayName(name, componentPrefix);
-        const content = generateStoryContent(name, displayName, 'custom', customLicenseHeader);
-        await writeText(filePath, content);
-        if (existed) {
-            result.updated.push(filename);
-        }
-        else {
-            result.created.push(filename);
-        }
-    }
-    // --- Remove stale story files ---
-    const entries = await readdir(storiesDir, { withFileTypes: true });
-    for (const entry of entries) {
-        if (!entry.isFile() || !entry.name.endsWith('.stories.mjs')) {
-            continue;
-        }
-        if (!expectedFiles.has(entry.name)) {
-            await removeFile(join(storiesDir, entry.name));
-            result.removed.push(entry.name);
-        }
-    }
-    return result;
-}
-/**
- * Removes the entire `stories/furnace/` directory from the engine.
- *
- * @param engineDir - Path to the Firefox engine source root
- * @returns Number of files that were removed
- */
-export async function cleanStories(engineDir) {
-    const storiesDir = join(getStoriesDir(engineDir), 'furnace');
-    if (!(await pathExists(storiesDir))) {
-        return 0;
-    }
-    const entries = await readdir(storiesDir, { withFileTypes: true });
-    const count = entries.filter((e) => e.isFile()).length;
-    await removeDir(storiesDir);
-    return count;
-}

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

@@ -1,39 +0,0 @@
-import type { CustomComponentConfig, FurnaceOptInCheck, ValidationIssue } from '../types/furnace.js';
-/**
- * Validates accessibility patterns in a component's composed source: its
- * host module and every companion module (see
- * {@link readComposedComponentSource}). Checks for ARIA roles, keyboard
- * handlers, l10n, and focus delegation.
- *
- * @param componentDir - Directory holding the component's sources
- * @param tagName - Custom element tag name, used to locate `<tagName>.mjs`
- * @param customConfig - When the component is custom, its matching entry
- *   from `furnace.json`. Used to skip the `no-keyboard-handler` warning
- *   when the component declares keyboard coverage either explicitly
- *   (`keyboardCovered: true`) or via `composes` naming a native-interactive
- *   inner element. Optional so stock/override callers and test fixtures
- *   without config in scope can continue to call without changes.
- * @param optInChecks - `furnace.json#optInChecks`. `icon-button-label`
- *   adds the icon-only `<moz-button>` naming check.
- */
-export declare function validateAccessibility(componentDir: string, tagName: string, customConfig?: CustomComponentConfig, optInChecks?: readonly FurnaceOptInCheck[]): Promise<ValidationIssue[]>;
-/**
- * Detects hardcoded user-visible template text that should usually be
- * localized.
- *
- * Scoped to three positive contexts rather than scanning the whole file,
- * because a bare `>…<` regex catches JS comparisons (`if (x > 0 && y <
- * 100)`), diagnostic strings (`console.error("Failed <id> lookup")`), and
- * identifier literals that are never shown to a user. Only matches that
- * actually enter a UI render path count:
- *
- *   1. Content inside a Lit `` html`…` `` tagged template literal.
- *   2. The string literal on the RHS of `.textContent = "…"` or
- *      `.innerHTML = "…"`.
- *   3. The string literal assigned to an XUL-widget `label=`,
- *      `title=`, or `tooltiptext=` attribute when constructing DOM in JS.
- *
- * A file-wide `// furnace-ignore: hardcoded-text` comment suppresses all
- * findings in that file (matches the pre-existing escape hatch).
- */
-export declare function containsHardcodedTemplateText(content: string): boolean;