@hominis/fireforge 0.45.0 → 0.46.1

package/dist/src/core/furnace-state-persist.d.ts

@@ -4,25 +4,25 @@
  * There are exactly two sanctioned ways checksums land in
  * furnace-state.json:
  *
- *  1. The BATCH path inside `applyAllComponents` (persistState: true), which
- *     replaces `appliedChecksums` wholesale — correct only when the run
- *     covered every component.
- *  2. The per-component MERGE in this module, which rewrites only the
+ *  1. The batch path inside `applyAllComponents` (persistState: true), which
+ *     replaces `appliedChecksums` wholesale. That is correct only when the
+ *     run covered every component.
+ *  2. The per-component merge in this module, which rewrites only the
  *     `<type>/<name>/…` keys of the component that was applied.
  *
- * Every targeted (named) apply/deploy MUST use path 2 with
+ * Every targeted (named) apply/deploy must use path 2 with
  * `persistState: false`. Routing a named run through the batch path wipes
  * every other component's checksum state: the batch loops filter to the
  * named component, so the wholesale replace persists a state file containing
  * only that component. Downstream, `diffDeletedFiles` and
  * `findOrphanedEngineFiles` both key on `appliedChecksums`, so the wiped
- * components' stale engine files become undetectable by apply AND by
+ * components' stale engine files become undetectable by apply and by
  * `furnace validate`.
  */
 import { type ApplyAllComponentsResult } from './furnace-apply.js';
-import { type getFurnacePaths } from './furnace-config.js';
+import { type FurnacePaths } from './furnace-config.js';
 /**
- * Counts applied entries that carry at least one BLOCKING step error
+ * Counts applied entries that carry at least one blocking step error
  * (advisory step errors are warnings and never fail a run).
  */
 export declare function getStepFailureCount(result: ApplyAllComponentsResult): number;
@@ -33,7 +33,7 @@ export declare function getStepFailureCount(result: ApplyAllComponentsResult): n
  * Named runs are atomic: if any apply step fails, the rollback journal
  * restores the engine to its pre-run state and this helper returns `false`
  * so state is not touched. The conditions must stay in lock-step with the
- * rollback trigger in `applyAllComponents` — both read step errors, so a
+ * rollback trigger in `applyAllComponents`: both read step errors, so a
  * future refactor cannot drift them apart and accidentally persist partial
  * state.
  */
@@ -43,7 +43,7 @@ export declare function shouldPersistSingleComponentState(result: ApplyAllCompon
  *
  * Guards against future refactors that might reorder or misroute the
  * applied[] array: a named run persists state under a single component
- * name, so the first applied entry MUST be that component. Persisting a
+ * name, so the first applied entry must be that component. Persisting a
  * different component's checksums would cause the next status/apply run to
  * mis-report health for both components involved.
  *
@@ -55,7 +55,7 @@ export declare function getPersistableAppliedEntry(commandLabel: string, name: s
 };
 /**
  * Persists checksum state for a successfully applied named component by
- * MERGING its `<type>/<name>/…` keys into the existing state — never
+ * merging its `<type>/<name>/…` keys into the existing state rather than
  * replacing the whole map.
  *
  * @param projectRoot - Root directory of the project
@@ -65,4 +65,4 @@ export declare function getPersistableAppliedEntry(commandLabel: string, name: s
 export declare function persistSingleComponentState(projectRoot: string, appliedEntry: {
     name: string;
     type: 'override' | 'custom';
-}, furnacePaths: ReturnType<typeof getFurnacePaths>): Promise<void>;
+}, furnacePaths: FurnacePaths): Promise<void>;

package/dist/src/core/furnace-state-persist.js

@@ -5,19 +5,19 @@
  * There are exactly two sanctioned ways checksums land in
  * furnace-state.json:
  *
- *  1. The BATCH path inside `applyAllComponents` (persistState: true), which
- *     replaces `appliedChecksums` wholesale — correct only when the run
- *     covered every component.
- *  2. The per-component MERGE in this module, which rewrites only the
+ *  1. The batch path inside `applyAllComponents` (persistState: true), which
+ *     replaces `appliedChecksums` wholesale. That is correct only when the
+ *     run covered every component.
+ *  2. The per-component merge in this module, which rewrites only the
  *     `<type>/<name>/…` keys of the component that was applied.
  *
- * Every targeted (named) apply/deploy MUST use path 2 with
+ * Every targeted (named) apply/deploy must use path 2 with
  * `persistState: false`. Routing a named run through the batch path wipes
  * every other component's checksum state: the batch loops filter to the
  * named component, so the wholesale replace persists a state file containing
  * only that component. Downstream, `diffDeletedFiles` and
  * `findOrphanedEngineFiles` both key on `appliedChecksums`, so the wiped
- * components' stale engine files become undetectable by apply AND by
+ * components' stale engine files become undetectable by apply and by
  * `furnace validate`.
  */
 import { join } from 'node:path';
@@ -26,7 +26,7 @@ import { computeComponentChecksums, prefixChecksums, } from './furnace-apply.js'
 import { updateFurnaceState } from './furnace-config.js';
 import { countEntriesWithBlockingStepErrors } from './furnace-step-errors.js';
 /**
- * Counts applied entries that carry at least one BLOCKING step error
+ * Counts applied entries that carry at least one blocking step error
  * (advisory step errors are warnings and never fail a run).
  */
 export function getStepFailureCount(result) {
@@ -39,7 +39,7 @@ export function getStepFailureCount(result) {
  * Named runs are atomic: if any apply step fails, the rollback journal
  * restores the engine to its pre-run state and this helper returns `false`
  * so state is not touched. The conditions must stay in lock-step with the
- * rollback trigger in `applyAllComponents` — both read step errors, so a
+ * rollback trigger in `applyAllComponents`: both read step errors, so a
  * future refactor cannot drift them apart and accidentally persist partial
  * state.
  */
@@ -57,7 +57,7 @@ export function shouldPersistSingleComponentState(result, isDryRun) {
  *
  * Guards against future refactors that might reorder or misroute the
  * applied[] array: a named run persists state under a single component
- * name, so the first applied entry MUST be that component. Persisting a
+ * name, so the first applied entry must be that component. Persisting a
  * different component's checksums would cause the next status/apply run to
  * mis-report health for both components involved.
  *
@@ -87,7 +87,7 @@ export function getPersistableAppliedEntry(commandLabel, name, appliedEntry) {
 }
 /**
  * Persists checksum state for a successfully applied named component by
- * MERGING its `<type>/<name>/…` keys into the existing state — never
+ * merging its `<type>/<name>/…` keys into the existing state rather than
  * replacing the whole map.
  *
  * @param projectRoot - Root directory of the project

package/dist/src/core/furnace-step-errors.d.ts

@@ -1,12 +1,12 @@
 /**
  * Shared predicates over {@link StepError} lists.
  *
- * Step errors come in two severities: BLOCKING (the default — the apply is
- * considered failed, triggers rollback and a non-zero exit) and ADVISORY
- * (`advisory: true` — reported as a warning, never blocks; used by the
- * `.ftl` helpers whose contract is graceful degradation). Every gate that
- * decides rollback/failure must count only blocking errors; every reporter
- * should still surface advisory ones. This module is a leaf (types-only
+ * Step errors come in two severities: blocking (the default: the apply is
+ * considered failed, triggers rollback and a non-zero exit) and advisory
+ * (`advisory: true`, which is reported as a warning, never blocks, and is
+ * used by the `.ftl` helpers whose contract is graceful degradation). Every
+ * gate that decides rollback/failure must count only blocking errors, and
+ * every reporter should still surface advisory ones. This module is a leaf (types-only
  * imports) so both `furnace-apply.ts` and its callers can share the
  * predicates without import cycles.
  */

package/dist/src/core/furnace-step-errors.js

@@ -2,12 +2,12 @@
 /**
  * Shared predicates over {@link StepError} lists.
  *
- * Step errors come in two severities: BLOCKING (the default — the apply is
- * considered failed, triggers rollback and a non-zero exit) and ADVISORY
- * (`advisory: true` — reported as a warning, never blocks; used by the
- * `.ftl` helpers whose contract is graceful degradation). Every gate that
- * decides rollback/failure must count only blocking errors; every reporter
- * should still surface advisory ones. This module is a leaf (types-only
+ * Step errors come in two severities: blocking (the default: the apply is
+ * considered failed, triggers rollback and a non-zero exit) and advisory
+ * (`advisory: true`, which is reported as a warning, never blocks, and is
+ * used by the `.ftl` helpers whose contract is graceful degradation). Every
+ * gate that decides rollback/failure must count only blocking errors, and
+ * every reporter should still surface advisory ones. This module is a leaf (types-only
  * imports) so both `furnace-apply.ts` and its callers can share the
  * predicates without import cycles.
  */

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

@@ -81,7 +81,7 @@ function hasPositiveTabindex(content) {
  * Collects `[start, end)` spans of `<label>…</label>` elements whose content
  * includes actual label text. Labels cannot nest per HTML, so the non-greedy
  * inner match is sound. A span qualifies only when the inner content minus
- * tags still contains non-whitespace — an empty or tag-only wrapper provides
+ * tags still contains non-whitespace. An empty or tag-only wrapper provides
  * no accessible name. A `${…}` Lit binding counts as label text: dynamic
  * (usually localized) text is a legitimate accessible name.
  */
@@ -132,12 +132,12 @@ function hasTemplateKeyboardHandler(content) {
 }
 /**
  * Native HTML elements that dispatch `click` on Enter and Space via the
- * platform. Attaching `@click` to these is NOT a keyboard-a11y bug because
- * the browser already handles the keyboard activation path — a duplicate
+ * platform. Attaching `@click` to these is not a keyboard-a11y bug, because
+ * the browser already handles the keyboard activation path. A duplicate
  * `@keydown`/`@keypress` handler would usually double-fire the action.
  *
- * `<a>` is accepted only when an `href` attribute is present; bare `<a>` is
- * non-interactive and is treated as synthetic.
+ * `<a>` is accepted only when an `href` attribute is present. A bare `<a>`
+ * is non-interactive and is treated as synthetic.
  */
 const NATIVE_CLICK_INTERACTIVE_TAGS = new Set([
     'button',
@@ -178,7 +178,7 @@ function isKeyboardCoveredByComposition(customConfig) {
  * *synthetic* interactive element (e.g. `<div @click>`), which lacks native
  * keyboard activation and therefore needs an explicit key handler for
  * Enter/Space. Returns false when every `@click` handler sits on a native
- * interactive element — those already fire `click` on keyboard activation.
+ * interactive element. Those already fire `click` on keyboard activation.
  */
 function hasTemplateClickOnSyntheticInteractive(content) {
     const pattern = /@click\s*=\s*\$\{/g;
@@ -219,7 +219,7 @@ function isClickOnSyntheticInteractive(content, clickIndex) {
         return true;
     const tagName = tagMatch[1].toLowerCase();
     if (tagName === 'a') {
-        // Bare <a> (no href) is non-interactive; require a keyboard handler.
+        // Bare <a> (no href) is non-interactive, so require a keyboard handler.
         // Look forward from the tag open for the closing `>` and scan the
         // attribute text in between for an href attribute.
         const tagEnd = content.indexOf('>', tagOpenIndex);
@@ -236,20 +236,20 @@ const SYMBOL_ONLY_ASCII = '+-*=<>|/\\^~@#&!?%';
  * Reports whether `text` is decoration (arrows, maths, emoji, bare
  * punctuation) rather than user-facing prose that needs localizing.
  *
- * The letter/number/mark test comes first and is script-agnostic — a rule
+ * The letter/number/mark test comes first and is script-agnostic. A rule
  * keyed on `code > 0xff` would classify every code point above U+00FF as a
  * symbol, exempting all CJK, Cyrillic, Greek, Arabic, Hebrew, Devanagari and
- * Thai text from a **localization** validator.
+ * Thai text from a localization validator.
  *
- * Combining marks are deliberately NOT counted as text: the check is an
+ * Combining marks are not counted as text: the check is an
  * `every()`, so a script's base letters already disqualify the string, and
  * treating marks as text would flag emoji carrying a variation selector
- * (U+FE0F is category Mn — `⚙️` is U+2699 + U+FE0F).
+ * (U+FE0F is category Mn, and `⚙️` is U+2699 + U+FE0F).
  *
- * High code points that are not letters — emoji, arrows, CJK punctuation —
+ * High code points that are not letters (emoji, arrows, CJK punctuation)
  * stay exempt, which is the rule's intent.
  *
- * A handful of emoji are ALSO Unicode letters, and the letter test alone
+ * A handful of emoji are also Unicode letters, and the letter test alone
  * gets them wrong: U+2139 (`ℹ`, the base of the common `ℹ️`) is category Ll,
  * so `\p{L}` would classify an info badge as prose needing localization.
  * Non-ASCII code points carrying `Emoji` are therefore read as symbols
@@ -335,7 +335,7 @@ function hasFlaggedTextInLitTemplates(content) {
     return false;
 }
 function hasFlaggedTextInDomAssignment(content) {
-    // `<expr>.textContent = "abc"` and `<expr>.innerHTML = "abc"` — these are
+    // `<expr>.textContent = "abc"` and `<expr>.innerHTML = "abc"`: these are
     // user-visible render paths. Template-literal RHS is excluded (usually
     // dynamic), matching the `${` guard used elsewhere in this helper.
     const assignPattern = /\.(?:textContent|innerHTML)\s*=\s*(["'])((?:\\.|(?!\1).)*)\1/g;

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

@@ -170,7 +170,7 @@ function hasCustomElementDefineCall(mjsContent) {
 /**
  * Detects whether the module's `customElements.define(...)` call includes a
  * literal `extends:` option (third argument). That shape is the marker for
- * a customized built-in element — the class extends a specific
+ * a customized built-in element: the class extends a specific
  * `HTMLxxxElement` rather than the autonomous `MozLitElement` path.
  *
  * Firefox's own widgets use this pattern for toolkit anchors (e.g.
@@ -193,24 +193,24 @@ function hasCustomElementExtendsOption(mjsContent) {
  *
  * Two shapes are accepted:
  *
- * 1. Autonomous custom element: `class X extends MozLitElement` — the
+ * 1. Autonomous custom element: `class X extends MozLitElement`, the
  *    default FireForge pattern for fork-authored components and most
  *    toolkit widgets.
  * 2. Customized built-in: `class X extends HTML<Something>Element` paired
  *    with a `customElements.define(..., ..., { extends: "<tagname>" })`
  *    call. Firefox's `moz-support-link`, `moz-button-group` tabbing
- *    widgets, and a handful of other toolkit components use this form;
+ *    widgets, and a handful of other toolkit components use this form.
  *    `furnace override` of those components writes the original source
  *    verbatim and the validator must not reject them.
  *
- * A class that extends a plain `HTMLElement` WITHOUT a `extends:` option
- * is still rejected — that's the legitimate `not-moz-lit-element` case
+ * A class that extends a plain `HTMLElement` without an `extends:` option
+ * is still rejected. That is the legitimate `not-moz-lit-element` case
  * the rule was originally designed to catch.
  */
 function classExtendsMozLitElement(mjsContent) {
     const hasClassDeclaration = /class\s+\w+\s+extends\s+/.test(mjsContent);
     if (!hasClassDeclaration) {
-        // No class declaration — skip this check since the component may use a
+        // No class declaration, so skip this check since the component may use a
         // different pattern (e.g. function-based). Other validators will catch
         // structural issues.
         return true;
@@ -218,8 +218,8 @@ function classExtendsMozLitElement(mjsContent) {
     if (/class\s+\w+\s+extends\s+MozLitElement\b/.test(mjsContent)) {
         return true;
     }
-    // Customized built-in: extend a specific HTMLxxxElement AND the define
-    // call carries an `extends:` option. Both halves are required — a class
+    // Customized built-in: extend a specific HTMLxxxElement and the define
+    // call carries an `extends:` option. Both halves are required: a class
     // that extends `HTMLAnchorElement` without the matching define option is
     // almost certainly an author mistake, and a define call with `extends:`
     // without a matching class is unreachable.
@@ -243,7 +243,7 @@ function collectCssVariableReferences(cssContent) {
     return referencedVariables;
 }
 /**
- * Collects CSS custom property *declarations* — names appearing on the
+ * Collects CSS custom property *declarations*, i.e. names appearing on the
  * left-hand side of a `--name:` declaration. Used to auto-exempt
  * component-local runtime variables from the token-prefix check: if the
  * component both declares and consumes a variable in its own CSS file, it

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

@@ -44,10 +44,10 @@ export declare function withRegistrationValidationCache<T>(body: () => Promise<T
  *
  * Scan set is the union of (a) the configured `tokenHostDocuments` (or
  * the upstream default when unset) and (b) any `browser/base/content/*.xhtml`
- * document that references `tagName` — the auto-detection path catches
+ * document that references `tagName`. The auto-detection path catches
  * forks that mount components from a replacement chrome document without
  * having configured `tokenHostDocuments`. The warning fires only when
- * NONE of the documents in the final scan set link the tokens CSS.
+ * none of the documents in the final scan set link the tokens CSS.
  */
 export declare function validateTokenLink(componentDir: string, tagName: string, root: string, tokenPrefix?: string, tokenHostDocuments?: string[]): Promise<ValidationIssue[]>;
 /**

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

@@ -1,9 +1,9 @@
 // SPDX-License-Identifier: EUPL-1.2
-import { createHash } from 'node:crypto';
 import { readdir } from 'node:fs/promises';
 import { join } from 'node:path';
 import { toError } from '../utils/errors.js';
 import { pathExists, readText } from '../utils/fs.js';
+import { sha256Hex } from '../utils/hash.js';
 import { warn } from '../utils/logger.js';
 import { escapeRegex, stripJsComments } from '../utils/regex.js';
 import { getProjectPaths, loadConfig } from './config.js';
@@ -94,7 +94,7 @@ export async function checkRegistrationConsistency(root, name, config, ftlDir) {
     // Check target directory
     const targetDir = join(engineDir, config.targetPath);
     status.targetExists = await pathExists(targetDir);
-    // Compare files (sourceExists is guaranteed true — we early-returned above)
+    // Compare files (sourceExists is guaranteed true, we early-returned above)
     if (status.targetExists) {
         const entries = await readdir(componentDir, { withFileTypes: true });
         for (const entry of entries) {
@@ -110,7 +110,7 @@ export async function checkRegistrationConsistency(root, name, config, ftlDir) {
                 continue;
             }
             // Deploy writes CSS-with-include-directives in fragment-expanded form,
-            // so the drift oracle must compare the *expanded* source — otherwise a
+            // so the drift oracle must compare the *expanded* source. Otherwise a
             // freshly deployed component would read as permanently drifted, and a
             // fragment edit would never read as drifted at all.
             let srcContent = await readText(srcPath);
@@ -119,8 +119,8 @@ export async function checkRegistrationConsistency(root, name, config, ftlDir) {
                     srcContent = (await expandCssFragments(srcContent, furnacePaths.sharedDir)).expanded;
                 }
                 catch {
-                    // Missing fragment: validate reports it as `missing-fragment`;
-                    // for drift purposes fall back to the raw source so the compare
+                    // Missing fragment: validate reports it as `missing-fragment`.
+                    // For drift purposes fall back to the raw source so the compare
                     // still happens deterministically.
                 }
             }
@@ -129,8 +129,8 @@ export async function checkRegistrationConsistency(root, name, config, ftlDir) {
             // comparisons hashed raw bytes, so on a CRLF checkout `furnace status`
             // and `furnace validate` reported drift for files apply had just
             // decided were identical.
-            const srcHash = createHash('sha256').update(normalizeForChecksum(srcContent)).digest('hex');
-            const destHash = createHash('sha256').update(normalizeForChecksum(destContent)).digest('hex');
+            const srcHash = sha256Hex(normalizeForChecksum(srcContent));
+            const destHash = sha256Hex(normalizeForChecksum(destContent));
             if (srcHash !== destHash) {
                 status.driftedFiles.push(entry.name);
                 status.filesInSync = false;
@@ -155,10 +155,8 @@ export async function checkRegistrationConsistency(root, name, config, ftlDir) {
             else {
                 const srcContent = await readText(ftlSrc);
                 const destContent = await readText(ftlDest);
-                const srcHash = createHash('sha256').update(normalizeForChecksum(srcContent)).digest('hex');
-                const destHash = createHash('sha256')
-                    .update(normalizeForChecksum(destContent))
-                    .digest('hex');
+                const srcHash = sha256Hex(normalizeForChecksum(srcContent));
+                const destHash = sha256Hex(normalizeForChecksum(destContent));
                 if (srcHash !== destHash) {
                     status.driftedFiles.push(ftlName);
                     status.filesInSync = false;
@@ -177,7 +175,7 @@ export async function checkRegistrationConsistency(root, name, config, ftlDir) {
     const cePath = join(engineDir, CUSTOM_ELEMENTS_JS);
     if (await pathExists(cePath)) {
         const ceContent = await readText(cePath);
-        // Structure-aware check shared with the ADD path — a bare substring
+        // Structure-aware check shared with the add path. A bare substring
         // test counted any mention of the tag (a leftover comment, an
         // unrelated string) as "registered", masking genuinely missing
         // registrations from both validate and the re-apply drift oracle.
@@ -269,7 +267,7 @@ const AUTO_DETECT_HOST_DIR = 'browser/base/content';
  * This catches a fork that mounts a custom element from its own top-level
  * chrome document (e.g. `mybrowser.xhtml`) without setting
  * `tokenHostDocuments`: scanning only the stock `browser.xhtml` would miss
- * the tokens CSS link in the ACTUAL host document and false-fire the
+ * the tokens CSS link in the actual host document and false-fire the
  * warning.
  *
  * @param engineDir Absolute engine root.
@@ -282,7 +280,7 @@ const AUTO_DETECT_HOST_DIR = 'browser/base/content';
  * `validateAllComponents` walks every component, and re-parsing
  * `fireforge.json` plus re-scanning every `.xhtml` under the chrome-document
  * directory per component is one config parse and one full directory read
- * PER COMPONENT, for work that depends only on the project and the engine.
+ * per component, for work that depends only on the project and the engine.
  *
  * Keyed by root/engine dir and cleared by
  * {@link resetRegistrationValidationCaches} at the start of each run, so a
@@ -293,9 +291,9 @@ const chromeDocumentCache = new Map();
 /**
  * Whether a batch validation is in flight.
  *
- * The caches are consulted ONLY while this is set. Outside a batch — a direct
+ * The caches are consulted only while this is set. Outside a batch (a direct
  * `validateComponent` call from `furnace status`, from apply's consistency
- * check, or from a test — every read goes to disk, so a caller that mutates
+ * check, or from a test) every read goes to disk, so a caller that mutates
  * the engine between calls can never be served a stale document.
  */
 let batchInFlight = false;
@@ -358,7 +356,7 @@ async function loadChromeDocuments(engineDir) {
     return documents;
 }
 async function autoDetectTokenHostDocuments(engineDir, tagName, already) {
-    // Reads the directory ONCE per run rather than once per component: only the
+    // Reads the directory once per run rather than once per component: only the
     // tag being searched for differs between components.
     const documents = await loadChromeDocuments(engineDir);
     const alreadySet = new Set(already);
@@ -379,10 +377,10 @@ async function autoDetectTokenHostDocuments(engineDir, tagName, already) {
  *
  * Scan set is the union of (a) the configured `tokenHostDocuments` (or
  * the upstream default when unset) and (b) any `browser/base/content/*.xhtml`
- * document that references `tagName` — the auto-detection path catches
+ * document that references `tagName`. The auto-detection path catches
  * forks that mount components from a replacement chrome document without
  * having configured `tokenHostDocuments`. The warning fires only when
- * NONE of the documents in the final scan set link the tokens CSS.
+ * none of the documents in the final scan set link the tokens CSS.
  */
 export async function validateTokenLink(componentDir, tagName, root, tokenPrefix, tokenHostDocuments) {
     const issues = [];
@@ -483,7 +481,7 @@ export async function runPostApplyConsistencyChecks(root, config, result, ftlDir
             }
         }
         catch {
-            // Consistency check is best-effort; failures here should not block apply
+            // Consistency check is best-effort. Failures here should not block apply
         }
     }
 }

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

@@ -2,7 +2,7 @@ import type { ComponentType, CustomComponentConfig, ValidationIssue } from '../t
 /**
  * Returns true when file content carries unresolved three-way-merge
  * conflict markers (as left behind by `furnace refresh`). Shared between
- * the structure validator and `furnace sync`'s pre-apply gate — both must
+ * the structure validator and `furnace sync`'s pre-apply gate. Both must
  * agree on what "conflicted" means so a file that validate flags can never
  * slip through sync into the engine.
  */

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

@@ -5,7 +5,7 @@ import { pathExists, readText } from '../utils/fs.js';
 /**
  * Returns true when file content carries unresolved three-way-merge
  * conflict markers (as left behind by `furnace refresh`). Shared between
- * the structure validator and `furnace sync`'s pre-apply gate — both must
+ * the structure validator and `furnace sync`'s pre-apply gate. Both must
  * agree on what "conflicted" means so a file that validate flags can never
  * slip through sync into the engine.
  */
@@ -37,7 +37,7 @@ export async function validateStructure(componentDir, tagName, type, customConfi
             message: `Required file ${tagName}.mjs not found.`,
         });
     }
-    // .css should exist — except for library components (base class + helpers,
+    // .css should exist, except for library components (base class + helpers,
     // no element of their own), which render nothing and need no stylesheet.
     if (!(await pathExists(cssPath)) && customConfig?.kind !== 'library') {
         issues.push({
@@ -52,8 +52,8 @@ export async function validateStructure(componentDir, tagName, type, customConfi
     // localization payload is empty, which is hard to spot in review.
     //
     // Components that declare `sharedFtl` participate in a pre-existing
-    // feature-scoped bundle, so there is no per-component .ftl to require —
-    // the shared file is owned by whoever authored the feature bundle.
+    // feature-scoped bundle, so there is no per-component .ftl to require.
+    // The shared file is owned by whoever authored the feature bundle.
     if (type === 'custom' && customConfig?.localized && !customConfig.sharedFtl) {
         const ftlPath = join(componentDir, `${tagName}.ftl`);
         if (!(await pathExists(ftlPath))) {

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

@@ -61,8 +61,8 @@ export async function validateComponent(componentDir, tagName, type, config, roo
     if (root) {
         issues.push(...(await validateTokenLink(componentDir, tagName, root, config?.tokenPrefix, config?.tokenHostDocuments)));
     }
-    // CSS fragment checks: missing fragment files are structural errors;
-    // stale deployed expansions are drift the next deploy refreshes.
+    // CSS fragment checks: missing fragment files are structural errors.
+    // Stale deployed expansions are drift the next deploy refreshes.
     if (type === 'custom') {
         const furnacePaths = getFurnacePaths(root ?? join(componentDir, '..', '..', '..'));
         const engineTargetDir = root && config?.custom[tagName]
@@ -81,7 +81,7 @@ export async function validateComponent(componentDir, tagName, type, config, roo
     // When root is provided and this is a custom component with registration,
     // also run registration pattern and jar.mn validation for this component.
     // Skipped when an outer orchestrator (validateAllComponents) will run the
-    // aggregate versions itself; otherwise the same issues are reported twice.
+    // aggregate versions itself. Otherwise the same issues are reported twice.
     if (root && config && type === 'custom' && !options?.skipAggregateChecks) {
         const customConfig = config.custom[tagName];
         if (customConfig?.register) {
@@ -183,7 +183,7 @@ export async function validateAllComponents(root) {
                 continue;
             }
             // Pass root so that per-component token link validation runs.
-            // Skip registration/jar.mn checks inside validateComponent — the aggregate
+            // Skip registration/jar.mn checks inside validateComponent. The aggregate
             // validators below run them exactly once across all components, which both
             // surfaces cross-component issues and avoids double-counting.
             const issues = await validateComponent(componentDir, name, 'custom', config, root, {
@@ -209,7 +209,7 @@ export async function validateAllComponents(root) {
         // `furnace create --with-tests --xpcshell` scaffolds a test directory at
         // `browser/base/content/test/<binary>-xpcshell/<name>/`. A leftover
         // scaffold whose `<name>` is not in furnace.json is almost always the
-        // aftermath of an incomplete `furnace remove` or `rename`; flag it as an
+        // aftermath of an incomplete `furnace remove` or `rename`. Flag it as an
         // `orphan-xpcshell-scaffold` error so operators delete or re-create the
         // scaffold instead of discovering the mismatch at test run time. A
         // missing engine or scaffold parent directory degrades silently, so this
@@ -224,14 +224,14 @@ export async function validateAllComponents(root) {
             }
         }
         catch {
-            // Validation degrades gracefully — the absence of an engine
+            // Validation degrades gracefully: the absence of an engine
             // directory, permission denial reading the scaffold tree, or any
             // other transient fs issue should never cascade into false
             // "orphan" reports.
         }
         // jsconfig chrome-module paths drift: when `typecheckJsconfig` is
-        // configured, deploy maintains a paths mapping per deployed module file;
-        // missing or stale entries mean typed cross-module imports are silently
+        // configured, deploy maintains a paths mapping per deployed module file.
+        // Missing or stale entries mean typed cross-module imports are silently
         // degrading to `any` in the consumer's typecheck.
         if (config.typecheckJsconfig) {
             try {
@@ -256,7 +256,7 @@ export async function validateAllComponents(root) {
             }
             catch {
                 // Drift detection must not break validation when the jsconfig is
-                // missing or unparsable — deploy reports those cases with guidance.
+                // missing or unparsable. Deploy reports those cases with guidance.
             }
         }
         return results;

package/dist/src/core/furnace-version-drift.d.ts

@@ -5,19 +5,19 @@
  * Overrides are forks of Firefox source files taken at a specific point in
  * time. If Firefox moves forward and the override's `baseVersion` is not
  * refreshed, the override may apply against a file whose upstream shape has
- * changed — the single biggest silent failure mode for furnace.
+ * changed, which is the single biggest silent failure mode for furnace.
  *
  * Deliberately pure and string-only: no I/O, and no parsing of Firefox
  * version components. String equality is sufficient because `fireforge.json`
  * stores a canonical version string (e.g. `"140.9.0esr"`) and overrides are
  * created with exactly that string copied from
- * `forgeConfig.firefox.version`. Any mismatch is worth surfacing — even
+ * `forgeConfig.firefox.version`. Any mismatch is worth surfacing: even
  * "140.0" vs "140.9.0esr" is a real drift signal.
  *
- * The result GATES apply/deploy: both warn and then FAIL without --force
+ * The result gates apply/deploy: both warn and then fail without --force
  * (see furnaceApplyCommand / furnaceDeployCommand), and `furnace sync`
  * re-checks it after refresh before applying. Status reports drift alongside
- * the component overview. Keep this doc in sync with the gates — it is not
+ * the component overview. Keep this doc in sync with the gates. It is not
  * advisory.
  */
 import type { FurnaceConfig } from '../types/furnace.js';
@@ -35,7 +35,7 @@ export interface OverrideVersionDrift {
 /**
  * Classifies how severe a version drift is by comparing the numeric
  * components of the two version strings. Falls back to `'major'` when
- * either version is unparseable — this ensures that unusual version
+ * either version is unparseable. This ensures that unusual version
  * formats surface with the highest visibility rather than being silently
  * downgraded.
  */

package/dist/src/core/furnace-version-drift.js

@@ -6,19 +6,19 @@
  * Overrides are forks of Firefox source files taken at a specific point in
  * time. If Firefox moves forward and the override's `baseVersion` is not
  * refreshed, the override may apply against a file whose upstream shape has
- * changed — the single biggest silent failure mode for furnace.
+ * changed, which is the single biggest silent failure mode for furnace.
  *
  * Deliberately pure and string-only: no I/O, and no parsing of Firefox
  * version components. String equality is sufficient because `fireforge.json`
  * stores a canonical version string (e.g. `"140.9.0esr"`) and overrides are
  * created with exactly that string copied from
- * `forgeConfig.firefox.version`. Any mismatch is worth surfacing — even
+ * `forgeConfig.firefox.version`. Any mismatch is worth surfacing: even
  * "140.0" vs "140.9.0esr" is a real drift signal.
  *
- * The result GATES apply/deploy: both warn and then FAIL without --force
+ * The result gates apply/deploy: both warn and then fail without --force
  * (see furnaceApplyCommand / furnaceDeployCommand), and `furnace sync`
  * re-checks it after refresh before applying. Status reports drift alongside
- * the component overview. Keep this doc in sync with the gates — it is not
+ * the component overview. Keep this doc in sync with the gates. It is not
  * advisory.
  */
 /**
@@ -39,7 +39,7 @@ function parseVersionComponents(version) {
 /**
  * Classifies how severe a version drift is by comparing the numeric
  * components of the two version strings. Falls back to `'major'` when
- * either version is unparseable — this ensures that unusual version
+ * either version is unparseable. This ensures that unusual version
  * formats surface with the highest visibility rather than being silently
  * downgraded.
  */