@hominis/fireforge 0.43.1 → 0.44.0

package/dist/src/utils/validation.js

@@ -36,15 +36,15 @@ export function isPositiveInteger(value) {
  * Parses a CLI flag value as a positive integer. Throws
  * {@link InvalidArgumentError} on NaN, non-integer, or non-positive input.
  *
- * Intended for use inside Commander `argParser` bodies where the raw
- * input arrives as a string. Without this wrapper the default pattern
- * (`parseInt(v, 10)`) silently hands NaN to downstream planners, which
- * then embed it into filenames / orders instead of failing fast.
+ * Intended for use inside Commander `argParser` bodies where the raw input
+ * arrives as a string. The default pattern (`parseInt(v, 10)`) silently
+ * hands NaN to downstream planners, which then embed it into filenames and
+ * orders instead of failing fast.
  *
  * Rejects leading-zero forms ("01"), decimals ("1.5"), whitespace, and
- * non-numeric garbage via a strict regex — we only accept the canonical
- * representation so there is no ambiguity between what the user typed
- * and what the value becomes on disk.
+ * non-numeric garbage via a strict regex — only the canonical
+ * representation is accepted, so there is no ambiguity between what the user
+ * typed and what the value becomes on disk.
  *
  * @param flagName - Flag name to include in the error (e.g. `--order`)
  * @param rawValue - Raw string value from Commander
@@ -108,19 +108,32 @@ export function isValidFirefoxCandidate(candidate) {
     return /^build[1-9]\d{0,3}$/.test(candidate);
 }
 /**
- * Valid Firefox product identifiers.
+ * Naming contract for this module's checks.
+ *
+ * `validate*` is easy to spread across incompatible return contracts — some
+ * throwing and returning void, some returning an issue list, some a parsed
+ * value, some a boolean, some an error MESSAGE — and a caller cannot tell
+ * which from the name. Passing a THROWING `validate*` to a clack `validate`
+ * callback, which expects a returned message, kills the prompt instead of
+ * re-prompting.
  *
- * `satisfies readonly FirefoxProduct[]` links the runtime list to the union at
- * `types/config.ts:5` in ONE direction: it rejects an entry here that the union
- * does not declare. It cannot see a union member missing from this list —
- * widening a `readonly T[]` check never fails for being short. The reverse
- * direction is covered by the exhaustive switch in
- * `utils/__tests__/validation.test.ts`, which fails to compile when the union
- * grows.
+ * The two dominant contracts keep the prefix:
+ *   - `validate*` — throws on failure, or returns an issue list.
+ *   - `is*` / `has*` — a type predicate or boolean.
+ * The message-returning minority is `describe*Problem`, which reads as what
+ * it is: a description of what is wrong, or `undefined`.
  *
- * Two further copies of this list existed before 0.41.0 — an inline literal
- * inside the validator below and `SOURCE_PRODUCTS` in `commands/source.ts` —
- * neither linked to the union.
+ * `assert*` is uniform throughout: throw-or-continue.
+ */
+/**
+ * Valid Firefox product identifiers.
+ *
+ * `satisfies readonly FirefoxProduct[]` links the runtime list to the union
+ * in ONE direction: it rejects an entry here that the union does not
+ * declare. It cannot see a union member missing from this list — widening a
+ * `readonly T[]` check never fails for being short. The reverse direction is
+ * covered by the exhaustive switch in `utils/__tests__/validation.test.ts`,
+ * which fails to compile when the union grows.
  */
 export const FIREFOX_PRODUCTS = [
     'firefox',
@@ -132,12 +145,30 @@ export const FIREFOX_PRODUCTS = [
  * Validates a Firefox product string.
  *
  * A type predicate, matching its siblings {@link isValidPatchCategory} and
- * {@link isValidProjectLicense}. It returned plain `boolean` until 0.41.0,
- * which forced `as FirefoxProduct` casts at both call sites even though the
- * `.includes` check IS the runtime proof.
+ * {@link isValidProjectLicense}. Returning plain `boolean` would force
+ * `as FirefoxProduct` casts at the call sites even though the `.includes`
+ * check IS the runtime proof.
  */
-export function isValidFirefoxProduct(product) {
-    return FIREFOX_PRODUCTS.includes(product);
+export const isValidFirefoxProduct = makeEnumGuard(FIREFOX_PRODUCTS);
+/**
+ * Builds a type predicate from a `readonly` tuple of allowed values.
+ *
+ * Deriving the type from the list — rather than declaring a union and
+ * hand-maintaining a matching array — removes a whole class of drift: a
+ * union can otherwise accept a stale allowlist with no compile error, and a
+ * copy of the member list on the `fireforge.json` read path can silently
+ * reject a newly added value.
+ *
+ * Returning a predicate rather than a boolean is what removes the `as`
+ * casts: `.includes` IS the runtime proof, so the caller should not have to
+ * re-assert it. `ParsedRecord.stringEnum` (src/utils/parse.ts) consumes
+ * exactly this shape.
+ *
+ * @param values - The allowed values, as a `readonly` tuple
+ * @returns A type predicate narrowing a string to one of `values`
+ */
+export function makeEnumGuard(values) {
+    return (value) => values.includes(value);
 }
 /**
  * Valid project license SPDX identifiers.
@@ -146,9 +177,7 @@ export const PROJECT_LICENSES = ['EUPL-1.2', 'MPL-2.0', '0BSD', 'GPL-2.0-or-late
 /**
  * Validates a project license string.
  */
-export function isValidProjectLicense(license) {
-    return PROJECT_LICENSES.includes(license);
-}
+export const isValidProjectLicense = makeEnumGuard(PROJECT_LICENSES);
 /**
  * Valid patch categories.
  */
@@ -156,9 +185,7 @@ export const PATCH_CATEGORIES = ['branding', 'ui', 'privacy', 'security', 'infra
 /**
  * Validates a patch category string.
  */
-export function isValidPatchCategory(category) {
-    return PATCH_CATEGORIES.includes(category);
-}
+export const isValidPatchCategory = makeEnumGuard(PATCH_CATEGORIES);
 /**
  * Checks whether a Firefox version string has an ESR suffix.
  */
@@ -194,7 +221,7 @@ export function inferProductFromVersion(version) {
  *
  * @returns An error message if incompatible, or undefined if valid.
  */
-export function validateFirefoxProductVersionCompatibility(version, product) {
+export function describeProductVersionIncompatibility(version, product) {
     const versionIsEsr = isEsrVersion(version);
     const versionIsBeta = isBetaVersion(version);
     switch (product) {
@@ -247,7 +274,7 @@ export function isDefined(value) {
  *
  * @returns An error message if invalid, or undefined if valid.
  */
-export function validateTokenName(name) {
+export function describeTokenNameProblem(name) {
     // Strip leading -- for validation (callers may pass with or without)
     const ident = name.replace(/^--/, '');
     if (!ident) {
@@ -282,7 +309,7 @@ export function validateTokenName(name) {
  * @throws InvalidArgumentError if the resulting name is not a valid CSS custom property.
  */
 export function normalizeTokenName(name) {
-    const error = validateTokenName(name);
+    const error = describeTokenNameProblem(name);
     if (error) {
         throw new InvalidArgumentError(error, 'tokenName');
     }
@@ -323,7 +350,7 @@ export function normalizePatchDisplayName(name, category) {
  * @param name - The patch name to validate
  * @returns Error message if invalid, undefined if valid
  */
-export function validatePatchName(name) {
+export function describePatchNameProblem(name) {
     if (!name.trim())
         return 'Name is required';
     if (name.length > 50)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hominis/fireforge",
-  "version": "0.43.1",
+  "version": "0.44.0",
   "description": "FireForge — a build tool for customizing Firefox",
   "type": "module",
   "main": "./dist/src/index.js",
@@ -38,7 +38,7 @@
     "format:check": "prettier --check --ignore-unknown \"src/**/*.ts\" \"bin/**/*.ts\" \"scripts/**/*.mjs\" \"eslint-rules/**/*.js\" \"package.json\" \"eslint.config.js\" \"vitest.config.ts\" \"vitest.pack.config.ts\" \"tsconfig.json\" \"tsconfig.build.json\" \".lintstagedrc.json\" \".prettierignore\" \".prettierrc\" \".gitignore\" \"README.md\" \"CHANGELOG.md\" \"docs/**/*.md\" \"knip.json\"",
     "prepare": "node -e \"import('./scripts/prepare.mjs').catch((error) => { if (error && typeof error === 'object' && 'code' in error && error.code === 'ERR_MODULE_NOT_FOUND') process.exit(0); throw error; })\"",
     "prepack": "npm run build && node ./scripts/generate-build-info.mjs --loud",
-    "release:check": "npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run deadcode:check && npm run cycles:check && npm run test:coverage && npm run pack:verify && npm run pack:dry-run",
+    "release:check": "npm run format:check && npm run whitespace:check && npm run lint:ci && npm run typecheck && npm run deadcode:check && npm run cycles:check && npm run test:coverage && npm run pack:verify",
     "prepublishOnly": "npm run release:check"
   },
   "files": [

package/dist/src/commands/doctor/post-rebase-audit.d.ts

@@ -1,2 +0,0 @@
-import type { DoctorCheckDefinition } from '../doctor-check-core.js';
-export declare const POST_REBASE_AUDIT_CHECK: DoctorCheckDefinition;

package/dist/src/commands/doctor-furnace-manifest-sync.d.ts

@@ -1,18 +0,0 @@
-/**
- * "Furnace manifest sync" doctor check.
- *
- * Surfaces orphaned component directories on disk whose names are missing
- * from `furnace.json`. The motivating eval case is the concurrent-override
- * race (eval 2) where two parallel `furnace override` commands both left
- * their directory on disk but only the second reached
- * `writeFurnaceConfig`. Under `--repair-furnace`, override orphans are
- * re-registered from the `override.json` sidecar the command wrote during
- * the copy phase; custom orphans are listed for the operator to either
- * re-run `furnace create` against or delete manually, because custom
- * components have no similar persisted metadata.
- *
- * Lives in a sibling module to keep `doctor-furnace.ts` under the
- * per-file LOC budget.
- */
-import type { DoctorCheckDefinition } from './doctor-check-core.js';
-export declare const furnaceManifestSyncCheck: DoctorCheckDefinition;

package/dist/src/core/manifest-helpers.d.ts

@@ -1,38 +0,0 @@
-import type { JarMnToken, MozBuildToken } from './manifest-tokenizers.js';
-/**
- * Ordering comparator matching mozbuild's `StrictOrderingOnAppendList`
- * (`mozbuild.util.UnsortedError`): entries are compared **case-insensitively**,
- * so `HominisAppearanceController` (`appe`) sorts before
- * `HominisAppMenuIntegration` (`appm`) even though a raw byte comparison
- * places the uppercase `M` (0x4D) before the lowercase `e` (0x65).
- *
- * A naive `a > b` insertion landed the new entry in byte order, which
- * `mach configure` then rejected with `UnsortedError`, aborting the build.
- * Ties on the lower-cased key fall back to byte order so the comparison is
- * total and stable.
- */
-export declare function mozbuildSortCompare(a: string, b: string): number;
-/**
- * Inserts a line into an array of lines in alphabetical order within a
- * specified range. The comparison key is extracted from each line.
- *
- * @returns Object with insertIndex and previousEntry
- */
-export declare function findAlphabeticalPosition(lines: string[], startLine: number, endLine: number, newKey: string, extractKey: (line: string) => string | undefined): {
-    insertIndex: number;
-    previousEntry: string | undefined;
-};
-/**
- * Find alphabetical position within a tokenized jar.mn section.
- */
-export declare function findAlphabeticalTokenPosition(tokens: JarMnToken[], sectionTargetPattern: RegExp, newKey: string): {
-    insertIndex: number;
-    previousEntry: string | undefined;
-};
-/**
- * Find alphabetical position within tokenized moz.build list items.
- */
-export declare function findAlphabeticalMozBuildPosition(tokens: MozBuildToken[], newKey: string): {
-    insertIndex: number;
-    previousEntry: string | undefined;
-};

package/dist/src/core/manifest-helpers.js

@@ -1,120 +0,0 @@
-/**
- * Ordering comparator matching mozbuild's `StrictOrderingOnAppendList`
- * (`mozbuild.util.UnsortedError`): entries are compared **case-insensitively**,
- * so `HominisAppearanceController` (`appe`) sorts before
- * `HominisAppMenuIntegration` (`appm`) even though a raw byte comparison
- * places the uppercase `M` (0x4D) before the lowercase `e` (0x65).
- *
- * A naive `a > b` insertion landed the new entry in byte order, which
- * `mach configure` then rejected with `UnsortedError`, aborting the build.
- * Ties on the lower-cased key fall back to byte order so the comparison is
- * total and stable.
- */
-export function mozbuildSortCompare(a, b) {
-    const la = a.toLowerCase();
-    const lb = b.toLowerCase();
-    if (la < lb)
-        return -1;
-    if (la > lb)
-        return 1;
-    if (a < b)
-        return -1;
-    if (a > b)
-        return 1;
-    return 0;
-}
-/**
- * Inserts a line into an array of lines in alphabetical order within a
- * specified range. The comparison key is extracted from each line.
- *
- * @returns Object with insertIndex and previousEntry
- */
-export function findAlphabeticalPosition(lines, startLine, endLine, newKey, extractKey) {
-    // Check if existing entries are actually sorted; if not, append at end
-    const existingKeys = [];
-    for (let i = startLine; i < endLine; i++) {
-        const line = lines[i];
-        if (line === undefined)
-            continue;
-        const key = extractKey(line);
-        if (key !== undefined) {
-            existingKeys.push(key);
-        }
-    }
-    const isSorted = existingKeys.every((k, idx) => idx === 0 || mozbuildSortCompare(k, existingKeys[idx - 1] ?? '') >= 0);
-    if (!isSorted) {
-        return { insertIndex: endLine, previousEntry: undefined };
-    }
-    let insertIndex = endLine;
-    let previousEntry;
-    for (let i = startLine; i < endLine; i++) {
-        const line = lines[i];
-        if (line === undefined)
-            continue;
-        const key = extractKey(line);
-        if (key === undefined)
-            continue;
-        if (mozbuildSortCompare(key, newKey) > 0) {
-            insertIndex = i;
-            break;
-        }
-        insertIndex = i + 1;
-        previousEntry = line.trim();
-    }
-    return { insertIndex, previousEntry };
-}
-/**
- * Find alphabetical position within a tokenized jar.mn section.
- */
-export function findAlphabeticalTokenPosition(tokens, sectionTargetPattern, newKey) {
-    // Find entry tokens in the section matching the pattern
-    const sectionEntries = tokens.filter((t) => t.type === 'entry' && t.parsed && sectionTargetPattern.test(t.parsed.target));
-    let insertLineIndex;
-    let previousEntry;
-    if (sectionEntries.length === 0) {
-        // Empty section: find the section header and insert after it
-        const headerToken = tokens.find((t) => t.type === 'header' || (t.type === 'directive' && sectionTargetPattern.test(t.raw)));
-        if (headerToken) {
-            return { insertIndex: headerToken.lineIndex + 1, previousEntry: undefined };
-        }
-        return { insertIndex: -1, previousEntry: undefined };
-    }
-    // Default: after the last section entry
-    insertLineIndex = (sectionEntries[sectionEntries.length - 1]?.lineIndex ?? 0) + 1;
-    for (const entry of sectionEntries) {
-        if (!entry.parsed)
-            continue;
-        const match = sectionTargetPattern.exec(entry.parsed.target);
-        const key = match?.[1] ?? entry.parsed.target;
-        if (mozbuildSortCompare(key, newKey) > 0) {
-            insertLineIndex = entry.lineIndex;
-            break;
-        }
-        insertLineIndex = entry.lineIndex + 1;
-        previousEntry = entry.raw.trim();
-    }
-    return { insertIndex: insertLineIndex, previousEntry };
-}
-/**
- * Find alphabetical position within tokenized moz.build list items.
- */
-export function findAlphabeticalMozBuildPosition(tokens, newKey) {
-    const items = tokens.filter((t) => t.type === 'list-item');
-    if (items.length === 0) {
-        // Insert after list-open
-        const openToken = tokens.find((t) => t.type === 'list-open');
-        return { insertIndex: (openToken?.lineIndex ?? 0) + 1, previousEntry: undefined };
-    }
-    let insertLineIndex = (items[items.length - 1]?.lineIndex ?? 0) + 1;
-    let previousEntry;
-    for (const item of items) {
-        const key = item.parsed?.value ?? '';
-        if (mozbuildSortCompare(key, newKey) > 0) {
-            insertLineIndex = item.lineIndex;
-            break;
-        }
-        insertLineIndex = item.lineIndex + 1;
-        previousEntry = item.raw.trim();
-    }
-    return { insertIndex: insertLineIndex, previousEntry };
-}