bobs-workshop 0.2.7 → 0.3.1

package/dist/tools/structural/cache.js

@@ -0,0 +1,226 @@
+import { LRUCache } from "lru-cache";
+import { createHash } from "crypto";
+import { readFile, stat } from "fs/promises";
+import { AnalysisError, ErrorCode } from "./types.js";
+export class CacheManager {
+    constructor(options = {}) {
+        this.stats = {
+            hits: 0,
+            misses: 0,
+            evictions: 0,
+            memoryUsage: 0
+        };
+        this.options = {
+            invalidation: options.invalidation || "content-hash",
+            ttl: options.ttl || 3600000 // 1 hour default
+        };
+        // Initialize LRU caches as per specification
+        this.fileCache = new LRUCache({
+            max: 1000,
+            dispose: (value) => {
+                // Clean up source file when evicted
+                if (value?.sourceFile) {
+                    try {
+                        value.sourceFile.forget();
+                    }
+                    catch (e) {
+                        // Ignore cleanup errors
+                    }
+                }
+                this.stats.evictions++;
+            }
+        });
+        this.symbolCache = new LRUCache({
+            max: 10000,
+            dispose: () => {
+                this.stats.evictions++;
+            }
+        });
+        this.analysisCache = new LRUCache({
+            max: 5000,
+            dispose: () => {
+                this.stats.evictions++;
+            }
+        });
+    }
+    async getContentHash(filePath) {
+        try {
+            const content = await readFile(filePath, "utf8");
+            return createHash("sha256").update(content).digest("hex");
+        }
+        catch (error) {
+            throw new AnalysisError({
+                code: ErrorCode.FILE_NOT_FOUND,
+                message: `Failed to read file for hashing: ${filePath}`,
+                details: { file: filePath }
+            });
+        }
+    }
+    async getFileStats(filePath) {
+        try {
+            const stats = await stat(filePath);
+            return {
+                lastModified: stats.mtimeMs,
+                size: stats.size
+            };
+        }
+        catch (error) {
+            throw new AnalysisError({
+                code: ErrorCode.FILE_NOT_FOUND,
+                message: `Failed to get file stats: ${filePath}`,
+                details: { file: filePath }
+            });
+        }
+    }
+    async isFileCacheValid(filePath, cached) {
+        if (this.options.invalidation === "manual") {
+            return true;
+        }
+        const stats = await this.getFileStats(filePath);
+        if (this.options.invalidation === "timestamp") {
+            return stats.lastModified <= cached.lastModified;
+        }
+        if (this.options.invalidation === "content-hash") {
+            const currentHash = await this.getContentHash(filePath);
+            return currentHash === cached.contentHash;
+        }
+        return false;
+    }
+    async getCachedFile(filePath) {
+        const cached = this.fileCache.get(filePath);
+        if (cached && await this.isFileCacheValid(filePath, cached)) {
+            this.stats.hits++;
+            return cached;
+        }
+        if (cached) {
+            this.fileCache.delete(filePath);
+        }
+        this.stats.misses++;
+        return undefined;
+    }
+    async setCachedFile(filePath, sourceFile) {
+        const stats = await this.getFileStats(filePath);
+        const contentHash = this.options.invalidation === "content-hash"
+            ? await this.getContentHash(filePath)
+            : "";
+        this.fileCache.set(filePath, {
+            sourceFile,
+            lastModified: stats.lastModified,
+            contentHash
+        });
+    }
+    getCachedSymbol(key) {
+        const cached = this.symbolCache.get(key);
+        if (cached) {
+            this.stats.hits++;
+            return cached;
+        }
+        this.stats.misses++;
+        return undefined;
+    }
+    setCachedSymbol(key, symbol) {
+        this.symbolCache.set(key, symbol);
+    }
+    async getCachedAnalysis(key) {
+        const cached = this.analysisCache.get(key);
+        if (!cached) {
+            this.stats.misses++;
+            return undefined;
+        }
+        // Check TTL
+        if (Date.now() - cached.timestamp > this.options.ttl) {
+            this.analysisCache.delete(key);
+            this.stats.misses++;
+            return undefined;
+        }
+        this.stats.hits++;
+        return cached.data;
+    }
+    async setCachedAnalysis(key, data) {
+        this.analysisCache.set(key, {
+            data,
+            timestamp: Date.now()
+        });
+    }
+    generateCacheKey(...parts) {
+        const normalized = parts.map(part => {
+            if (part === undefined || part === null) {
+                return "null";
+            }
+            if (typeof part === "object") {
+                return JSON.stringify(part, Object.keys(part).sort());
+            }
+            return String(part);
+        }).join(":");
+        return createHash("sha256").update(normalized).digest("hex");
+    }
+    async clearFileCache() {
+        this.fileCache.clear();
+    }
+    async clearSymbolCache() {
+        this.symbolCache.clear();
+    }
+    async clearAnalysisCache() {
+        this.analysisCache.clear();
+    }
+    async clearAll() {
+        await this.clearFileCache();
+        await this.clearSymbolCache();
+        await this.clearAnalysisCache();
+    }
+    getMemoryUsage() {
+        const fileCount = this.fileCache.size;
+        const symbolCount = this.symbolCache.size;
+        const analysisCount = this.analysisCache.size;
+        // Rough estimation of memory usage
+        const avgFileSize = 50 * 1024; // 50KB average per file
+        const avgSymbolSize = 1024; // 1KB average per symbol
+        const avgAnalysisSize = 2 * 1024; // 2KB average per analysis
+        const totalMemory = (fileCount * avgFileSize) + (symbolCount * avgSymbolSize) + (analysisCount * avgAnalysisSize);
+        this.stats.memoryUsage = totalMemory;
+        return totalMemory;
+    }
+    getStats() {
+        return {
+            fileCache: {
+                size: this.fileCache.size,
+                capacity: 1000
+            },
+            symbolCache: {
+                size: this.symbolCache.size,
+                capacity: 10000
+            },
+            analysisCache: {
+                size: this.analysisCache.size,
+                capacity: 5000
+            },
+            stats: { ...this.stats, memoryUsage: this.getMemoryUsage() }
+        };
+    }
+    // Cache strategy based on project size
+    static getCacheStrategy(fileCount) {
+        if (fileCount < 100)
+            return "memory";
+        if (fileCount < 1000)
+            return "memory";
+        if (fileCount < 5000)
+            return "hybrid";
+        return "disk";
+    }
+}
+// Global cache instance
+export const cacheManager = new CacheManager();
+// Helper for caching function results
+export function memoize(fn, keyGenerator) {
+    return (async (...args) => {
+        const key = keyGenerator ? keyGenerator(...args) : cacheManager.generateCacheKey(...args);
+        const cached = await cacheManager.getCachedAnalysis(key);
+        if (cached !== undefined) {
+            return cached;
+        }
+        const result = await fn(...args);
+        await cacheManager.setCachedAnalysis(key, result);
+        return result;
+    });
+}
+//# sourceMappingURL=cache.js.map

package/dist/tools/structural/cache.js.map

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

package/dist/tools/structural/engines/python/index.js

@@ -0,0 +1,118 @@
+import { ErrorCode, AnalysisError } from "../../types.js";
+/**
+ * Python Structural Search Engine (Stub Implementation)
+ *
+ * This is a placeholder for the Python structural search engine.
+ * Full implementation will use libcst for AST parsing and analysis.
+ *
+ * Planned features:
+ * - Find references and definitions in Python code
+ * - Analyze dependencies (import statements)
+ * - Detect circular dependencies
+ * - Find unused exports
+ * - Call graph analysis
+ */
+export class PythonEngine {
+    /**
+     * Find all references to a symbol
+     * @throws {AnalysisError} Not implemented
+     */
+    async findReferences(symbolName, scope, options) {
+        throw new AnalysisError({
+            code: ErrorCode.PARSE_ERROR,
+            message: "Python structural search is not yet implemented. This feature is planned for Phase 2.",
+            details: {
+                symbolName,
+                file: scope,
+                suggestion: "Use lexical or semantic search modes for Python files, or contribute to the Python engine implementation!"
+            }
+        });
+    }
+    /**
+     * Find the definition of a symbol
+     * @throws {AnalysisError} Not implemented
+     */
+    async findDefinition(symbolName, scope, options) {
+        throw new AnalysisError({
+            code: ErrorCode.PARSE_ERROR,
+            message: "Python structural search is not yet implemented. This feature is planned for Phase 2.",
+            details: {
+                symbolName,
+                file: scope,
+                suggestion: "Use lexical or semantic search modes for Python files, or contribute to the Python engine implementation!"
+            }
+        });
+    }
+    /**
+     * Get dependencies of a file or symbol
+     * @throws {AnalysisError} Not implemented
+     */
+    async getDependencies(target, options) {
+        throw new AnalysisError({
+            code: ErrorCode.PARSE_ERROR,
+            message: "Python structural search is not yet implemented. This feature is planned for Phase 2.",
+            details: {
+                file: target,
+                suggestion: "Use lexical or semantic search modes for Python files, or contribute to the Python engine implementation!"
+            }
+        });
+    }
+    /**
+     * Get dependency graph
+     * @throws {AnalysisError} Not implemented
+     */
+    async getDependencyGraph(filePath, depth = 2) {
+        throw new AnalysisError({
+            code: ErrorCode.PARSE_ERROR,
+            message: "Python structural search is not yet implemented. This feature is planned for Phase 2.",
+            details: {
+                file: filePath,
+                suggestion: "Use lexical or semantic search modes for Python files, or contribute to the Python engine implementation!"
+            }
+        });
+    }
+    /**
+     * Find architectural issues
+     * @throws {AnalysisError} Not implemented
+     */
+    async findArchitecturalIssues(scope) {
+        throw new AnalysisError({
+            code: ErrorCode.PARSE_ERROR,
+            message: "Python structural search is not yet implemented. This feature is planned for Phase 2.",
+            details: {
+                file: scope,
+                suggestion: "Use lexical or semantic search modes for Python files, or contribute to the Python engine implementation!"
+            }
+        });
+    }
+    /**
+     * Find unused exports
+     * @throws {AnalysisError} Not implemented
+     */
+    async findUnusedExports(scope) {
+        throw new AnalysisError({
+            code: ErrorCode.PARSE_ERROR,
+            message: "Python structural search is not yet implemented. This feature is planned for Phase 2.",
+            details: {
+                file: scope,
+                suggestion: "Use lexical or semantic search modes for Python files, or contribute to the Python engine implementation!"
+            }
+        });
+    }
+    /**
+     * Get refactor impact
+     * @throws {AnalysisError} Not implemented
+     */
+    async getRefactorImpact(symbol, scope) {
+        throw new AnalysisError({
+            code: ErrorCode.PARSE_ERROR,
+            message: "Python structural search is not yet implemented. This feature is planned for Phase 2.",
+            details: {
+                symbolName: symbol,
+                file: scope,
+                suggestion: "Use lexical or semantic search modes for Python files, or contribute to the Python engine implementation!"
+            }
+        });
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/tools/structural/engines/python/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../../src/tools/structural/engines/python/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAOL,SAAS,EACT,aAAa,EACd,MAAM,gBAAgB,CAAC;AAExB;;;;;;;;;;;;GAYG;AACH,MAAM,OAAO,YAAY;IACvB;;;OAGG;IACH,KAAK,CAAC,cAAc,CAClB,UAAkB,EAClB,KAAa,EACb,OAAiC;QAEjC,MAAM,IAAI,aAAa,CAAC;YACtB,IAAI,EAAE,SAAS,CAAC,WAAW;YAC3B,OAAO,EAAE,uFAAuF;YAChG,OAAO,EAAE;gBACP,UAAU;gBACV,IAAI,EAAE,KAAK;gBACX,UAAU,EAAE,2GAA2G;aACxH;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,cAAc,CAClB,UAAkB,EAClB,KAAa,EACb,OAAiC;QAEjC,MAAM,IAAI,aAAa,CAAC;YACtB,IAAI,EAAE,SAAS,CAAC,WAAW;YAC3B,OAAO,EAAE,uFAAuF;YAChG,OAAO,EAAE;gBACP,UAAU;gBACV,IAAI,EAAE,KAAK;gBACX,UAAU,EAAE,2GAA2G;aACxH;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,eAAe,CAAC,MAAc,EAAE,OAAiC;QACrE,MAAM,IAAI,aAAa,CAAC;YACtB,IAAI,EAAE,SAAS,CAAC,WAAW;YAC3B,OAAO,EAAE,uFAAuF;YAChG,OAAO,EAAE;gBACP,IAAI,EAAE,MAAM;gBACZ,UAAU,EAAE,2GAA2G;aACxH;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,kBAAkB,CAAC,QAAgB,EAAE,QAAgB,CAAC;QAC1D,MAAM,IAAI,aAAa,CAAC;YACtB,IAAI,EAAE,SAAS,CAAC,WAAW;YAC3B,OAAO,EAAE,uFAAuF;YAChG,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ;gBACd,UAAU,EAAE,2GAA2G;aACxH;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,uBAAuB,CAAC,KAAa;QACzC,MAAM,IAAI,aAAa,CAAC;YACtB,IAAI,EAAE,SAAS,CAAC,WAAW;YAC3B,OAAO,EAAE,uFAAuF;YAChG,OAAO,EAAE;gBACP,IAAI,EAAE,KAAK;gBACX,UAAU,EAAE,2GAA2G;aACxH;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,iBAAiB,CAAC,KAAa;QACnC,MAAM,IAAI,aAAa,CAAC;YACtB,IAAI,EAAE,SAAS,CAAC,WAAW;YAC3B,OAAO,EAAE,uFAAuF;YAChG,OAAO,EAAE;gBACP,IAAI,EAAE,KAAK;gBACX,UAAU,EAAE,2GAA2G;aACxH;SACF,CAAC,CAAC;IACL,CAAC;IAED;;;OAGG;IACH,KAAK,CAAC,iBAAiB,CAAC,MAAc,EAAE,KAAa;QACnD,MAAM,IAAI,aAAa,CAAC;YACtB,IAAI,EAAE,SAAS,CAAC,WAAW;YAC3B,OAAO,EAAE,uFAAuF;YAChG,OAAO,EAAE;gBACP,UAAU,EAAE,MAAM;gBAClB,IAAI,EAAE,KAAK;gBACX,UAAU,EAAE,2GAA2G;aACxH;SACF,CAAC,CAAC;IACL,CAAC;CACF"}

package/dist/tools/structural/engines/typescript/__tests__/typescript-engine.test.js

@@ -0,0 +1,97 @@
+import { TypeScriptEngine } from '../index.js';
+import { describe, it, expect, beforeEach } from '@jest/globals';
+describe('TypeScriptEngine', () => {
+    let engine;
+    beforeEach(() => {
+        engine = new TypeScriptEngine();
+    });
+    describe('findReferences', () => {
+        it('should find references to a symbol', async () => {
+            // This is a placeholder test - in production, you'd use a test fixture
+            const results = await engine.findReferences('TypeScriptEngine', __dirname, { maxResults: 10 });
+            expect(Array.isArray(results)).toBe(true);
+        }, 30000); // 30 second timeout for AST parsing
+        it('should respect maxResults limit', async () => {
+            const results = await engine.findReferences('TypeScriptEngine', __dirname, { maxResults: 5 });
+            expect(results.length).toBeLessThanOrEqual(5);
+        }, 30000);
+        it('should handle non-existent symbols gracefully', async () => {
+            const results = await engine.findReferences('NonExistentSymbolXYZ123', __dirname, { maxResults: 10 });
+            expect(Array.isArray(results)).toBe(true);
+            expect(results.length).toBe(0);
+        }, 30000);
+    });
+    describe('findDefinition', () => {
+        it('should find definition of a symbol', async () => {
+            const result = await engine.findDefinition('TypeScriptEngine', __dirname);
+            // Result can be null if symbol not found in scope
+            expect(result === null || typeof result === 'object').toBe(true);
+        }, 30000);
+        it('should return null for non-existent symbols', async () => {
+            const result = await engine.findDefinition('NonExistentSymbolXYZ123', __dirname);
+            expect(result).toBeNull();
+        }, 30000);
+    });
+    describe('getDependencies', () => {
+        it('should get dependencies for a file', async () => {
+            const results = await engine.getDependencies(__filename, { maxResults: 20 });
+            expect(Array.isArray(results)).toBe(true);
+        }, 30000);
+        it('should return import information', async () => {
+            const results = await engine.getDependencies(__filename, { maxResults: 20 });
+            if (results.length > 0) {
+                expect(results[0]).toHaveProperty('file');
+                expect(results[0]).toHaveProperty('symbol');
+                expect(results[0]).toHaveProperty('kind');
+            }
+        }, 30000);
+    });
+    describe('findArchitecturalIssues', () => {
+        it('should return an array of issues', async () => {
+            const issues = await engine.findArchitecturalIssues(__dirname);
+            expect(Array.isArray(issues)).toBe(true);
+        }, 30000);
+        it('should identify circular dependencies if present', async () => {
+            const issues = await engine.findArchitecturalIssues(__dirname);
+            // Issues array can be empty if no problems found
+            issues.forEach(issue => {
+                expect(issue).toHaveProperty('type');
+                expect(issue).toHaveProperty('severity');
+                expect(issue).toHaveProperty('message');
+                expect(issue).toHaveProperty('location');
+            });
+        }, 30000);
+    });
+    describe('findUnusedExports', () => {
+        it('should return an array of unused exports', async () => {
+            const unused = await engine.findUnusedExports(__dirname);
+            expect(Array.isArray(unused)).toBe(true);
+        }, 30000);
+        it('should include symbol name and location', async () => {
+            const unused = await engine.findUnusedExports(__dirname);
+            unused.forEach(item => {
+                expect(item).toHaveProperty('name');
+                expect(item).toHaveProperty('kind');
+                expect(item).toHaveProperty('location');
+                expect(item).toHaveProperty('exportedFrom');
+            });
+        }, 30000);
+    });
+    describe('getRefactorImpact', () => {
+        it('should calculate refactor impact', async () => {
+            const impact = await engine.getRefactorImpact('TypeScriptEngine', __dirname);
+            expect(impact).toHaveProperty('symbol');
+            expect(impact).toHaveProperty('referenceCount');
+            expect(impact).toHaveProperty('affectedFiles');
+            expect(impact).toHaveProperty('testFiles');
+            expect(Array.isArray(impact.affectedFiles)).toBe(true);
+            expect(Array.isArray(impact.testFiles)).toBe(true);
+        }, 30000);
+        it('should return zero references for non-existent symbol', async () => {
+            const impact = await engine.getRefactorImpact('NonExistentSymbolXYZ123', __dirname);
+            expect(impact.referenceCount).toBe(0);
+            expect(impact.affectedFiles.length).toBe(0);
+        }, 30000);
+    });
+});
+//# sourceMappingURL=typescript-engine.test.js.map

package/dist/tools/structural/engines/typescript/__tests__/typescript-engine.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"typescript-engine.test.js","sourceRoot":"","sources":["../../../../../../src/tools/structural/engines/typescript/__tests__/typescript-engine.test.ts"],"names":[],"mappings":"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"}