solve-engine 2.24.0 → 2.26.0

package/dist/{Lexer-CCHFDcgP.d.cts → Lexer-DqtnZMC5.d.ts}

@@ -1,4 +1,5 @@
-import { T as Token } from './Token-CbP_OutD.cjs';
+import { T as Token } from './Token-D8f7yaz1.js';
+import { E as EngineError } from './EngineError-C-kBwYlN.js';
 
 /** Trie node for multi-word phrase matching. */
 interface PhraseNode {
@@ -101,6 +102,14 @@ interface ScanLineResult {
     tokens: Token[];
     /** Inline solve spans found in this line (empty if none). */
     inlineSolves: InlineSolveSpan[];
+    /**
+     * The structured error the tokeniser raised on this line, if it raised one
+     * (an unterminated string literal is the one it can raise today). The line
+     * carries no tokens then, and the rest of the document is unaffected: a
+     * half-typed quote used to escape {@link ExpressionLexer.scanDocument} as
+     * a throw and take every other line's result down with it.
+     */
+    error?: EngineError;
 }
 /**
  * A token, as the lexer produces it.
@@ -120,9 +129,19 @@ declare class LexerToken implements Token {
     col: number;
     /** See {@link Token.sourceEnd}. Set only on normalizer-fused tokens. */
     sourceEnd?: number | undefined;
+    /** See {@link Token.fault}. Set only on a fused token standing for a run the engine refuses to read. */
+    fault?: {
+        readonly code: string;
+        readonly message: string;
+    } | undefined;
     constructor(type: string, typeId: number, value: string, text: string, offset: number, lineBreaks: number, line: number, col: number, 
     /** See {@link Token.sourceEnd}. Set only on normalizer-fused tokens. */
-    sourceEnd?: number | undefined);
+    sourceEnd?: number | undefined, 
+    /** See {@link Token.fault}. Set only on a fused token standing for a run the engine refuses to read. */
+    fault?: {
+        readonly code: string;
+        readonly message: string;
+    } | undefined);
 }
 /**
  * Plugin interface for extending the ExpressionLexer with custom tokens.
@@ -208,16 +227,6 @@ interface LexerVocabulary {
  */
 declare class ExpressionLexer {
     private static readonly CHAR_CLASS;
-    /**
-     * Configured TokenLookup from TokenClassRegistry. When set, replaces
-     * the internal keyword map and unit set with registry-built equivalents.
-     * Enables data-driven keyword/unit registration across locale keywords,
-     * provider keywords, and plugins.
-     *
-     * Set at construction time via the constructor parameter. Plugin-registered
-     * keywords/units (via registerVocabulary()) are checked alongside
-     * the configuredLookup, neither source is bypassed.
-     */ private configuredLookup;
     private input;
     private pos;
     private len;
@@ -227,7 +236,16 @@ declare class ExpressionLexer {
     private keywordMap;
     private mergedKeywords;
     private mergedUnits;
-    private pluginKeywordMap;
+    /**
+     * Who registered each plugin keyword, unit and two-character operator, in
+     * registration order. Two packages may claim the same word (the
+     * compatibility index warns, and the last registered wins, as before); the
+     * owner lists make unregistration exact, so removing one package hands the
+     * word back to the other rather than deleting it for both.
+     */
+    private pluginKeywordOwners;
+    private pluginUnitOwners;
+    private pluginOperatorOwners;
     private pluginOperators;
     private pluginUnits;
     private hasPluginOps;
@@ -235,7 +253,7 @@ declare class ExpressionLexer {
     private locale;
     /**
      * Inline solve spans collected during the most recent tokenization pass.
-     * Populated by [Symbol.iterator]() and consumed by scanDocument().
+     * Populated by tokenizeInto() and consumed by scanDocument().
      */
     _inlineSolveSpans: InlineSolveSpan[];
     private pluginRawLinePatterns;
@@ -260,7 +278,14 @@ declare class ExpressionLexer {
     private matchRawLine;
     /** Rebuild merged keyword and unit collections after plugin registration. */
     private rebuildMergedUnits;
-    constructor(localeCode?: string, lookup?: TokenLookup);
+    /**
+     * @param localeCode - Locale whose keyword table seeds the lexer.
+     * @param _lookup - Ignored. The lexer built its keyword, unit and phrase
+     *   tables from the locale and the registered packages and never read the
+     *   lookup it was handed; the parameter stays so existing callers compile.
+     *   @deprecated Removed in 3.0.
+     */
+    constructor(localeCode?: string, _lookup?: TokenLookup);
     /**
      * Register a plugin to extend the lexer with custom tokens.
      *
@@ -276,6 +301,10 @@ declare class ExpressionLexer {
      * that conflicts with a built-in one.
      */
     registerVocabulary(plugin: LexerVocabulary): void;
+    /** Record `owner`'s claim on `key`. The newest claim is the one in force. */
+    private claim;
+    /** Drop `owner`'s claim on `key`, and return the claim now in force, if any is left. */
+    private release;
     /**
      * Unregister a plugin, removing its custom tokens from the lexer.
      *
@@ -307,9 +336,9 @@ declare class ExpressionLexer {
      *   lines that classifyLine() marks as having inline solves.
      *
      * Tokenization is scoped to each line by temporarily restricting
-     * `this.len` to the line end position, so the [Symbol.iterator]
-     * generator naturally stops at the line boundary. After tokenization,
-     * `this.len` is restored and `this.pos` advances past the newline.
+     * `this.len` to the line end position, so tokenizeInto() naturally
+     * stops at the line boundary. After tokenization, `this.len` is
+     * restored and `this.pos` advances past the newline.
      *
      * @param text The full document text (with newlines).
      * @returns Array of ScanLineResult, one per line, in document order.
@@ -318,9 +347,7 @@ declare class ExpressionLexer {
     /**
      * Tokenize an expression string into an array of Tokens.
      *
-     * Delegates to the lazy [Symbol.iterator]() generator and collects all
-     * yielded tokens via Array.from(). For memory-sensitive use cases, prefer
-     * iterating the lexer directly with for...of to avoid array allocation.
+     * Runs {@link tokenizeInto} into a fresh array.
      *
      * Optimizations:
      *  - CHAR_CLASS jump table (Uint8Array) → switch on small integers
@@ -332,20 +359,31 @@ declare class ExpressionLexer {
      */
     tokenizeAll(): Token[];
     /**
-     * Lazy token-by-token generator. Yields each token without allocating an
-     * intermediate Token[] array. Supports for...of and spread usage.
+     * Scan the current input and append every token to `out`.
+     *
+     * This is the scanner itself: {@link tokenizeAll} and the iterator are
+     * thin wrappers over it. It pushes into an array the caller owns rather
+     * than yielding, because a generator paid a resume per token and
+     * `Array.from` a second pass on top, and because a caller that catches a
+     * tokeniser fault (highlighting a line with an unterminated quote) still
+     * holds the tokens read before it.
      *
-     * Usage:
-     *   for (const t of lexer) { ... }  // lazy, no array allocation
-     *   const tokens = [...lexer];       // materializes via spread
-     *   const tokens = lexer.tokenizeAll(); // materializes via Array.from()
+     * IMPORTANT: `this.len` is read ONCE on entry (const len = this.len).
+     * `scanDocument()` relies on this to scope a pass to a single line by
+     * restricting `this.len` to the line end before calling. Do not re-read
+     * `this.len` mid-loop without also updating `scanDocument()`.
      *
-     * IMPORTANT: This generator captures `this.len` ONCE at creation time
-     * (const len = this.len). `scanDocument()` relies on this behavior to
-     * scope tokenization to a single line by temporarily restricting
-     * `this.len` to the line end position before creating the iterator.
-     * Do NOT refactor to re-read `this.len` mid-loop without also updating
-     * `scanDocument()`.
+     * @param out - The array to append to. Left as it was if the input is empty.
+     */
+    tokenizeInto(out: Token[]): void;
+    /**
+     * Iterate the tokens of the current input.
+     *
+     * Runs {@link tokenizeInto} first, so the tokens are the same as before,
+     * but a fault part way through the line is thrown from the first
+     * `next()` rather than at the token it occurred on. A caller that wants
+     * the tokens read before a fault calls {@link tokenizeInto} with its own
+     * array.
      */
     [Symbol.iterator](): Generator<Token, void, undefined>;
     /**
@@ -456,6 +494,27 @@ declare class ExpressionLexer {
      * `#12345` (length 5), `#ff0000zz` (trailing word) do not.
      */
     private matchHexColourEnd;
+    /**
+     * Whether an inline-solve opener (`s` + backtick) occurs in `[from, end)`.
+     *
+     * Bounded by hand rather than written as `input.indexOf("s\`", from)`. This
+     * used to be the `indexOf` form with an `idx < end` check afterwards, which
+     * is correct but not bounded: when {@link scanDocument} is classifying,
+     * `this.input` is the whole document, so a line with no marker scanned to
+     * the END OF THE DOCUMENT before the check could reject the hit. Every line
+     * paid for every line after it, and a whole-document parse was quadratic in
+     * line count (measured at 28.9 us per line at 10,000 lines against 10.1 us
+     * at 1,000, and two thirds of the parse's self time in a profile). A prose
+     * document with many candidate `s` characters was worse still. The
+     * wikilink close in {@link indexOfWithin} had the same shape.
+     */
+    private hasInlineSolveWithin;
+    /**
+     * `input.indexOf(needle, from)` restricted to `[from, end)`, returning -1
+     * when the needle does not occur wholly before `end`. See
+     * {@link hasInlineSolveWithin} for why the plain `indexOf` was not enough.
+     */
+    private indexOfWithin;
     private classifyFromPositions;
     /**
      * Classify a single line of markdown text.
@@ -530,11 +589,11 @@ declare class Lexer {
     private tokenIdx;
     /**
      * @param localeCode - Locale code (e.g., "en", "de"). Defaults to "en".
-     * @param tokenLookup - Optional TokenLookup from TokenClassRegistry.
-     *   When provided, configures ExpressionLexer to use registry-built
-     *   keyword/unit/phrase lookups instead of internal instance maps.
+     * @param _tokenLookup - Ignored. The lexer never read the lookup it was
+     *   handed; the parameter stays so existing callers compile.
+     *   @deprecated Removed in 3.0.
      */
-    constructor(localeCode?: string, tokenLookup?: TokenLookup);
+    constructor(localeCode?: string, _tokenLookup?: TokenLookup);
     reset(input: string, state?: LexerState): void;
     /**
      * Classify a single line of markdown text (Phase B).

package/dist/{PackageCompatibility-CeAPVHZr.d.cts → PackageCompatibility-CNiTtC6S.d.cts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-B9-7fJGH.cjs';
+import { I as IEnginePackage } from './PackageRegistry-BHBCFswo.cjs';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping

package/dist/{PackageCompatibility-Bq82y0ZN.d.ts → PackageCompatibility-fj_f7uqC.d.ts}

@@ -1,4 +1,4 @@
-import { I as IEnginePackage } from './PackageRegistry-CDEgfhT_.js';
+import { I as IEnginePackage } from './PackageRegistry-CNZUwWHJ.js';
 
 /**
  * Package load-time compatibility checking, the "detect overlapping