@hominis/fireforge 0.54.0 → 0.60.0

package/dist/src/core/furnace-fragment-includers.js

@@ -1,122 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Reverse index from shared CSS fragments to the custom components that
- * include them, plus the staleness probe a targeted `furnace deploy <tag>`
- * runs over the OTHER includers of the fragments it just refreshed.
- *
- * Fragment staleness was only ever a validator finding
- * (`stale-fragment-expansion` in {@link validateCssFragments}), printed per
- * includer by `furnace validate` and `deploy --dry-run`. A targeted deploy
- * validates only the component it was asked for, so the one command that
- * changes a fragment's deployed state for SOME includers is the one that
- * never mentioned the rest: after a fragment edit, `deploy <a> <b>` left
- * every other consumer carrying the old expansion, and nothing said so
- * until a `grep` over the engine found it.
- *
- * Only custom components are indexed. Override components are copied
- * byte-for-byte and never expand fragments.
- */
-import { readdir } from 'node:fs/promises';
-import { join } from 'node:path';
-import { pathExists, readText } from '../utils/fs.js';
-import { extractExpandedFragmentBodies, listFragmentIncludes, readFragmentSource, } from './furnace-css-fragments.js';
-/** Workspace `.css` sheets of one custom component, with their includes. */
-async function listComponentSheetIncludes(componentDir) {
-    if (!(await pathExists(componentDir)))
-        return [];
-    let entries;
-    try {
-        entries = await readdir(componentDir);
-    }
-    catch {
-        // An unreadable component directory includes nothing. Same degradation
-        // as validateCssFragments: the index must never crash a deploy.
-        return [];
-    }
-    const sheets = [];
-    for (const fileName of entries.sort()) {
-        if (!fileName.endsWith('.css'))
-            continue;
-        const includes = listFragmentIncludes(await readText(join(componentDir, fileName)));
-        if (includes.length > 0)
-            sheets.push({ fileName, includes });
-    }
-    return sheets;
-}
-/**
- * Maps every fragment name to the custom tags whose workspace sheets
- * include it.
- *
- * @param customDir - `components/custom/` directory
- * @param custom - The `custom` map from furnace.json
- */
-export async function collectFragmentIncluders(customDir, custom) {
-    const index = new Map();
-    for (const tag of Object.keys(custom).sort()) {
-        for (const sheet of await listComponentSheetIncludes(join(customDir, tag))) {
-            for (const fragment of sheet.includes) {
-                const tags = index.get(fragment) ?? new Set();
-                tags.add(tag);
-                index.set(fragment, tags);
-            }
-        }
-    }
-    return index;
-}
-/**
- * Finds the other DEPLOYED includers of the fragments `targetTag` includes
- * whose engine sheets do not carry the current fragment source.
- *
- * Only fragments the target includes are considered: a fragment unrelated
- * to this deploy is not its business. An includer whose engine sheet does
- * not exist is not deployed and is skipped. A deployed sheet with no
- * expansion at all counts as stale, the same rule `validateCssFragments`
- * applies.
- *
- * @returns The fragments the target includes, and the stale includers
- *   (sorted by tag), each naming the fragments that are stale for it
- */
-export async function findStaleIncludersOfTargetFragments(args) {
-    const { targetTag, custom, furnacePaths, engineDir } = args;
-    const index = await collectFragmentIncluders(furnacePaths.customDir, custom);
-    const fragments = [...index]
-        .filter(([, tags]) => tags.has(targetTag))
-        .map(([fragment]) => fragment)
-        .sort();
-    if (fragments.length === 0)
-        return { fragments, stale: [] };
-    const targetFragments = new Set(fragments);
-    const sources = new Map();
-    const stale = [];
-    for (const tag of Object.keys(custom).sort()) {
-        if (tag === targetTag)
-            continue;
-        const componentConfig = custom[tag];
-        if (!componentConfig)
-            continue;
-        const engineTargetDir = join(engineDir, componentConfig.targetPath);
-        const staleFragments = new Set();
-        for (const sheet of await listComponentSheetIncludes(join(furnacePaths.customDir, tag))) {
-            const relevant = sheet.includes.filter((f) => targetFragments.has(f));
-            if (relevant.length === 0)
-                continue;
-            const destPath = join(engineTargetDir, sheet.fileName);
-            if (!(await pathExists(destPath)))
-                continue;
-            const bodies = extractExpandedFragmentBodies(await readText(destPath));
-            for (const fragment of relevant) {
-                let source = sources.get(fragment);
-                if (source === undefined) {
-                    source = await readFragmentSource(furnacePaths.sharedDir, fragment);
-                    sources.set(fragment, source);
-                }
-                if (bodies.get(fragment) !== source)
-                    staleFragments.add(fragment);
-            }
-        }
-        if (staleFragments.size > 0) {
-            stale.push({ tag, fragments: [...staleFragments].sort() });
-        }
-    }
-    return { fragments, stale };
-}

package/dist/src/core/furnace-graph-utils.d.ts

@@ -1,11 +0,0 @@
-import type { CustomComponentConfig, FurnaceConfig } from '../types/furnace.js';
-/** Throws a {@link FurnaceError} if the composes graph among custom components contains a cycle. */
-export declare function detectComposesCycles(custom: FurnaceConfig['custom']): void;
-/** Validates that every `composes` reference in custom components points to a known component. */
-export declare function validateComposesReferences(stock: string[], overrides: FurnaceConfig['overrides'], custom: FurnaceConfig['custom']): void;
-/**
- * Returns custom component names in topological order so that components
- * depended upon via `composes` are applied before those that compose them.
- * Falls back to insertion order when there are no composes edges.
- */
-export declare function topologicalSortCustom(custom: Record<string, CustomComponentConfig>): string[];

package/dist/src/core/furnace-graph-utils.js

@@ -1,93 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-import { FurnaceError } from '../errors/furnace.js';
-/** Throws a {@link FurnaceError} if the composes graph among custom components contains a cycle. */
-export function detectComposesCycles(custom) {
-    const visited = new Set();
-    const stack = new Set();
-    function visit(name, path) {
-        if (stack.has(name)) {
-            const cycle = [...path.slice(path.indexOf(name)), name];
-            throw new FurnaceError(`Furnace config: circular composes dependency detected: ${cycle.join(' → ')}`);
-        }
-        if (visited.has(name))
-            return;
-        stack.add(name);
-        path.push(name);
-        const deps = custom[name]?.composes;
-        if (deps) {
-            for (const dep of deps) {
-                if (dep in custom) {
-                    visit(dep, path);
-                }
-            }
-        }
-        path.pop();
-        stack.delete(name);
-        visited.add(name);
-    }
-    for (const name of Object.keys(custom)) {
-        visit(name, []);
-    }
-}
-/** Validates that every `composes` reference in custom components points to a known component. */
-export function validateComposesReferences(stock, overrides, custom) {
-    const known = new Set([...stock, ...Object.keys(overrides), ...Object.keys(custom)]);
-    for (const [name, config] of Object.entries(custom)) {
-        if (!config.composes)
-            continue;
-        for (const ref of config.composes) {
-            if (!known.has(ref)) {
-                throw new FurnaceError(`Furnace config: custom "${name}" composes unknown component "${ref}". ` +
-                    'The referenced component must be registered as stock, override, or custom.');
-            }
-        }
-    }
-}
-/**
- * Returns custom component names in topological order so that components
- * depended upon via `composes` are applied before those that compose them.
- * Falls back to insertion order when there are no composes edges.
- */
-export function topologicalSortCustom(custom) {
-    const names = Object.keys(custom);
-    const inDegree = new Map();
-    const dependents = new Map();
-    for (const name of names) {
-        inDegree.set(name, 0);
-        dependents.set(name, []);
-    }
-    for (const [name, config] of Object.entries(custom)) {
-        if (!config.composes)
-            continue;
-        for (const dep of config.composes) {
-            if (dep in custom) {
-                inDegree.set(name, (inDegree.get(name) ?? 0) + 1);
-                dependents.get(dep)?.push(name);
-            }
-        }
-    }
-    const queue = names.filter((n) => (inDegree.get(n) ?? 0) === 0);
-    const sorted = [];
-    while (queue.length > 0) {
-        // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- guarded by while condition
-        const current = queue.shift();
-        sorted.push(current);
-        for (const dep of dependents.get(current) ?? []) {
-            const newDegree = (inDegree.get(dep) ?? 1) - 1;
-            inDegree.set(dep, newDegree);
-            if (newDegree === 0) {
-                queue.push(dep);
-            }
-        }
-    }
-    // If a cycle was somehow missed by config validation, fall back to insertion order
-    // for any nodes not reached.
-    if (sorted.length < names.length) {
-        for (const name of names) {
-            if (!sorted.includes(name)) {
-                sorted.push(name);
-            }
-        }
-    }
-    return sorted;
-}

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

@@ -1,61 +0,0 @@
-/**
- * Maintains `compilerOptions.paths` entries in a consumer-owned jsconfig so
- * typed cross-module imports of multi-file Furnace components work.
- *
- * When a main widget imports a sibling helper via its deployed chrome URL
- * (`chrome://global/content/elements/<helper>.mjs`), a wildcard module shim
- * swallows the import: value imports degrade to `any` and
- * `import(...).SomeType` typedefs fail with TS2694. The fix is a `paths`
- * mapping from the chrome URL to the real workspace source. Furnace already
- * owns the jar.mn side of that mapping, so it maintains the jsconfig side
- * automatically on every deploy.
- *
- * Ownership contract: only entries whose key starts with
- * `chrome://global/content/elements/` and whose mapped path resolves into
- * the Furnace custom-components workspace are managed (added, updated,
- * pruned). Everything else in the jsconfig, including hand-written `paths`
- * entries pointing elsewhere, is preserved verbatim. No `baseUrl` is
- * required or written: relative `paths` resolve against the config file's
- * directory.
- */
-import type { FurnaceConfig } from '../types/furnace.js';
-/** Result summary of a jsconfig paths sync. */
-export interface JsconfigSyncResult {
-    /** Keys newly added to compilerOptions.paths. */
-    added: string[];
-    /** Managed keys whose mapped path changed. */
-    updated: string[];
-    /** Managed keys removed because their component/file is gone. */
-    pruned: string[];
-    /** True when the file was (or would be) rewritten. */
-    changed: boolean;
-}
-/**
- * Reconciles the managed `compilerOptions.paths` entries of the configured
- * jsconfig against the current Furnace workspace. Idempotent, and writes
- * only when something actually changes. Dry-run returns the diff without
- * writing.
- *
- * The consumer owns the jsconfig file: a missing file is an error with
- * guidance rather than a silent scaffold. JSONC comments and trailing commas
- * are preserved. Furnace edits only `compilerOptions.paths`.
- *
- * @param root - Project root directory
- * @param config - Loaded Furnace configuration (must carry `typecheckJsconfig`)
- * @param options - `dryRun` skips the write but still reports the diff
- */
-export declare function syncFurnaceJsconfigPaths(root: string, config: FurnaceConfig, options?: {
-    dryRun?: boolean;
-}): Promise<JsconfigSyncResult>;
-/**
- * Computes jsconfig `paths` drift for `furnace validate`: managed entries
- * that are missing or stale relative to the current workspace. Read-only:
- * delegates to {@link syncFurnaceJsconfigPaths} in dry-run mode.
- */
-export declare function findJsconfigPathsDrift(root: string, config: FurnaceConfig): Promise<JsconfigSyncResult>;
-/**
- * Runs the jsconfig paths sync after a successful deploy/sync and reports
- * the diff. No-op when `typecheckJsconfig` is unset. Shared by
- * `furnace deploy` and `furnace sync` so both report identically.
- */
-export declare function reportJsconfigPathsSync(root: string, config: FurnaceConfig, dryRun: boolean): Promise<void>;

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

@@ -1,208 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Maintains `compilerOptions.paths` entries in a consumer-owned jsconfig so
- * typed cross-module imports of multi-file Furnace components work.
- *
- * When a main widget imports a sibling helper via its deployed chrome URL
- * (`chrome://global/content/elements/<helper>.mjs`), a wildcard module shim
- * swallows the import: value imports degrade to `any` and
- * `import(...).SomeType` typedefs fail with TS2694. The fix is a `paths`
- * mapping from the chrome URL to the real workspace source. Furnace already
- * owns the jar.mn side of that mapping, so it maintains the jsconfig side
- * automatically on every deploy.
- *
- * Ownership contract: only entries whose key starts with
- * `chrome://global/content/elements/` and whose mapped path resolves into
- * the Furnace custom-components workspace are managed (added, updated,
- * pruned). Everything else in the jsconfig, including hand-written `paths`
- * entries pointing elsewhere, is preserved verbatim. No `baseUrl` is
- * required or written: relative `paths` resolve against the config file's
- * directory.
- */
-import { readdir } from 'node:fs/promises';
-import { dirname, join, relative, resolve } from 'node:path';
-import { applyEdits, modify, parse } from 'jsonc-parser';
-import { FurnaceError } from '../errors/furnace.js';
-import { toError } from '../utils/errors.js';
-import { pathExists, readText, writeTextIfChanged } from '../utils/fs.js';
-import { info } from '../utils/logger.js';
-import { isPathInsideRoot, normalizePathSlashes } from '../utils/paths.js';
-import { getFurnacePaths } from './furnace-config.js';
-/** Chrome URL prefix under which registered custom-element files deploy. */
-const CHROME_ELEMENTS_URL_PREFIX = 'chrome://global/content/elements/';
-/**
- * Computes the desired managed `paths` entries: one per `.mjs` file of
- * every custom component, registered or not, keyed by its deployed
- * chrome URL and mapped to the workspace source relative to the jsconfig
- * directory. `register: false` components (notably `kind: "library"`
- * base-class modules, which require register: false) are included because
- * deploy copies their files and writes jar.mn entries under
- * `content/global/elements/` unconditionally. Only the customElements.js
- * registration is gated on `register`, so their chrome URLs are just as
- * real as a registered component's.
- *
- * The mapping target is the workspace source, not the deployed engine
- * copy. Those are the files developers edit, and they exist even when the
- * engine has not been deployed yet.
- */
-async function computeDesiredChromePathEntries(config, customDir, jsconfigAbsPath) {
-    const jsconfigDir = dirname(jsconfigAbsPath);
-    const entries = {};
-    for (const name of Object.keys(config.custom)) {
-        const componentDir = join(customDir, name);
-        if (!(await pathExists(componentDir)))
-            continue;
-        const files = await readdir(componentDir);
-        for (const file of files.sort()) {
-            if (!file.endsWith('.mjs'))
-                continue;
-            // Emit a `./`-prefixed relative value. TypeScript treats a bare
-            // `paths` value (`moz-widget/moz-widget.mjs`) as non-relative and
-            // rejects it without `baseUrl` (TS5090). A `./`-prefixed value
-            // resolves against the jsconfig directory with no `baseUrl` (which
-            // TS6 deprecates, TS5101). `../`-prefixed paths are already relative
-            // and left untouched.
-            const rel = normalizePathSlashes(relative(jsconfigDir, join(componentDir, file)));
-            const sourcePath = rel.startsWith('.') ? rel : `./${rel}`;
-            entries[`${CHROME_ELEMENTS_URL_PREFIX}${file}`] = [sourcePath];
-        }
-    }
-    return entries;
-}
-/**
- * Compares two `paths` values treating a leading `./` as insignificant, so
- * the reconciler does not churn between `./x` and bare `x` forms (either
- * direction). Used to decide whether a managed entry is stale.
- */
-function samePathValue(a, b) {
-    const strip = (p) => (p.startsWith('./') ? p.slice(2) : p);
-    return strip(a) === strip(b);
-}
-/** True when `key`/`value` is a Furnace-managed chrome-elements mapping. */
-function isManagedEntry(key, value, jsconfigDir, customDir) {
-    if (!key.startsWith(CHROME_ELEMENTS_URL_PREFIX))
-        return false;
-    if (!Array.isArray(value) || value.length !== 1 || typeof value[0] !== 'string')
-        return false;
-    // Containment via `relative`, not a string prefix: a hard-coded `'/'`
-    // separator never matches the backslashes `resolve` emits on Windows, which
-    // demoted every managed entry to "unmanaged" there, so no pruning and no
-    // updates.
-    return isPathInsideRoot(customDir, resolve(jsconfigDir, value[0]));
-}
-/**
- * Reconciles the managed `compilerOptions.paths` entries of the configured
- * jsconfig against the current Furnace workspace. Idempotent, and writes
- * only when something actually changes. Dry-run returns the diff without
- * writing.
- *
- * The consumer owns the jsconfig file: a missing file is an error with
- * guidance rather than a silent scaffold. JSONC comments and trailing commas
- * are preserved. Furnace edits only `compilerOptions.paths`.
- *
- * @param root - Project root directory
- * @param config - Loaded Furnace configuration (must carry `typecheckJsconfig`)
- * @param options - `dryRun` skips the write but still reports the diff
- */
-export async function syncFurnaceJsconfigPaths(root, config, options) {
-    const result = { added: [], updated: [], pruned: [], changed: false };
-    const jsconfigRel = config.typecheckJsconfig;
-    if (!jsconfigRel)
-        return result;
-    const jsconfigAbs = resolve(root, jsconfigRel);
-    if (!(await pathExists(jsconfigAbs))) {
-        throw new FurnaceError(`furnace.json sets "typecheckJsconfig": "${jsconfigRel}", but the file does not exist. ` +
-            'Create the jsconfig (it stays consumer-owned; Furnace only maintains the ' +
-            `"compilerOptions.paths" entries under ${CHROME_ELEMENTS_URL_PREFIX}*), ` +
-            'or remove the setting.');
-    }
-    const jsconfigText = await readText(jsconfigAbs);
-    const parseErrors = [];
-    let jsconfig;
-    try {
-        // No cast: the target is declared `unknown` and is validated below, so
-        // an assertion here would be discarded on assignment anyway.
-        jsconfig = parse(jsconfigText, parseErrors, {
-            allowTrailingComma: true,
-            disallowComments: false,
-        });
-    }
-    catch (error) {
-        throw new FurnaceError(`Could not parse ${jsconfigRel} as JSONC: ${toError(error).message}.`);
-    }
-    if (parseErrors.length > 0 ||
-        typeof jsconfig !== 'object' ||
-        jsconfig === null ||
-        Array.isArray(jsconfig)) {
-        throw new FurnaceError(`Could not parse ${jsconfigRel} as JSONC: expected an object jsconfig file.`);
-    }
-    const jsconfigObject = jsconfig;
-    const furnacePaths = getFurnacePaths(root);
-    const desired = await computeDesiredChromePathEntries(config, furnacePaths.customDir, jsconfigAbs);
-    const jsconfigDir = dirname(jsconfigAbs);
-    const currentPaths = {
-        ...(jsconfigObject.compilerOptions?.paths ?? {}),
-    };
-    const nextPaths = {};
-    // Preserve every unmanaged entry verbatim. Prune managed entries that are
-    // no longer desired. Update managed entries whose target moved.
-    for (const [key, value] of Object.entries(currentPaths)) {
-        if (!isManagedEntry(key, value, jsconfigDir, furnacePaths.customDir)) {
-            nextPaths[key] = value;
-            continue;
-        }
-        const want = desired[key];
-        if (want === undefined) {
-            result.pruned.push(key);
-            continue;
-        }
-        // Treat `./x` and bare `x` as equal so a previously-synced bare value (or
-        // a hand-written `./` prefix) is not rewritten as "stale" on every run.
-        // The existing value is kept verbatim when equivalent, so there is no
-        // churn either way. Only a genuinely different target updates (to the
-        // `./` form).
-        if (!samePathValue(value[0], want[0] ?? '')) {
-            result.updated.push(key);
-            nextPaths[key] = want;
-        }
-        else {
-            nextPaths[key] = value;
-        }
-    }
-    for (const [key, want] of Object.entries(desired)) {
-        if (!(key in nextPaths)) {
-            result.added.push(key);
-            nextPaths[key] = want;
-        }
-    }
-    result.changed = result.added.length > 0 || result.updated.length > 0 || result.pruned.length > 0;
-    if (!result.changed || options?.dryRun === true)
-        return result;
-    const edits = modify(jsconfigText, ['compilerOptions', 'paths'], nextPaths, {
-        formattingOptions: { insertSpaces: true, tabSize: 2, eol: '\n' },
-    });
-    await writeTextIfChanged(jsconfigAbs, applyEdits(jsconfigText, edits));
-    return result;
-}
-/**
- * Computes jsconfig `paths` drift for `furnace validate`: managed entries
- * that are missing or stale relative to the current workspace. Read-only:
- * delegates to {@link syncFurnaceJsconfigPaths} in dry-run mode.
- */
-export async function findJsconfigPathsDrift(root, config) {
-    return syncFurnaceJsconfigPaths(root, config, { dryRun: true });
-}
-/**
- * Runs the jsconfig paths sync after a successful deploy/sync and reports
- * the diff. No-op when `typecheckJsconfig` is unset. Shared by
- * `furnace deploy` and `furnace sync` so both report identically.
- */
-export async function reportJsconfigPathsSync(root, config, dryRun) {
-    if (!config.typecheckJsconfig)
-        return;
-    const sync = await syncFurnaceJsconfigPaths(root, config, { dryRun });
-    if (!sync.changed)
-        return;
-    info(`${dryRun ? '[dry-run] Would update' : 'Updated'} ${config.typecheckJsconfig} chrome-module paths: ` +
-        `+${sync.added.length} added, ~${sync.updated.length} updated, -${sync.pruned.length} pruned`);
-}

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

@@ -1,15 +0,0 @@
-/**
- * Marker-comment resolution shared between furnace apply and deploy.
- *
- * When `markerComment` is unset in fireforge.json, fall back to
- * `binaryName.toUpperCase()` so the patch-lint rule
- * `lintModificationComments` (which keys on `${binaryName.toUpperCase()}:`)
- * accepts furnace-emitted edits on the next `lint`/`export` round-trip. The
- * helper tolerates the undefined-config case (a project that has not run
- * `fireforge setup` yet) and the missing-binaryName case (test fixtures that
- * mock `loadConfig` with a partial shape).
- */
-export declare function resolveFurnaceMarkerComment(forgeConfig: {
-    markerComment?: string;
-    binaryName?: string;
-} | undefined): string | undefined;

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

@@ -1,21 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Marker-comment resolution shared between furnace apply and deploy.
- *
- * When `markerComment` is unset in fireforge.json, fall back to
- * `binaryName.toUpperCase()` so the patch-lint rule
- * `lintModificationComments` (which keys on `${binaryName.toUpperCase()}:`)
- * accepts furnace-emitted edits on the next `lint`/`export` round-trip. The
- * helper tolerates the undefined-config case (a project that has not run
- * `fireforge setup` yet) and the missing-binaryName case (test fixtures that
- * mock `loadConfig` with a partial shape).
- */
-export function resolveFurnaceMarkerComment(forgeConfig) {
-    if (!forgeConfig)
-        return undefined;
-    if (forgeConfig.markerComment !== undefined)
-        return forgeConfig.markerComment;
-    if (forgeConfig.binaryName)
-        return forgeConfig.binaryName.toUpperCase();
-    return undefined;
-}