aicodeman 0.2.8

package/dist/utils/stale-expiration-map.d.ts

@@ -0,0 +1,159 @@
+/**
+ * @fileoverview Map with automatic TTL-based entry expiration.
+ *
+ * StaleExpirationMap automatically removes entries that haven't been accessed
+ * within a configurable TTL (time-to-live). Useful for caches and tracking
+ * ephemeral data that should be cleaned up after a period of inactivity.
+ *
+ * @module utils/stale-expiration-map
+ */
+import type { Disposable } from '../types.js';
+/**
+ * Configuration options for StaleExpirationMap.
+ */
+export interface StaleExpirationMapOptions<K, V> {
+    /** Time-to-live in milliseconds before entries expire */
+    ttlMs: number;
+    /** How often to run cleanup (default: ttlMs / 2) */
+    cleanupIntervalMs?: number;
+    /** Optional callback when an entry expires */
+    onExpire?: (key: K, value: V) => void;
+    /** Whether to refresh TTL on get (default: true) */
+    refreshOnGet?: boolean;
+}
+/**
+ * A Map that automatically expires entries after a TTL.
+ *
+ * Entries are removed if not accessed within the TTL period.
+ * Periodic cleanup runs to remove expired entries.
+ *
+ * @example
+ * ```typescript
+ * const cache = new StaleExpirationMap<string, object>({
+ *   ttlMs: 5 * 60 * 1000,  // 5 minutes
+ *   onExpire: (key, value) => console.log(`Expired: ${key}`)
+ * });
+ *
+ * cache.set('key1', { data: 'value' });
+ * // After 5 minutes of no access, 'key1' will be automatically removed
+ * ```
+ */
+export declare class StaleExpirationMap<K, V> implements Disposable {
+    private entries;
+    private cleanupTimer;
+    private _isDisposed;
+    private readonly ttlMs;
+    private readonly cleanupIntervalMs;
+    private readonly onExpire?;
+    private readonly refreshOnGet;
+    /**
+     * Creates a new StaleExpirationMap.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options: StaleExpirationMapOptions<K, V>);
+    /**
+     * Whether this map has been disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * Number of entries in the map.
+     */
+    get size(): number;
+    /**
+     * Set a value with automatic TTL tracking.
+     *
+     * @param key - Key to set
+     * @param value - Value to associate
+     * @returns this (for chaining)
+     */
+    set(key: K, value: V): this;
+    /**
+     * Get a value, optionally refreshing its TTL.
+     *
+     * @param key - Key to look up
+     * @returns Value if found and not expired, undefined otherwise
+     */
+    get(key: K): V | undefined;
+    /**
+     * Check if a key exists and is not expired.
+     *
+     * @param key - Key to check
+     * @returns True if key exists and is not expired
+     */
+    has(key: K): boolean;
+    /**
+     * Peek at a value without refreshing its TTL.
+     *
+     * @param key - Key to peek
+     * @returns Value if found and not expired, undefined otherwise
+     */
+    peek(key: K): V | undefined;
+    /**
+     * Delete an entry.
+     *
+     * @param key - Key to delete
+     * @returns True if entry existed and was deleted
+     */
+    delete(key: K): boolean;
+    /**
+     * Clear all entries.
+     */
+    clear(): void;
+    /**
+     * Touch an entry to refresh its TTL without returning the value.
+     *
+     * @param key - Key to touch
+     * @returns True if entry exists
+     */
+    touch(key: K): boolean;
+    /**
+     * Get the age of an entry in milliseconds.
+     *
+     * @param key - Key to check
+     * @returns Age in ms, or undefined if not found
+     */
+    getAge(key: K): number | undefined;
+    /**
+     * Get remaining TTL for an entry in milliseconds.
+     *
+     * @param key - Key to check
+     * @returns Remaining TTL in ms, or undefined if not found/expired
+     */
+    getRemainingTtl(key: K): number | undefined;
+    /**
+     * Iterate over all non-expired entries.
+     */
+    [Symbol.iterator](): IterableIterator<[K, V]>;
+    /**
+     * Get all keys (non-expired).
+     */
+    keys(): IterableIterator<K>;
+    /**
+     * Get all values (non-expired).
+     */
+    values(): IterableIterator<V>;
+    /**
+     * Run cleanup immediately, removing all expired entries.
+     *
+     * @returns Number of entries removed
+     */
+    cleanup(): number;
+    /**
+     * Dispose the map, stopping cleanup timer and clearing entries.
+     */
+    dispose(): void;
+    /**
+     * Check if an entry has expired.
+     */
+    private isExpired;
+    /**
+     * Start the periodic cleanup timer.
+     */
+    private startCleanup;
+    /**
+     * Stop the periodic cleanup timer.
+     */
+    private stopCleanup;
+}
+//# sourceMappingURL=stale-expiration-map.d.ts.map

package/dist/utils/stale-expiration-map.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-expiration-map.d.ts","sourceRoot":"","sources":["../../src/utils/stale-expiration-map.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAW9C;;GAEG;AACH,MAAM,WAAW,yBAAyB,CAAC,CAAC,EAAE,CAAC;IAC7C,yDAAyD;IACzD,KAAK,EAAE,MAAM,CAAC;IACd,oDAAoD;IACpD,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,8CAA8C;IAC9C,QAAQ,CAAC,EAAE,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,KAAK,IAAI,CAAC;IACtC,oDAAoD;IACpD,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,kBAAkB,CAAC,CAAC,EAAE,CAAC,CAAE,YAAW,UAAU;IACzD,OAAO,CAAC,OAAO,CAA+B;IAC9C,OAAO,CAAC,YAAY,CAA+B;IACnD,OAAO,CAAC,WAAW,CAAS;IAE5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAS;IAC3C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAA6B;IACvD,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAU;IAEvC;;;;OAIG;gBACS,OAAO,EAAE,yBAAyB,CAAC,CAAC,EAAE,CAAC,CAAC;IAUpD;;OAEG;IACH,IAAI,UAAU,IAAI,OAAO,CAExB;IAED;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;;;OAMG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,IAAI;IAY3B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAkB1B;;;;;OAKG;IACH,GAAG,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAYpB;;;;;OAKG;IACH,IAAI,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,GAAG,SAAS;IAY3B;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IASvB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,CAAC,GAAG,OAAO;IAQtB;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM,GAAG,SAAS;IAMlC;;;;;OAKG;IACH,eAAe,CAAC,GAAG,EAAE,CAAC,GAAG,MAAM,GAAG,SAAS;IAS3C;;OAEG;IACF,CAAC,MAAM,CAAC,QAAQ,CAAC,IAAI,gBAAgB,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;IAQ9C;;OAEG;IACF,IAAI,IAAI,gBAAgB,CAAC,CAAC,CAAC;IAQ5B;;OAEG;IACF,MAAM,IAAI,gBAAgB,CAAC,CAAC,CAAC;IAQ9B;;;;OAIG;IACH,OAAO,IAAI,MAAM;IAejB;;OAEG;IACH,OAAO,IAAI,IAAI;IAQf;;OAEG;IACH,OAAO,CAAC,SAAS;IAIjB;;OAEG;IACH,OAAO,CAAC,YAAY;IAapB;;OAEG;IACH,OAAO,CAAC,WAAW;CAMpB"}

package/dist/utils/stale-expiration-map.js

@@ -0,0 +1,277 @@
+/**
+ * @fileoverview Map with automatic TTL-based entry expiration.
+ *
+ * StaleExpirationMap automatically removes entries that haven't been accessed
+ * within a configurable TTL (time-to-live). Useful for caches and tracking
+ * ephemeral data that should be cleaned up after a period of inactivity.
+ *
+ * @module utils/stale-expiration-map
+ */
+/**
+ * A Map that automatically expires entries after a TTL.
+ *
+ * Entries are removed if not accessed within the TTL period.
+ * Periodic cleanup runs to remove expired entries.
+ *
+ * @example
+ * ```typescript
+ * const cache = new StaleExpirationMap<string, object>({
+ *   ttlMs: 5 * 60 * 1000,  // 5 minutes
+ *   onExpire: (key, value) => console.log(`Expired: ${key}`)
+ * });
+ *
+ * cache.set('key1', { data: 'value' });
+ * // After 5 minutes of no access, 'key1' will be automatically removed
+ * ```
+ */
+export class StaleExpirationMap {
+    entries = new Map();
+    cleanupTimer = null;
+    _isDisposed = false;
+    ttlMs;
+    cleanupIntervalMs;
+    onExpire;
+    refreshOnGet;
+    /**
+     * Creates a new StaleExpirationMap.
+     *
+     * @param options - Configuration options
+     */
+    constructor(options) {
+        this.ttlMs = options.ttlMs;
+        this.cleanupIntervalMs = options.cleanupIntervalMs ?? Math.floor(options.ttlMs / 2);
+        this.onExpire = options.onExpire;
+        this.refreshOnGet = options.refreshOnGet ?? true;
+        // Start periodic cleanup
+        this.startCleanup();
+    }
+    /**
+     * Whether this map has been disposed.
+     */
+    get isDisposed() {
+        return this._isDisposed;
+    }
+    /**
+     * Number of entries in the map.
+     */
+    get size() {
+        return this.entries.size;
+    }
+    /**
+     * Set a value with automatic TTL tracking.
+     *
+     * @param key - Key to set
+     * @param value - Value to associate
+     * @returns this (for chaining)
+     */
+    set(key, value) {
+        if (this._isDisposed)
+            return this;
+        const now = Date.now();
+        this.entries.set(key, {
+            value,
+            lastAccessedAt: now,
+            createdAt: now,
+        });
+        return this;
+    }
+    /**
+     * Get a value, optionally refreshing its TTL.
+     *
+     * @param key - Key to look up
+     * @returns Value if found and not expired, undefined otherwise
+     */
+    get(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        // Check if expired
+        if (this.isExpired(entry)) {
+            this.delete(key);
+            return undefined;
+        }
+        // Refresh access time if configured
+        if (this.refreshOnGet) {
+            entry.lastAccessedAt = Date.now();
+        }
+        return entry.value;
+    }
+    /**
+     * Check if a key exists and is not expired.
+     *
+     * @param key - Key to check
+     * @returns True if key exists and is not expired
+     */
+    has(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return false;
+        if (this.isExpired(entry)) {
+            this.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Peek at a value without refreshing its TTL.
+     *
+     * @param key - Key to peek
+     * @returns Value if found and not expired, undefined otherwise
+     */
+    peek(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        if (this.isExpired(entry)) {
+            this.delete(key);
+            return undefined;
+        }
+        return entry.value;
+    }
+    /**
+     * Delete an entry.
+     *
+     * @param key - Key to delete
+     * @returns True if entry existed and was deleted
+     */
+    delete(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return false;
+        this.entries.delete(key);
+        // Don't call onExpire for manual deletes
+        return true;
+    }
+    /**
+     * Clear all entries.
+     */
+    clear() {
+        this.entries.clear();
+    }
+    /**
+     * Touch an entry to refresh its TTL without returning the value.
+     *
+     * @param key - Key to touch
+     * @returns True if entry exists
+     */
+    touch(key) {
+        const entry = this.entries.get(key);
+        if (!entry || this.isExpired(entry))
+            return false;
+        entry.lastAccessedAt = Date.now();
+        return true;
+    }
+    /**
+     * Get the age of an entry in milliseconds.
+     *
+     * @param key - Key to check
+     * @returns Age in ms, or undefined if not found
+     */
+    getAge(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        return Date.now() - entry.createdAt;
+    }
+    /**
+     * Get remaining TTL for an entry in milliseconds.
+     *
+     * @param key - Key to check
+     * @returns Remaining TTL in ms, or undefined if not found/expired
+     */
+    getRemainingTtl(key) {
+        const entry = this.entries.get(key);
+        if (!entry)
+            return undefined;
+        const elapsed = Date.now() - entry.lastAccessedAt;
+        const remaining = this.ttlMs - elapsed;
+        return remaining > 0 ? remaining : 0;
+    }
+    /**
+     * Iterate over all non-expired entries.
+     */
+    *[Symbol.iterator]() {
+        for (const [key, entry] of this.entries) {
+            if (!this.isExpired(entry)) {
+                yield [key, entry.value];
+            }
+        }
+    }
+    /**
+     * Get all keys (non-expired).
+     */
+    *keys() {
+        for (const [key, entry] of this.entries) {
+            if (!this.isExpired(entry)) {
+                yield key;
+            }
+        }
+    }
+    /**
+     * Get all values (non-expired).
+     */
+    *values() {
+        for (const [, entry] of this.entries) {
+            if (!this.isExpired(entry)) {
+                yield entry.value;
+            }
+        }
+    }
+    /**
+     * Run cleanup immediately, removing all expired entries.
+     *
+     * @returns Number of entries removed
+     */
+    cleanup() {
+        let removed = 0;
+        const now = Date.now();
+        for (const [key, entry] of this.entries) {
+            if (now - entry.lastAccessedAt > this.ttlMs) {
+                this.entries.delete(key);
+                this.onExpire?.(key, entry.value);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /**
+     * Dispose the map, stopping cleanup timer and clearing entries.
+     */
+    dispose() {
+        if (this._isDisposed)
+            return;
+        this._isDisposed = true;
+        this.stopCleanup();
+        this.entries.clear();
+    }
+    /**
+     * Check if an entry has expired.
+     */
+    isExpired(entry) {
+        return Date.now() - entry.lastAccessedAt > this.ttlMs;
+    }
+    /**
+     * Start the periodic cleanup timer.
+     */
+    startCleanup() {
+        if (this.cleanupTimer)
+            return;
+        this.cleanupTimer = setInterval(() => {
+            if (!this._isDisposed) {
+                this.cleanup();
+            }
+        }, this.cleanupIntervalMs);
+        // Don't prevent process exit
+        this.cleanupTimer.unref();
+    }
+    /**
+     * Stop the periodic cleanup timer.
+     */
+    stopCleanup() {
+        if (this.cleanupTimer) {
+            clearInterval(this.cleanupTimer);
+            this.cleanupTimer = null;
+        }
+    }
+}
+//# sourceMappingURL=stale-expiration-map.js.map

package/dist/utils/stale-expiration-map.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"stale-expiration-map.js","sourceRoot":"","sources":["../../src/utils/stale-expiration-map.ts"],"names":[],"mappings":"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"}

package/dist/utils/string-similarity.d.ts

@@ -0,0 +1,108 @@
+/**
+ * @fileoverview String similarity utilities for fuzzy matching.
+ *
+ * Provides Levenshtein distance and similarity scoring for:
+ * - Completion phrase fuzzy matching
+ * - Todo content deduplication
+ *
+ * @module utils/string-similarity
+ */
+/**
+ * Calculate the Levenshtein (edit) distance between two strings.
+ * This is the minimum number of single-character edits (insertions,
+ * deletions, or substitutions) required to change one string into the other.
+ *
+ * Uses Wagner-Fischer algorithm with O(min(m,n)) space optimization.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns The edit distance (0 = identical)
+ *
+ * @example
+ * levenshteinDistance('hello', 'hello') // 0
+ * levenshteinDistance('hello', 'helo')  // 1 (one deletion)
+ * levenshteinDistance('COMPLETE', 'COMPLET') // 1 (one deletion)
+ */
+export declare function levenshteinDistance(a: string, b: string): number;
+/**
+ * Calculate similarity ratio between two strings (0 to 1).
+ * Uses Levenshtein distance normalized by the longer string's length.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @returns Similarity ratio (1.0 = identical, 0.0 = completely different)
+ *
+ * @example
+ * stringSimilarity('hello', 'hello') // 1.0
+ * stringSimilarity('hello', 'helo')  // 0.8 (4/5 similar)
+ * stringSimilarity('abc', 'xyz')     // 0.0 (3 edits, length 3)
+ */
+export declare function stringSimilarity(a: string, b: string): number;
+/**
+ * Check if two strings are similar within a given threshold.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @param threshold - Minimum similarity ratio (default: 0.85 = 85% similar)
+ * @returns True if similarity >= threshold
+ *
+ * @example
+ * isSimilar('COMPLETE', 'COMPLET', 0.85)  // true (87.5% similar)
+ * isSimilar('COMPLETE', 'DONE', 0.85)     // false (0% similar)
+ */
+export declare function isSimilar(a: string, b: string, threshold?: number): boolean;
+/**
+ * Check if two strings are similar with edit distance tolerance.
+ * More intuitive for short strings than percentage-based threshold.
+ *
+ * @param a - First string
+ * @param b - Second string
+ * @param maxDistance - Maximum allowed edit distance (default: 2)
+ * @returns True if edit distance <= maxDistance
+ *
+ * @example
+ * isSimilarByDistance('COMPLETE', 'COMPLET', 2)   // true (distance 1)
+ * isSimilarByDistance('COMPLETE', 'COMP', 2)     // false (distance 4)
+ */
+export declare function isSimilarByDistance(a: string, b: string, maxDistance?: number): boolean;
+/**
+ * Normalize a completion phrase for comparison.
+ * Handles variations in case, whitespace, and separators.
+ *
+ * @param phrase - Raw completion phrase
+ * @returns Normalized phrase (uppercase, no separators)
+ *
+ * @example
+ * normalizePhrase('task_done')   // 'TASKDONE'
+ * normalizePhrase('TASK-DONE')   // 'TASKDONE'
+ * normalizePhrase('Task Done')   // 'TASKDONE'
+ */
+export declare function normalizePhrase(phrase: string): string;
+/**
+ * Check if two completion phrases match with fuzzy tolerance.
+ *
+ * First normalizes both phrases, then checks:
+ * 1. Exact match after normalization
+ * 2. Edit distance <= maxDistance for typo tolerance
+ *
+ * @param phrase1 - First phrase to compare
+ * @param phrase2 - Second phrase to compare
+ * @param maxDistance - Maximum edit distance for fuzzy match (default: 2)
+ * @returns True if phrases match (exact or fuzzy)
+ *
+ * @example
+ * fuzzyPhraseMatch('COMPLETE', 'COMPLETE')        // true (exact)
+ * fuzzyPhraseMatch('COMPLETE', 'COMPLET')         // true (typo)
+ * fuzzyPhraseMatch('TASK_DONE', 'TASKDONE')       // true (separator)
+ * fuzzyPhraseMatch('COMPLETE', 'FINISHED')        // false (different word)
+ */
+export declare function fuzzyPhraseMatch(phrase1: string, phrase2: string, maxDistance?: number): boolean;
+/**
+ * Generate a content hash for todo deduplication.
+ * Normalizes content and generates a simple hash.
+ *
+ * @param content - Todo item content
+ * @returns Normalized hash string for comparison
+ */
+export declare function todoContentHash(content: string): string;
+//# sourceMappingURL=string-similarity.d.ts.map

package/dist/utils/string-similarity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"string-similarity.d.ts","sourceRoot":"","sources":["../../src/utils/string-similarity.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CA0ChE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAQ7D;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,SAAS,SAAO,GAAG,OAAO,CAEzE;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,EAAE,WAAW,SAAI,GAAG,OAAO,CAElF;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAKtD;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,WAAW,SAAI,GAAG,OAAO,CAe3F;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAgBvD"}