@hominis/fireforge 0.46.0 → 0.46.1

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

@@ -10,7 +10,7 @@ import { parseStringArray } from './furnace-config-array-utils.js';
 /**
  * Validates a `tokenHostDocuments` raw value. Each entry must be a non-empty
  * relative path contained in the engine tree. Throws `FurnaceError` on
- * violation; does nothing for `undefined` (field is optional).
+ * violation. Does nothing for `undefined` (field is optional).
  */
 export function validateTokenHostDocuments(raw) {
     if (raw === undefined)
@@ -27,8 +27,8 @@ export function validateTokenHostDocuments(raw) {
 }
 /**
  * Validates a `runtimeVariables` raw value. Each entry must start with `--`
- * (it is a CSS custom property name). Throws `FurnaceError` on violation;
- * does nothing for `undefined` (field is optional).
+ * (it is a CSS custom property name). Throws `FurnaceError` on violation.
+ * Does nothing for `undefined` (field is optional).
  */
 export function validateRuntimeVariables(raw) {
     if (raw === undefined)

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

@@ -110,8 +110,8 @@ export function applyOptionalFurnaceFields(migrated, config) {
         }
         config.ftlBasePath = migrated['ftlBasePath'];
     }
-    // Validate optional typecheckJsconfig — consumer-owned jsconfig whose
-    // chrome-elements `paths` entries Furnace maintains on deploy.
+    // Validate optional typecheckJsconfig. This is a consumer-owned jsconfig
+    // whose chrome-elements `paths` entries Furnace maintains on deploy.
     if (migrated['typecheckJsconfig'] !== undefined) {
         const jsconfigPath = migrated['typecheckJsconfig'];
         if (!isString(jsconfigPath) || jsconfigPath.includes('..')) {

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

@@ -70,8 +70,8 @@ export declare function writeFurnaceConfig(root: string, config: FurnaceConfig):
  * matching override stamp `doctor` fails Furnace component validation on
  * every override.
  *
- * The stamp is deliberately unconditional — `fireforge furnace validate` is
- * the right tool for "does this override still apply", and rebase has
+ * 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
@@ -92,11 +92,11 @@ export declare function stampFurnaceOverrideBaseVersions(root: string, version:
  * declarations.
  *
  * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers on
- * the no-arg call shape still get a valid config without a prefix; the CLI
+ * 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
+ * @param options - Optional init context. Pass `{ binaryName }` to derive
  *   the token prefix.
  * @returns A valid FurnaceConfig
  */

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

@@ -61,7 +61,7 @@ function hasEntries(record) {
 const CURRENT_CONFIG_VERSION = 1;
 /**
  * Rejects a config whose `version` field is not the single schema version that
- * exists. A non-integer or sub-1 value is a malformed document; a value above
+ * exists. A non-integer or sub-1 value is a malformed document. A value above
  * the current version was written by a newer FireForge and cannot be read here.
  */
 function validateConfigVersion(version) {
@@ -100,10 +100,10 @@ export function validateFurnaceConfig(data) {
     if (raw['tokenAllowlist'] !== undefined) {
         parseStringArray(raw['tokenAllowlist'], 'tokenAllowlist');
     }
-    // Validate optional runtimeVariables — CSS runtime state channels
+    // Validate optional runtimeVariables: CSS runtime state channels
     // (e.g. `--cam-x`) that are exempt from `token-prefix-violation`.
     validateRuntimeVariables(raw['runtimeVariables']);
-    // Validate optional tokenHostDocuments — list of chrome XHTMLs that the
+    // Validate optional tokenHostDocuments: list of chrome XHTMLs that the
     // `missing-token-link` validator scans for the tokens CSS link.
     validateTokenHostDocuments(raw['tokenHostDocuments']);
     const stock = parseStockList(raw['stock']);
@@ -115,8 +115,8 @@ export function validateFurnaceConfig(data) {
     validateComposesReferences(stock, overrides, custom);
     // Warn when two custom components share a targetPath. Nothing technically
     // prevents co-location, but per-component removal and orphan detection
-    // both reason about "files this component deployed into its directory" —
-    // shared directories make those judgements ambiguous, and can lead to
+    // both reason about "files this component deployed into its directory".
+    // Shared directories make those judgements ambiguous, and can lead to
     // `furnace remove` of one component deleting the other's deployed files.
     const targetPathOwners = new Map();
     for (const [name, custom_] of Object.entries(custom)) {
@@ -154,8 +154,8 @@ function validateFurnaceState(data) {
     return result.state;
 }
 // Single source of truth: the list the union is derived from. The copy
-// this replaced was annotated, not linked — it caught a member REMOVED
-// from the union but never one ADDED to it, and listed them in a
+// this replaced was annotated rather than linked, so it caught a member
+// removed from the union but never one added to it, and listed them in a
 // different order.
 const PENDING_REPAIR_OPERATIONS = FURNACE_PENDING_REPAIR_OPERATIONS;
 function parsePendingRepair(data) {
@@ -338,14 +338,14 @@ export async function writeFurnaceConfig(root, config) {
     if (await pathExists(paths.furnaceConfig)) {
         try {
             const raw = await readJson(paths.furnaceConfig);
-            // JSON.parse output is JSON data by construction, so the object
-            // check is the only invariant left for the JsonObject contract.
+            // JSON.parse only produces JSON data, so the object check is the
+            // only invariant left for the JsonObject contract.
             if (isObject(raw))
                 existing = raw;
         }
         catch {
             // A missing or corrupt furnace.json means there is no prior document to
-            // preserve key order from; the writer falls back to canonical ordering.
+            // preserve key order from. The writer falls back to canonical ordering.
             existing = undefined;
         }
     }
@@ -359,8 +359,8 @@ export async function writeFurnaceConfig(root, config) {
  * matching override stamp `doctor` fails Furnace component validation on
  * every override.
  *
- * The stamp is deliberately unconditional — `fireforge furnace validate` is
- * the right tool for "does this override still apply", and rebase has
+ * 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
@@ -396,11 +396,11 @@ export async function stampFurnaceOverrideBaseVersions(root, version) {
  * declarations.
  *
  * `validateFurnaceConfig` treats `tokenPrefix` as optional, so callers on
- * the no-arg call shape still get a valid config without a prefix; the CLI
+ * 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
+ * @param options - Optional init context. Pass `{ binaryName }` to derive
  *   the token prefix.
  * @returns A valid FurnaceConfig
  */
@@ -468,8 +468,8 @@ export async function updateFurnaceState(root, updates) {
  * Engine-relative path of the directory `furnace preview` writes its
  * generated Storybook story files into. Treated as Furnace-managed so
  * `status` does not flag them as unmanaged and `lint` does not fail on their
- * (intentionally bare) license headers — they are tool output, not files an
- * operator commits or hand-edits.
+ * (intentionally bare) license headers. They are tool output rather than
+ * files an operator commits or hand-edits.
  */
 const FURNACE_STORYBOOK_STORIES_PREFIX = 'browser/components/storybook/stories/furnace/';
 /**
@@ -504,8 +504,8 @@ export async function collectFurnaceManagedPrefixes(root) {
     }
     // Always include the preview-generated stories prefix when furnace is
     // initialised. The directory may not exist yet (no preview ever ran),
-    // but classifying it as furnace-managed is safe even when empty —
-    // status simply has nothing to bucket.
+    // but classifying it as furnace-managed is safe even when empty. Status
+    // simply has nothing to bucket.
     prefixes.add(FURNACE_STORYBOOK_STORIES_PREFIX);
     return prefixes;
 }

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

@@ -5,7 +5,7 @@ export declare const JAR_MN = "toolkit/content/jar.mn";
 /**
  * Upstream home of the MozLitElement widget sources.
  *
- * The trailing slash is NOT included: `build-audit-transforms.ts` needs
+ * The trailing slash is not included: `build-audit-transforms.ts` needs
  * `${WIDGETS_DIR}/` and its ordered prefix table depends on that slash, so
  * appending it at the one site that wants it keeps the others correct.
  */
@@ -27,15 +27,15 @@ export declare function xpcshellTestParentDir(binaryName: string): string;
 /**
  * Resolves the engine-relative directory a browser-chrome scaffold is
  * written to: the `--test-dir` override when given, else
- * `browser/base/content/test/<binaryName>`. The scaffolder AND the
+ * `browser/base/content/test/<binaryName>`. The scaffolder and the
  * dry-run / success formatters resolve through this one function, so the
  * printed plan cannot disagree with the files that land on disk.
  */
 export declare function resolveBrowserChromeTestDir(binaryName: string, override?: string): string;
 /**
  * Resolves the engine-relative directory an xpcshell scaffold is written
- * to. A `--test-dir` override names the FINAL directory (no per-component
- * segment is appended); the default is
+ * to. A `--test-dir` override names the final directory (no per-component
+ * segment is appended). The default is
  * `browser/base/content/test/<binaryName>-xpcshell/<componentName>`.
  */
 export declare function resolveXpcshellTestDir(binaryName: string, componentName: string, override?: string): string;
@@ -62,8 +62,8 @@ export declare function resolveFtlChromeSubPath(ftlBasePath?: string): string |
  * given `ftlBasePath`. For the default toolkit tree this yields
  * `toolkit/locales/jar.mn`.
  *
- * Returns `undefined` when the path does not contain a `locales/` segment —
- * callers must treat that as "cannot locate" and degrade gracefully.
+ * Returns `undefined` when the path does not contain a `locales/` segment.
+ * Callers must treat that as "cannot locate" and degrade gracefully.
  */
 export declare function resolveFtlLocaleJarMnPath(ftlBasePath?: string): string | undefined;
 /**

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

@@ -7,7 +7,7 @@ export const JAR_MN = 'toolkit/content/jar.mn';
 /**
  * Upstream home of the MozLitElement widget sources.
  *
- * The trailing slash is NOT included: `build-audit-transforms.ts` needs
+ * The trailing slash is not included: `build-audit-transforms.ts` needs
  * `${WIDGETS_DIR}/` and its ordered prefix table depends on that slash, so
  * appending it at the one site that wants it keeps the others correct.
  */
@@ -39,7 +39,7 @@ export function xpcshellTestParentDir(binaryName) {
 /**
  * Resolves the engine-relative directory a browser-chrome scaffold is
  * written to: the `--test-dir` override when given, else
- * `browser/base/content/test/<binaryName>`. The scaffolder AND the
+ * `browser/base/content/test/<binaryName>`. The scaffolder and the
  * dry-run / success formatters resolve through this one function, so the
  * printed plan cannot disagree with the files that land on disk.
  */
@@ -48,8 +48,8 @@ export function resolveBrowserChromeTestDir(binaryName, override) {
 }
 /**
  * Resolves the engine-relative directory an xpcshell scaffold is written
- * to. A `--test-dir` override names the FINAL directory (no per-component
- * segment is appended); the default is
+ * to. A `--test-dir` override names the final directory (no per-component
+ * segment is appended). The default is
  * `browser/base/content/test/<binaryName>-xpcshell/<componentName>`.
  */
 export function resolveXpcshellTestDir(binaryName, componentName, override) {
@@ -90,8 +90,8 @@ export function resolveFtlChromeSubPath(ftlBasePath) {
  * given `ftlBasePath`. For the default toolkit tree this yields
  * `toolkit/locales/jar.mn`.
  *
- * Returns `undefined` when the path does not contain a `locales/` segment —
- * callers must treat that as "cannot locate" and degrade gracefully.
+ * Returns `undefined` when the path does not contain a `locales/` segment.
+ * Callers must treat that as "cannot locate" and degrade gracefully.
  */
 export function resolveFtlLocaleJarMnPath(ftlBasePath) {
     const path = normalizePathSlashes(ftlBasePath ?? FTL_DIR);

package/dist/src/core/furnace-css-fragments.d.ts

@@ -9,8 +9,8 @@
  *     @fireforge-include shared-anims.css
  *
  * naming a fragment file in `components/shared/`. `furnace deploy` expands
- * the fragment into the *deployed* copy only — the workspace source stays
- * DRY — fencing the expansion between the directive line and a matching
+ * the fragment into the *deployed* copy only (the workspace source stays
+ * DRY), fencing the expansion between the directive line and a matching
  * `@fireforge-end-include` marker so re-deploys can refresh it idempotently.
  *
  * Drift contract: the apply fast-path and `furnace validate` compare the
@@ -24,7 +24,7 @@ export { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
 export declare function listFragmentIncludes(css: string): string[];
 /**
  * Collapses fenced fragment expansions back to their bare directives.
- * Inverse of {@link expandCssFragments}; used to compare a deployed file
+ * Inverse of {@link expandCssFragments}. Used to compare a deployed file
  * against its workspace source and to re-expand idempotently.
  */
 export declare function stripExpandedFragments(css: string): string;
@@ -52,7 +52,7 @@ export declare function expandCssFragments(css: string, sharedDir: string): Prom
 export declare function extractExpandedFragmentBodies(css: string): Map<string, string>;
 /**
  * Deploys one component file: CSS sources carrying include directives are
- * written as their fragment-expanded form; everything else is a plain
+ * written as their fragment-expanded form. Everything else is a plain
  * copy. Extracted here so `applyCustomComponent` stays inside the
  * per-file line budget.
  *
@@ -73,7 +73,7 @@ export declare function describeFragmentExpansion(src: string): Promise<string>;
  * @param componentDir - Workspace directory of the component
  * @param tagName - Component tag name for issue attribution
  * @param sharedDir - Shared fragments directory
- * @param engineTargetDir - Deployed directory in the engine (optional —
- *   pre-deploy validation skips the staleness check)
+ * @param engineTargetDir - Deployed directory in the engine. Optional, and
+ *   pre-deploy validation skips the staleness check.
  */
 export declare function validateCssFragments(componentDir: string, tagName: string, sharedDir: string, engineTargetDir?: string): Promise<ValidationIssue[]>;

package/dist/src/core/furnace-css-fragments.js

@@ -10,8 +10,8 @@
  *     @fireforge-include shared-anims.css
  *
  * naming a fragment file in `components/shared/`. `furnace deploy` expands
- * the fragment into the *deployed* copy only — the workspace source stays
- * DRY — fencing the expansion between the directive line and a matching
+ * the fragment into the *deployed* copy only (the workspace source stays
+ * DRY), fencing the expansion between the directive line and a matching
  * `@fireforge-end-include` marker so re-deploys can refresh it idempotently.
  *
  * Drift contract: the apply fast-path and `furnace validate` compare the
@@ -24,7 +24,7 @@ import { join } from 'node:path';
 import { FurnaceError } from '../errors/furnace.js';
 import { copyFile, pathExists, readText, writeText } from '../utils/fs.js';
 export { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
-// Local copy of the directory name for message text — importing the
+// Local copy of the directory name for message text. Importing the
 // binding for value use keeps a single source of truth.
 import { SHARED_FRAGMENTS_DIR } from './furnace-config.js';
 const INCLUDE_PATTERN = /^\s*\/\*\s*@fireforge-include\s+([\w./-]+)\s*\*\/\s*$/;
@@ -41,7 +41,7 @@ export function listFragmentIncludes(css) {
 }
 /**
  * Collapses fenced fragment expansions back to their bare directives.
- * Inverse of {@link expandCssFragments}; used to compare a deployed file
+ * Inverse of {@link expandCssFragments}. Used to compare a deployed file
  * against its workspace source and to re-expand idempotently.
  */
 export function stripExpandedFragments(css) {
@@ -54,8 +54,8 @@ export function stripExpandedFragments(css) {
         if (!inc?.[1])
             continue;
         // A bare directive (workspace file) has no fence to strip. Only skip
-        // the expansion body when a matching end marker actually follows —
-        // otherwise an unterminated fence would silently eat the rest of the
+        // the expansion body when a matching end marker actually follows.
+        // Otherwise an unterminated fence would silently eat the rest of the
         // file.
         let endIndex = -1;
         for (let j = i + 1; j < lines.length; j++) {
@@ -141,7 +141,7 @@ export function extractExpandedFragmentBodies(css) {
 }
 /**
  * Deploys one component file: CSS sources carrying include directives are
- * written as their fragment-expanded form; everything else is a plain
+ * written as their fragment-expanded form. Everything else is a plain
  * copy. Extracted here so `applyCustomComponent` stays inside the
  * per-file line budget.
  *
@@ -180,8 +180,8 @@ export async function describeFragmentExpansion(src) {
  * @param componentDir - Workspace directory of the component
  * @param tagName - Component tag name for issue attribution
  * @param sharedDir - Shared fragments directory
- * @param engineTargetDir - Deployed directory in the engine (optional —
- *   pre-deploy validation skips the staleness check)
+ * @param engineTargetDir - Deployed directory in the engine. Optional, and
+ *   pre-deploy validation skips the staleness check.
  */
 export async function validateCssFragments(componentDir, tagName, sharedDir, engineTargetDir) {
     const issues = [];
@@ -194,8 +194,8 @@ export async function validateCssFragments(componentDir, tagName, sharedDir, eng
         entries = await readdir(componentDir);
     }
     catch {
-        // An unreadable component directory contributes no fragment issues; return
-        // what has been collected so far rather than failing validation.
+        // An unreadable component directory contributes no fragment issues.
+        // Return what has been collected so far rather than failing validation.
         return issues;
     }
     for (const fileName of entries) {

package/dist/src/core/furnace-dir-entry.d.ts

@@ -11,7 +11,7 @@ export interface DirectoryEntry {
     name: string;
 }
 /**
- * True for a plain-file directory entry — symlinks and directories are
+ * True for a plain-file directory entry. Symlinks and directories are
  * never copy candidates.
  *
  * @param entry - Directory entry to classify

package/dist/src/core/furnace-dir-entry.js

@@ -6,7 +6,7 @@
  * and its dry-run mirror can share one definition without importing each other.
  */
 /**
- * True for a plain-file directory entry — symlinks and directories are
+ * True for a plain-file directory entry. Symlinks and directories are
  * never copy candidates.
  *
  * @param entry - Directory entry to classify

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

@@ -11,10 +11,10 @@
  * automatically on every deploy.
  *
  * Ownership contract: only entries whose key starts with
- * `chrome://global/content/elements/` AND whose mapped path resolves into
+ * `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
+ * 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.
  */
@@ -32,13 +32,13 @@ export interface JsconfigSyncResult {
 }
 /**
  * Reconciles the managed `compilerOptions.paths` entries of the configured
- * jsconfig against the current Furnace workspace. Idempotent; writes only
- * when something actually changes; dry-run returns the diff without
+ * 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`.
+ * are preserved. Furnace edits only `compilerOptions.paths`.
  *
  * @param root - Project root directory
  * @param config - Loaded Furnace configuration (must carry `typecheckJsconfig`)
@@ -49,7 +49,7 @@ export declare function syncFurnaceJsconfigPaths(root: string, config: FurnaceCo
 }): Promise<JsconfigSyncResult>;
 /**
  * Computes jsconfig `paths` drift for `furnace validate`: managed entries
- * that are missing or stale relative to the current workspace. Read-only —
+ * 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>;

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

@@ -12,10 +12,10 @@
  * automatically on every deploy.
  *
  * Ownership contract: only entries whose key starts with
- * `chrome://global/content/elements/` AND whose mapped path resolves into
+ * `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
+ * 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.
  */
@@ -32,18 +32,18 @@ import { getFurnacePaths } from './furnace-config.js';
 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
+ * 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
+ * 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
+ * `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.
  *
- * Workspace sources (not deployed engine copies) are the mapping target —
- * they are the files developers edit, and they exist even when the engine
- * has not been deployed yet.
+ * 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);
@@ -58,7 +58,7 @@ async function computeDesiredChromePathEntries(config, customDir, jsconfigAbsPat
                 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
+            // 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.
@@ -86,18 +86,19 @@ function isManagedEntry(key, value, jsconfigDir, customDir) {
         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 — no pruning, no updates.
+    // 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; writes only
- * when something actually changes; dry-run returns the diff without
+ * 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`.
+ * are preserved. Furnace edits only `compilerOptions.paths`.
  *
  * @param root - Project root directory
  * @param config - Loaded Furnace configuration (must carry `typecheckJsconfig`)
@@ -143,8 +144,8 @@ export async function syncFurnaceJsconfigPaths(root, config, options) {
         ...(jsconfigObject.compilerOptions?.paths ?? {}),
     };
     const nextPaths = {};
-    // Preserve every unmanaged entry verbatim; prune managed entries that are
-    // no longer desired; update managed entries whose target moved.
+    // 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;
@@ -157,8 +158,9 @@ export async function syncFurnaceJsconfigPaths(root, config, options) {
         }
         // 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 — no churn either
-        // way; only a genuinely different target updates (to the `./` form).
+        // 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;
@@ -184,7 +186,7 @@ export async function syncFurnaceJsconfigPaths(root, config, options) {
 }
 /**
  * Computes jsconfig `paths` drift for `furnace validate`: managed entries
- * that are missing or stale relative to the current workspace. Read-only —
+ * 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) {