@hominis/fireforge 0.10.1 → 0.11.0

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

@@ -1,6 +1,6 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { chmod, mkdir, readFile, rm, stat, writeFile } from 'node:fs/promises';
-import { dirname } from 'node:path';
+import { chmod, mkdir, readdir, readFile, rename, rm, stat, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
 import { toError } from '../utils/errors.js';
 import { pathExists } from '../utils/fs.js';
@@ -9,12 +9,40 @@ export function createRollbackJournal() {
     return {
         files: new Map(),
         createdDirs: new Set(),
+        skippedSymlinks: new Set(),
     };
 }
 /** Records a directory that should be removed if the operation later rolls back. */
 export function recordCreatedDir(journal, dirPath) {
     journal.createdDirs.add(dirPath);
 }
+/**
+ * Recursively snapshots every file under a directory tree so a later rollback
+ * can restore deleted files. Skips symlinks to avoid following them out of the
+ * tree. The directory itself is not recorded as "created" — callers that
+ * intend to delete and restore the directory should record it explicitly.
+ *
+ * Safe to call on a missing path: it returns without recording anything.
+ */
+export async function snapshotDir(journal, dirPath) {
+    if (!(await pathExists(dirPath))) {
+        return;
+    }
+    const entries = await readdir(dirPath, { withFileTypes: true });
+    for (const entry of entries) {
+        if (entry.isSymbolicLink()) {
+            journal.skippedSymlinks.add(join(dirPath, entry.name));
+            continue;
+        }
+        const childPath = join(dirPath, entry.name);
+        if (entry.isDirectory()) {
+            await snapshotDir(journal, childPath);
+        }
+        else if (entry.isFile()) {
+            await snapshotFile(journal, childPath);
+        }
+    }
+}
 /** Snapshots a file once so rollback can restore its previous contents or absence. */
 export async function snapshotFile(journal, filePath) {
     if (journal.files.has(filePath)) {
@@ -37,16 +65,59 @@ async function restoreFile(filePath, snapshot) {
         return;
     }
     await mkdir(dirname(filePath), { recursive: true });
-    await writeFile(filePath, snapshot.content ?? new Uint8Array());
-    if (snapshot.mode !== undefined) {
-        await chmod(filePath, snapshot.mode);
+    // Write to a sibling temp file and atomically rename it over the target.
+    // A direct writeFile would race with any in-flight write by the body (e.g. a
+    // signal-handler-driven rollback landing on top of a still-running
+    // `writeFile('corrupted')` from the body), producing interleaved byte
+    // sequences like `"pristined"` where the first 8 bytes come from the
+    // rollback write and the trailing byte from the body write. rename(2) is
+    // atomic within a filesystem, so either the body's write or the rollback's
+    // rename wins outright and the target is never left in a hybrid state.
+    const tempPath = `${filePath}.rollback-${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+    try {
+        await writeFile(tempPath, snapshot.content ?? new Uint8Array());
+        if (snapshot.mode !== undefined) {
+            await chmod(tempPath, snapshot.mode);
+        }
+        await rename(tempPath, filePath);
+    }
+    catch (error) {
+        await rm(tempPath, { force: true }).catch(() => undefined);
+        throw error;
     }
 }
+/** Maximum number of concurrent file restorations during rollback. */
+const RESTORE_CONCURRENCY = 8;
 /** Restores all snapshotted files and removes directories created during the operation. */
 export async function restoreRollbackJournal(journal) {
     const fileEntries = [...journal.files.entries()].sort(([left], [right]) => right.length - left.length);
-    for (const [filePath, snapshot] of fileEntries) {
-        await restoreFile(filePath, snapshot);
+    // Restore files in parallel with bounded concurrency. Each restoreFile uses
+    // atomic rename, so concurrent restorations to different paths are safe.
+    const errors = [];
+    let index = 0;
+    async function worker() {
+        while (index < fileEntries.length) {
+            const current = index++;
+            const entry = fileEntries[current];
+            if (!entry)
+                break;
+            const [filePath, snapshot] = entry;
+            try {
+                await restoreFile(filePath, snapshot);
+            }
+            catch (error) {
+                errors.push({
+                    path: filePath,
+                    error: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    const workers = Array.from({ length: Math.min(RESTORE_CONCURRENCY, fileEntries.length) }, () => worker());
+    await Promise.all(workers);
+    if (errors.length > 0) {
+        const summary = errors.map((e) => `${e.path}: ${e.error}`).join('; ');
+        throw new FurnaceError(`Rollback failed to restore ${errors.length} file(s): ${summary}`);
     }
     const createdDirs = [...journal.createdDirs].sort((left, right) => right.length - left.length);
     for (const dirPath of createdDirs) {

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

@@ -1,4 +1,10 @@
 import type { ScannedComponent } from '../types/furnace.js';
+/**
+ * Additional Firefox source directories known to contain MozLitElement
+ * components. Used by `--deep` scan mode to discover components beyond
+ * the primary widgets directory.
+ */
+export declare const DEEP_SCAN_PATHS: readonly string[];
 /**
  * Parses customElements.js to extract tag-to-module mappings.
  *
@@ -23,14 +29,14 @@ export declare function scanCustomElementsRegistrations(engineDir: string): Prom
  * @param engineDir - Path to the Firefox engine source root
  * @returns Array of discovered components
  */
-export declare function scanWidgetsDirectory(engineDir: string): Promise<ScannedComponent[]>;
+export declare function scanWidgetsDirectory(engineDir: string, ftlDir?: string, extraPaths?: string[], componentPrefix?: string): Promise<ScannedComponent[]>;
 /**
  * Gets detailed information about a single component by tag name.
  * @param engineDir - Path to the Firefox engine source root
  * @param tagName - Component tag name (e.g., "moz-button")
  * @returns Component details, or null if not found in the source tree
  */
-export declare function getComponentDetails(engineDir: string, tagName: string): Promise<ScannedComponent | null>;
+export declare function getComponentDetails(engineDir: string, tagName: string, ftlDir?: string): Promise<ScannedComponent | null>;
 /**
  * Checks whether a component directory exists in the engine source tree.
  * @param engineDir - Path to the Firefox engine source root

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

@@ -1,12 +1,33 @@
 // SPDX-License-Identifier: EUPL-1.2
+import { createHash } from 'node:crypto';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
-import { CUSTOM_ELEMENTS_JS } from './furnace-constants.js';
+import { verbose, warn } from '../utils/logger.js';
+import { asEstree, getNodeSource, parseScript, walkAST } from './ast-utils.js';
+import { CUSTOM_ELEMENTS_JS, FTL_DIR } from './furnace-constants.js';
 /** Path to the widgets directory within the engine source tree */
 const WIDGETS_DIR = 'toolkit/content/widgets';
-/** Path to the Fluent localization directory for toolkit global components */
-const FTL_DIR = 'toolkit/locales/en-US/toolkit/global';
+/**
+ * Additional Firefox source directories known to contain MozLitElement
+ * components. Used by `--deep` scan mode to discover components beyond
+ * the primary widgets directory.
+ */
+export const DEEP_SCAN_PATHS = [
+    'browser/components/shopping',
+    'browser/components/migration',
+    'browser/components/firefoxview',
+    'browser/components/sidebar',
+    'browser/components/backup',
+    'toolkit/components/aboutprocesses',
+    'toolkit/components/printing',
+];
+/**
+ * Module-level cache for parsed customElements.js registrations, keyed by
+ * SHA-256 of the file content. Avoids re-parsing the same file within a
+ * single process lifetime (scan → status → apply chain).
+ */
+let registrationCache;
 /**
  * Parses customElements.js to extract tag-to-module mappings.
  *
@@ -27,34 +48,104 @@ export async function scanCustomElementsRegistrations(engineDir) {
         return registrations;
     }
     const content = await readText(filePath);
-    const lines = content.split('\n');
-    for (let i = 0; i < lines.length; i++) {
-        const line = lines[i];
-        if (line === undefined)
-            continue;
-        const callbackMatch = /setElementCreationCallback\(\s*"([^"]+)"/.exec(line);
-        if (!callbackMatch?.[1])
-            continue;
-        const tagName = callbackMatch[1];
-        let modulePath = '';
-        // Search the following lines for an import() statement
-        const searchEnd = Math.min(i + 5, lines.length);
-        for (let j = i + 1; j < searchEnd; j++) {
-            const importLine = lines[j];
-            if (importLine === undefined)
+    const contentHash = createHash('sha256').update(content).digest('hex');
+    // Return cached result if file hasn't changed since last parse.
+    if (registrationCache && registrationCache.hash === contentHash) {
+        return new Map(registrationCache.registrations);
+    }
+    try {
+        const ast = parseScript(content);
+        const recordRegistration = (tagName, modulePath = '') => {
+            const existing = registrations.get(tagName);
+            if (existing && existing.length > 0 && modulePath.length === 0) {
+                return;
+            }
+            registrations.set(tagName, modulePath);
+        };
+        walkAST(ast, {
+            enter(node) {
+                if (node.type === 'ForOfStatement') {
+                    const forOf = asEstree(node);
+                    if (forOf.right.type !== 'ArrayExpression') {
+                        return;
+                    }
+                    const bodySource = getNodeSource(content, asEstree(forOf.body));
+                    if (!bodySource.includes('setElementCreationCallback')) {
+                        return;
+                    }
+                    for (const element of forOf.right.elements) {
+                        if (!element || element.type !== 'ArrayExpression')
+                            continue;
+                        const [tagNode, moduleNode] = element.elements;
+                        if (!tagNode || !moduleNode)
+                            continue;
+                        if (tagNode.type !== 'Literal' || moduleNode.type !== 'Literal')
+                            continue;
+                        if (typeof tagNode.value !== 'string' || typeof moduleNode.value !== 'string')
+                            continue;
+                        recordRegistration(tagNode.value, moduleNode.value);
+                    }
+                    return;
+                }
+                if (node.type !== 'CallExpression') {
+                    return;
+                }
+                const call = asEstree(node);
+                if (call.callee.type !== 'MemberExpression') {
+                    return;
+                }
+                const property = call.callee.property;
+                if (property.type !== 'Identifier' || property.name !== 'setElementCreationCallback') {
+                    return;
+                }
+                const [tagArg] = call.arguments;
+                if (!tagArg || tagArg.type !== 'Literal' || typeof tagArg.value !== 'string') {
+                    return;
+                }
+                const callSource = getNodeSource(content, call);
+                const moduleMatch = /(?:import|importESModule|loadSubScript)\(\s*"([^"]+)"/.exec(callSource) ??
+                    /(?:import|importESModule|loadSubScript)\(\s*'([^']+)'/.exec(callSource);
+                if (!moduleMatch?.[1]) {
+                    return;
+                }
+                recordRegistration(tagArg.value, moduleMatch[1]);
+            },
+        });
+    }
+    catch (parseError) {
+        // Best-effort scanner: if upstream syntax changes or the file is damaged,
+        // fall back to the old literal callback heuristic instead of failing the
+        // whole scan command.
+        const reason = parseError instanceof Error ? parseError.message : String(parseError);
+        warn(`AST parsing of customElements.js failed (${reason}). Falling back to regex-based heuristic. ` +
+            'Results may be incomplete — run "fireforge furnace validate" to verify registration consistency.');
+        verbose(`Scanner regex fallback activated due to parse error: ${reason}`);
+        const lines = content.split('\n');
+        for (let i = 0; i < lines.length; i++) {
+            const line = lines[i];
+            if (line === undefined)
                 continue;
-            const importMatch = /import\(\s*"([^"]+)"/.exec(importLine);
-            if (importMatch?.[1]) {
-                modulePath = importMatch[1];
-                break;
+            const callbackMatch = /setElementCreationCallback\(\s*"([^"]+)"/.exec(line);
+            if (!callbackMatch?.[1])
+                continue;
+            const tagName = callbackMatch[1];
+            let modulePath = '';
+            const searchEnd = Math.min(i + 15, lines.length);
+            for (let j = i + 1; j < searchEnd; j++) {
+                const importLine = lines[j];
+                if (importLine === undefined)
+                    continue;
+                const importMatch = /(?:import|importESModule|loadSubScript)\(\s*"([^"]+)"/.exec(importLine);
+                if (importMatch?.[1]) {
+                    modulePath = importMatch[1];
+                    break;
+                }
             }
+            registrations.set(tagName, modulePath);
         }
-        if (!modulePath) {
-            // No module path found in the lookahead lines; skip this entry
-            continue;
-        }
-        registrations.set(tagName, modulePath);
     }
+    // Cache results for subsequent calls within the same process.
+    registrationCache = { hash: contentHash, registrations: new Map(registrations) };
     return registrations;
 }
 /**
@@ -67,37 +158,43 @@ export async function scanCustomElementsRegistrations(engineDir) {
  * @param engineDir - Path to the Firefox engine source root
  * @returns Array of discovered components
  */
-export async function scanWidgetsDirectory(engineDir) {
-    const widgetsPath = join(engineDir, WIDGETS_DIR);
-    if (!(await pathExists(widgetsPath))) {
-        return [];
-    }
-    const entries = await readdir(widgetsPath, { withFileTypes: true });
+export async function scanWidgetsDirectory(engineDir, ftlDir, extraPaths, componentPrefix) {
+    const searchPaths = [WIDGETS_DIR, ...(extraPaths ?? [])];
     const registrations = await scanCustomElementsRegistrations(engineDir);
     const components = [];
-    for (const entry of entries) {
-        if (!entry.isDirectory() || !entry.name.startsWith('moz-')) {
+    const seen = new Set();
+    const prefix = componentPrefix ?? 'moz-';
+    for (const searchDir of searchPaths) {
+        const dirPath = join(engineDir, searchDir);
+        if (!(await pathExists(dirPath))) {
             continue;
         }
-        const tagName = entry.name;
-        const componentDir = join(widgetsPath, tagName);
-        const componentEntries = await readdir(componentDir, { withFileTypes: true });
-        // Only include directories that contain a .mjs file
-        const hasMjs = componentEntries.some((e) => e.isFile() && e.name.endsWith('.mjs'));
-        if (!hasMjs) {
-            continue;
+        const entries = await readdir(dirPath, { withFileTypes: true });
+        for (const entry of entries) {
+            if (!entry.isDirectory() || !entry.name.startsWith(prefix) || seen.has(entry.name)) {
+                continue;
+            }
+            const tagName = entry.name;
+            seen.add(tagName);
+            const componentDir = join(dirPath, tagName);
+            const componentEntries = await readdir(componentDir, { withFileTypes: true });
+            // Only include directories that contain a .mjs file
+            const hasMjs = componentEntries.some((e) => e.isFile() && e.name.endsWith('.mjs'));
+            if (!hasMjs) {
+                continue;
+            }
+            const hasCSS = componentEntries.some((e) => e.isFile() && e.name.endsWith('.css'));
+            const ftlPath = join(engineDir, ftlDir ?? FTL_DIR, `${tagName}.ftl`);
+            const hasFTL = await pathExists(ftlPath);
+            const isRegistered = registrations.has(tagName);
+            components.push({
+                tagName,
+                sourcePath: join(searchDir, tagName),
+                hasCSS,
+                hasFTL,
+                isRegistered,
+            });
         }
-        const hasCSS = componentEntries.some((e) => e.isFile() && e.name.endsWith('.css'));
-        const ftlPath = join(engineDir, FTL_DIR, `${tagName}.ftl`);
-        const hasFTL = await pathExists(ftlPath);
-        const isRegistered = registrations.has(tagName);
-        components.push({
-            tagName,
-            sourcePath: join(WIDGETS_DIR, tagName),
-            hasCSS,
-            hasFTL,
-            isRegistered,
-        });
     }
     return components;
 }
@@ -107,7 +204,7 @@ export async function scanWidgetsDirectory(engineDir) {
  * @param tagName - Component tag name (e.g., "moz-button")
  * @returns Component details, or null if not found in the source tree
  */
-export async function getComponentDetails(engineDir, tagName) {
+export async function getComponentDetails(engineDir, tagName, ftlDir) {
     const componentDir = join(engineDir, WIDGETS_DIR, tagName);
     if (!(await pathExists(componentDir))) {
         return null;
@@ -118,7 +215,7 @@ export async function getComponentDetails(engineDir, tagName) {
         return null;
     }
     const hasCSS = entries.some((e) => e.isFile() && e.name.endsWith('.css'));
-    const ftlPath = join(engineDir, FTL_DIR, `${tagName}.ftl`);
+    const ftlPath = join(engineDir, ftlDir ?? FTL_DIR, `${tagName}.ftl`);
     const hasFTL = await pathExists(ftlPath);
     const registrations = await scanCustomElementsRegistrations(engineDir);
     const isRegistered = registrations.has(tagName);

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

@@ -4,6 +4,7 @@ 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');
@@ -26,8 +27,8 @@ const TITLE_CATEGORIES = {
  * @param tagName - Component tag name (e.g. "moz-button")
  * @returns Display name (e.g. "Button")
  */
-function generateDisplayName(tagName) {
-    const withoutPrefix = tagName.replace(/^moz-/, '');
+function generateDisplayName(tagName, componentPrefix) {
+    const withoutPrefix = stripComponentPrefix(tagName, componentPrefix);
     return withoutPrefix
         .split('-')
         .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
@@ -108,6 +109,7 @@ export async function syncStories(root) {
     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`;
@@ -116,7 +118,7 @@ export async function syncStories(root) {
         if (await pathExists(filePath)) {
             continue;
         }
-        const displayName = generateDisplayName(tagName);
+        const displayName = generateDisplayName(tagName, componentPrefix);
         const content = generateStoryContent(tagName, displayName, 'stock');
         await writeText(filePath, content);
         result.created.push(filename);
@@ -127,7 +129,7 @@ export async function syncStories(root) {
         expectedFiles.add(filename);
         const filePath = join(storiesDir, filename);
         const existed = await pathExists(filePath);
-        const displayName = generateDisplayName(name);
+        const displayName = generateDisplayName(name, componentPrefix);
         const content = generateStoryContent(name, displayName, 'override', customLicenseHeader);
         await writeText(filePath, content);
         if (existed) {
@@ -143,7 +145,7 @@ export async function syncStories(root) {
         expectedFiles.add(filename);
         const filePath = join(storiesDir, filename);
         const existed = await pathExists(filePath);
-        const displayName = generateDisplayName(name);
+        const displayName = generateDisplayName(name, componentPrefix);
         const content = generateStoryContent(name, displayName, 'custom', customLicenseHeader);
         await writeText(filePath, content);
         if (existed) {

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

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: EUPL-1.2
 import { join } from 'node:path';
 import { pathExists, readText } from '../utils/fs.js';
-import { containsHardcodedTemplateText, createIssue, hasAriaRole, hasDelegatesFocusEnabled, hasGenericInteractiveElement, hasTemplateClickHandler, hasTemplateKeyboardHandler, } from './furnace-validate-helpers.js';
+import { containsHardcodedTemplateText, createIssue, hasAriaRole, hasDelegatesFocusEnabled, hasGenericInteractiveElement, hasPositiveTabindex, hasTemplateClickHandler, hasTemplateKeyboardHandler, hasUnlabelledFormInput, } from './furnace-validate-helpers.js';
 /**
  * Validates accessibility patterns in a component's .mjs file.
  * Checks for ARIA roles, keyboard handlers, l10n, and focus delegation.
@@ -27,6 +27,12 @@ export async function validateAccessibility(componentDir, tagName) {
     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.'));
     }
+    if (hasPositiveTabindex(content)) {
+        issues.push(createIssue(tagName, 'warning', 'positive-tabindex', 'Positive tabindex disrupts natural tab order. Use tabindex="0" for focusable elements or tabindex="-1" for programmatic focus only.'));
+    }
+    if (hasUnlabelledFormInput(content)) {
+        issues.push(createIssue(tagName, 'warning', 'unlabelled-form-input', 'Form input without an accessible label. Add aria-label, aria-labelledby, or an associated <label> element.'));
+    }
     return issues;
 }
 //# sourceMappingURL=furnace-validate-accessibility.js.map

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

@@ -1,6 +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.
+ * Checks imports, class hierarchy, registration, design tokens, and compose references.
  */
 export declare function validateCompatibility(componentDir: string, tagName: string, type: ComponentType, config?: FurnaceConfig, root?: string): Promise<ValidationIssue[]>;

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

@@ -38,11 +38,76 @@ async function validateCssCompatibility(cssPath, tagName, type, config, root) {
             }
         }
     }
+    // Flag excessive !important usage
+    const importantCount = (cssContent.match(/!important/g) ?? []).length;
+    if (importantCount > 3) {
+        issues.push(createIssue(tagName, 'warning', 'excessive-important', `Found ${importantCount} uses of !important. Minimize !important to avoid specificity issues; prefer structural CSS changes.`));
+    }
+    // Check for animations without prefers-reduced-motion
+    if (/(?:animation|transition)\s*:/m.test(cssContent) &&
+        !/@media\s*\(\s*prefers-reduced-motion/m.test(rawCss)) {
+        issues.push(createIssue(tagName, 'warning', 'missing-reduced-motion', 'CSS uses animation or transition without a prefers-reduced-motion media query. Add one for accessibility.'));
+    }
+    // Check for prefers-color-scheme without design token usage
+    if (/@media\s*\(\s*prefers-color-scheme/m.test(rawCss)) {
+        issues.push(createIssue(tagName, 'warning', 'prefers-color-scheme', 'CSS contains a prefers-color-scheme media query. Prefer using design tokens (CSS custom properties) for theming consistency.'));
+    }
+    return issues;
+}
+/**
+ * Checks whether a tag name appears in an HTML template context (as an element
+ * tag in a template literal) or as a CSS tag selector. Substring matches in
+ * string literals, comments, or variable names are excluded.
+ */
+function isReferencedAsElement(source, tagName) {
+    // Match as an HTML element: <tagName or </tagName
+    const htmlPattern = new RegExp(`</?${escapeForValidation(tagName)}[\\s/>]`);
+    if (htmlPattern.test(source))
+        return true;
+    // Match as a CSS tag selector: standalone word at start of line or after combinators
+    const cssPattern = new RegExp(`(?:^|[\\s,>+~])${escapeForValidation(tagName)}(?:[\\s,{:>+~.[#]|$)`, 'm');
+    if (cssPattern.test(source))
+        return true;
+    // Also accept querySelector/querySelectorAll('tagName') as intentional usage
+    const querySelectorPattern = new RegExp(`querySelector(?:All)?\\(\\s*["'\`]${escapeForValidation(tagName)}(?:[\\s"'\`.,>+~:[#])`);
+    if (querySelectorPattern.test(source))
+        return true;
+    return false;
+}
+function escapeForValidation(str) {
+    return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+/**
+ * Validates that composed tags declared in furnace.json are actually referenced
+ * in the component's source (.mjs and .css) in an HTML template or CSS context.
+ * A compose entry that is not referenced as an element tag is likely a metadata
+ * error.
+ */
+async function validateComposeReferences(componentDir, tagName, composes) {
+    if (composes.length === 0)
+        return [];
+    const issues = [];
+    const mjsPath = join(componentDir, `${tagName}.mjs`);
+    const cssPath = join(componentDir, `${tagName}.css`);
+    let mjsContent = '';
+    let cssContent = '';
+    if (await pathExists(mjsPath)) {
+        mjsContent = await readText(mjsPath);
+    }
+    if (await pathExists(cssPath)) {
+        cssContent = await readText(cssPath);
+    }
+    const combinedSource = mjsContent + cssContent;
+    for (const composed of composes) {
+        if (!isReferencedAsElement(combinedSource, composed)) {
+            issues.push(createIssue(tagName, 'warning', 'compose-not-referenced', `Declares composition of "${composed}" but no HTML template or CSS selector reference found in source files. Remove the entry from composes or add a reference.`));
+        }
+    }
     return issues;
 }
 /**
  * Validates compatibility patterns in a component's .mjs and .css files.
- * Checks imports, class hierarchy, registration, and design tokens.
+ * Checks imports, class hierarchy, registration, design tokens, and compose references.
  */
 export async function validateCompatibility(componentDir, tagName, type, config, root) {
     const issues = [];
@@ -52,6 +117,25 @@ export async function validateCompatibility(componentDir, tagName, type, config,
     issues.push(...mjsIssues);
     const cssIssues = await validateCssCompatibility(cssPath, tagName, type, config, root);
     issues.push(...cssIssues);
+    // Compose reference validation (custom components only)
+    if (type === 'custom' && config) {
+        const customConfig = config.custom[tagName];
+        if (customConfig?.composes && customConfig.composes.length > 0) {
+            issues.push(...(await validateComposeReferences(componentDir, tagName, customConfig.composes)));
+            // Warn when a composed component is not registered in furnace.json
+            const allKnown = new Set([
+                ...config.stock,
+                ...Object.keys(config.overrides),
+                ...Object.keys(config.custom),
+            ]);
+            for (const composed of customConfig.composes) {
+                if (!allKnown.has(composed)) {
+                    issues.push(createIssue(tagName, 'warning', 'compose-not-registered', `Composes "${composed}" which is not registered in furnace.json. ` +
+                        'The dependency may be missing at runtime. Add it as stock, override, or custom.'));
+                }
+            }
+        }
+    }
     return issues;
 }
 //# sourceMappingURL=furnace-validate-compatibility.js.map

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

@@ -5,6 +5,10 @@ export declare function createIssue(component: string, severity: ValidationIssue
 export declare function hasAriaRole(content: string): boolean;
 /** Detects generic elements being used as custom interactive controls. */
 export declare function hasGenericInteractiveElement(content: string): boolean;
+/** Detects a positive tabindex value, which disrupts natural tab order. */
+export declare function hasPositiveTabindex(content: string): boolean;
+/** Detects form inputs without associated labels. */
+export declare function hasUnlabelledFormInput(content: string): boolean;
 /** Detects Lit-style template click handlers. */
 export declare function hasTemplateClickHandler(content: string): boolean;
 /** Detects Lit-style template keyboard handlers. */

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

@@ -16,6 +16,34 @@ export function hasAriaRole(content) {
 export function hasGenericInteractiveElement(content) {
     return /<(div|span)\b(?=[^>]*(?:@click|@key(?:down|press|up)|\btabindex\s*=|\.onclick\s*=))/i.test(content);
 }
+/** Detects a positive tabindex value, which disrupts natural tab order. */
+export function hasPositiveTabindex(content) {
+    const match = content.match(/tabindex\s*=\s*["']?(\d+)/g);
+    if (!match)
+        return false;
+    return match.some((m) => {
+        const value = /(\d+)/.exec(m)?.[1];
+        return value !== undefined && parseInt(value, 10) > 0;
+    });
+}
+/** Detects form inputs without associated labels. */
+export function hasUnlabelledFormInput(content) {
+    // Look for <input> or <select> or <textarea> without aria-label, aria-labelledby, or id
+    // (id implies an external <label for="..."> could exist)
+    const inputPattern = /<(input|select|textarea)\b([^>]*)>/gi;
+    let inputMatch;
+    while ((inputMatch = inputPattern.exec(content)) !== null) {
+        const attrs = inputMatch[2] ?? '';
+        if (/aria-label\s*=/.test(attrs) ||
+            /aria-labelledby\s*=/.test(attrs) ||
+            /\bid\s*=/.test(attrs) ||
+            /type\s*=\s*["']hidden["']/i.test(attrs)) {
+            continue;
+        }
+        return true;
+    }
+    return false;
+}
 /** Detects Lit-style template click handlers. */
 export function hasTemplateClickHandler(content) {
     return /@click\s*=\s*\$\{/.test(content);
@@ -85,6 +113,9 @@ export function hasCustomElementDefineCall(mjsContent) {
 export function classExtendsMozLitElement(mjsContent) {
     const hasClassDeclaration = /class\s+\w+\s+extends\s+/.test(mjsContent);
     if (!hasClassDeclaration) {
+        // No class declaration — skip this check since the component may use a
+        // different pattern (e.g. function-based). Other validators will catch
+        // structural issues.
         return true;
     }
     return /class\s+\w+\s+extends\s+MozLitElement\b/.test(mjsContent);