@hominis/fireforge 0.55.0 → 0.60.0

package/dist/src/types/config.js

@@ -1,15 +0,0 @@
-/** The built-in steps of `fireforge check`, in table order. */
-export const CHECK_BUILTIN_STEPS = [
-    'status',
-    'verify',
-    'lint',
-    'typecheck',
-    'furnace-validate',
-    'token-coverage',
-];
-/**
- * Build modes for mach.
- *
- * Derived from the list so the runtime allowlist cannot drift from the type.
- */
-export const BUILD_MODES = ['dev', 'debug', 'release'];

package/dist/src/types/furnace.d.ts

@@ -1,422 +0,0 @@
-/**
- * Component type classification.
- */
-export type ComponentType = 'stock' | 'override' | 'custom';
-/**
- * Override scope.
- */
-export type OverrideType = 'css-only' | 'full';
-/**
- * Info about a component discovered by scanning engine/.
- */
-export interface ScannedComponent {
-    /** Tag name (e.g., "moz-button") */
-    tagName: string;
-    /** Path relative to engine/ (e.g., "toolkit/content/widgets/moz-button") */
-    sourcePath: string;
-    /** Whether it has a .css file */
-    hasCSS: boolean;
-    /** Whether it has a .ftl localization file */
-    hasFTL: boolean;
-    /** Whether it's registered in customElements.js */
-    isRegistered: boolean;
-}
-/**
- * Metadata for an override component in the workspace.
- */
-export interface OverrideComponentConfig {
-    /** Override scope */
-    type: OverrideType;
-    /** Description of the override */
-    description: string;
-    /** Path in engine/ where the original lives */
-    basePath: string;
-    /** Firefox version this override was based on */
-    baseVersion: string;
-    /** Git commit SHA the override was based on. Older overrides may lack this field. */
-    baseCommit?: string;
-}
-/**
- * Metadata for a custom component in the workspace.
- */
-export interface CustomComponentConfig {
-    /** Description of the custom component */
-    description: string;
-    /** Target path in engine/ where this will be placed */
-    targetPath: string;
-    /** Whether to register in customElements.js */
-    register: boolean;
-    /**
-     * What the component is. `'element'` (the default when unset) is a custom
-     * element with its own tag. `'library'` is a base class + helpers module
-     * that defines no element of its own (e.g. a shared MozLitElement
-     * subclass other components extend): `furnace validate` skips the
-     * `no-custom-element-define` / `not-moz-lit-element` compatibility checks
-     * and the `missing-css` structural advisory for it, while headers, module
-     * shape, `relative-import`, and (when a `.css` exists) the CSS
-     * compatibility rules still apply. A library exports no element, so
-     * `kind: "library"` requires `register: false`. The combination with
-     * `register: true` is rejected at config parse time.
-     */
-    kind?: 'element' | 'library';
-    /** Whether this component uses Fluent l10n */
-    localized: boolean;
-    /** Stock component tag names composed internally by this component */
-    composes?: string[];
-    /**
-     * Opts the component out of the `no-keyboard-handler` accessibility check
-     * when it wraps a native-interactive inner element that is not tracked in
-     * `composes` (for example a hand-authored `<button>` or a non-stock
-     * `moz-*` widget). When `true`, the check is skipped even if the template
-     * appears to attach `@click` to synthetic markup.
-     *
-     * Leave unset for the default behavior: the validator still silences the
-     * check automatically when any entry in `composes` matches its native-
-     * interactive allowlist (e.g. `moz-button`, `moz-toggle`). This flag is
-     * only needed when `composes` does not capture the inner element.
-     *
-     * Operator-asserted: setting this to `true` does not re-check the
-     * component, so it can be used to silence genuine findings. Prefer adding
-     * the wrapped element to `composes` when that field applies.
-     */
-    keyboardCovered?: boolean;
-    /**
-     * Path of a pre-existing feature-scoped Fluent bundle this component
-     * participates in, in the same form used by `insertFTLIfNeeded` (for
-     * example `browser/mybrowser-dock.ftl`). When set:
-     *
-     *   - `furnace create --localized` does not scaffold a per-component
-     *     `.ftl` stub. The component shares the feature bundle.
-     *   - The generated `.mjs` calls `insertFTLIfNeeded("<sharedFtl>")` at
-     *     the shared path instead of the per-component one.
-     *   - `furnace validate`'s `missing-ftl` structural rule is skipped for
-     *     the component (there is no `<tag>.ftl` to require).
-     *   - `furnace apply` does not copy a per-component `.ftl` into the FTL
-     *     tree nor register a new entry in the locale `jar.mn`. The shared
-     *     file is owned by whoever authored the feature bundle.
-     *
-     * Requires `localized: true`. Mutually exclusive with the per-component
-     * `.ftl` scaffold. Does not auto-migrate previous per-component FTL
-     * state: flipping an existing component onto `sharedFtl` leaves the
-     * prior per-component entry in the engine tree and the locale `jar.mn`
-     * until explicitly cleaned up.
-     */
-    sharedFtl?: string;
-}
-/** A reviewed `furnace validate` finding (`furnace.json#validationExceptions[]`). */
-export interface FurnaceValidationException {
-    /** Component tag name the finding is reported on. */
-    component: string;
-    /** The finding's check name, as `furnace validate` prints it in brackets. */
-    check: string;
-    /**
-     * Narrows the exception to the findings on this element tag (a finding's
-     * `tags`): a `panel-item` menu row can be accepted without muting the
-     * check for every other element of the component.
-     */
-    tag?: string;
-    /**
-     * Narrows the exception to the findings in this module file of the
-     * component (a finding's `files`), by file name: a vendored bundle whose
-     * bytes are pinned can be accepted without muting the check for the
-     * authored modules beside it.
-     */
-    file?: string;
-    /** Why the finding is accepted. Required: the entry is the review record. */
-    reason: string;
-}
-/**
- * `furnace validate` checks that run only when `furnace.json#optInChecks`
- * names them. `icon-button-label`: an icon-only `<moz-button>` (an
- * `iconsrc` or an `icon` type, no `label` and no text content) carries
- * neither `data-l10n-id` nor `aria-label`.
- */
-export declare const FURNACE_OPT_IN_CHECKS: readonly ["icon-button-label"];
-/** One opt-in check name. */
-export type FurnaceOptInCheck = (typeof FURNACE_OPT_IN_CHECKS)[number];
-/**
- * The furnace.json schema.
- */
-export interface FurnaceConfig {
-    /** Schema version */
-    version: 1;
-    /** Prefix for custom component tag names (default: "moz-") */
-    componentPrefix: string;
-    /** Optional CSS custom property prefix for design tokens (e.g. "--mybrowser-") */
-    tokenPrefix?: string;
-    /** Custom properties allowed even though they don't match tokenPrefix (e.g. ["--background-color-box"]) */
-    tokenAllowlist?: string[];
-    /**
-     * CSS custom-property prefixes that identify upstream / platform
-     * variables the fork does not own. `token coverage` counts matches as
-     * `allowlisted` rather than `unknown` so a copied upstream baseline does
-     * not drag fork-owned coverage percentages down. Defaults to `['--moz-']`
-     * when unset. Pass an explicit empty array to count every prefix.
-     */
-    platformPrefixes?: string[];
-    /**
-     * Custom properties used as runtime state channels, written and read by
-     * the component itself (e.g. per-frame camera/tile positions) rather than
-     * consumed as design tokens. Listed names are exempt from the
-     * `token-prefix-violation` check even when they do not match `tokenPrefix`
-     * and are not in `tokenAllowlist`. Use this for cross-component runtime
-     * variables (e.g. set in JS, read in CSS of a child). Component-local
-     * variables that are both declared and consumed inside the same component's
-     * own CSS file are auto-exempted and do not need an entry here.
-     */
-    runtimeVariables?: string[];
-    /**
-     * Chrome documents scanned by the `missing-token-link` validator to confirm
-     * the tokens CSS file is `<link>`ed. Forks with multiple chrome host
-     * documents (e.g. `mybrowser.xhtml` beside the stock `browser.xhtml`) should
-     * list every document that may own the link. When omitted, defaults to
-     * `['browser/base/content/browser.xhtml']`, the upstream Firefox path.
-     */
-    tokenHostDocuments?: string[];
-    /**
-     * Stylesheets that load beside others in a document no queue link shows,
-     * for `token lint`: `{ "<glob>": ["<path or glob>", …] }`. A sheet the key
-     * matches may reference the tokens its partners declare.
-     */
-    tokenSiblingSheets?: Record<string, string[]>;
-    /**
-     * Override the default Fluent (.ftl) base path within the engine.
-     * Defaults to `toolkit/locales/en-US/toolkit/global` when not set.
-     */
-    ftlBasePath?: string;
-    /**
-     * Additional directories to scan for components (relative to engine root).
-     * Always includes `toolkit/content/widgets` by default.
-     */
-    scanPaths?: string[];
-    /**
-     * Project-relative path (or paths) to consumer-owned jsconfig/tsconfig
-     * files whose `compilerOptions.paths` entries for deployed component
-     * modules (`chrome://global/content/elements/<file>.mjs`) Furnace keeps in
-     * sync on deploy, each relative to its own directory. Only entries under
-     * that chrome prefix that map into `components/custom/` are managed.
-     * Everything else is preserved. Unset disables jsconfig maintenance.
-     */
-    typecheckJsconfig?: string | string[];
-    /**
-     * Project-relative `.d.ts` Furnace writes on deploy: an
-     * `HTMLElementTagNameMap` entry per registered custom component whose
-     * module defines an exported element class, typed through its deployed
-     * chrome URL. Unset writes nothing.
-     */
-    typecheckTagMap?: string;
-    /**
-     * Reviewed `furnace validate` findings. Each entry suppresses every
-     * finding of `check` on `component`, and `furnace validate` reports an
-     * entry that no longer matches anything as a stale-exception warning.
-     */
-    validationExceptions?: FurnaceValidationException[];
-    /**
-     * The fewest components a full `furnace validate` must judge. A run under
-     * it fails with `component-floor`, so a moved or emptied components tree
-     * cannot pass by validating nothing.
-     */
-    minComponents?: number;
-    /**
-     * Opt-in `furnace validate` checks (see {@link FURNACE_OPT_IN_CHECKS}).
-     * Unset runs only the default checks.
-     */
-    optInChecks?: FurnaceOptInCheck[];
-    /** Stock components tracked for preview */
-    stock: string[];
-    /** Override components */
-    overrides: Record<string, OverrideComponentConfig>;
-    /** Custom components */
-    custom: Record<string, CustomComponentConfig>;
-}
-/**
- * Operations that can leave a pending-repair marker when they fail to roll
- * back cleanly. The marker is consumed by `fireforge doctor`, which either
- * re-runs apply for engine-side failures or validates the current authoring
- * state before clearing authoring markers. The string is surfaced in doctor's
- * failure message verbatim, so new entries should be self-explanatory.
- */
-export declare const FURNACE_PENDING_REPAIR_OPERATIONS: readonly ["preview-teardown", "apply-rollback", "deploy-rollback", "remove-rollback", "create-rollback", "override-rollback", "scan-rollback", "rename-rollback", "refresh-rollback", "chrome-doc-rollback"];
-/**
- * Operations that can leave a pending-repair marker when they fail to roll
- * back cleanly. Derived from the list above so the runtime allowlist in
- * `furnace-config.ts` cannot drift from the union.
- */
-export type FurnacePendingRepairOperation = (typeof FURNACE_PENDING_REPAIR_OPERATIONS)[number];
-/**
- * Marker persisted into `.fireforge/furnace-state.json` when a furnace
- * mutation failed to roll back cleanly. Its presence tells the next
- * `fireforge doctor` run that the engine and workspace may have drifted
- * out-of-band from what the state file records.
- */
-export interface FurnacePendingRepair {
-    /** The operation that failed to clean up. Doctor uses it to route the fix. */
-    operation: FurnacePendingRepairOperation;
-    /** ISO timestamp of when the repair marker was written. */
-    timestamp: string;
-    /** Human-readable summary of the failure. Doctor shows it. */
-    reason: string;
-}
-/**
- * State tracking for apply operations (stored in .fireforge/furnace-state.json).
- */
-export interface FurnaceState {
-    /** ISO timestamp of last successful apply */
-    lastApply?: string;
-    /** Checksums of component files at last apply, keyed by relative path */
-    appliedChecksums?: Record<string, string>;
-    /**
-     * SHA-256 hashes of engine-side files written during the last apply, keyed
-     * by engine-relative path. Used by drift detection to avoid byte-comparing
-     * engine files against workspace sources when the cached hash still matches
-     * the on-disk content. Populated alongside `appliedChecksums` on successful
-     * apply.
-     */
-    engineChecksums?: Record<string, string>;
-    /**
-     * Set when a furnace mutation failed to roll back cleanly and the engine
-     * may be in an inconsistent state. Cleared by `fireforge doctor` after
-     * reconciliation. See {@link FurnacePendingRepair}.
-     */
-    pendingRepair?: FurnacePendingRepair;
-}
-/**
- * A registration-step error captured while applying a component.
- * In non-dry-run apply/deploy workflows, these trigger rollback of touched files.
- */
-export interface StepError {
-    step: string;
-    error: string;
-    /**
-     * Advisory step errors are reported as warnings and never trigger rollback
-     * or a non-zero exit. Used by the `.ftl` helpers, whose module contract is
-     * graceful degradation: a missing locale jar.mn on a fork without a locale
-     * package must not block a working `.mjs`/`.css` from shipping.
-     */
-    advisory?: boolean;
-}
-/**
- * Why `applyAllComponents` skipped a component, so a summary can say more
- * than "skipped". `already-current`: the source is unchanged since the last
- * recorded apply and the engine copy still matches it (fragment expansions
- * included), so there was nothing to write. The apply state is shared by
- * every session on the checkout, so the recorded apply may be another
- * session's, e.g. a peer's `test --build`.
- */
-export type ApplySkipKind = 'already-current';
-/**
- * Result of applying all components to the engine source tree.
- */
-export interface ApplyResult {
-    /** Components that were successfully applied */
-    applied: Array<{
-        name: string;
-        type: ComponentType;
-        filesAffected: string[];
-        /** Non-fatal registration step errors */
-        stepErrors?: StepError[];
-    }>;
-    /**
-     * Components that were skipped (e.g., no changes). `kind` names the
-     * reason for summaries; `reason` is the stable free-text form.
-     */
-    skipped: Array<{
-        name: string;
-        reason: string;
-        kind?: ApplySkipKind;
-    }>;
-    /** Components that failed to apply */
-    errors: Array<{
-        name: string;
-        error: string;
-    }>;
-    /**
-     * Set to true when the rollback journal was restored after a partial failure.
-     * When true, entries in `applied` reflect what was attempted, not what
-     * persisted. The engine has been restored to its pre-apply state.
-     */
-    rolledBack?: boolean;
-    /**
-     * Operator-facing warnings, printed by `logApplyResult`. Populated when
-     * apply overwrote a deployed, patch-owned file whose engine bytes
-     * differed from the component source, which is the case where a
-     * shipped engine-only fix is silently reverted by the copy.
-     */
-    warnings?: string[];
-}
-/**
- * An action that would be performed during a dry-run deploy.
- */
-export interface DryRunAction {
-    component: string;
-    action: 'copy' | 'expand-fragments' | 'register-ce' | 'register-jar' | 'copy-ftl' | 'undeploy-remove' | 'undeploy-restore' | 'unregister-ce' | 'unregister-jar';
-    source?: string;
-    target?: string;
-    description: string;
-}
-/**
- * Registration consistency status for a single component.
- */
-export interface RegistrationStatus {
-    sourceExists: boolean;
-    targetExists: boolean;
-    filesInSync: boolean;
-    jarMnCss: boolean;
-    jarMnMjs: boolean;
-    customElementsPresent: boolean;
-    customElementsCorrectBlock: boolean;
-    driftedFiles: string[];
-    missingTargetFiles: string[];
-}
-/**
- * Result of syncing Storybook story files.
- */
-export interface SyncResult {
-    /** Story files that were created */
-    created: string[];
-    /** Story files that were updated (regenerated) */
-    updated: string[];
-    /** Story files that were removed */
-    removed: string[];
-}
-/**
- * A single validation finding for a furnace component.
- */
-export interface ValidationIssue {
-    /** Component tag name */
-    component: string;
-    /** Severity: 'error' blocks apply, 'warning' is advisory */
-    severity: 'error' | 'warning';
-    /** Short machine-readable check name (e.g., "missing-mjs", "no-aria-role") */
-    check: string;
-    /** Human-readable description of the issue */
-    message: string;
-    /** Element tags the finding is about, when it is about particular elements. */
-    tags?: string[];
-    /** Component module files the finding is in (`hardcoded-text`), by file name. */
-    files?: string[];
-}
-/** Resolved test-harness selection for a `furnace create` run. */
-export type ResolvedTestStyle = 'mochikit' | 'browser-chrome' | 'xpcshell' | 'none';
-/**
- * The four paths and the name that every per-component apply, dry-run, FTL
- * and drift helper needs some subset of.
- *
- * Passing these positionally is unsafe: they are all `string`, so any
- * permutation typechecks against any other and a swap surfaces as a
- * wrong-directory read at runtime. Helpers take
- * `Pick<ComponentApplyContext, …>` of exactly the members they read, so a
- * caller is never asked to invent a value it does not have.
- */
-export interface ComponentApplyContext {
-    /** Project root, what registration consistency resolves against. */
-    root: string;
-    /** Firefox source directory the component deploys into. */
-    engineDir: string;
-    /** Component name as it appears in `furnace.json`. */
-    name: string;
-    /** Absolute path to the component's authoring directory. */
-    componentDir: string;
-    /** Engine-relative locale directory holding the component's `.ftl`. */
-    ftlDir: string;
-}

package/dist/src/types/furnace.js

@@ -1,26 +0,0 @@
-/**
- * `furnace validate` checks that run only when `furnace.json#optInChecks`
- * names them. `icon-button-label`: an icon-only `<moz-button>` (an
- * `iconsrc` or an `icon` type, no `label` and no text content) carries
- * neither `data-l10n-id` nor `aria-label`.
- */
-export const FURNACE_OPT_IN_CHECKS = ['icon-button-label'];
-/**
- * Operations that can leave a pending-repair marker when they fail to roll
- * back cleanly. The marker is consumed by `fireforge doctor`, which either
- * re-runs apply for engine-side failures or validates the current authoring
- * state before clearing authoring markers. The string is surfaced in doctor's
- * failure message verbatim, so new entries should be self-explanatory.
- */
-export const FURNACE_PENDING_REPAIR_OPERATIONS = [
-    'preview-teardown',
-    'apply-rollback',
-    'deploy-rollback',
-    'remove-rollback',
-    'create-rollback',
-    'override-rollback',
-    'scan-rollback',
-    'rename-rollback',
-    'refresh-rollback',
-    'chrome-doc-rollback',
-];

package/dist/src/types/index.d.ts

@@ -1,5 +0,0 @@
-/**
- * Re-exports all type definitions.
- */
-export type { BuildConfig, FireForgeConfig, FirefoxConfig, FirefoxProduct, PatchLintFileSizeThresholds, PatchLintFileSizeTier, PatchLintPatchSizeMetric, ProjectLicense, ProjectPaths, WireConfig, } from './config.js';
-export type { ApplyResult, ComponentType, CustomComponentConfig, DryRunAction, FurnaceConfig, FurnaceState, OverrideComponentConfig, OverrideType, StepError, ValidationIssue, } from './furnace.js';

package/dist/src/types/index.js

@@ -1,5 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Re-exports all type definitions.
- */
-export {};

package/dist/src/types/json.d.ts

@@ -1,22 +0,0 @@
-/**
- * Domain types for raw JSON documents (fireforge.json, furnace.json).
- *
- * FireForge reads and writes some documents in their raw, unvalidated
- * form. For example, `fireforge config --force` round-trips keys that
- * the validated `FireForgeConfig` schema would strip. These types give that
- * pipeline a concrete value contract: every value is JSON data, never a
- * function, class instance, symbol, or other non-serializable runtime value.
- */
-/**
- * Any value representable in a JSON document.
- */
-export type JsonValue = string | number | boolean | null | JsonValue[] | JsonObject;
-/**
- * A JSON object node. `undefined` is admitted as a property value (not a
- * `JsonValue`) so in-memory documents can be built field-by-field from
- * optional inputs. `JSON.stringify` drops such properties on write, exactly
- * like an absent key.
- */
-export interface JsonObject {
-    [key: string]: JsonValue | undefined;
-}

package/dist/src/types/json.js

@@ -1,11 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Domain types for raw JSON documents (fireforge.json, furnace.json).
- *
- * FireForge reads and writes some documents in their raw, unvalidated
- * form. For example, `fireforge config --force` round-trips keys that
- * the validated `FireForgeConfig` schema would strip. These types give that
- * pipeline a concrete value contract: every value is JSON data, never a
- * function, class instance, symbol, or other non-serializable runtime value.
- */
-export {};

package/dist/src/types/typecheck.d.ts

@@ -1,51 +0,0 @@
-/**
- * Types for the `fireforge typecheck` command.
- *
- * Kept separate from `PatchLintIssue` because the two flows model
- * different things: patch-lint issues are keyed on a stable `check`
- * rule ID (consumed by `lintIgnore`, severity gates, and the
- * cross-patch tagger), while typecheck issues carry a raw TypeScript
- * diagnostic code that should never enter the patch-lint vocabulary.
- * Conflating them would let `lintIgnore` accidentally suppress TS
- * errors and would force `PatchLintIssue` to grow line / column /
- * code fields that have no meaning for patch-hygiene rules.
- */
-/**
- * A single diagnostic produced by `runTypecheck` for one source file.
- */
-export interface TypecheckIssue {
-    /** Absolute path to the source file the diagnostic originated in. */
-    file: string;
-    /** 1-based line number. */
-    line: number;
-    /** 1-based column number. */
-    column: number;
-    /** Raw TypeScript diagnostic code (e.g. 2322 for a type mismatch). */
-    code: number;
-    /**
-     * Severity bucket. TS also reports `Suggestion` and `Message`
-     * categories, but `runTypecheck` collapses both into `'warning'` so
-     * the CLI has only two visible levels.
-     */
-    category: 'error' | 'warning';
-    /** Human-readable message text (already flattened from chains). */
-    message: string;
-    /**
-     * Project-relative path of the originating jsconfig.json. Useful
-     * when typecheck.projects names multiple projects and the operator
-     * needs to know which one fired.
-     */
-    project: string;
-}
-/**
- * Per-project typecheck output. One entry per `typecheck.projects`
- * jsconfig path, in the order the projects were declared.
- */
-export interface TypecheckProjectResult {
-    /** Project-relative path of the jsconfig.json. */
-    project: string;
-    /** All issues from this project (errors + warnings). */
-    issues: TypecheckIssue[];
-    /** How many root files the program was built against (excludes the synthetic shim). */
-    filesChecked: number;
-}

package/dist/src/types/typecheck.js

@@ -1,14 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Types for the `fireforge typecheck` command.
- *
- * Kept separate from `PatchLintIssue` because the two flows model
- * different things: patch-lint issues are keyed on a stable `check`
- * rule ID (consumed by `lintIgnore`, severity gates, and the
- * cross-patch tagger), while typecheck issues carry a raw TypeScript
- * diagnostic code that should never enter the patch-lint vocabulary.
- * Conflating them would let `lintIgnore` accidentally suppress TS
- * errors and would force `PatchLintIssue` to grow line / column /
- * code fields that have no meaning for patch-hygiene rules.
- */
-export {};

package/dist/src/utils/assert.d.ts

@@ -1,34 +0,0 @@
-/**
- * A failure description, or a thunk producing one.
- *
- * The thunk form exists so a hot call site pays nothing on the passing
- * path: `assert(ok, () => \`bad state: ${JSON.stringify(x)}\`)` builds
- * the string only when the assertion actually fails, where a plain
- * template literal would build it on every call.
- */
-type AssertionMessage = string | (() => string);
-/**
- * Asserts that an internal invariant holds.
- *
- * @param condition - The invariant. Falsy means it was violated.
- * @param message - What was supposed to be true, phrased as the invariant
- *   rather than the symptom (e.g. "rollback journal registered before
- *   first mutation", not "journal is undefined"). Pass a thunk on a hot
- *   path.
- * @throws {@link InternalInvariantError} when `condition` is falsy.
- */
-export declare function assert(condition: unknown, message: AssertionMessage): asserts condition;
-/**
- * Returns a value that must be present, throwing if it is not.
- *
- * Checks and returns in one step, so an indexed read can be asserted inline
- * (`push({ content: expectDefined(lines[k], …) })`) without first binding
- * it to a local.
- *
- * @param value - The value that should be present
- * @param message - What was supposed to be present, and why
- * @returns `value`, narrowed to exclude `null` and `undefined`
- * @throws {@link InternalInvariantError} when `value` is `null` or `undefined`.
- */
-export declare function expectDefined<T>(value: T, message: AssertionMessage): NonNullable<T>;
-export {};

package/dist/src/utils/assert.js

@@ -1,61 +0,0 @@
-// SPDX-License-Identifier: EUPL-1.2
-/**
- * Runtime assertions for FireForge's own internal invariants.
- *
- * These check state that FireForge itself established: a journal was
- * registered before the first mutation, a lock is held before a write,
- * manifest ordering is contiguous after a renumber. They are not input
- * validation. Anything derived from user input, the filesystem, or a
- * subprocess belongs in a typed error from `src/errors/` with a
- * `userMessage` that tells the operator what to do. An assertion failure
- * says the opposite: nothing the operator could have done would have
- * prevented it.
- *
- * Shared helpers provide consistent classification and TypeScript narrowing,
- * and keep expensive failure descriptions lazy on successful paths.
- *
- * This module is a leaf: it imports the error class and nothing else, per
- * the dependency-direction note in `src/utils/errors.ts`.
- */
-import { InternalInvariantError } from '../errors/base.js';
-/**
- * Resolves an {@link AssertionMessage} at failure time.
- * @param message - Literal description, or a thunk producing one
- * @returns The description text
- */
-function resolveMessage(message) {
-    return typeof message === 'function' ? message() : message;
-}
-/**
- * Asserts that an internal invariant holds.
- *
- * @param condition - The invariant. Falsy means it was violated.
- * @param message - What was supposed to be true, phrased as the invariant
- *   rather than the symptom (e.g. "rollback journal registered before
- *   first mutation", not "journal is undefined"). Pass a thunk on a hot
- *   path.
- * @throws {@link InternalInvariantError} when `condition` is falsy.
- */
-export function assert(condition, message) {
-    if (!condition) {
-        throw new InternalInvariantError(resolveMessage(message));
-    }
-}
-/**
- * Returns a value that must be present, throwing if it is not.
- *
- * Checks and returns in one step, so an indexed read can be asserted inline
- * (`push({ content: expectDefined(lines[k], …) })`) without first binding
- * it to a local.
- *
- * @param value - The value that should be present
- * @param message - What was supposed to be present, and why
- * @returns `value`, narrowed to exclude `null` and `undefined`
- * @throws {@link InternalInvariantError} when `value` is `null` or `undefined`.
- */
-export function expectDefined(value, message) {
-    if (value === null || value === undefined) {
-        throw new InternalInvariantError(resolveMessage(message));
-    }
-    return value;
-}