solve-engine 1.0.2 → 1.1.1

package/dist/testing.d.cts

@@ -0,0 +1,271 @@
+import { I as IEnginePackage, E as ExpressionEngine } from './PackageRegistry-BHWJP83F.cjs';
+import { V as Value } from './Value-BUi1RA3S.cjs';
+import { E as EngineError } from './EngineError-B61GS1jp.cjs';
+import { C as CompatibilityReport } from './PackageCompatibility-B-7rK1TD.cjs';
+import './Parselet-BHcgK9S7.cjs';
+import './BytecodeBuilder-Bp9xeTmX.cjs';
+import './Token-B1hdkedD.cjs';
+import './pipeline-CtfJtPQc.cjs';
+import './variables.cjs';
+import './Lexer-BOs7euZe.cjs';
+import './resolvers.cjs';
+import '@tanstack/query-core';
+import './TokenNormalizer-DRc1Js1V.cjs';
+import './ScopeManager-8vf02dwj.cjs';
+import './Configuration-C9W8tJv_.cjs';
+
+/**
+ * A test kit for package authors, the supported way to test a package by the
+ * expressions it enables rather than by the opcodes it emits.
+ *
+ * Before this entry point a package author had two options, both bad: reach
+ * into engine internals, or assert on whatever bytecode a parselet happened to
+ * emit. The first is unstable across engine versions, the second pins the
+ * implementation instead of the behaviour, so a refactor that keeps every
+ * answer correct still breaks the tests. This module is a thin, dependency-free
+ * layer over the same public surface a host uses: it constructs an
+ * {@link ExpressionEngine} with the given packages and evaluates strings.
+ *
+ * It speaks in expressions. {@link expectExpression} evaluates a string and
+ * asserts on the result or the failure code; {@link expectPackage} asserts on
+ * the three mistakes a package actually makes (shadowing prose, colliding with
+ * another package's vocabulary, and declaring an `engineVersion` range that the
+ * running engine does not satisfy).
+ *
+ * Framework-agnostic on purpose. Nothing here imports jest, vitest or any
+ * runner: an assertion that fails throws an {@link ExpectationError}, and one
+ * that passes returns, so the kit drops into whatever runner the author already
+ * has (or into a plain script, or `node:assert`). Runtime dependency-free and
+ * side-effect free, so `solve-engine/testing` stays honest under the package's
+ * `"sideEffects": false` contract.
+ *
+ * @example
+ * ```ts
+ * import { createTestEngine, expectExpression } from "solve-engine/testing";
+ *
+ * const engine = createTestEngine([myPackage]);
+ * expectExpression(engine, "2 gp + 3 gp").toEqual(5, "gp");
+ * expectExpression(engine, "gp").toFailWith("UNDEFINED_VARIABLE");
+ * ```
+ */
+
+/**
+ * The failure a matcher throws when an expectation is not met.
+ *
+ * A dedicated `Error` subclass rather than a bare `throw new Error`, so a
+ * caller (or a reporter) can tell a kit assertion failure apart from an
+ * unrelated exception with `instanceof`, and so the structured `expected` and
+ * `actual` fields survive alongside the human-readable message. This is NOT an
+ * {@link EngineError}: that type classifies pipeline-stage failures inside the
+ * engine, whereas this classifies a test-assertion mismatch, a different
+ * concern that would be miscategorised under any of `EngineError`'s categories.
+ */
+declare class ExpectationError extends Error {
+    /** A short, machine-readable label for which expectation failed. */
+    readonly code: string;
+    /** What the matcher was told to expect, in plain words. */
+    readonly expected?: string;
+    /** What it found instead. */
+    readonly actual?: string;
+    constructor(init: {
+        code: string;
+        message: string;
+        expected?: string;
+        actual?: string;
+    });
+}
+/** Options for {@link createTestEngine}. */
+interface TestEngineOptions {
+    /** Locale passed to the engine. Defaults to `"en"`. */
+    locale?: string;
+    /**
+     * Whether to load the engine's built-in packages (arithmetic, units, dates,
+     * and the rest) before the packages under test. Defaults to `true`, because
+     * almost every package builds on arithmetic and most authors want a
+     * realistic engine. Set `false` to test a package in isolation.
+     */
+    includeBuiltins?: boolean;
+}
+/**
+ * Build an {@link ExpressionEngine} loaded with the packages under test.
+ *
+ * The built-in packages load first (unless {@link TestEngineOptions.includeBuiltins}
+ * is `false`), then each package in `packages` is registered in order, exactly
+ * as a host would. Registration is honest: a package whose declared
+ * `engineVersion` the running engine does not satisfy, or whose lexer keyword
+ * collides with a built-in, throws here rather than being swallowed. That is
+ * deliberately different from passing packages straight to the
+ * `ExpressionEngine` constructor, which contains a bad package by logging and
+ * continuing, useful in production, wrong for a test that needs to know the
+ * package it is testing actually loaded.
+ *
+ * Call {@link ExpressionEngine.clear} when a test is finished with the engine
+ * if the test creates many, see the engine's own lifecycle note.
+ *
+ * @example
+ * ```ts
+ * const engine = createTestEngine([myPackage]);
+ * const engineOnly = createTestEngine([myPackage], { includeBuiltins: false });
+ * ```
+ */
+declare function createTestEngine(packages?: IEnginePackage[], options?: TestEngineOptions): ExpressionEngine;
+/**
+ * The normalised outcome of evaluating one expression, computed once when
+ * {@link expectExpression} runs and read by every matcher on the result.
+ *
+ * The engine surfaces a failure two different ways, and a package author should
+ * not have to know which: a parse/eval error is THROWN as an
+ * {@link EngineError} (with a `.code`), while a plugin-raised error is RETURNED
+ * as a {@link Value} of {@link ValueType.Error} (its `value` is the code, its
+ * `unit` is the message). Both collapse to the `"error"` status here. A value
+ * still resolving asynchronously is its own `"pending"` status, since the kit
+ * evaluates synchronously and cannot report a final number for it.
+ */
+type Outcome = {
+    status: "value";
+    value: Value;
+} | {
+    status: "pending";
+    value: Value;
+} | {
+    status: "error";
+    code: string;
+    message: string;
+    source: EngineError | Value;
+};
+/**
+ * Assertions about the result of one evaluated expression, returned by
+ * {@link expectExpression}. Every matcher returns `this`, so assertions chain,
+ * and throws an {@link ExpectationError} when it fails.
+ */
+declare class ExpressionAssertion {
+    private readonly expression;
+    private readonly outcome;
+    constructor(expression: string, outcome: Outcome);
+    /** The raw resolved {@link Value}, for an assertion the matchers do not cover. Throws if the expression failed. */
+    get value(): Value;
+    /**
+     * Assert the expression evaluated to a value (not an error, not a pending
+     * async result). Says nothing about what the value is.
+     */
+    toEvaluate(): this;
+    /**
+     * Assert the expression evaluated to `expected`, and, when `unit` is given,
+     * that the result carries exactly that unit. A number compares against the
+     * value's numeric magnitude within a small floating-point tolerance; a
+     * string compares against the value's own string; a boolean against its
+     * boolean reading. Omitting `unit` leaves the unit unchecked, so
+     * `toEqual(5)` passes for both `5` and `5 gp`.
+     */
+    toEqual(expected: number | string | boolean, unit?: string): this;
+    /** Assert the expression failed (a thrown engine error or a plugin-raised error value). Says nothing about the code. */
+    toBeError(): this;
+    /**
+     * Assert the expression failed with exactly `code`, the error catalog code
+     * (e.g. `"UNDEFINED_VARIABLE"`, or a package's own code). Reports the code
+     * it actually got when they differ, so a near-miss is obvious.
+     */
+    toFailWith(code: string): this;
+    /**
+     * Assert the expression returned a value still resolving asynchronously.
+     * The kit evaluates synchronously, so a package whose result comes from an
+     * async resolver reports pending on first evaluation, this is how a test
+     * confirms the async path was taken without resolving it.
+     */
+    toBePending(): this;
+}
+/**
+ * Evaluate `expression` on `engine` and return an assertion object.
+ *
+ * The expression is evaluated once, immediately, and every matcher reads that
+ * one outcome, so calling several matchers on the same result does not
+ * re-evaluate.
+ *
+ * @example
+ * ```ts
+ * expectExpression(engine, "2 gp + 3 gp").toEqual(5, "gp");
+ * expectExpression(engine, "gp").toFailWith("UNDEFINED_VARIABLE");
+ * ```
+ */
+declare function expectExpression(engine: ExpressionEngine, expression: string): ExpressionAssertion;
+/**
+ * A modest set of everyday English words a package's keywords should not claim.
+ *
+ * A starting point for {@link PackageAssertion.notToShadow}, not an exhaustive
+ * dictionary: it leans on the function words and common nouns/verbs a package
+ * is most tempted to grab as a trigger (`price`, `of`, `per`, `sum`, `total`).
+ * Pass your own list to check against the specific prose your package sits in.
+ */
+declare const COMMON_PROSE_WORDS: readonly string[];
+/** How strict {@link PackageAssertion.notToCollideWith} is about the conflicts it will accept. */
+type CollisionStrictness = "error" | "warning" | "info";
+/** One shadowed word found by {@link PackageAssertion.notToShadow}: the prose word and how the package claims it. */
+interface ShadowedWord {
+    /** The prose word the package claims. */
+    word: string;
+    /** Which descriptor field claims it. */
+    via: "keyword" | "unit" | "operator" | "phrase";
+    /** The token type the word becomes, when the field maps to one. */
+    tokenType?: string;
+}
+/**
+ * Assertions about a package's declared descriptor, returned by
+ * {@link expectPackage}. These catch the three mistakes the issue calls out,
+ * before the package is ever registered. Every matcher returns `this` and
+ * throws an {@link ExpectationError} when it fails.
+ */
+declare class PackageAssertion {
+    private readonly pkg;
+    constructor(pkg: IEnginePackage);
+    /**
+     * Assert none of the package's claimed words shadow a prose word.
+     *
+     * A trigger word that is also an ordinary word turns a line of prose into
+     * arithmetic, the single most common package mistake and the subject of the
+     * trigger-words guide. This checks the words the package declares
+     * (lexer keywords, units, operators, and single-word phrases) against
+     * `words` (defaulting to {@link COMMON_PROSE_WORDS}), case-insensitively.
+     *
+     * @returns the shadowed words, empty when the package is clean, for a test
+     * that wants to inspect rather than assert.
+     */
+    notToShadow(words?: readonly string[]): ShadowedWord[];
+    /**
+     * Assert the package does not collide with any of `others` in a way that
+     * would silently break one of them (two packages claiming the same lexer
+     * keyword, plugin-function index, async-resolver namespace, and so on).
+     *
+     * `strictness` sets which severities fail the assertion: `"error"` (the
+     * default) fails only on the collisions that always break something,
+     * `"warning"` also fails on the ones that silently pick a winner, `"info"`
+     * fails on cosmetic overlaps too.
+     *
+     * @returns the full compatibility report, so a test can inspect every
+     * conflict, including ones below the strictness threshold.
+     */
+    notToCollideWith(others: IEnginePackage[], strictness?: CollisionStrictness): CompatibilityReport;
+    /**
+     * Assert the package's declared `engineVersion` range is satisfied by the
+     * running engine (or by `engineVersion` when given).
+     *
+     * A package that declares a range and never checks it resolves is the third
+     * mistake the issue names: it looks fine until the one engine version it
+     * cannot run against, where the range either fails to match or turns out to
+     * be a malformed string. A package with no declared range passes (no
+     * constraint is always compatible).
+     */
+    toDeclareCompatibleEngineVersion(engineVersion?: string): this;
+}
+/**
+ * Begin an assertion about a package's declared descriptor.
+ *
+ * @example
+ * ```ts
+ * expectPackage(myPackage).notToShadow(["price", "in", "of"]);
+ * expectPackage(myPackage).notToCollideWith(BUILTIN_PACKAGES);
+ * expectPackage(myPackage).toDeclareCompatibleEngineVersion();
+ * ```
+ */
+declare function expectPackage(pkg: IEnginePackage): PackageAssertion;
+
+export { COMMON_PROSE_WORDS, type CollisionStrictness, ExpectationError, ExpressionAssertion, PackageAssertion, type ShadowedWord, type TestEngineOptions, createTestEngine, expectExpression, expectPackage };

package/dist/testing.d.ts

@@ -0,0 +1,271 @@
+import { I as IEnginePackage, E as ExpressionEngine } from './PackageRegistry-_8rDlvxI.js';
+import { V as Value } from './Value-BUi1RA3S.js';
+import { E as EngineError } from './EngineError-B61GS1jp.js';
+import { C as CompatibilityReport } from './PackageCompatibility-Dh59eF-X.js';
+import './Parselet-BBT8riYh.js';
+import './BytecodeBuilder-Bp9xeTmX.js';
+import './Token-B1hdkedD.js';
+import './pipeline-DCd5M6Gk.js';
+import './variables.js';
+import './Lexer-CSI_lwbW.js';
+import './resolvers.js';
+import '@tanstack/query-core';
+import './TokenNormalizer-C6VzZgHa.js';
+import './ScopeManager-CxA24W5n.js';
+import './Configuration-C9W8tJv_.js';
+
+/**
+ * A test kit for package authors, the supported way to test a package by the
+ * expressions it enables rather than by the opcodes it emits.
+ *
+ * Before this entry point a package author had two options, both bad: reach
+ * into engine internals, or assert on whatever bytecode a parselet happened to
+ * emit. The first is unstable across engine versions, the second pins the
+ * implementation instead of the behaviour, so a refactor that keeps every
+ * answer correct still breaks the tests. This module is a thin, dependency-free
+ * layer over the same public surface a host uses: it constructs an
+ * {@link ExpressionEngine} with the given packages and evaluates strings.
+ *
+ * It speaks in expressions. {@link expectExpression} evaluates a string and
+ * asserts on the result or the failure code; {@link expectPackage} asserts on
+ * the three mistakes a package actually makes (shadowing prose, colliding with
+ * another package's vocabulary, and declaring an `engineVersion` range that the
+ * running engine does not satisfy).
+ *
+ * Framework-agnostic on purpose. Nothing here imports jest, vitest or any
+ * runner: an assertion that fails throws an {@link ExpectationError}, and one
+ * that passes returns, so the kit drops into whatever runner the author already
+ * has (or into a plain script, or `node:assert`). Runtime dependency-free and
+ * side-effect free, so `solve-engine/testing` stays honest under the package's
+ * `"sideEffects": false` contract.
+ *
+ * @example
+ * ```ts
+ * import { createTestEngine, expectExpression } from "solve-engine/testing";
+ *
+ * const engine = createTestEngine([myPackage]);
+ * expectExpression(engine, "2 gp + 3 gp").toEqual(5, "gp");
+ * expectExpression(engine, "gp").toFailWith("UNDEFINED_VARIABLE");
+ * ```
+ */
+
+/**
+ * The failure a matcher throws when an expectation is not met.
+ *
+ * A dedicated `Error` subclass rather than a bare `throw new Error`, so a
+ * caller (or a reporter) can tell a kit assertion failure apart from an
+ * unrelated exception with `instanceof`, and so the structured `expected` and
+ * `actual` fields survive alongside the human-readable message. This is NOT an
+ * {@link EngineError}: that type classifies pipeline-stage failures inside the
+ * engine, whereas this classifies a test-assertion mismatch, a different
+ * concern that would be miscategorised under any of `EngineError`'s categories.
+ */
+declare class ExpectationError extends Error {
+    /** A short, machine-readable label for which expectation failed. */
+    readonly code: string;
+    /** What the matcher was told to expect, in plain words. */
+    readonly expected?: string;
+    /** What it found instead. */
+    readonly actual?: string;
+    constructor(init: {
+        code: string;
+        message: string;
+        expected?: string;
+        actual?: string;
+    });
+}
+/** Options for {@link createTestEngine}. */
+interface TestEngineOptions {
+    /** Locale passed to the engine. Defaults to `"en"`. */
+    locale?: string;
+    /**
+     * Whether to load the engine's built-in packages (arithmetic, units, dates,
+     * and the rest) before the packages under test. Defaults to `true`, because
+     * almost every package builds on arithmetic and most authors want a
+     * realistic engine. Set `false` to test a package in isolation.
+     */
+    includeBuiltins?: boolean;
+}
+/**
+ * Build an {@link ExpressionEngine} loaded with the packages under test.
+ *
+ * The built-in packages load first (unless {@link TestEngineOptions.includeBuiltins}
+ * is `false`), then each package in `packages` is registered in order, exactly
+ * as a host would. Registration is honest: a package whose declared
+ * `engineVersion` the running engine does not satisfy, or whose lexer keyword
+ * collides with a built-in, throws here rather than being swallowed. That is
+ * deliberately different from passing packages straight to the
+ * `ExpressionEngine` constructor, which contains a bad package by logging and
+ * continuing, useful in production, wrong for a test that needs to know the
+ * package it is testing actually loaded.
+ *
+ * Call {@link ExpressionEngine.clear} when a test is finished with the engine
+ * if the test creates many, see the engine's own lifecycle note.
+ *
+ * @example
+ * ```ts
+ * const engine = createTestEngine([myPackage]);
+ * const engineOnly = createTestEngine([myPackage], { includeBuiltins: false });
+ * ```
+ */
+declare function createTestEngine(packages?: IEnginePackage[], options?: TestEngineOptions): ExpressionEngine;
+/**
+ * The normalised outcome of evaluating one expression, computed once when
+ * {@link expectExpression} runs and read by every matcher on the result.
+ *
+ * The engine surfaces a failure two different ways, and a package author should
+ * not have to know which: a parse/eval error is THROWN as an
+ * {@link EngineError} (with a `.code`), while a plugin-raised error is RETURNED
+ * as a {@link Value} of {@link ValueType.Error} (its `value` is the code, its
+ * `unit` is the message). Both collapse to the `"error"` status here. A value
+ * still resolving asynchronously is its own `"pending"` status, since the kit
+ * evaluates synchronously and cannot report a final number for it.
+ */
+type Outcome = {
+    status: "value";
+    value: Value;
+} | {
+    status: "pending";
+    value: Value;
+} | {
+    status: "error";
+    code: string;
+    message: string;
+    source: EngineError | Value;
+};
+/**
+ * Assertions about the result of one evaluated expression, returned by
+ * {@link expectExpression}. Every matcher returns `this`, so assertions chain,
+ * and throws an {@link ExpectationError} when it fails.
+ */
+declare class ExpressionAssertion {
+    private readonly expression;
+    private readonly outcome;
+    constructor(expression: string, outcome: Outcome);
+    /** The raw resolved {@link Value}, for an assertion the matchers do not cover. Throws if the expression failed. */
+    get value(): Value;
+    /**
+     * Assert the expression evaluated to a value (not an error, not a pending
+     * async result). Says nothing about what the value is.
+     */
+    toEvaluate(): this;
+    /**
+     * Assert the expression evaluated to `expected`, and, when `unit` is given,
+     * that the result carries exactly that unit. A number compares against the
+     * value's numeric magnitude within a small floating-point tolerance; a
+     * string compares against the value's own string; a boolean against its
+     * boolean reading. Omitting `unit` leaves the unit unchecked, so
+     * `toEqual(5)` passes for both `5` and `5 gp`.
+     */
+    toEqual(expected: number | string | boolean, unit?: string): this;
+    /** Assert the expression failed (a thrown engine error or a plugin-raised error value). Says nothing about the code. */
+    toBeError(): this;
+    /**
+     * Assert the expression failed with exactly `code`, the error catalog code
+     * (e.g. `"UNDEFINED_VARIABLE"`, or a package's own code). Reports the code
+     * it actually got when they differ, so a near-miss is obvious.
+     */
+    toFailWith(code: string): this;
+    /**
+     * Assert the expression returned a value still resolving asynchronously.
+     * The kit evaluates synchronously, so a package whose result comes from an
+     * async resolver reports pending on first evaluation, this is how a test
+     * confirms the async path was taken without resolving it.
+     */
+    toBePending(): this;
+}
+/**
+ * Evaluate `expression` on `engine` and return an assertion object.
+ *
+ * The expression is evaluated once, immediately, and every matcher reads that
+ * one outcome, so calling several matchers on the same result does not
+ * re-evaluate.
+ *
+ * @example
+ * ```ts
+ * expectExpression(engine, "2 gp + 3 gp").toEqual(5, "gp");
+ * expectExpression(engine, "gp").toFailWith("UNDEFINED_VARIABLE");
+ * ```
+ */
+declare function expectExpression(engine: ExpressionEngine, expression: string): ExpressionAssertion;
+/**
+ * A modest set of everyday English words a package's keywords should not claim.
+ *
+ * A starting point for {@link PackageAssertion.notToShadow}, not an exhaustive
+ * dictionary: it leans on the function words and common nouns/verbs a package
+ * is most tempted to grab as a trigger (`price`, `of`, `per`, `sum`, `total`).
+ * Pass your own list to check against the specific prose your package sits in.
+ */
+declare const COMMON_PROSE_WORDS: readonly string[];
+/** How strict {@link PackageAssertion.notToCollideWith} is about the conflicts it will accept. */
+type CollisionStrictness = "error" | "warning" | "info";
+/** One shadowed word found by {@link PackageAssertion.notToShadow}: the prose word and how the package claims it. */
+interface ShadowedWord {
+    /** The prose word the package claims. */
+    word: string;
+    /** Which descriptor field claims it. */
+    via: "keyword" | "unit" | "operator" | "phrase";
+    /** The token type the word becomes, when the field maps to one. */
+    tokenType?: string;
+}
+/**
+ * Assertions about a package's declared descriptor, returned by
+ * {@link expectPackage}. These catch the three mistakes the issue calls out,
+ * before the package is ever registered. Every matcher returns `this` and
+ * throws an {@link ExpectationError} when it fails.
+ */
+declare class PackageAssertion {
+    private readonly pkg;
+    constructor(pkg: IEnginePackage);
+    /**
+     * Assert none of the package's claimed words shadow a prose word.
+     *
+     * A trigger word that is also an ordinary word turns a line of prose into
+     * arithmetic, the single most common package mistake and the subject of the
+     * trigger-words guide. This checks the words the package declares
+     * (lexer keywords, units, operators, and single-word phrases) against
+     * `words` (defaulting to {@link COMMON_PROSE_WORDS}), case-insensitively.
+     *
+     * @returns the shadowed words, empty when the package is clean, for a test
+     * that wants to inspect rather than assert.
+     */
+    notToShadow(words?: readonly string[]): ShadowedWord[];
+    /**
+     * Assert the package does not collide with any of `others` in a way that
+     * would silently break one of them (two packages claiming the same lexer
+     * keyword, plugin-function index, async-resolver namespace, and so on).
+     *
+     * `strictness` sets which severities fail the assertion: `"error"` (the
+     * default) fails only on the collisions that always break something,
+     * `"warning"` also fails on the ones that silently pick a winner, `"info"`
+     * fails on cosmetic overlaps too.
+     *
+     * @returns the full compatibility report, so a test can inspect every
+     * conflict, including ones below the strictness threshold.
+     */
+    notToCollideWith(others: IEnginePackage[], strictness?: CollisionStrictness): CompatibilityReport;
+    /**
+     * Assert the package's declared `engineVersion` range is satisfied by the
+     * running engine (or by `engineVersion` when given).
+     *
+     * A package that declares a range and never checks it resolves is the third
+     * mistake the issue names: it looks fine until the one engine version it
+     * cannot run against, where the range either fails to match or turns out to
+     * be a malformed string. A package with no declared range passes (no
+     * constraint is always compatible).
+     */
+    toDeclareCompatibleEngineVersion(engineVersion?: string): this;
+}
+/**
+ * Begin an assertion about a package's declared descriptor.
+ *
+ * @example
+ * ```ts
+ * expectPackage(myPackage).notToShadow(["price", "in", "of"]);
+ * expectPackage(myPackage).notToCollideWith(BUILTIN_PACKAGES);
+ * expectPackage(myPackage).toDeclareCompatibleEngineVersion();
+ * ```
+ */
+declare function expectPackage(pkg: IEnginePackage): PackageAssertion;
+
+export { COMMON_PROSE_WORDS, type CollisionStrictness, ExpectationError, ExpressionAssertion, PackageAssertion, type ShadowedWord, type TestEngineOptions, createTestEngine, expectExpression, expectPackage };