@hominis/fireforge 0.9.0

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

@@ -0,0 +1,185 @@
+// 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 { 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) {
+    const withoutPrefix = tagName.replace(/^moz-/, '');
+    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();
+    // --- 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);
+        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);
+        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);
+        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;
+}
+//# sourceMappingURL=furnace-stories.js.map

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

@@ -0,0 +1,6 @@
+import type { ValidationIssue } from '../types/furnace.js';
+/**
+ * Validates accessibility patterns in a component's .mjs file.
+ * Checks for ARIA roles, keyboard handlers, l10n, and focus delegation.
+ */
+export declare function validateAccessibility(componentDir: string, tagName: string): Promise<ValidationIssue[]>;

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

@@ -0,0 +1,32 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { containsHardcodedTemplateText, createIssue, hasAriaRole, hasDelegatesFocusEnabled, hasTemplateClickHandler, hasTemplateKeyboardHandler, } from './furnace-validate-helpers.js';
+/**
+ * Validates accessibility patterns in a component's .mjs file.
+ * Checks for ARIA roles, keyboard handlers, l10n, and focus delegation.
+ */
+export async function validateAccessibility(componentDir, tagName) {
+    const mjsPath = join(componentDir, `${tagName}.mjs`);
+    if (!(await pathExists(mjsPath)))
+        return [];
+    const content = await readText(mjsPath);
+    const issues = [];
+    if (!hasAriaRole(content)) {
+        issues.push(createIssue(tagName, 'warning', 'no-aria-role', 'No ARIA role attribute found. Consider adding role= for screen reader support.'));
+    }
+    const hasClick = hasTemplateClickHandler(content);
+    const hasKeyboardHandler = hasTemplateKeyboardHandler(content);
+    if (hasClick && !hasKeyboardHandler) {
+        issues.push(createIssue(tagName, 'warning', 'no-keyboard-handler', 'Interactive element has @click but no keyboard event handler (@keydown/@keypress/@keyup).'));
+    }
+    if (containsHardcodedTemplateText(content)) {
+        issues.push(createIssue(tagName, 'warning', 'hardcoded-text', 'Possible hardcoded string found. Use data-l10n-id for localization.'));
+    }
+    const isInteractive = hasClick || hasKeyboardHandler;
+    if (isInteractive && !hasDelegatesFocusEnabled(content)) {
+        issues.push(createIssue(tagName, 'warning', 'no-delegates-focus', 'Interactive component without delegatesFocus in shadowRootOptions. Focus may not delegate to inner elements.'));
+    }
+    return issues;
+}
+//# sourceMappingURL=furnace-validate-accessibility.js.map

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

@@ -0,0 +1,4 @@
+export { validateAccessibility } from './furnace-validate-accessibility.js';
+export { validateCompatibility } from './furnace-validate-compatibility.js';
+export { checkRegistrationConsistency, validateJarMnEntries, validateRegistrationPatterns, validateTokenLink, } from './furnace-validate-registration.js';
+export { validateStructure } from './furnace-validate-structure.js';

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

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: EUPL-1.2
+// Re-export all validation checks from their focused modules.
+export { validateAccessibility } from './furnace-validate-accessibility.js';
+export { validateCompatibility } from './furnace-validate-compatibility.js';
+export { checkRegistrationConsistency, validateJarMnEntries, validateRegistrationPatterns, validateTokenLink, } from './furnace-validate-registration.js';
+export { validateStructure } from './furnace-validate-structure.js';
+//# sourceMappingURL=furnace-validate-checks.js.map

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

@@ -0,0 +1,6 @@
+import type { ComponentType, FurnaceConfig, ValidationIssue } from '../types/furnace.js';
+/**
+ * Validates compatibility patterns in a component's .mjs and .css files.
+ * Checks imports, class hierarchy, registration, and design tokens.
+ */
+export declare function validateCompatibility(componentDir: string, tagName: string, type: ComponentType, config?: FurnaceConfig, root?: string): Promise<ValidationIssue[]>;

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

@@ -0,0 +1,57 @@
+// 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 { classExtendsMozLitElement, collectCssVariableReferences, createIssue, getTokenPrefixContext, hasCustomElementDefineCall, hasRelativeModuleImport, stripCssBlockComments, } from './furnace-validate-helpers.js';
+async function validateMjsCompatibility(mjsPath, tagName) {
+    if (!(await pathExists(mjsPath)))
+        return [];
+    const mjsContent = await readText(mjsPath);
+    const issues = [];
+    if (hasRelativeModuleImport(mjsContent)) {
+        issues.push(createIssue(tagName, 'error', 'relative-import', 'Imports must use chrome:// URIs, not relative paths.'));
+    }
+    if (!hasCustomElementDefineCall(mjsContent)) {
+        issues.push(createIssue(tagName, 'error', 'no-custom-element-define', 'Missing customElements.define() call. Component will not be registered.'));
+    }
+    if (!classExtendsMozLitElement(mjsContent)) {
+        issues.push(createIssue(tagName, 'error', 'not-moz-lit-element', 'Component class must extend MozLitElement.'));
+    }
+    return issues;
+}
+async function validateCssCompatibility(cssPath, tagName, type, config, root) {
+    if (!(await pathExists(cssPath)))
+        return [];
+    const rawCss = await readText(cssPath);
+    const cssContent = stripCssBlockComments(rawCss);
+    const issues = [];
+    if (hasRawCssColors(cssContent)) {
+        issues.push(createIssue(tagName, 'error', 'raw-color-value', 'Raw color value found. Use CSS custom properties (var(--...)) for design token consistency.'));
+    }
+    if (config?.tokenPrefix) {
+        const { allowlist, inheritedOverrideVars } = await getTokenPrefixContext(tagName, type, config, root);
+        for (const prop of collectCssVariableReferences(cssContent)) {
+            if (!prop.startsWith(config.tokenPrefix) &&
+                !allowlist.has(prop) &&
+                !inheritedOverrideVars.has(prop)) {
+                issues.push(createIssue(tagName, 'error', 'token-prefix-violation', `CSS references var(${prop}) which does not match the required token prefix "${config.tokenPrefix}". Use a design token or add to tokenAllowlist.`));
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Validates compatibility patterns in a component's .mjs and .css files.
+ * Checks imports, class hierarchy, registration, and design tokens.
+ */
+export async function validateCompatibility(componentDir, tagName, type, config, root) {
+    const issues = [];
+    const mjsPath = join(componentDir, `${tagName}.mjs`);
+    const cssPath = join(componentDir, `${tagName}.css`);
+    const mjsIssues = await validateMjsCompatibility(mjsPath, tagName);
+    issues.push(...mjsIssues);
+    const cssIssues = await validateCssCompatibility(cssPath, tagName, type, config, root);
+    issues.push(...cssIssues);
+    return issues;
+}
+//# sourceMappingURL=furnace-validate-compatibility.js.map

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

@@ -0,0 +1,28 @@
+import type { ComponentType, FurnaceConfig, ValidationIssue } from '../types/furnace.js';
+/** Creates a normalized validation issue object. */
+export declare function createIssue(component: string, severity: ValidationIssue['severity'], check: ValidationIssue['check'], message: string): ValidationIssue;
+/** Detects whether template or script content assigns an ARIA role. */
+export declare function hasAriaRole(content: string): boolean;
+/** Detects Lit-style template click handlers. */
+export declare function hasTemplateClickHandler(content: string): boolean;
+/** Detects Lit-style template keyboard handlers. */
+export declare function hasTemplateKeyboardHandler(content: string): boolean;
+/** Detects hardcoded user-visible template text that should usually be localized. */
+export declare function containsHardcodedTemplateText(content: string): boolean;
+/** Detects whether a component opts into shadow-root focus delegation. */
+export declare function hasDelegatesFocusEnabled(content: string): boolean;
+/** Removes CSS block comments before running simple string-based checks. */
+export declare function stripCssBlockComments(content: string): string;
+/** Detects relative ES module imports in a component module file. */
+export declare function hasRelativeModuleImport(mjsContent: string): boolean;
+/** Detects whether a module defines a custom element at runtime. */
+export declare function hasCustomElementDefineCall(mjsContent: string): boolean;
+/** Checks whether a declared component class extends MozLitElement. */
+export declare function classExtendsMozLitElement(mjsContent: string): boolean;
+/** Collects CSS custom property references used via var(--token-name). */
+export declare function collectCssVariableReferences(cssContent: string): string[];
+/** Builds token-validation context from the config allowlist and inherited override CSS. */
+export declare function getTokenPrefixContext(tagName: string, type: ComponentType, config: FurnaceConfig, root: string | undefined): Promise<{
+    allowlist: Set<string>;
+    inheritedOverrideVars: Set<string>;
+}>;

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

@@ -0,0 +1,129 @@
+// SPDX-License-Identifier: EUPL-1.2
+import { join } from 'node:path';
+import { pathExists, readText } from '../utils/fs.js';
+import { getProjectPaths } from './config.js';
+/** Creates a normalized validation issue object. */
+export function createIssue(component, severity, check, message) {
+    return { component, severity, check, message };
+}
+/** Detects whether template or script content assigns an ARIA role. */
+export function hasAriaRole(content) {
+    return (/role\s*=\s*["']/.test(content) ||
+        /\.role\s*=/.test(content) ||
+        /setAttribute\(\s*["']role["']/.test(content));
+}
+/** Detects Lit-style template click handlers. */
+export function hasTemplateClickHandler(content) {
+    return /@click\s*=\s*\$\{/.test(content);
+}
+/** Detects Lit-style template keyboard handlers. */
+export function hasTemplateKeyboardHandler(content) {
+    return /@key(down|press|up)\s*=\s*\$\{/.test(content);
+}
+function isSymbolOnlyText(text) {
+    return Array.from(text).every((character) => {
+        const code = character.codePointAt(0) ?? 0;
+        return code > 0xff || '+-*=<>|/\\^~@#&!?%'.includes(character);
+    });
+}
+function isWithinLocalizedElement(content, matchIndex) {
+    const contentBefore = content.slice(0, matchIndex + 1);
+    const lastTagOpen = contentBefore.lastIndexOf('<');
+    if (lastTagOpen === -1) {
+        return false;
+    }
+    const tagContent = contentBefore.slice(lastTagOpen, matchIndex + 1);
+    return /data-l10n-id\s*=/.test(tagContent);
+}
+/** Detects hardcoded user-visible template text that should usually be localized. */
+export function containsHardcodedTemplateText(content) {
+    if (/furnace-ignore:\s*hardcoded-text/.test(content)) {
+        return false;
+    }
+    const textPattern = />([^<$\s][^<$]*)</g;
+    let textMatch;
+    while ((textMatch = textPattern.exec(content)) !== null) {
+        const text = textMatch[1]?.trim() ?? '';
+        if (/\$\{/.test(text)) {
+            continue;
+        }
+        if (Array.from(text).length <= 1) {
+            continue;
+        }
+        if (isSymbolOnlyText(text)) {
+            continue;
+        }
+        if (isWithinLocalizedElement(content, textMatch.index)) {
+            continue;
+        }
+        return true;
+    }
+    return false;
+}
+/** Detects whether a component opts into shadow-root focus delegation. */
+export function hasDelegatesFocusEnabled(content) {
+    return /shadowRootOptions[\s\S]*?delegatesFocus\s*:\s*true/.test(content);
+}
+/** Removes CSS block comments before running simple string-based checks. */
+export function stripCssBlockComments(content) {
+    return content.replace(/\/\*[\s\S]*?\*\//g, '');
+}
+/** Detects relative ES module imports in a component module file. */
+export function hasRelativeModuleImport(mjsContent) {
+    return (/^\s*import\s.*from\s+["']\.\.?\//m.test(mjsContent) ||
+        /^\s*import\s+["']\.\.?\//m.test(mjsContent));
+}
+/** Detects whether a module defines a custom element at runtime. */
+export function hasCustomElementDefineCall(mjsContent) {
+    return /customElements\.define\s*\(/.test(mjsContent);
+}
+/** Checks whether a declared component class extends MozLitElement. */
+export function classExtendsMozLitElement(mjsContent) {
+    const hasClassDeclaration = /class\s+\w+\s+extends\s+/.test(mjsContent);
+    if (!hasClassDeclaration) {
+        return true;
+    }
+    return /class\s+\w+\s+extends\s+MozLitElement\b/.test(mjsContent);
+}
+/** Collects CSS custom property references used via var(--token-name). */
+export function collectCssVariableReferences(cssContent) {
+    const referencedVariables = [];
+    const variablePattern = /var\(\s*(--[\w-]+)/g;
+    let match;
+    while ((match = variablePattern.exec(cssContent)) !== null) {
+        const variableName = match[1];
+        if (variableName) {
+            referencedVariables.push(variableName);
+        }
+    }
+    return referencedVariables;
+}
+async function collectInheritedOverrideVariables(tagName, config, root) {
+    const inheritedVariables = new Set();
+    const basePath = config.overrides[tagName]?.basePath;
+    if (!basePath) {
+        return inheritedVariables;
+    }
+    const { engine: engineDir } = getProjectPaths(root);
+    const originalCssPath = join(engineDir, basePath, `${tagName}.css`);
+    if (!(await pathExists(originalCssPath))) {
+        return inheritedVariables;
+    }
+    const originalCssContent = stripCssBlockComments(await readText(originalCssPath));
+    for (const variableName of collectCssVariableReferences(originalCssContent)) {
+        inheritedVariables.add(variableName);
+    }
+    return inheritedVariables;
+}
+/** Builds token-validation context from the config allowlist and inherited override CSS. */
+export async function getTokenPrefixContext(tagName, type, config, root) {
+    const allowlist = new Set(config.tokenAllowlist ?? []);
+    if (type !== 'override' || !root) {
+        return { allowlist, inheritedOverrideVars: new Set() };
+    }
+    return {
+        allowlist,
+        inheritedOverrideVars: await collectInheritedOverrideVariables(tagName, config, root),
+    };
+}
+//# sourceMappingURL=furnace-validate-helpers.js.map

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

@@ -0,0 +1,37 @@
+import type { CustomComponentConfig, FurnaceConfig, RegistrationStatus, ValidationIssue } from '../types/furnace.js';
+/**
+ * Validates that all Furnace-managed .mjs components are registered in the
+ * DOMContentLoaded/importESModule block (Pattern B), not the loadSubScript
+ * block (Pattern A).
+ *
+ * @param root - Project root directory
+ * @param config - Furnace configuration
+ * @returns Array of validation issues for mis-placed registrations
+ */
+export declare function validateRegistrationPatterns(root: string, config: FurnaceConfig): Promise<ValidationIssue[]>;
+/**
+ * Checks registration consistency for a single custom component.
+ *
+ * Compares source files, engine target files, jar.mn entries, and
+ * customElements.js registration for a given component.
+ *
+ * @param root - Project root directory
+ * @param name - Component tag name
+ * @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>;
+/**
+ * Validates that each custom component with `register: true` has its .mjs and
+ * .css entries in jar.mn.
+ *
+ * @param root - Project root directory
+ * @param config - Furnace configuration
+ * @returns Array of validation issues for missing jar.mn entries
+ */
+export declare function validateJarMnEntries(root: string, config: FurnaceConfig): Promise<ValidationIssue[]>;
+/**
+ * Validates that components using design tokens have the tokens CSS
+ * 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[]>;