solve-engine 1.0.0-beta.0 → 1.0.0-beta.2

package/dist/normalizer.d.ts

@@ -0,0 +1,364 @@
+import { T as Token } from './Token-0jpvUdPY.js';
+import { T as TokenFusion, N as NormalizerRule, a as NormalizerMatch } from './NormalizerRule-CEjf1FyD.js';
+
+/**
+ * TokenNormalizer, post-lexer token normalization pass.
+ *
+ * ## Purpose
+ * Applies domain-specific {@link NormalizerRule | NormalizerRules} to the raw
+ * token stream produced by the {@link ExpressionLexer}. This keeps the lexer
+ * slim and focused on single-token production, while multi-token pattern
+ * matching (phrases, implicit operators, domain merges) lives here.
+ *
+ * ## What rules can do
+ * - **Phrase fusion**: Merge consecutive words into compound tokens
+ *   (e.g., `IDENT + ... + IDENT` → `CARET`)
+ * - **Implicit operator insertion**: Insert missing operators between tokens
+ *   (e.g., `NUMBER IDENT` → `NUMBER STAR IDENT`)
+ * - **Domain-specific transformations**: Coalesce item names, currency pairs,
+ *   percentage syntax, etc.
+ *
+ * ## Architecture
+ * Providers register NormalizerRules alongside Parselets and OpCode handlers
+ * via {@link IEnginePackage.normalizerRules}. The normalizer applies them
+ * greedily left-to-right in multiple passes with safety limits.
+ *
+ * @module TokenNormalizer
+ */
+
+/**
+ * Configuration options for the normalization pass.
+ *
+ * These control safety limits and diagnostic callbacks. The defaults
+ * are chosen to be generous enough for any realistic expression while
+ * preventing runaway token expansion from recursive rules.
+ */
+interface NormalizerOptions {
+    /**
+     * Maximum number of full passes over the token stream before bailing out.
+     * Prevents infinite loops from recursive rule chains.
+     * @default 100
+     */
+    maxPasses?: number;
+    /**
+     * Maximum number of tokens allowed after normalization.
+     * If exceeded, an Error is thrown rather than passing a bloated stream
+     * to the parser.
+     * @default 10000
+     */
+    maxTokens?: number;
+    /**
+     * Callback invoked for each fusion event during normalization.
+     * Used by diagnostic mode to populate {@link NormalizerOutput.fusions}.
+     * When `undefined`, fusions are still tracked internally but no callbacks fire.
+     */
+    onFusion?: (fusion: TokenFusion) => void;
+}
+/**
+ * Creates a new normalized token from fused source tokens.
+ *
+ * The fused token inherits position information (offset, line, column)
+ * from the first source token, which preserves source-map accuracy
+ * for error messages and diagnostic highlighting.
+ *
+ * @param type         - The new token type (e.g., "CARET", "TIMES_BY")
+ * @param text         - The combined text representation (e.g., "to the power of")
+ * @param sourceTokens - The original tokens being fused (at least 2)
+ * @returns A new {@link LexerToken} with the fused type and combined text
+ */
+declare function createFusedToken(type: string, text: string, sourceTokens: Token[]): Token;
+/**
+ * Token normalizer: applies {@link NormalizerRule | NormalizerRules} to a token stream.
+ *
+ * ## Lifecycle
+ * 1. **Registration**: Rules are added via {@link register} and sorted by priority
+ * 2. **Normalization**: {@link normalize} applies rules greedily left-to-right
+ * 3. **Cleanup**: {@link clear} or {@link unregister} removes rules
+ *
+ * ## Normalization algorithm
+ * The normalizer uses a greedy left-to-right multi-pass algorithm:
+ * - At each token position, rules are tried in priority order (highest first)
+ * - When a rule matches, matched tokens are consumed and replaced
+ * - Processing continues from the replacement position
+ * - Multiple passes handle cascading matches (one rule's output triggers another)
+ * - Safety limits ({@link NormalizerOptions.maxPasses}) prevent infinite loops
+ *
+ * @example
+ * ```ts
+ * const normalizer = new TokenNormalizer();
+ * normalizer.register(phraseRule);       // "to the power of" → CARET
+ * normalizer.register(implicitMultRule); // "2 x" → "2 * x"
+ * const normalized = normalizer.normalize(rawTokens);
+ * ```
+ */
+declare class TokenNormalizer {
+    /** Registered rules, unsorted, the source of truth. */
+    private rules;
+    /**
+     * Priority-sorted copy of {@link rules}, rebuilt lazily on the next
+     * {@link normalize} call after a mutation. Rules are registered once at
+     * engine/package-registration time and essentially never change during a
+     * session, but normalize() runs on every keystroke-driven evaluation, an
+     * earlier version re-sorted a fresh copy of `rules` on every single call,
+     * which meant every keystroke paid for an allocation + sort of a list that
+     * had usually not changed since the last one. `null` means "stale, rebuild
+     * on next use"; {@link register}/{@link unregister}/{@link clear} all
+     * invalidate it.
+     */
+    private sortedRulesCache;
+    /**
+     * Phrase trie for single-pass multi-word phrase fusion.
+     * Tried at each token position BEFORE other rules, the trie walk
+     * is O(depth) vs O(R × W) for separate rule matching.
+     */
+    private phraseTrie;
+    /** Merged options with defaults applied. */
+    private options;
+    /**
+     * @param options - Configuration overrides for safety limits and diagnostic callbacks
+     */
+    constructor(options?: NormalizerOptions);
+    /**
+     * Register a normalization rule.
+     *
+     * Rules are sorted by priority (descending) on each {@link normalize} call.
+     * Multiple rules can share the same priority, they are tried in registration
+     * order when priorities are equal.
+     *
+     * @param rule - The rule to register
+     */
+    register(rule: NormalizerRule): void;
+    /**
+     * Unregister a normalization rule by its {@link NormalizerRule.name | name}.
+     *
+     * If multiple rules share the same name, all are removed. This is safe to
+     * call with a name that doesn't match any rule, it simply has no effect.
+     *
+     * @param ruleName - The name of the rule to remove
+     */
+    unregister(ruleName: string): void;
+    /**
+     * Remove all registered rules, resetting the normalizer to its initial state.
+     * Also clears the phrase trie.
+     */
+    clear(): void;
+    /**
+     * Priority-sorted view of {@link rules} (descending priority; registration
+     * order preserved for ties, since {@link Array.prototype.sort} is stable).
+     * Cached until the next mutation. See {@link sortedRulesCache}.
+     */
+    private getSortedRules;
+    /**
+     * Get the number of currently registered rules (excludes phrase trie entries).
+     */
+    get ruleCount(): number;
+    /**
+     * Register a multi-word phrase for fusion into a single compound token.
+     *
+     * This is the preferred way to add phrase patterns. It inserts into the
+     * internal {@link PhraseTrie}, which collapses all phrase rules into a
+     * single O(depth) trie walk per position, no separate rule scanning.
+     *
+     * @param phrase    - Multi-word phrase (e.g., "to the power of", "abyssal whip")
+     * @param tokenType - Target token type after fusion (e.g., "CARET", "ITEM")
+     */
+    addPhrase(phrase: string, tokenType: string): void;
+    /**
+     * Check whether a word can start any registered phrase.
+     *
+     * Used by {@link implicitMultiplyRule} to suppress `*` insertion
+     * before phrase-starting identifiers (e.g., "2 power of 3" → `2 ^ 3`,
+     * not `2 * power of 3`). Delegates to {@link PhraseTrie.canStart}.
+     */
+    /**
+     * Get all registered phrases and their target token types.
+     *
+     * Exposes the full phrase trie structure for diagnostic rendering
+     * in the playground's NormalizerTab. Returns ALL registered phrases,
+     * not just the ones that matched in the last evaluation.
+     */
+    getPhrases(): Record<string, string>;
+    canStartPhrase(word: string): boolean;
+    /**
+     * Normalize a token stream by applying all registered rules.
+     *
+     * ## Algorithm
+     * Applies rules greedily left-to-right in multiple passes:
+     * 1. Sort rules by priority (descending)
+     * 2. Walk the token stream left to right
+     * 3. At each position, try rules in priority order
+     * 4. On match: consume matched tokens, insert replacements, restart from insert point
+     * 5. On no match: pass token through unchanged
+     * 6. Repeat until a full pass produces no changes, or maxPasses is reached
+     *
+     * ## Fusion tracking
+     * When a rule consumes more tokens than it produces, the normalizer calls
+     * `onFusion` with a {@link TokenFusion} record for diagnostic collection.
+     * This populates {@link NormalizerOutput.fusions} in the playground pipeline view.
+     *
+     * ## Safety
+     * If the normalized token count exceeds {@link NormalizerOptions.maxTokens},
+     * an Error is thrown to prevent memory exhaustion from runaway rule expansion.
+     *
+     * @param tokens   - Raw tokens from the lexer
+     * @param onFusion - Optional fusion callback (overrides {@link NormalizerOptions.onFusion})
+     * @returns Normalized tokens ready for parsing
+     * @throws {Error} If the normalized token count exceeds maxTokens
+     */
+    normalize(tokens: Token[], onFusion?: (fusion: TokenFusion) => void): Token[];
+}
+
+/**
+ * PhraseTrie, optimized word-level trie for multi-word phrase fusion.
+ *
+ * ## Problem
+ * The normalizer previously applied N separate `phraseFusionRule` instances,
+ * each scanning forward from the current token position. For R phrase rules
+ * and W average phrase length, this cost O(N × R × W) per pass.
+ *
+ * ## Solution
+ * A single trie walk per position collapses all phrase rules into O(D)
+ * where D ≤ longest phrase depth (typically ≤ 5 words). The trie tracks
+ * the deepest terminal node reached, implementing longest-match-wins
+ * without priority sorting.
+ *
+ * ## Optimizations
+ * 1. **Set<string> quick-reject**, the `startWords` set contains the first
+ *    word of every registered phrase. At each position, if the token's
+ *    lowercase value isn't in the set, we bail in O(1) without touching
+ *    the trie. ~80% of tokens (numbers, operators) hit this fast path.
+ * 2. **Longest-match-wins**, the `matchAt()` walk continues past terminal
+ *    nodes, tracking the deepest one. Shorter overlapping phrases (e.g.,
+ *    "power of") don't need lower priority, the trie naturally prefers
+ *    the longer match.
+ * 3. **Map-based children**, `Map<string, TrieNode>` gives O(1) amortized
+ *    child lookup per word, faster than array scanning for sparse branches.
+ *
+ * ## Package integration
+ * Packages add phrases via {@link TokenNormalizer.addPhrase} (public API)
+ * or the {@link IEnginePackage.phrases} declarative field. Each call to
+ * `addPhrase()` inserts the phrase into this trie and updates `startWords`.
+ *
+ * @module PhraseTrie
+ */
+
+/**
+ * Word-level trie for single-pass multi-word phrase matching.
+ *
+ * @example
+ * ```ts
+ * const trie = new PhraseTrie();
+ * trie.addPhrase("to the power of", "CARET");
+ * trie.addPhrase("power of", "CARET");
+ * trie.addPhrase("abyssal whip", "ITEM");
+ *
+ * // At position 0 with tokens ["to","the","power","of","3"]
+ * const match = trie.matchAt(tokens, 0);
+ * // → { consumed: 4, replacement: [CARET("to the power of")] }
+ * ```
+ */
+declare class PhraseTrie {
+    /**
+     * First words that can start any registered phrase (all lowercase).
+     * O(1) quick-reject: if `tokens[pos].value.toLowerCase()` isn't here,
+     * no phrase can match at this position.
+     */
+    private startWords;
+    /**
+     * Root maps first word → child node.
+     * Two-level root avoids an unnecessary intermediate TrieNode.
+     */
+    private root;
+    /**
+     * Register a phrase for fusion into a single compound token.
+     *
+     * @param phrase    - Multi-word phrase (e.g., "to the power of")
+     * @param tokenType - Target token type after fusion (e.g., "CARET")
+     */
+    addPhrase(phrase: string, tokenType: string): void;
+    /**
+     * Attempt to match a phrase starting at `pos` in the token stream.
+     *
+     * Walks the trie one token at a time, tracking the deepest terminal
+     * node reached. Returns the longest match found, or `null` if no
+     * phrase starts at this position.
+     *
+     * @param tokens - The current token stream
+     * @param pos    - Position to attempt matching from
+     * @returns The longest {@link NormalizerMatch}, or `null` on no match
+     */
+    matchAt(tokens: Token[], pos: number): NormalizerMatch | null;
+    /** Number of unique first words (not total phrases). */
+    get size(): number;
+    /**
+     * Return all registered phrases and their target token types.
+     *
+     * Used by diagnostic mode to expose the complete trie structure to the
+     * playground's NormalizerTab for rendering ALL registered phrases
+     * (not just the ones that matched in this evaluation).
+     */
+    getAllPhrases(): Record<string, string>;
+    /** Check if any phrase starts with this word (case-insensitive). */
+    canStart(word: string): boolean;
+}
+
+/**
+ * Built-in normalization rules for the {@link TokenNormalizer}.
+ *
+ * These rules handle common expression patterns that span multiple tokens.
+ * Phrase fusion (e.g., "to the power of" → CARET) is handled by the
+ * internal {@link PhraseTrie}. See {@link TokenNormalizer.addPhrase}.
+ * This module only exports non-phrase rules like {@link implicitMultiplyRule}.
+ *
+ * @module BuiltinNormalizerRules
+ */
+
+/**
+ * Creates a normalization rule that inserts an implicit multiplication operator
+ * between adjacent tokens where multiplication is implied.
+ *
+ * ## When it fires
+ * Inserts a STAR token between:
+ * - `NUMBER IDENT` (e.g., "2 x" → "2 * x")
+ * - `RPAREN IDENT` (e.g., "(x+1)y" → "(x+1) * y")
+ * - `NUMBER LPAREN` (e.g., "2(x+1)" → "2 * (x+1)")
+ * - `NUMBER PI` / `NUMBER E` (e.g., "2π" → "2 * π")
+ *
+ * ## When it doesn't fire
+ * - When the following identifier starts a multi-word phrase
+ *   (checked against {@link PHRASE_START_WORDS})
+ * - When the following token is not an identifier or parenthesized expression
+ *
+ * ## Priority
+ * Default priority is 50, below phrase fusion so phrases match first.
+ *
+ * @param priority - Rule priority (default 50)
+ * @returns A {@link NormalizerRule} that inserts implicit multiply operators
+ */
+declare function implicitMultiplyRule(priority?: number, canStart?: (word: string) => boolean): NormalizerRule;
+/**
+ * Creates built-in non-phrase normalization rules.
+ *
+ * Returns implicit multiply insertion (priority 50).
+ *
+ * **Prefer** calling {@link implicitMultiplyRule} directly with a
+ * `canStart` predicate wired to the normalizer's phrase trie:
+ * ```ts
+ * normalizer.register(implicitMultiplyRule(50, (w) => normalizer.canStartPhrase(w)));
+ * ```
+ * Without the predicate, this function falls back to a hardcoded
+ * {@link PHRASE_START_WORDS} set that won't reflect package-registered phrases.
+ *
+ * @returns An array of {@link NormalizerRule} instances ready for registration
+ */
+declare function createBuiltinNormalizerRules(): NormalizerRule[];
+/**
+ * Built-in phrase → tokenType mappings.
+ *
+ * These are registered into the engine's {@link PhraseTrie} during
+ * construction. Tests that create a standalone {@link TokenNormalizer}
+ * should register these via {@link TokenNormalizer.addPhrase}.
+ */
+declare const BUILTIN_PHRASES: Record<string, string>;
+
+export { BUILTIN_PHRASES, NormalizerMatch, type NormalizerOptions, NormalizerRule, PhraseTrie, TokenFusion, TokenNormalizer, createBuiltinNormalizerRules, createFusedToken, implicitMultiplyRule };

package/dist/normalizer.js

@@ -0,0 +1,11 @@
+import './chunk-2RWAXT6O.js';
+export { BUILTIN_PHRASES, PhraseTrie, TokenNormalizer, createBuiltinNormalizerRules, createFusedToken, implicitMultiplyRule } from './chunk-64W6GLLZ.js';
+import './chunk-XVWCOTR6.js';
+import './chunk-RIN643A3.js';
+import './chunk-GOLDJNMZ.js';
+import './chunk-LIPPNDBE.js';
+import './chunk-4MG4XKO2.js';
+import './chunk-6RDSQURE.js';
+import './chunk-YLJ4XMA6.js';
+//# sourceMappingURL=normalizer.js.map
+//# sourceMappingURL=normalizer.js.map

package/dist/normalizer.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"normalizer.js"}

package/dist/packages.cjs

@@ -0,0 +1,121 @@
+'use strict';
+
+var chunkRZCWSXTA_cjs = require('./chunk-RZCWSXTA.cjs');
+require('./chunk-C4XZV6E7.cjs');
+require('./chunk-EBSPLUW4.cjs');
+require('./chunk-N5YFR4UP.cjs');
+require('./chunk-WQTTOGXC.cjs');
+require('./chunk-Z2XP767T.cjs');
+require('./chunk-J73SJHR3.cjs');
+require('./chunk-FEAIOR7N.cjs');
+require('./chunk-XJCMXB2E.cjs');
+require('./chunk-MZOVP3WI.cjs');
+require('./chunk-VEKIWQ3F.cjs');
+require('./chunk-OT6OJY7C.cjs');
+require('./chunk-HTXVVJRA.cjs');
+require('./chunk-OC6LTXYS.cjs');
+require('./chunk-QNJ4ACRT.cjs');
+require('./chunk-NMD5VRN4.cjs');
+require('./chunk-GW32KPCU.cjs');
+require('./chunk-3YNVWKR2.cjs');
+require('./chunk-EHAHVROS.cjs');
+require('./chunk-53B6KDDJ.cjs');
+require('./chunk-M4N5GA5Z.cjs');
+require('./chunk-B7LXJ6LC.cjs');
+
+
+
+Object.defineProperty(exports, "ARITHMETIC_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.ARITHMETIC_PACKAGE; }
+});
+Object.defineProperty(exports, "BIGINT_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.BIGINT_PACKAGE; }
+});
+Object.defineProperty(exports, "BUILTIN_PACKAGES", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.BUILTIN_PACKAGES; }
+});
+Object.defineProperty(exports, "CONDITIONALS_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.CONDITIONALS_PACKAGE; }
+});
+Object.defineProperty(exports, "CONVERTERS_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.CONVERTERS_PACKAGE; }
+});
+Object.defineProperty(exports, "CURRENCY_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.CURRENCY_PACKAGE; }
+});
+Object.defineProperty(exports, "DATETIME_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.DATETIME_PACKAGE; }
+});
+Object.defineProperty(exports, "DICE_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.DICE_PACKAGE; }
+});
+Object.defineProperty(exports, "FINANCE_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.FINANCE_PACKAGE; }
+});
+Object.defineProperty(exports, "FUNCTION_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.FUNCTION_PACKAGE; }
+});
+Object.defineProperty(exports, "LINES_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.LINES_PACKAGE; }
+});
+Object.defineProperty(exports, "MAPREDUCE_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.MAPREDUCE_PACKAGE; }
+});
+Object.defineProperty(exports, "MATHPHRASES_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.MATHPHRASES_PACKAGE; }
+});
+Object.defineProperty(exports, "MATRIX_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.MATRIX_PACKAGE; }
+});
+Object.defineProperty(exports, "PERCENTAGE_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.PERCENTAGE_PACKAGE; }
+});
+Object.defineProperty(exports, "SYMBOLIC_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.SYMBOLIC_PACKAGE; }
+});
+Object.defineProperty(exports, "TIME_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.TIME_PACKAGE; }
+});
+Object.defineProperty(exports, "UOM_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.UOM_PACKAGE; }
+});
+Object.defineProperty(exports, "VARIABLES_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.VARIABLES_PACKAGE; }
+});
+Object.defineProperty(exports, "VECTOR_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.VECTOR_PACKAGE; }
+});
+Object.defineProperty(exports, "WEATHER_PACKAGE", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.WEATHER_PACKAGE; }
+});
+Object.defineProperty(exports, "createKnowledgePackage", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.createKnowledgePackage; }
+});
+Object.defineProperty(exports, "createStocksPackage", {
+  enumerable: true,
+  get: function () { return chunkRZCWSXTA_cjs.createStocksPackage; }
+});
+//# sourceMappingURL=packages.cjs.map
+//# sourceMappingURL=packages.cjs.map

package/dist/packages.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"packages.cjs"}