@hominis/fireforge 0.50.0 → 0.52.0

package/dist/src/core/file-lock-shared.js

@@ -0,0 +1,117 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * Shared holds on a FireForge directory lock.
+ *
+ * Every lock used to be exclusive, so two build-less `fireforge test` runs
+ * on one objdir, each with its own profile and (under auto ports) its own
+ * ports, still waited for each other: the gate's browser tiers ran strictly
+ * serially on a 14-core host. A shared hold lets such runs overlap while
+ * anything that writes (a build, a re-export, a test run that builds)
+ * still holds the lock alone.
+ *
+ * The scheme reuses the exclusive lock as a turnstile, so arrival order and
+ * stale-holder reaping come from the machinery that already exists:
+ *
+ *  - A shared holder takes the exclusive lock in the ordinary way, records
+ *    itself under `<lock>.shared/<uuid>/` (an owner record like the lock's
+ *    own), and releases the exclusive lock at once.
+ *  - An exclusive holder takes the exclusive lock, then waits until no live
+ *    shared holder is left. While it waits it already holds the turnstile,
+ *    so no new shared holder can slip in ahead of it: a writer queued
+ *    behind readers is served once they finish, never starved by newcomers.
+ *
+ * A shared holder whose process died is reaped by the same PID-first
+ * liveness check the exclusive lock uses.
+ */
+import { randomUUID } from 'node:crypto';
+import { mkdir, readdir, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { getNodeErrorCode, toError } from '../utils/errors.js';
+import { verbose } from '../utils/logger.js';
+import { isLockOwnerAlive, readLockOwner, writeLockOwner } from './file-lock-owner.js';
+/** The directory holding a lock's shared-holder records. */
+export function sharedHoldersDir(lockPath) {
+    return `${lockPath}.shared`;
+}
+/** Holder directories this process registered, for the signal sweep. */
+const heldShares = new Set();
+/**
+ * Counts the live shared holders of a lock, reaping any whose process is
+ * gone. A missing directory means none.
+ *
+ * @param lockPath - The lock directory
+ * @param options - `reap: false` only counts (status reads)
+ */
+export async function countLiveSharedHolders(lockPath, options = {}) {
+    const dir = sharedHoldersDir(lockPath);
+    let entries;
+    try {
+        entries = await readdir(dir);
+    }
+    catch (error) {
+        if (getNodeErrorCode(error) === 'ENOENT')
+            return 0;
+        if (options.reap === false)
+            return 0;
+        throw toError(error);
+    }
+    let live = 0;
+    for (const entry of entries) {
+        const holder = join(dir, entry);
+        const owner = await readLockOwner(holder);
+        if (owner.present && isLockOwnerAlive(owner)) {
+            live += 1;
+            continue;
+        }
+        // A record still being written has no owner yet; only an owner that
+        // names a dead process is reaped, so a racing registration survives.
+        if (owner.present && options.reap !== false) {
+            verbose(`Reaping shared hold ${holder}: PID ${owner.pid} is gone.`);
+            await rm(holder, { recursive: true, force: true });
+        }
+    }
+    return live;
+}
+/**
+ * Records a shared hold. Call while holding the lock's exclusive turnstile.
+ *
+ * @param lockPath - The lock directory
+ * @param metadata - Owner metadata lines (`command=…`)
+ */
+export async function registerSharedHold(lockPath, metadata) {
+    const holder = join(sharedHoldersDir(lockPath), randomUUID());
+    await mkdir(holder, { recursive: true });
+    await writeLockOwner(holder, randomUUID(), [...(metadata ?? []), 'mode=shared']);
+    heldShares.add(holder);
+    return {
+        async release() {
+            heldShares.delete(holder);
+            try {
+                await rm(holder, { recursive: true, force: true });
+            }
+            catch (error) {
+                verbose(`Could not remove shared hold ${holder}: ${toError(error).message}`);
+            }
+        },
+    };
+}
+/**
+ * Removes every shared hold this process registered, for the signal path.
+ * Never throws.
+ *
+ * @returns The holder paths removed
+ */
+export async function releaseSharedHoldsForSignal() {
+    const removed = [];
+    for (const holder of [...heldShares]) {
+        heldShares.delete(holder);
+        try {
+            await rm(holder, { recursive: true, force: true });
+            removed.push(holder);
+        }
+        catch {
+            // Shutdown path: nothing to do.
+        }
+    }
+    return removed;
+}

package/dist/src/core/file-lock.d.ts

@@ -1,7 +1,9 @@
 import { LOCK_PID_FILE } from './file-lock-owner.js';
 import { type LockQueueState } from './file-lock-queue.js';
+import { type LockMode } from './file-lock-shared.js';
 export { LOCK_PID_FILE };
 export { formatLockQueuePosition, type LockQueueState } from './file-lock-queue.js';
+export type { LockMode } from './file-lock-shared.js';
 /**
  * Snapshot of the current lock holder handed to {@link FileLockOptions.onWaitProgress}.
  * `metadata` carries the pid file's human-diagnostic lines (line 3 onward,
@@ -84,6 +86,11 @@ export interface FileLockOptions {
     onStaleLockMessage?: (ageMs: number) => string | undefined;
     /** Extra owner-file lines for human diagnostics. Lock mechanics ignore them. */
     ownerMetadata?: readonly string[];
+    /**
+     * `exclusive` (default) or `shared`. Shared holders overlap each other and
+     * exclude exclusive ones; see `file-lock-shared.ts`.
+     */
+    mode?: LockMode | undefined;
 }
 /** Derives the sibling lock-directory path used to guard a file-based resource. */
 export declare function createSiblingLockPath(filePath: string, suffix?: string): string;
@@ -97,6 +104,8 @@ export interface LockStatusSnapshot {
     /** Milliseconds since the lock directory was created, when held. */
     heldForMs?: number | undefined;
     queueDepth: number;
+    /** Live shared holders (build-less test runs under a shared lock). */
+    sharedHolders?: number | undefined;
 }
 /**
  * Inspects a lock without acquiring it. Read-only and fail-open: a missing

package/dist/src/core/file-lock.js

@@ -9,6 +9,7 @@ import { verbose, warn } from '../utils/logger.js';
 import { sleep } from '../utils/sleep.js';
 import { isLockOwnerAlive, LOCK_PID_FILE, readLockOwner, writeLockOwner, } from './file-lock-owner.js';
 import { readLockQueue, registerWaiter, } from './file-lock-queue.js';
+import { countLiveSharedHolders, registerSharedHold, releaseSharedHoldsForSignal, } from './file-lock-shared.js';
 export { LOCK_PID_FILE };
 export { formatLockQueuePosition } from './file-lock-queue.js';
 const DEFAULT_LOCK_TIMEOUT_MS = 30_000;
@@ -38,6 +39,8 @@ export function createSiblingLockPath(filePath, suffix = '.fireforge.lock') {
  */
 export async function readLockStatus(lockPath) {
     const queue = await readLockQueue(lockPath);
+    const shared = await countLiveSharedHolders(lockPath, { reap: false });
+    const sharedPart = shared > 0 ? { sharedHolders: shared } : {};
     let heldForMs;
     try {
         // Clamped: filesystem mtime resolution can round a just-created lock
@@ -46,13 +49,13 @@ export async function readLockStatus(lockPath) {
         heldForMs = Math.max(0, Date.now() - (await stat(lockPath)).mtimeMs);
     }
     catch {
-        return { held: false, queueDepth: queue.depth };
+        return { held: false, queueDepth: queue.depth, ...sharedPart };
     }
     const owner = await readLockOwner(lockPath);
     const holder = owner.present
         ? { pid: owner.pid, alive: isLockOwnerAlive(owner), metadata: owner.metadata }
         : undefined;
-    return { held: true, holder, heldForMs, queueDepth: queue.depth };
+    return { held: true, holder, heldForMs, queueDepth: queue.depth, ...sharedPart };
 }
 /**
  * Reads the contended lock's owner and queue in one go. One probe per cycle
@@ -334,6 +337,7 @@ export async function forceReleaseHeldLocksForSignal() {
             removed.push(lockPath);
         }
     }
+    removed.push(...(await releaseSharedHoldsForSignal()));
     return removed;
 }
 /** Runs an async operation while holding a directory lock, with stale-lock recovery. */
@@ -467,8 +471,36 @@ export async function withFileLock(lockPath, operation, options = {}) {
     // `writeLockOwner` removes the just-created directory before throwing.
     const ownerToken = randomUUID();
     await writeLockOwner(lockPath, ownerToken, options.ownerMetadata);
+    return runWhileHeld(lockPath, ownerToken, operation, options, {
+        deadline: Math.max(deadline, Date.now() + pollMs),
+        pollMs,
+    });
+}
+/**
+ * Runs `operation` once the turnstile is ours: as a shared holder (turnstile
+ * released at once), or exclusively once every shared holder has drained.
+ */
+async function runWhileHeld(lockPath, ownerToken, operation, options, drain) {
+    if (options.mode === 'shared') {
+        // The exclusive lock was only the turnstile: record the shared hold and
+        // let the next waiter in. See file-lock-shared.ts.
+        let hold;
+        try {
+            hold = await registerSharedHold(lockPath, options.ownerMetadata);
+        }
+        finally {
+            await releaseLock(lockPath, ownerToken);
+        }
+        try {
+            return await operation();
+        }
+        finally {
+            await hold.release();
+        }
+    }
     heldLocks.add(lockPath);
     try {
+        await waitForSharedHoldersToDrain(lockPath, drain.deadline, drain.pollMs);
         return await operation();
     }
     finally {
@@ -476,3 +508,27 @@ export async function withFileLock(lockPath, operation, options = {}) {
         await releaseLock(lockPath, ownerToken);
     }
 }
+/**
+ * Holds an exclusive acquisition until every live shared holder has gone.
+ * The turnstile is already ours, so no new shared holder can join meanwhile.
+ *
+ * @throws LockContentionError when shared holders outlast the budget
+ */
+async function waitForSharedHoldersToDrain(lockPath, deadline, pollMs) {
+    let announced = false;
+    for (;;) {
+        const live = await countLiveSharedHolders(lockPath);
+        if (live === 0)
+            return;
+        if (Date.now() >= deadline) {
+            throw new LockContentionError(`Timed out waiting for file lock ${lockPath}: ${live} shared holder(s) (build-less ` +
+                'test runs under a shared lock) still hold it. Wait for them to finish, or retry ' +
+                'with a larger --wait-lock.');
+        }
+        if (!announced) {
+            verbose(`Waiting for ${live} shared holder(s) of ${lockPath} to finish.`);
+            announced = true;
+        }
+        await sleep(Math.max(pollMs, 100));
+    }
+}

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

@@ -17,7 +17,8 @@ import { topologicalSortCustom } from './furnace-graph-utils.js';
 import { resolveFurnaceMarkerComment } from './furnace-marker.js';
 import { recordFurnaceRollbackFailure } from './furnace-operation.js';
 import { assertFurnaceEngineDirReady } from './furnace-precondition.js';
-import { addJarMnEntries, removeCustomElementRegistration, removeJarMnEntries, } from './furnace-registration.js';
+import { addJarMnEntries, removeCustomElementRegistration } from './furnace-registration.js';
+import { removeJarMnFileEntries } from './furnace-registration-jar-inplace.js';
 import { createRollbackJournal, restoreRollbackJournalOrThrow, snapshotFile, } from './furnace-rollback.js';
 import { blockingStepErrors, hasBlockingStepErrors } from './furnace-step-errors.js';
 import { runPostApplyConsistencyChecks } from './furnace-validate-registration.js';
@@ -132,8 +133,8 @@ async function applyOverrideBatch(ctx) {
 /**
  * After undeploying deleted files, the in-engine jar.mn and
  * customElements.js still carry entries for the removed files. Re-sync them
- * by removing all of `name`'s jar.mn entries and re-adding only those that
- * still exist in the workspace. If the .mjs itself was deleted, also drop
+ * by removing only the deleted files' jar.mn lines in place and adding any
+ * live file that has none. If the .mjs itself was deleted, also drop
  * the customElements.js registration. Snapshots are taken under the same
  * journal so the undo path is symmetric with apply.
  */
@@ -144,18 +145,17 @@ async function reconcileCustomRegistrationAfterUndeploy(args) {
     const deletedRegistrationFiles = deletedFiles.filter((f) => f.endsWith('.mjs') || f.endsWith('.css'));
     if (deletedRegistrationFiles.length === 0)
         return;
-    // jar.mn re-sync. addJarMnEntries is idempotent on duplicates but does not
-    // drop stale entries, so we need a remove-then-add cycle. The journal
-    // snapshot before each mutation gives us a clean rollback target.
+    // jar.mn re-sync: drop only the deleted files' lines, so the rest of the
+    // widget's block keeps its order and the owning patch carries no reorder
+    // hunks. addJarMnEntries is idempotent, so the add pass inserts only a
+    // live file that has no line yet. The journal snapshot before the
+    // mutation gives us a clean rollback target.
     if (rollbackJournal) {
         await snapshotFile(rollbackJournal, join(engineDir, JAR_MN));
     }
-    await removeJarMnEntries(engineDir, name);
+    await removeJarMnFileEntries(engineDir, name, deletedRegistrationFiles);
     const liveJarFiles = Object.keys(currentChecksums).filter((f) => f.endsWith('.mjs') || f.endsWith('.css'));
     if (liveJarFiles.length > 0) {
-        // applyCustomComponent has already added live entries, and the remove
-        // above dropped them too, so re-add now to leave jar.mn in the correct
-        // state.
         await addJarMnEntries(engineDir, name, liveJarFiles);
     }
     filesAffected.push(JAR_MN);

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

@@ -1,9 +1,17 @@
 import { type FurnaceOptInCheck, type FurnaceValidationException } from '../types/furnace.js';
 /**
- * Parses `validationExceptions[]`: `{ component, check, reason }` objects,
- * no other keys, every field a non-empty string, and no two entries for the
- * same component and check.
+ * Parses `validationExceptions[]`: `{ component, check, tag?, file?, reason }`
+ * objects, no other keys, every field a non-empty string, at most one of
+ * `tag` and `file` (a bare file name of the component), and no two entries
+ * for the same component, check and scope.
  */
 export declare function parseValidationExceptions(raw: unknown): FurnaceValidationException[];
+/**
+ * Parses `tokenSiblingSheets`: an object from a sheet glob to a non-empty
+ * list of partner paths or globs.
+ */
+export declare function parseTokenSiblingSheets(raw: unknown): Record<string, string[]>;
+/** Parses `minComponents`: a positive integer. */
+export declare function parseMinComponents(raw: unknown): number;
 /** Parses `optInChecks[]`: names from {@link FURNACE_OPT_IN_CHECKS}. */
 export declare function parseOptInChecks(raw: unknown): FurnaceOptInCheck[];

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

@@ -1,7 +1,8 @@
 // SPDX-License-Identifier: EUPL-1.2
 /**
- * Validators for the two `furnace validate` policy fields of furnace.json:
- * `validationExceptions[]` and `optInChecks[]`.
+ * Validators for the `furnace validate` and `token lint` policy fields of
+ * furnace.json: `validationExceptions[]`, `optInChecks[]`, `minComponents`
+ * and `tokenSiblingSheets`.
  *
  * Strict on purpose, like `buildAudit.unpackaged`: every exception is a
  * standing suppression of a finding, so a malformed one must fail at load
@@ -10,7 +11,7 @@
 import { FurnaceError } from '../errors/furnace.js';
 import { FURNACE_OPT_IN_CHECKS, } from '../types/furnace.js';
 import { isArray, isObject, isString } from '../utils/validation.js';
-const EXCEPTION_KEYS = new Set(['component', 'check', 'reason']);
+const EXCEPTION_KEYS = new Set(['component', 'check', 'tag', 'file', 'reason']);
 function requireNonEmptyString(entry, key, field) {
     const value = entry[key];
     if (!isString(value) || value.trim().length === 0) {
@@ -19,9 +20,10 @@ function requireNonEmptyString(entry, key, field) {
     return value;
 }
 /**
- * Parses `validationExceptions[]`: `{ component, check, reason }` objects,
- * no other keys, every field a non-empty string, and no two entries for the
- * same component and check.
+ * Parses `validationExceptions[]`: `{ component, check, tag?, file?, reason }`
+ * objects, no other keys, every field a non-empty string, at most one of
+ * `tag` and `file` (a bare file name of the component), and no two entries
+ * for the same component, check and scope.
  */
 export function parseValidationExceptions(raw) {
     if (!isArray(raw)) {
@@ -43,9 +45,31 @@ export function parseValidationExceptions(raw) {
             check: requireNonEmptyString(entry, 'check', field),
             reason: requireNonEmptyString(entry, 'reason', field),
         };
-        const identity = `${exception.component}\u0000${exception.check}`;
+        if (entry['tag'] !== undefined)
+            exception.tag = requireNonEmptyString(entry, 'tag', field);
+        if (entry['file'] !== undefined) {
+            if (exception.tag !== undefined) {
+                throw new FurnaceError(`Furnace config: "${field}" may name a "tag" or a "file", not both`);
+            }
+            const file = requireNonEmptyString(entry, 'file', field);
+            if (/[\\/]/.test(file) || file === '.' || file === '..') {
+                throw new FurnaceError(`Furnace config: "${field}.file" must be a file name in the component's directory, not a path`);
+            }
+            exception.file = file;
+        }
+        const scope = exception.tag !== undefined
+            ? `tag:${exception.tag}`
+            : exception.file !== undefined
+                ? `file:${exception.file}`
+                : '';
+        const identity = `${exception.component}\u0000${exception.check}\u0000${scope}`;
         if (seen.has(identity)) {
-            throw new FurnaceError(`Furnace config: "${field}" repeats the exception for ${exception.component} [${exception.check}]`);
+            const on = exception.tag !== undefined
+                ? ` on <${exception.tag}>`
+                : exception.file !== undefined
+                    ? ` in ${exception.file}`
+                    : '';
+            throw new FurnaceError(`Furnace config: "${field}" repeats the exception for ${exception.component} [${exception.check}]${on}`);
         }
         seen.add(identity);
         return exception;
@@ -54,6 +78,33 @@ export function parseValidationExceptions(raw) {
 function isOptInCheck(value) {
     return FURNACE_OPT_IN_CHECKS.includes(value);
 }
+/**
+ * Parses `tokenSiblingSheets`: an object from a sheet glob to a non-empty
+ * list of partner paths or globs.
+ */
+export function parseTokenSiblingSheets(raw) {
+    if (!isObject(raw)) {
+        throw new FurnaceError('Furnace config: "tokenSiblingSheets" must be an object');
+    }
+    const out = {};
+    for (const [pattern, partners] of Object.entries(raw)) {
+        const valid = isArray(partners) &&
+            partners.length > 0 &&
+            partners.every((partner) => isString(partner) && partner.trim() !== '');
+        if (pattern.includes('..') || !valid || partners.some((p) => String(p).includes('..'))) {
+            throw new FurnaceError(`Furnace config: "tokenSiblingSheets.${pattern}" must be a non-empty list of engine-relative paths or globs (no "..")`);
+        }
+        out[pattern] = partners;
+    }
+    return out;
+}
+/** Parses `minComponents`: a positive integer. */
+export function parseMinComponents(raw) {
+    if (typeof raw !== 'number' || !Number.isInteger(raw) || raw < 1) {
+        throw new FurnaceError('Furnace config: "minComponents" must be a positive integer');
+    }
+    return raw;
+}
 /** Parses `optInChecks[]`: names from {@link FURNACE_OPT_IN_CHECKS}. */
 export function parseOptInChecks(raw) {
     if (!isArray(raw)) {

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

@@ -8,7 +8,7 @@
 import { FurnaceError } from '../errors/furnace.js';
 import { isJsonObject, isString } from '../utils/validation.js';
 import { parseStringArray } from './furnace-config-array-utils.js';
-import { parseOptInChecks, parseValidationExceptions, } from './furnace-config-validate-exceptions.js';
+import { parseMinComponents, parseOptInChecks, parseTokenSiblingSheets, parseValidationExceptions, } from './furnace-config-validate-exceptions.js';
 /**
  * Validates an override component config object.
  * @param data - Raw data to validate
@@ -94,6 +94,9 @@ export function applyOptionalFurnaceFields(migrated, config) {
     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');
     }
@@ -137,4 +140,7 @@ export function applyOptionalFurnaceFields(migrated, config) {
     if (migrated['optInChecks'] !== undefined) {
         config.optInChecks = parseOptInChecks(migrated['optInChecks']);
     }
+    if (migrated['minComponents'] !== undefined) {
+        config.minComponents = parseMinComponents(migrated['minComponents']);
+    }
 }

package/dist/src/core/furnace-registration-jar-inplace.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Removes the lines registering `files` for `tagName`, leaving every other
+ * line of the block where it is. Returns how many lines were removed.
+ */
+export declare function removeJarMnFileEntries(engineDir: string, tagName: string, files: readonly string[]): Promise<number>;
+/**
+ * Rewrites `oldTag`'s lines in place as `newTag`'s. A line whose renamed
+ * file is in `liveFiles` keeps its position and layout; one whose file is
+ * gone is dropped. Returns the renamed files that already had a line; the
+ * caller's `addJarMnEntries` pass then inserts only the rest.
+ */
+export declare function renameJarMnEntriesInPlace(engineDir: string, oldTag: string, newTag: string, liveFiles: readonly string[], renameFile: (file: string) => string): Promise<string[]>;

package/dist/src/core/furnace-registration-jar-inplace.js

@@ -0,0 +1,80 @@
+// SPDX-License-Identifier: EUPL-1.2
+/**
+ * In-place edits to a widget's `toolkit/content/jar.mn` block.
+ *
+ * Undeploying one file and renaming a component used to drop every line of
+ * the widget and re-add the live ones, which re-sorted the whole block and
+ * left the owning patch carrying reorder hunks. These helpers touch only
+ * the lines that change: a deleted file's line goes, a renamed component's
+ * lines are rewritten where they stand, and anything still missing is left
+ * for `addJarMnEntries` to insert.
+ */
+import { join } from 'node:path';
+import { pathExists, readText, writeText } from '../utils/fs.js';
+import { escapeRegex } from '../utils/regex.js';
+import { JAR_MN } from './furnace-constants.js';
+/**
+ * The file a widget jar.mn line registers: the `(widgets/<tag>/<file>)`
+ * source mapping, or the legacy `content/global/elements/<tag>.<ext>`
+ * target written before the mapping existed. Undefined when the line is
+ * not one of this tag's.
+ */
+function registeredFile(line, tagName) {
+    const tag = escapeRegex(tagName);
+    const source = new RegExp(`\\(widgets/${tag}/([^)]+)\\)`).exec(line);
+    if (source)
+        return source[1];
+    const legacy = new RegExp(`content/global/elements/(${tag}\\.[^\\s]+)`).exec(line);
+    return legacy?.[1];
+}
+/**
+ * Removes the lines registering `files` for `tagName`, leaving every other
+ * line of the block where it is. Returns how many lines were removed.
+ */
+export async function removeJarMnFileEntries(engineDir, tagName, files) {
+    const filePath = join(engineDir, JAR_MN);
+    if (files.length === 0 || !(await pathExists(filePath)))
+        return 0;
+    const doomed = new Set(files);
+    const lines = (await readText(filePath)).split('\n');
+    const kept = lines.filter((line) => {
+        const file = registeredFile(line, tagName);
+        return file === undefined || !doomed.has(file);
+    });
+    const removed = lines.length - kept.length;
+    if (removed > 0)
+        await writeText(filePath, kept.join('\n'));
+    return removed;
+}
+/**
+ * Rewrites `oldTag`'s lines in place as `newTag`'s. A line whose renamed
+ * file is in `liveFiles` keeps its position and layout; one whose file is
+ * gone is dropped. Returns the renamed files that already had a line; the
+ * caller's `addJarMnEntries` pass then inserts only the rest.
+ */
+export async function renameJarMnEntriesInPlace(engineDir, oldTag, newTag, liveFiles, renameFile) {
+    const filePath = join(engineDir, JAR_MN);
+    if (!(await pathExists(filePath)))
+        return [];
+    const live = new Set(liveFiles);
+    const covered = [];
+    const out = [];
+    for (const line of (await readText(filePath)).split('\n')) {
+        const file = registeredFile(line, oldTag);
+        if (file === undefined) {
+            out.push(line);
+            continue;
+        }
+        const renamed = renameFile(file);
+        if (!live.has(renamed) || covered.includes(renamed))
+            continue;
+        // Textual substitution keeps the indent, column spacing and any
+        // trailing comment the line carried.
+        out.push(line
+            .replace(`content/global/elements/${file}`, `content/global/elements/${renamed}`)
+            .replace(`(widgets/${oldTag}/${file})`, `(widgets/${newTag}/${renamed})`));
+        covered.push(renamed);
+    }
+    await writeText(filePath, out.join('\n'));
+    return covered;
+}

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

@@ -1,7 +1,9 @@
 import type { CustomComponentConfig, FurnaceOptInCheck, ValidationIssue } from '../types/furnace.js';
 /**
- * Validates accessibility patterns in a component's .mjs file.
- * Checks for ARIA roles, keyboard handlers, l10n, and focus delegation.
+ * Validates accessibility patterns in a component's composed source: its
+ * host module and every companion module (see
+ * {@link readComposedComponentSource}). Checks for ARIA roles, keyboard
+ * handlers, l10n, and focus delegation.
  *
  * @param componentDir - Directory holding the component's sources
  * @param tagName - Custom element tag name, used to locate `<tagName>.mjs`
@@ -32,6 +34,6 @@ export declare function validateAccessibility(componentDir: string, tagName: str
  *      `title=`, or `tooltiptext=` attribute when constructing DOM in JS.
  *
  * A file-wide `// furnace-ignore: hardcoded-text` comment suppresses all
- * findings (matches the pre-existing escape hatch).
+ * findings in that file (matches the pre-existing escape hatch).
  */
 export declare function containsHardcodedTemplateText(content: string): boolean;