@lokascript/semantic 1.3.0 → 2.0.0

package/dist/cache/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Cache Module
+ *
+ * LRU caching for semantic analysis results.
+ */
+export { SemanticCache, semanticCache, createSemanticCache, withCache, type SemanticCacheConfig, type CacheStats, } from './semantic-cache';
+//# sourceMappingURL=index.d.ts.map

package/dist/cache/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cache/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,aAAa,EACb,aAAa,EACb,mBAAmB,EACnB,SAAS,EACT,KAAK,mBAAmB,EACxB,KAAK,UAAU,GAChB,MAAM,kBAAkB,CAAC"}

package/dist/cache/semantic-cache.d.ts

@@ -0,0 +1,138 @@
+/**
+ * Semantic Result Cache
+ *
+ * LRU cache for semantic analysis results to optimize repeated parsing.
+ *
+ * Design:
+ * - Cache key: `${language}:${input}` for simple, fast lookups
+ * - LRU eviction when max size reached
+ * - Optional TTL (time-to-live) for cache entries
+ * - Statistics for monitoring cache effectiveness
+ * - Thread-safe for browser environments (single-threaded)
+ */
+import type { SemanticAnalysisResult } from '../core-bridge';
+/**
+ * Cache configuration options.
+ */
+export interface SemanticCacheConfig {
+    /** Maximum number of entries to cache. Default: 1000 */
+    maxSize?: number;
+    /** Time-to-live in milliseconds. 0 = no expiration. Default: 0 */
+    ttlMs?: number;
+    /** Enable/disable caching. Default: true */
+    enabled?: boolean;
+}
+/**
+ * Cache statistics.
+ */
+export interface CacheStats {
+    /** Total cache hits */
+    hits: number;
+    /** Total cache misses */
+    misses: number;
+    /** Current cache size */
+    size: number;
+    /** Maximum cache size */
+    maxSize: number;
+    /** Hit rate (0-1) */
+    hitRate: number;
+    /** Total evictions due to size limit */
+    evictions: number;
+    /** Total expirations due to TTL */
+    expirations: number;
+    /** Whether caching is enabled */
+    enabled: boolean;
+}
+/**
+ * LRU Cache for semantic analysis results.
+ *
+ * Uses Map's insertion order for LRU eviction - when we access an entry,
+ * we delete and re-insert it to move it to the end (most recently used).
+ */
+export declare class SemanticCache {
+    private cache;
+    private config;
+    private stats;
+    constructor(config?: SemanticCacheConfig);
+    /**
+     * Generate cache key from input and language.
+     */
+    private makeKey;
+    /**
+     * Check if an entry has expired.
+     */
+    private isExpired;
+    /**
+     * Evict the least recently used entry.
+     */
+    private evictLRU;
+    /**
+     * Get a cached result.
+     *
+     * @param input - The input string
+     * @param language - The language code
+     * @returns The cached result, or undefined if not found/expired
+     */
+    get(input: string, language: string): SemanticAnalysisResult | undefined;
+    /**
+     * Store a result in the cache.
+     *
+     * @param input - The input string
+     * @param language - The language code
+     * @param result - The analysis result to cache
+     */
+    set(input: string, language: string, result: SemanticAnalysisResult): void;
+    /**
+     * Check if a result is cached (without updating LRU).
+     */
+    has(input: string, language: string): boolean;
+    /**
+     * Remove a specific entry from the cache.
+     */
+    delete(input: string, language: string): boolean;
+    /**
+     * Clear all cached entries.
+     */
+    clear(): void;
+    /**
+     * Reset statistics.
+     */
+    resetStats(): void;
+    /**
+     * Get cache statistics.
+     */
+    getStats(): CacheStats;
+    /**
+     * Update cache configuration.
+     */
+    configure(config: Partial<SemanticCacheConfig>): void;
+    /**
+     * Enable caching.
+     */
+    enable(): void;
+    /**
+     * Disable caching.
+     */
+    disable(): void;
+    /**
+     * Get current configuration.
+     */
+    getConfig(): Readonly<Required<SemanticCacheConfig>>;
+}
+/**
+ * Default global cache instance.
+ */
+export declare const semanticCache: SemanticCache;
+/**
+ * Create a cache with custom configuration.
+ */
+export declare function createSemanticCache(config?: SemanticCacheConfig): SemanticCache;
+/**
+ * Decorator/wrapper for adding caching to an analyze function.
+ *
+ * @param analyzeFn - The analyze function to wrap
+ * @param cache - The cache instance to use
+ * @returns Wrapped function with caching
+ */
+export declare function withCache<T extends (input: string, language: string) => SemanticAnalysisResult>(analyzeFn: T, cache?: SemanticCache): T;
+//# sourceMappingURL=semantic-cache.d.ts.map

package/dist/cache/semantic-cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-cache.d.ts","sourceRoot":"","sources":["../../src/cache/semantic-cache.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAM7D;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,wDAAwD;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,kEAAkE;IAClE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4CAA4C;IAC5C,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAcD;;GAEG;AACH,MAAM,WAAW,UAAU;IACzB,uBAAuB;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,yBAAyB;IACzB,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;IAChB,qBAAqB;IACrB,OAAO,EAAE,MAAM,CAAC;IAChB,wCAAwC;IACxC,SAAS,EAAE,MAAM,CAAC;IAClB,mCAAmC;IACnC,WAAW,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,OAAO,EAAE,OAAO,CAAC;CAClB;AAMD;;;;;GAKG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,KAAK,CAA0B;IACvC,OAAO,CAAC,MAAM,CAAgC;IAC9C,OAAO,CAAC,KAAK,CAKX;gBAEU,MAAM,GAAE,mBAAwB;IAe5C;;OAEG;IACH,OAAO,CAAC,OAAO;IAIf;;OAEG;IACH,OAAO,CAAC,SAAS;IAKjB;;OAEG;IACH,OAAO,CAAC,QAAQ;IAShB;;;;;;OAMG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,sBAAsB,GAAG,SAAS;IA+BxE;;;;;;OAMG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,GAAG,IAAI;IAqB1E;;OAEG;IACH,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAgB7C;;OAEG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO;IAKhD;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,UAAU,IAAI,IAAI;IASlB;;OAEG;IACH,QAAQ,IAAI,UAAU;IActB;;OAEG;IACH,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,mBAAmB,CAAC,GAAG,IAAI;IAgBrD;;OAEG;IACH,MAAM,IAAI,IAAI;IAId;;OAEG;IACH,OAAO,IAAI,IAAI;IAIf;;OAEG;IACH,SAAS,IAAI,QAAQ,CAAC,QAAQ,CAAC,mBAAmB,CAAC,CAAC;CAGrD;AAMD;;GAEG;AACH,eAAO,MAAM,aAAa,eAAsB,CAAC;AAMjD;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,CAAC,EAAE,mBAAmB,GAAG,aAAa,CAE/E;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,CAAC,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,KAAK,sBAAsB,EAC7F,SAAS,EAAE,CAAC,EACZ,KAAK,GAAE,aAA6B,GACnC,CAAC,CAgBH"}

package/dist/core-bridge.d.ts

@@ -0,0 +1,154 @@
+/**
+ * Core Parser Bridge
+ *
+ * Provides the SemanticAnalyzer interface that integrates semantic parsing
+ * into the core hyperscript parser. This bridge enables confidence-driven
+ * fallback between semantic and traditional parsing.
+ */
+import type { SemanticNode, SemanticValue, ActionType, SemanticRole } from './types';
+import { type SemanticCacheConfig, type CacheStats } from './cache';
+/**
+ * Result of semantic analysis.
+ */
+export interface SemanticAnalysisResult {
+    /** Confidence score (0-1) for this analysis */
+    readonly confidence: number;
+    /** The parsed command info (if successful) */
+    readonly command?: {
+        readonly name: ActionType;
+        readonly roles: ReadonlyMap<SemanticRole, SemanticValue>;
+    };
+    /** The full semantic node (if successful) */
+    readonly node?: SemanticNode;
+    /** Any errors encountered */
+    readonly errors?: string[];
+    /** Number of tokens consumed */
+    readonly tokensConsumed?: number;
+}
+/**
+ * Interface for semantic analysis that can be integrated into the core parser.
+ * This allows the core parser to optionally use semantic parsing with
+ * confidence-based fallback to traditional parsing.
+ */
+export interface SemanticAnalyzer {
+    /**
+     * Analyze input in the specified language.
+     *
+     * @deprecated Since v1.4.0. Will be removed in v2.0.0.
+     * Prefer `parseSemantic()` from `@lokascript/semantic` for new code.
+     * This method is retained for backward compatibility but now uses the full
+     * parser internally to preserve event handler bodies.
+     *
+     * @param input The input string to analyze
+     * @param language ISO 639-1 language code
+     * @returns Analysis result with confidence score
+     */
+    analyze(input: string, language: string): SemanticAnalysisResult;
+    /**
+     * Check if semantic parsing is available for a language.
+     */
+    supportsLanguage(language: string): boolean;
+    /**
+     * Get the list of supported languages.
+     */
+    supportedLanguages(): string[];
+    /**
+     * Get cache statistics.
+     */
+    getCacheStats(): CacheStats;
+    /**
+     * Clear the result cache.
+     */
+    clearCache(): void;
+    /**
+     * Configure the cache.
+     */
+    configureCache(config: Partial<SemanticCacheConfig>): void;
+}
+/**
+ * Options for creating a SemanticAnalyzer.
+ */
+export interface SemanticAnalyzerOptions {
+    /** Cache configuration. Pass false to disable caching. */
+    cache?: SemanticCacheConfig | false;
+}
+/**
+ * Implementation of SemanticAnalyzer that wraps the semantic parser.
+ * Includes LRU caching for performance optimization on repeated inputs.
+ */
+export declare class SemanticAnalyzerImpl implements SemanticAnalyzer {
+    private readonly patternMatcher;
+    private readonly languages;
+    private readonly cache;
+    constructor(options?: SemanticAnalyzerOptions);
+    analyze(input: string, language: string): SemanticAnalysisResult;
+    /**
+     * Perform analysis without cache lookup.
+     *
+     * Uses full parser first to preserve complete AST structure (event handler
+     * bodies, compound statements, conditionals). Falls back to pattern matching
+     * only when the full parser fails, which provides fast simple-command detection
+     * but loses structural information like event handler bodies.
+     */
+    private analyzeUncached;
+    supportsLanguage(language: string): boolean;
+    supportedLanguages(): string[];
+    getCacheStats(): CacheStats;
+    clearCache(): void;
+    configureCache(config: Partial<SemanticCacheConfig>): void;
+    private buildSemanticNode;
+}
+/**
+ * Create a SemanticAnalyzer instance.
+ *
+ * @param options - Configuration options including cache settings
+ * @returns A new SemanticAnalyzer
+ *
+ * @example
+ * // Default: uses shared global cache
+ * const analyzer = createSemanticAnalyzer();
+ *
+ * @example
+ * // Custom cache size
+ * const analyzer = createSemanticAnalyzer({ cache: { maxSize: 500 } });
+ *
+ * @example
+ * // Disable caching
+ * const analyzer = createSemanticAnalyzer({ cache: false });
+ */
+export declare function createSemanticAnalyzer(options?: SemanticAnalyzerOptions): SemanticAnalyzer;
+export type { SemanticCacheConfig, CacheStats } from './cache';
+/**
+ * Default confidence threshold for preferring semantic parsing.
+ * If confidence is above this, use semantic result; otherwise fallback.
+ */
+export declare const DEFAULT_CONFIDENCE_THRESHOLD = 0.5;
+/**
+ * High confidence threshold for very certain matches.
+ */
+export declare const HIGH_CONFIDENCE_THRESHOLD = 0.8;
+/**
+ * Determine if semantic analysis should be used based on confidence.
+ */
+export declare function shouldUseSemanticResult(result: SemanticAnalysisResult, threshold?: number): boolean;
+/**
+ * Convert semantic roles to the format expected by core parser commands.
+ * This maps semantic roles to the positional/modifier structure used by
+ * the core command implementations.
+ *
+ * Role to preposition mapping:
+ * - patient → first positional arg
+ * - event → first positional arg
+ * - destination → 'into' (put) or 'on' (others)
+ * - source → 'from'
+ * - quantity → 'by'
+ * - duration → 'over' or 'for'
+ * - method → 'as'
+ * - style → 'with'
+ * - condition → 'if'
+ */
+export declare function rolesToCommandArgs(roles: ReadonlyMap<SemanticRole, SemanticValue>, command: ActionType): {
+    args: SemanticValue[];
+    modifiers: Record<string, SemanticValue>;
+};
+//# sourceMappingURL=core-bridge.d.ts.map

package/dist/core-bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"core-bridge.d.ts","sourceRoot":"","sources":["../src/core-bridge.ts"],"names":[],"mappings":"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"}