distill-mcp 0.6.0-beta

package/dist/ast/typescript.js

@@ -0,0 +1,357 @@
+/**
+ * TypeScript/JavaScript Parser
+ *
+ * Uses TypeScript Compiler API for accurate AST parsing.
+ */
+import ts from "typescript";
+import { createEmptyStructure } from "./types.js";
+/**
+ * Get line number from position in source file
+ */
+function getLineNumber(sourceFile, pos) {
+    return sourceFile.getLineAndCharacterOfPosition(pos).line + 1;
+}
+/**
+ * Get JSDoc comment for a node
+ */
+function getJSDoc(node) {
+    // Use ts.getJSDocCommentsAndTags which works across all node types
+    const jsDocs = ts.getJSDocCommentsAndTags(node);
+    if (jsDocs && jsDocs.length > 0) {
+        return jsDocs.map((doc) => doc.getText()).join("\n");
+    }
+    return undefined;
+}
+/**
+ * Check if a node has an export modifier
+ */
+function isExported(node) {
+    const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+    return modifiers?.some((m) => m.kind === ts.SyntaxKind.ExportKeyword) ?? false;
+}
+/**
+ * Check if a function is async
+ */
+function isAsync(node) {
+    const modifiers = ts.canHaveModifiers(node) ? ts.getModifiers(node) : undefined;
+    return modifiers?.some((m) => m.kind === ts.SyntaxKind.AsyncKeyword) ?? false;
+}
+/**
+ * Get function signature
+ */
+function getFunctionSignature(node, sourceFile) {
+    const params = node.parameters.map((p) => p.getText(sourceFile)).join(", ");
+    const returnType = node.type ? `: ${node.type.getText(sourceFile)}` : "";
+    const asyncMod = isAsync(node) ? "async " : "";
+    if (ts.isFunctionDeclaration(node) || ts.isMethodDeclaration(node)) {
+        const name = node.name?.getText(sourceFile) ?? "anonymous";
+        return `${asyncMod}function ${name}(${params})${returnType}`;
+    }
+    return `${asyncMod}(${params})${returnType} =>`;
+}
+/**
+ * Parse TypeScript/JavaScript content into FileStructure
+ * @param options ParseOptions - set detailed: true to extract signature/documentation
+ */
+export function parseTypeScript(content, isTypeScript = true, options = {}) {
+    const { detailed = false } = options;
+    const sourceFile = ts.createSourceFile(isTypeScript ? "temp.ts" : "temp.js", content, ts.ScriptTarget.Latest, true, isTypeScript ? ts.ScriptKind.TS : ts.ScriptKind.JS);
+    const language = isTypeScript ? "typescript" : "javascript";
+    const structure = createEmptyStructure(language, content.split("\n").length);
+    function visit(node, parentClass) {
+        const startLine = getLineNumber(sourceFile, node.getStart(sourceFile));
+        const endLine = getLineNumber(sourceFile, node.getEnd());
+        // Import declarations
+        if (ts.isImportDeclaration(node)) {
+            const importClause = node.importClause;
+            const moduleSpecifier = node.moduleSpecifier.getText(sourceFile).replace(/['"]/g, "");
+            if (importClause) {
+                // Default import
+                if (importClause.name) {
+                    const imp = {
+                        type: "import",
+                        name: importClause.name.getText(sourceFile),
+                        startLine,
+                        endLine,
+                    };
+                    if (detailed) {
+                        imp.signature = `import ${importClause.name.getText(sourceFile)} from "${moduleSpecifier}"`;
+                    }
+                    structure.imports.push(imp);
+                }
+                // Named imports
+                if (importClause.namedBindings && ts.isNamedImports(importClause.namedBindings)) {
+                    for (const element of importClause.namedBindings.elements) {
+                        const imp = {
+                            type: "import",
+                            name: element.name.getText(sourceFile),
+                            startLine,
+                            endLine,
+                        };
+                        if (detailed) {
+                            imp.signature = `import { ${element.name.getText(sourceFile)} } from "${moduleSpecifier}"`;
+                        }
+                        structure.imports.push(imp);
+                    }
+                }
+            }
+        }
+        // Function declarations
+        if (ts.isFunctionDeclaration(node) && node.name) {
+            const fn = {
+                type: "function",
+                name: node.name.getText(sourceFile),
+                startLine,
+                endLine,
+                isExported: isExported(node),
+                isAsync: isAsync(node),
+            };
+            if (detailed) {
+                fn.signature = getFunctionSignature(node, sourceFile);
+                fn.documentation = getJSDoc(node);
+            }
+            structure.functions.push(fn);
+        }
+        // Variable declarations with arrow functions
+        if (ts.isVariableStatement(node)) {
+            for (const decl of node.declarationList.declarations) {
+                if (decl.name && ts.isIdentifier(decl.name)) {
+                    const name = decl.name.getText(sourceFile);
+                    if (decl.initializer && ts.isArrowFunction(decl.initializer)) {
+                        const fn = {
+                            type: "function",
+                            name,
+                            startLine,
+                            endLine,
+                            isExported: isExported(node),
+                            isAsync: isAsync(decl.initializer),
+                        };
+                        if (detailed) {
+                            fn.signature = `const ${name} = ${getFunctionSignature(decl.initializer, sourceFile)}`;
+                            fn.documentation = getJSDoc(node);
+                        }
+                        structure.functions.push(fn);
+                    }
+                    else {
+                        structure.variables.push({
+                            type: "variable",
+                            name,
+                            startLine,
+                            endLine,
+                            isExported: isExported(node),
+                        });
+                    }
+                }
+            }
+        }
+        // Class declarations
+        if (ts.isClassDeclaration(node) && node.name) {
+            const className = node.name.getText(sourceFile);
+            const cls = {
+                type: "class",
+                name: className,
+                startLine,
+                endLine,
+                isExported: isExported(node),
+            };
+            if (detailed) {
+                cls.documentation = getJSDoc(node);
+            }
+            structure.classes.push(cls);
+            // Visit class members
+            for (const member of node.members) {
+                if (ts.isMethodDeclaration(member) && member.name) {
+                    const methodName = member.name.getText(sourceFile);
+                    const methodStart = getLineNumber(sourceFile, member.getStart(sourceFile));
+                    const methodEnd = getLineNumber(sourceFile, member.getEnd());
+                    const method = {
+                        type: "method",
+                        name: methodName,
+                        startLine: methodStart,
+                        endLine: methodEnd,
+                        isAsync: isAsync(member),
+                        parent: className,
+                    };
+                    if (detailed) {
+                        method.signature = getFunctionSignature(member, sourceFile);
+                        method.documentation = getJSDoc(member);
+                    }
+                    structure.functions.push(method);
+                }
+            }
+        }
+        // Interface declarations
+        if (ts.isInterfaceDeclaration(node) && node.name) {
+            const iface = {
+                type: "interface",
+                name: node.name.getText(sourceFile),
+                startLine,
+                endLine,
+                isExported: isExported(node),
+            };
+            if (detailed) {
+                iface.documentation = getJSDoc(node);
+            }
+            structure.interfaces.push(iface);
+        }
+        // Type alias declarations
+        if (ts.isTypeAliasDeclaration(node) && node.name) {
+            const typeAlias = {
+                type: "type",
+                name: node.name.getText(sourceFile),
+                startLine,
+                endLine,
+                isExported: isExported(node),
+            };
+            if (detailed) {
+                typeAlias.documentation = getJSDoc(node);
+            }
+            structure.types.push(typeAlias);
+        }
+        // Export declarations
+        if (ts.isExportDeclaration(node)) {
+            if (node.exportClause && ts.isNamedExports(node.exportClause)) {
+                for (const element of node.exportClause.elements) {
+                    structure.exports.push({
+                        type: "export",
+                        name: element.name.getText(sourceFile),
+                        startLine,
+                        endLine,
+                    });
+                }
+            }
+        }
+        ts.forEachChild(node, (child) => visit(child, parentClass));
+    }
+    visit(sourceFile);
+    return structure;
+}
+/**
+ * Find identifiers used in a code snippet
+ */
+function findUsedIdentifiers(code) {
+    const identifiers = new Set();
+    // Simple regex to find potential identifiers (not perfect but good enough)
+    const matches = code.match(/\b[A-Za-z_][A-Za-z0-9_]*\b/g);
+    if (matches) {
+        matches.forEach((m) => identifiers.add(m));
+    }
+    return identifiers;
+}
+/**
+ * Find related imports for extracted code
+ */
+function findRelatedImports(content, structure, extractedCode) {
+    const usedIds = findUsedIdentifiers(extractedCode);
+    const lines = content.split("\n");
+    const imports = [];
+    for (const imp of structure.imports) {
+        if (usedIds.has(imp.name)) {
+            const importLine = lines[imp.startLine - 1];
+            if (importLine && !imports.includes(importLine)) {
+                imports.push(importLine);
+            }
+        }
+    }
+    return imports;
+}
+/**
+ * Extract a specific element from TypeScript content
+ */
+export function extractTypeScriptElement(content, target, options, isTypeScript = true) {
+    // Extraction needs detailed parsing for proper signature/documentation display
+    const structure = parseTypeScript(content, isTypeScript, { detailed: true });
+    // Find the target element
+    let element;
+    switch (target.type) {
+        case "function":
+        case "method":
+            element = structure.functions.find((f) => f.name === target.name);
+            break;
+        case "class":
+            element = structure.classes.find((c) => c.name === target.name);
+            break;
+        case "interface":
+            element = structure.interfaces.find((i) => i.name === target.name);
+            break;
+        case "type":
+            element = structure.types.find((t) => t.name === target.name);
+            break;
+        case "variable":
+            element = structure.variables.find((v) => v.name === target.name);
+            break;
+    }
+    if (!element) {
+        return null;
+    }
+    const lines = content.split("\n");
+    // Include documentation if present and requested
+    let startLine = element.startLine;
+    if (options.includeComments && element.documentation) {
+        // Look for JSDoc above the element
+        for (let i = element.startLine - 2; i >= 0; i--) {
+            const line = lines[i]?.trim() ?? "";
+            if (line.startsWith("/**") || line.startsWith("*") || line.startsWith("*/")) {
+                startLine = i + 1;
+            }
+            else if (line === "") {
+                continue;
+            }
+            else {
+                break;
+            }
+        }
+    }
+    const extractedLines = lines.slice(startLine - 1, element.endLine);
+    const extractedCode = extractedLines.join("\n");
+    // Find related imports
+    const relatedImports = options.includeImports
+        ? findRelatedImports(content, structure, extractedCode)
+        : [];
+    return {
+        content: extractedCode,
+        elements: [element],
+        relatedImports,
+        startLine,
+        endLine: element.endLine,
+    };
+}
+/**
+ * Search for elements matching a query
+ */
+export function searchTypeScriptElements(content, query) {
+    // Search needs detailed parsing to match against signature/documentation
+    const structure = parseTypeScript(content, true, { detailed: true });
+    const queryLower = query.toLowerCase();
+    const results = [];
+    const allElements = [
+        ...structure.functions,
+        ...structure.classes,
+        ...structure.interfaces,
+        ...structure.types,
+        ...structure.variables,
+    ];
+    for (const element of allElements) {
+        if (element.name.toLowerCase().includes(queryLower) ||
+            element.signature?.toLowerCase().includes(queryLower) ||
+            element.documentation?.toLowerCase().includes(queryLower)) {
+            results.push(element);
+        }
+    }
+    return results;
+}
+/**
+ * TypeScript parser implementation
+ */
+export const typescriptParser = {
+    languages: ["typescript", "javascript"],
+    parse(content, options) {
+        return parseTypeScript(content, true, options);
+    },
+    extractElement(content, target, options) {
+        return extractTypeScriptElement(content, target, options, true);
+    },
+    searchElements(content, query) {
+        return searchTypeScriptElements(content, query);
+    },
+};

package/dist/cache/file-hash.d.ts

@@ -0,0 +1,33 @@
+/**
+ * File Hash Utilities
+ *
+ * Computes fast file hashes for cache validation.
+ * Uses a combination of file stats (mtime, size) for speed,
+ * with optional content hash for accuracy.
+ */
+import type { FileHashInfo } from "./types.js";
+/**
+ * Compute a fast hash based on file stats (mtime + size)
+ * This is fast but may miss in-place edits with same size
+ *
+ * @param filePath - Path to the file
+ * @returns FileHashInfo or null if file doesn't exist
+ */
+export declare function computeFastFileHash(filePath: string): Promise<FileHashInfo | null>;
+/**
+ * Compute a content-based hash (slower but accurate)
+ * Use for critical files or when fast hash fails validation
+ *
+ * @param filePath - Path to the file
+ * @returns MD5 hash string or null if file doesn't exist
+ */
+export declare function computeContentHash(filePath: string): Promise<string | null>;
+/**
+ * Validate if a file has changed since the hash was computed
+ *
+ * @param filePath - Path to the file
+ * @param storedHash - Previously computed hash to compare against
+ * @returns true if file is unchanged, false if changed or doesn't exist
+ */
+export declare function validateFileHash(filePath: string, storedHash: string): Promise<boolean>;
+//# sourceMappingURL=file-hash.d.ts.map

package/dist/cache/file-hash.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-hash.d.ts","sourceRoot":"","sources":["../../src/cache/file-hash.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAIH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C;;;;;;GAMG;AACH,wBAAsB,mBAAmB,CACvC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAY9B;AAED;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOxB;AAED;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,OAAO,CAAC,CAIlB"}

package/dist/cache/file-hash.js

@@ -0,0 +1,59 @@
+/**
+ * File Hash Utilities
+ *
+ * Computes fast file hashes for cache validation.
+ * Uses a combination of file stats (mtime, size) for speed,
+ * with optional content hash for accuracy.
+ */
+import * as fs from "fs/promises";
+import * as crypto from "crypto";
+/**
+ * Compute a fast hash based on file stats (mtime + size)
+ * This is fast but may miss in-place edits with same size
+ *
+ * @param filePath - Path to the file
+ * @returns FileHashInfo or null if file doesn't exist
+ */
+export async function computeFastFileHash(filePath) {
+    try {
+        const stats = await fs.stat(filePath);
+        const hash = `${stats.mtimeMs}-${stats.size}`;
+        return {
+            hash,
+            mtime: stats.mtimeMs,
+            size: stats.size,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compute a content-based hash (slower but accurate)
+ * Use for critical files or when fast hash fails validation
+ *
+ * @param filePath - Path to the file
+ * @returns MD5 hash string or null if file doesn't exist
+ */
+export async function computeContentHash(filePath) {
+    try {
+        const content = await fs.readFile(filePath);
+        return crypto.createHash("md5").update(content).digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Validate if a file has changed since the hash was computed
+ *
+ * @param filePath - Path to the file
+ * @param storedHash - Previously computed hash to compare against
+ * @returns true if file is unchanged, false if changed or doesn't exist
+ */
+export async function validateFileHash(filePath, storedHash) {
+    const currentHash = await computeFastFileHash(filePath);
+    if (!currentHash)
+        return false;
+    return currentHash.hash === storedHash;
+}

package/dist/cache/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Smart Cache Module
+ *
+ * Exports for the LRU cache with TTL and file hash validation.
+ */
+export * from "./types.js";
+export * from "./smart-cache.js";
+export * from "./file-hash.js";
+//# 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,cAAc,YAAY,CAAC;AAC3B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC"}

package/dist/cache/index.js

@@ -0,0 +1,8 @@
+/**
+ * Smart Cache Module
+ *
+ * Exports for the LRU cache with TTL and file hash validation.
+ */
+export * from "./types.js";
+export * from "./smart-cache.js";
+export * from "./file-hash.js";

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

@@ -0,0 +1,68 @@
+/**
+ * Smart Cache Implementation
+ *
+ * LRU cache with TTL and file hash validation.
+ * Designed for caching parsed file content but works for any data.
+ */
+import type { CacheStats, CacheConfig, CacheKey, CacheGetResult, SmartCacheOptions } from "./types.js";
+/**
+ * Smart Cache class with LRU eviction, TTL expiration, and file hash validation
+ */
+export declare class SmartCache {
+    private cache;
+    private config;
+    private stats;
+    private operationCount;
+    constructor(config?: Partial<CacheConfig>);
+    /**
+     * Get a value from cache with automatic validation
+     */
+    get<T>(key: CacheKey): Promise<CacheGetResult<T>>;
+    /**
+     * Set a value in cache
+     */
+    set<T>(key: CacheKey, value: T, options?: SmartCacheOptions): Promise<void>;
+    /**
+     * Invalidate a specific cache entry
+     */
+    invalidate(key: CacheKey): boolean;
+    /**
+     * Invalidate all entries for a specific file path
+     */
+    invalidateByPath(filePath: string): number;
+    /**
+     * Clear all cache entries
+     */
+    clear(): void;
+    /**
+     * Get cache statistics
+     */
+    getStats(): CacheStats;
+    /**
+     * Get list of cached keys (for debugging/inspection)
+     */
+    getKeys(): CacheKey[];
+    /**
+     * Check if a key exists (without updating access time)
+     */
+    has(key: CacheKey): boolean;
+    /**
+     * Get the number of entries in cache
+     */
+    get size(): number;
+    private updateHitRate;
+    private estimateSize;
+    private ensureCapacity;
+    private evictLRU;
+    private maybeCleanup;
+    private cleanupExpired;
+}
+/**
+ * Get the global cache instance (creates one if needed)
+ */
+export declare function getGlobalCache(): SmartCache;
+/**
+ * Reset the global cache (for testing or explicit reset)
+ */
+export declare function resetGlobalCache(): void;
+//# sourceMappingURL=smart-cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"smart-cache.d.ts","sourceRoot":"","sources":["../../src/cache/smart-cache.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAEV,UAAU,EACV,WAAW,EACX,QAAQ,EACR,cAAc,EACd,iBAAiB,EAClB,MAAM,YAAY,CAAC;AAYpB;;GAEG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,KAAK,CAA4B;IACzC,OAAO,CAAC,MAAM,CAAc;IAC5B,OAAO,CAAC,KAAK,CAAa;IAC1B,OAAO,CAAC,cAAc,CAAS;gBAEnB,MAAM,GAAE,OAAO,CAAC,WAAW,CAAM;IAgB7C;;OAEG;IACG,GAAG,CAAC,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,OAAO,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC;IAuDvD;;OAEG;IACG,GAAG,CAAC,CAAC,EACT,GAAG,EAAE,QAAQ,EACb,KAAK,EAAE,CAAC,EACR,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,IAAI,CAAC;IA6ChB;;OAEG;IACH,UAAU,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO;IAYlC;;OAEG;IACH,gBAAgB,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM;IAc1C;;OAEG;IACH,KAAK,IAAI,IAAI;IAMb;;OAEG;IACH,QAAQ,IAAI,UAAU;IAItB;;OAEG;IACH,OAAO,IAAI,QAAQ,EAAE;IAIrB;;OAEG;IACH,GAAG,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO;IAI3B;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;IAID,OAAO,CAAC,aAAa;IAMrB,OAAO,CAAC,YAAY;YAUN,cAAc;IAe5B,OAAO,CAAC,QAAQ;IAoBhB,OAAO,CAAC,YAAY;IAOpB,OAAO,CAAC,cAAc;CAWvB;AAKD;;GAEG;AACH,wBAAgB,cAAc,IAAI,UAAU,CAK3C;AAED;;GAEG;AACH,wBAAgB,gBAAgB,IAAI,IAAI,CAEvC"}