@hominis/fireforge 0.55.0 → 0.60.0

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

@@ -1,167 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Section validators for `validateFurnaceConfig`, split out of
- * `furnace-config.ts` to keep that module inside the per-file line
- * budget. Each helper owns one shape: the override entry, the stock
- * list, the named-component maps, and the optional-field tail.
- */
-import { FurnaceError } from '../errors/furnace.js';
-import { isJsonObject, isString } from '../utils/validation.js';
-import { parseStringArray } from './furnace-config-array-utils.js';
-import { parseMinComponents, parseOptInChecks, parseTokenSiblingSheets, parseValidationExceptions, } from './furnace-config-validate-exceptions.js';
-/**
- * Validates an override component config object.
- * @param data - Raw data to validate
- * @param name - Component name for error messages
- */
-export function parseOverrideConfig(data, name) {
-    const validTypes = ['css-only', 'full'];
-    if (!isString(data['type']) || !validTypes.includes(data['type'])) {
-        throw new FurnaceError(`Furnace config: override "${name}.type" must be one of: ${validTypes.join(', ')}`);
-    }
-    if (!isString(data['description'])) {
-        throw new FurnaceError(`Furnace config: override "${name}.description" must be a string`);
-    }
-    if (!isString(data['basePath'])) {
-        throw new FurnaceError(`Furnace config: override "${name}.basePath" must be a string`);
-    }
-    if (data['basePath'].includes('..')) {
-        throw new FurnaceError(`Furnace config: override "${name}.basePath" must not contain ".." (path traversal)`);
-    }
-    if (!isString(data['baseVersion'])) {
-        throw new FurnaceError(`Furnace config: override "${name}.baseVersion" must be a string`);
-    }
-    return {
-        type: data['type'] === 'css-only' ? 'css-only' : 'full',
-        description: data['description'],
-        basePath: data['basePath'],
-        baseVersion: data['baseVersion'],
-        ...(isString(data['baseCommit']) ? { baseCommit: data['baseCommit'] } : {}),
-    };
-}
-/**
- * Parses and validates the `stock` component list: lowercase identifiers,
- * no duplicates.
- */
-export function parseStockList(raw) {
-    const stock = parseStringArray(raw, 'stock');
-    const stockSet = new Set();
-    for (const name of stock) {
-        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
-            throw new FurnaceError(`Furnace config: stock entry "${name}" must match /^[a-z][a-z0-9-]*$/ (lowercase, no path separators)`);
-        }
-        if (stockSet.has(name)) {
-            throw new FurnaceError(`Furnace config: duplicate stock entry "${name}"`);
-        }
-        stockSet.add(name);
-    }
-    return stock;
-}
-/**
- * Parses one of the named-component maps (`overrides` / `custom`): the
- * map must be an object, every key a lowercase identifier, every value an
- * object handed to the kind-specific parser.
- */
-export function parseNamedComponentMap(raw, kind, key, parse) {
-    if (!isJsonObject(raw)) {
-        throw new FurnaceError(`Furnace config: "${key}" must be an object`);
-    }
-    const out = {};
-    for (const [name, value] of Object.entries(raw)) {
-        if (!/^[a-z][a-z0-9-]*$/.test(name)) {
-            throw new FurnaceError(`Furnace config: ${kind} name "${name}" must match /^[a-z][a-z0-9-]*$/ (lowercase, no path separators)`);
-        }
-        if (!isJsonObject(value)) {
-            throw new FurnaceError(`Furnace config: ${kind} "${name}" must be an object`);
-        }
-        out[name] = parse(value, name);
-    }
-    return out;
-}
-/**
- * Validates `typecheckJsconfig`: one path, or a non-empty list of distinct
- * paths, none with `..`. A one-entry list stays a list.
- */
-function parseTypecheckJsconfig(raw) {
-    const message = 'Furnace config: "typecheckJsconfig" must be a path or a non-empty array of distinct ' +
-        'paths, without ".." (path traversal)';
-    const paths = isString(raw) ? [raw] : Array.isArray(raw) ? raw : undefined;
-    if (paths === undefined ||
-        paths.length === 0 ||
-        paths.some((path) => !isString(path) || path.includes('..')) ||
-        new Set(paths).size !== paths.length) {
-        throw new FurnaceError(message);
-    }
-    return isString(raw) ? raw : paths;
-}
-/**
- * Copies the validated optional fields (token settings, platform
- * prefixes, ftl/jsconfig/scan paths) from the migrated raw config onto
- * the typed config, re-validating the path-shaped ones against
- * traversal.
- */
-export function applyOptionalFurnaceFields(migrated, config) {
-    if (migrated['tokenPrefix'] !== undefined && isString(migrated['tokenPrefix'])) {
-        config.tokenPrefix = migrated['tokenPrefix'];
-    }
-    if (migrated['tokenAllowlist'] !== undefined) {
-        config.tokenAllowlist = parseStringArray(migrated['tokenAllowlist'], 'tokenAllowlist');
-    }
-    if (migrated['platformPrefixes'] !== undefined) {
-        config.platformPrefixes = parseStringArray(migrated['platformPrefixes'], 'platformPrefixes');
-    }
-    if (migrated['tokenSiblingSheets'] !== undefined) {
-        config.tokenSiblingSheets = parseTokenSiblingSheets(migrated['tokenSiblingSheets']);
-    }
-    if (migrated['runtimeVariables'] !== undefined) {
-        config.runtimeVariables = parseStringArray(migrated['runtimeVariables'], 'runtimeVariables');
-    }
-    if (migrated['tokenHostDocuments'] !== undefined) {
-        const docs = parseStringArray(migrated['tokenHostDocuments'], 'tokenHostDocuments');
-        config.tokenHostDocuments = docs;
-    }
-    // Validate optional ftlBasePath
-    if (migrated['ftlBasePath'] !== undefined) {
-        if (!isString(migrated['ftlBasePath'])) {
-            throw new FurnaceError('Furnace config: "ftlBasePath" must be a string if provided');
-        }
-        if (migrated['ftlBasePath'].includes('..')) {
-            throw new FurnaceError('Furnace config: "ftlBasePath" must not contain ".." (path traversal)');
-        }
-        config.ftlBasePath = migrated['ftlBasePath'];
-    }
-    // Validate optional typecheckJsconfig: one or more consumer-owned
-    // jsconfigs whose chrome-elements `paths` entries Furnace maintains on
-    // deploy.
-    if (migrated['typecheckJsconfig'] !== undefined) {
-        config.typecheckJsconfig = parseTypecheckJsconfig(migrated['typecheckJsconfig']);
-    }
-    // Validate optional typecheckTagMap, the generated tag-map declaration.
-    if (migrated['typecheckTagMap'] !== undefined) {
-        const tagMap = migrated['typecheckTagMap'];
-        if (!isString(tagMap) || tagMap.includes('..') || !tagMap.endsWith('.d.ts')) {
-            throw new FurnaceError('Furnace config: "typecheckTagMap" must be a ".d.ts" path without ".." (path traversal)');
-        }
-        config.typecheckTagMap = tagMap;
-    }
-    // Validate optional scanPaths
-    if (migrated['scanPaths'] !== undefined) {
-        const paths = parseStringArray(migrated['scanPaths'], 'scanPaths');
-        for (const p of paths) {
-            if (p.includes('..')) {
-                throw new FurnaceError('Furnace config: "scanPaths" entries must not contain ".." (path traversal)');
-            }
-        }
-        config.scanPaths = paths;
-    }
-    // `furnace validate` policy: reviewed exceptions and opt-in checks.
-    if (migrated['validationExceptions'] !== undefined) {
-        config.validationExceptions = parseValidationExceptions(migrated['validationExceptions']);
-    }
-    if (migrated['optInChecks'] !== undefined) {
-        config.optInChecks = parseOptInChecks(migrated['optInChecks']);
-    }
-    if (migrated['minComponents'] !== undefined) {
-        config.minComponents = parseMinComponents(migrated['minComponents']);
-    }
-}

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

@@ -1,139 +0,0 @@
-import type { FurnaceConfig, FurnaceState } from '../types/furnace.js';
-import { detectComposesCycles } from './furnace-graph-utils.js';
-export { detectComposesCycles };
-/** Directory name for shared CSS fragments within components/ */
-export declare const SHARED_FRAGMENTS_DIR = "shared";
-/**
- * Paths for furnace-related files and directories.
- */
-export interface FurnacePaths {
-    /** Path to furnace.json */
-    furnaceConfig: string;
-    /** Path to components directory */
-    componentsDir: string;
-    /** Path to components/overrides directory */
-    overridesDir: string;
-    /** Path to components/custom directory */
-    customDir: string;
-    /** Path to components/shared directory (CSS fragments) */
-    sharedDir: string;
-    /** Path to .fireforge/furnace-state.json */
-    furnaceState: string;
-}
-/**
- * Gets all furnace-related paths based on a root directory.
- * @param root - Root directory of the project
- * @returns All furnace paths
- */
-export declare function getFurnacePaths(root: string): FurnacePaths;
-/**
- * Checks if a furnace.json exists in the given directory.
- * @param root - Root directory to check
- * @returns True if furnace.json exists
- */
-export declare function furnaceConfigExists(root: string): Promise<boolean>;
-/**
- * Validates a raw config object and returns a typed FurnaceConfig.
- * @param data - Raw data to validate
- * @returns Validated FurnaceConfig
- * @throws Error if validation fails
- */
-export declare function validateFurnaceConfig(data: unknown): FurnaceConfig;
-/**
- * Loads and validates the furnace.json configuration.
- * @param root - Root directory of the project
- * @returns Validated FurnaceConfig
- * @throws Error if config doesn't exist or is invalid
- */
-export declare function loadFurnaceConfig(root: string): Promise<FurnaceConfig>;
-/**
- * Clears applied furnace state while preserving `pendingRepair`.
- *
- * Used whenever the engine baseline is replaced or reset (download --force,
- * reset, rebase, rebase --abort): every applied checksum describes content
- * that no longer exists, but pendingRepair tracks authoring-side rollback
- * issues in the component WORKSPACE and must survive an engine refresh.
- * No-ops when the state file does not exist.
- */
-export declare function clearAppliedFurnaceState(root: string): Promise<void>;
-/**
- * Writes a furnace configuration to furnace.json.
- * @param root - Root directory of the project
- * @param config - Configuration to write
- */
-export declare function writeFurnaceConfig(root: string, config: FurnaceConfig): Promise<void>;
-/**
- * Stamps every override's `baseVersion` to the supplied version. Used by
- * `fireforge rebase` after a successful patch re-export, so an ESR bump does
- * not leave Furnace overrides in a doctor-failing drift state: `rebase`
- * stamps patch `sourceEsrVersion` via `stampPatchVersions`, and without the
- * matching override stamp `doctor` fails Furnace component validation on
- * every override.
- *
- * The stamp is unconditional: `fireforge furnace validate` is the right
- * tool for "does this override still apply", and rebase has
- * already attested that the patch layer re-validated against the new ESR.
- *
- * @param root - Root directory of the project
- * @param version - Firefox version string to stamp onto every override
- * @returns Number of overrides whose `baseVersion` was updated (either
- *   because it was missing or because it differed from `version`).
- */
-export declare function stampFurnaceOverrideBaseVersions(root: string, version: string): Promise<number>;
-/**
- * Creates a default furnace configuration.
- *
- * When a `binaryName` is provided, the default config carries a
- * `tokenPrefix` derived as `--<binaryName>-`. Without it, `fireforge token
- * coverage` on a fresh project reports `0 tokens` and labels every
- * custom-property reference as `unknown`, because the scan has no prefix to
- * key off. Deriving the prefix from the binary name matches the convention
- * the scaffolded tokens CSS already uses for its `--<binaryName>-*`
- * declarations.
- *
- * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers on
- * the no-arg call shape still get a valid config without a prefix. The CLI
- * init path always has a `binaryName` from `fireforge.json` and always sets
- * one.
- *
- * @param options - Optional init context. Pass `{ binaryName }` to derive
- *   the token prefix.
- * @returns A valid FurnaceConfig
- */
-export declare function createDefaultFurnaceConfig(options?: {
-    binaryName?: string;
-}): FurnaceConfig;
-/**
- * Loads furnace config if it exists, or creates and writes a default config.
- * @param root - Root directory of the project
- * @returns FurnaceConfig (existing or newly created)
- */
-export declare function ensureFurnaceConfig(root: string): Promise<FurnaceConfig>;
-/**
- * Loads the furnace state, or returns defaults if it doesn't exist.
- * @param root - Root directory of the project
- * @returns Furnace state
- */
-export declare function loadFurnaceState(root: string): Promise<FurnaceState>;
-/**
- * Saves the furnace state.
- * @param root - Root directory of the project
- * @param state - State to save
- */
-export declare function saveFurnaceState(root: string, state: FurnaceState): Promise<void>;
-/**
- * Updates furnace state fields transactionally under the state file lock.
- * @param root - Root directory of the project
- * @param updates - Fields to update, or a transactional updater function
- */
-export declare function updateFurnaceState(root: string, updates: Partial<FurnaceState> | ((current: FurnaceState) => FurnaceState)): Promise<void>;
-/**
- * Collects engine-relative path prefixes that are managed by the Furnace
- * component system (overrides, custom components, and their Fluent l10n
- * files). Used by `status` and `export-all` to classify engine changes
- * as Furnace-managed rather than unmanaged drift.
- *
- * Returns an empty set when no furnace config exists (opt-in subsystem).
- * Prefixes always end with `/` so callers can use `startsWith()`.
- */
-export declare function collectFurnaceManagedPrefixes(root: string): Promise<Set<string>>;