@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/utils/validation.js

@@ -1,394 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Type guards and validation utilities.
- * Used to safely narrow types from unknown values.
- */
-import { InvalidArgumentError } from '../errors/base.js';
-import { escapeRegex } from './regex.js';
-/**
- * Checks whether a value is a string.
- * @param value - Value to check
- * @returns True if value is a string
- */
-export function isString(value) {
-    return typeof value === 'string';
-}
-/**
- * Checks whether a value is a finite number (excludes NaN).
- * @param value - Value to check
- * @returns True if value is a finite number
- */
-export function isNumber(value) {
-    // Number.isFinite matches the documented contract: NaN and ±Infinity are
-    // excluded (a JSON config field of 1e999 parses to Infinity, which must
-    // not validate as a legal number).
-    return typeof value === 'number' && Number.isFinite(value);
-}
-/**
- * Checks whether a value is a positive integer (greater than zero).
- * @param value - Value to check
- * @returns True if value is a positive integer
- */
-export function isPositiveInteger(value) {
-    return isNumber(value) && Number.isInteger(value) && value > 0;
-}
-/**
- * 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. 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. 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
- */
-export function parsePositiveIntegerFlag(flagName, rawValue) {
-    if (!/^[1-9]\d*$/.test(rawValue)) {
-        throw new InvalidArgumentError(`${flagName} must be a positive integer, got "${rawValue}".`, flagName);
-    }
-    return Number.parseInt(rawValue, 10);
-}
-/**
- * Checks whether a value is a boolean.
- * @param value - Value to check
- * @returns True if value is a boolean
- */
-export function isBoolean(value) {
-    return typeof value === 'boolean';
-}
-/**
- * Checks whether a value is a non-null, non-array object.
- * @param value - Value to check
- * @returns True if value is a plain object
- */
-export function isObject(value) {
-    return typeof value === 'object' && value !== null && !Array.isArray(value);
-}
-/**
- * Checks whether a value is an array.
- * @param value - Value to check
- * @returns True if value is an array
- */
-export function isArray(value) {
-    return Array.isArray(value);
-}
-/**
- * Narrows a JSON value to a JSON object node (excludes arrays and `null`).
- *
- * Unlike {@link isObject} this accepts only values already known to be JSON
- * data, so the narrowed `JsonObject` keeps its concrete value contract.
- * Use it when walking a `JsonValue` tree rather than at `unknown` boundaries.
- * @param value - JSON value to check
- * @returns True if value is a JSON object node
- */
-export function isJsonObject(value) {
-    return isObject(value);
-}
-/**
- * Validates a Firefox version string.
- * Accepts formats like "140.9.0", "140.9.1", "140.9.0esr", "147.0b1"
- */
-export function isValidFirefoxVersion(version) {
-    // Stable/ESR: 140.9.0, 140.9.1, 140.9.0esr, 128.0.1esr
-    // Beta: 147.0b1, 147.0b2
-    return /^[1-9]\d{0,2}\.\d+(?:b[1-9]\d*|\.\d+(?:esr)?|esr)?$/.test(version);
-}
-/**
- * Orders two Firefox version strings semantically: major, minor and patch
- * numerically, with a beta (`153.0b7`) before the release it precedes
- * (`153.0`). An `esr` suffix does not change the order: `153.3.0esr` and
- * `153.3.0` compare equal, since the product says which line it is. A
- * lexical sort, which this replaces in `rebase`, put `153.10.0esr` before
- * `153.2.0esr` and `99.0` after `140.0esr`. A string that is not a Firefox
- * version sorts after every one that is, then lexically.
- * @returns Negative when `a` is older, positive when newer, 0 when equal
- */
-export function compareFirefoxVersions(a, b) {
-    const left = parseFirefoxVersionOrder(a);
-    const right = parseFirefoxVersionOrder(b);
-    if (left === undefined || right === undefined) {
-        if (left !== undefined)
-            return -1;
-        if (right !== undefined)
-            return 1;
-        return a < b ? -1 : a > b ? 1 : 0;
-    }
-    for (let i = 0; i < left.length; i++) {
-        const delta = (left[i] ?? 0) - (right[i] ?? 0);
-        if (delta !== 0)
-            return delta;
-    }
-    return 0;
-}
-/**
- * `[major, minor, patch, betaRank]`, where a release ranks above every beta
- * of the same version.
- */
-function parseFirefoxVersionOrder(version) {
-    const match = /^(\d+)\.(\d+)(?:\.(\d+))?(?:b(\d+))?(?:esr)?$/i.exec(version.trim());
-    if (!match)
-        return undefined;
-    const beta = match[4];
-    return [
-        Number(match[1]),
-        Number(match[2]),
-        Number(match[3] ?? 0),
-        beta === undefined ? Number.MAX_SAFE_INTEGER : Number(beta),
-    ];
-}
-/**
- * Validates a release-candidate build directory name.
- * Accepts formats like "build1", "build2", "build12" (no leading zero).
- */
-export function isValidFirefoxCandidate(candidate) {
-    return /^build[1-9]\d{0,3}$/.test(candidate);
-}
-/**
- * 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. 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.
- *
- * 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`.
- *
- * `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, because
- * widening a `readonly T[]` check never fails for being short. The reverse direction is
- * covered by the `ExhaustiveFirefoxProductList` operand below, which stops
- * compiling when the union grows past this list.
- */
-const FIREFOX_PRODUCT_VALUES = [
-    'firefox',
-    'firefox-esr',
-    'firefox-beta',
-    'firefox-devedition',
-];
-export const FIREFOX_PRODUCTS = FIREFOX_PRODUCT_VALUES;
-/**
- * Validates a Firefox product string.
- *
- * A type predicate, matching its sibling {@link isValidProjectLicense}.
- * Returning plain `boolean` would force `as FirefoxProduct` casts at the
- * call sites even though the `.includes` check is the runtime proof.
- */
-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.
- */
-export const PROJECT_LICENSES = ['EUPL-1.2', 'MPL-2.0', '0BSD', 'GPL-2.0-or-later'];
-/**
- * Validates a project license string.
- */
-export const isValidProjectLicense = makeEnumGuard(PROJECT_LICENSES);
-/**
- * Valid patch categories.
- */
-export const PATCH_CATEGORIES = ['branding', 'ui', 'privacy', 'security', 'infra'];
-/**
- * Checks whether a Firefox version string has an ESR suffix.
- */
-function isEsrVersion(version) {
-    return /esr$/i.test(version);
-}
-/**
- * Checks whether a Firefox version string is a beta version (e.g. "147.0b1").
- */
-function isBetaVersion(version) {
-    return /b\d+$/.test(version);
-}
-/**
- * Infers the Firefox product type from a version string.
- * Returns undefined if no clear inference can be made.
- */
-export function inferProductFromVersion(version) {
-    if (isEsrVersion(version)) {
-        return 'firefox-esr';
-    }
-    if (isBetaVersion(version)) {
-        return 'firefox-beta';
-    }
-    return undefined;
-}
-/**
- * Validates that a Firefox product and version are compatible.
- *
- * Rules:
- * - `firefox-esr` requires an ESR version (e.g. "140.9.0esr", "128.0.1esr").
- * - `firefox-beta` and `firefox-devedition` require a beta version (e.g. "147.0b1").
- * - `firefox` (stable) rejects both ESR and beta version strings.
- *
- * @returns An error message if incompatible, or undefined if valid.
- */
-export function describeProductVersionIncompatibility(version, product) {
-    const versionIsEsr = isEsrVersion(version);
-    const versionIsBeta = isBetaVersion(version);
-    switch (product) {
-        case 'firefox-esr':
-            if (!versionIsEsr) {
-                return (`Product "firefox-esr" requires an ESR version (e.g. "128.0esr"), ` +
-                    `but got "${version}"`);
-            }
-            break;
-        case 'firefox-beta':
-        case 'firefox-devedition':
-            if (!versionIsBeta) {
-                return (`Product "${product}" requires a beta version (e.g. "147.0b1"), ` + `but got "${version}"`);
-            }
-            break;
-        case 'firefox':
-            if (versionIsEsr) {
-                return (`Product "firefox" does not accept ESR versions. ` +
-                    `Use product "firefox-esr" with version "${version}", or remove the "esr" suffix`);
-            }
-            if (versionIsBeta) {
-                return (`Product "firefox" does not accept beta versions. ` +
-                    `Use product "firefox-beta" with version "${version}", or remove the beta suffix`);
-            }
-            break;
-    }
-    return undefined;
-}
-/**
- * Validates an application ID string.
- * Accepts reverse-domain format like "org.example.browser"
- */
-export function isValidAppId(appId) {
-    return /^[a-z][a-z0-9]*(\.[a-z][a-z0-9]*)+$/.test(appId);
-}
-/**
- * Validates that a string is a legal CSS custom property identifier (the part after `--`).
- *
- * A valid CSS custom property name requires the ident portion to:
- * - Be non-empty
- * - Contain no whitespace or control characters
- * - Contain no sequences that would break CSS syntax
- * - Consist of printable, CSS-safe characters (letters, digits, hyphens, underscores, etc.)
- *
- * @returns An error message if invalid, or undefined if valid.
- */
-export function describeTokenNameProblem(name) {
-    // Strip leading -- for validation (callers may pass with or without)
-    const ident = name.replace(/^--/, '');
-    if (!ident) {
-        return 'Token name must not be empty';
-    }
-    if (/\s/.test(ident)) {
-        return `Token name must not contain whitespace: "${name}"`;
-    }
-    // eslint-disable-next-line no-control-regex
-    if (/[\x00-\x1f\x7f]/.test(ident)) {
-        return `Token name must not contain control characters: "${name}"`;
-    }
-    if (ident.includes('*/') || ident.includes('/*')) {
-        // `/*` is the worse of the two by this function's own standard: an
-        // ident containing it opens an UNTERMINATED comment in tokens.css
-        // that swallows every following declaration.
-        return `Token name must not contain "/*" or "*/" (would break CSS comments): "${name}"`;
-    }
-    // Reject characters that would break CSS declaration syntax. Quotes are
-    // included: a quote character in an ident opens a CSS string that eats
-    // the rest of the declaration block.
-    if (/[{}();!'"]/.test(ident)) {
-        return `Token name contains characters that would corrupt CSS syntax: "${name}"`;
-    }
-    return undefined;
-}
-/**
- * Normalizes a CSS custom property token name.
- * Strips leading `--` if present, then always prepends `--`.
- * This allows users to pass either `--my-token` or `my-token`.
- *
- * @throws InvalidArgumentError if the resulting name is not a valid CSS custom property.
- */
-export function normalizeTokenName(name) {
-    const error = describeTokenNameProblem(name);
-    if (error) {
-        throw new InvalidArgumentError(error, 'tokenName');
-    }
-    const stripped = name.replace(/^--/, '');
-    return `--${stripped}`;
-}
-/**
- * Normalizes a patch display name against its category:
- * strips a trailing `.patch` and any redundant `NNN-<category>-` /
- * `<category>-` prefixes, case-insensitively and repeatedly, mirroring
- * the filename slug pipeline's require-the-category-token rule. A bare
- * leading number is never stripped, so names like `2-step-verification`
- * survive intact. Falls back to the `.patch`-stripped stem when the
- * strip would empty the name.
- */
-export function normalizePatchDisplayName(name, category) {
-    const stem = name.trim().replace(/\.patch$/i, '');
-    const escaped = escapeRegex(category);
-    const prefixes = [
-        new RegExp(`^\\d+[-_ ]+${escaped}[-_ ]+`, 'i'),
-        new RegExp(`^${escaped}[-_ ]+`, 'i'),
-    ];
-    let stripped = stem;
-    let changed = true;
-    while (changed) {
-        changed = false;
-        for (const prefix of prefixes) {
-            if (prefix.test(stripped)) {
-                stripped = stripped.replace(prefix, '');
-                changed = true;
-            }
-        }
-    }
-    return stripped.length > 0 ? stripped : stem;
-}
-/**
- * Validates a patch name.
- * @param name - The patch name to validate
- * @returns Error message if invalid, undefined if valid
- */
-export function describePatchNameProblem(name) {
-    if (!name.trim())
-        return 'Name is required';
-    if (name.length > 50)
-        return 'Name must be 50 characters or less';
-    if (!/^[a-zA-Z0-9\-_ ]+$/.test(name))
-        return 'Name can only contain letters, numbers, hyphens, underscores, and spaces';
-    return undefined;
-}