@thoughtflow/core 0.1.2

package/dist/tools/neural/neural-deadcode.tool.js

@@ -0,0 +1,133 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NeuralDeadcodeTool = void 0;
+const zod_1 = require("zod");
+const tool_base_class_1 = require("../base/tool-base.class");
+const dependency_extractor_1 = require("../../libs/codebase/graph/dependency-extractor");
+const explorer_1 = require("../../libs/codebase/indexer/explorer");
+const fs = __importStar(require("node:fs"));
+class NeuralDeadcodeTool extends tool_base_class_1.ToolBase {
+    name = "neuralDeadcode";
+    description = "Detect dead code: unused exports, unreachable functions, unused variables, and orphaned files using dependency graph analysis with LLM-guided false-positive filtering for uncertain cases.";
+    readonly = true;
+    constructor() {
+        super(zod_1.z.object({
+            projectPath: zod_1.z.string().optional(),
+            threshold: zod_1.z.number().optional().describe("Min lines of dead code to report a file"),
+            llmVerify: zod_1.z.boolean().optional().describe("Use LLM to verify uncertain cases"),
+        }));
+    }
+    async run(input, ctx) {
+        const rootPath = input.projectPath ?? process.cwd();
+        const threshold = input.threshold ?? 3;
+        const llmVerify = input.llmVerify ?? false;
+        const explorer = new explorer_1.CodebaseExplorer();
+        const files = explorer.explore({ rootPath });
+        const codeFiles = files.filter((f) => f.classification === "source-code")
+            .map((f) => ({ relativePath: f.relativePath, absolutePath: f.absolutePath }));
+        const depExtractor = new dependency_extractor_1.DependencyExtractor();
+        const graph = depExtractor.buildGraph(codeFiles, rootPath);
+        const usedFiles = new Set();
+        for (const edge of graph.edges) {
+            usedFiles.add(edge.to);
+        }
+        const deadExports = [];
+        const unreachableFiles = [];
+        for (const file of codeFiles) {
+            const content = fs.readFileSync(file.absolutePath, "utf8");
+            const exports = this.extractExports(content, file.relativePath);
+            const hasIncoming = graph.edges.some((e) => e.to === file.relativePath);
+            const isEntry = file.relativePath.match(/(index|main|app|server|cli)\.ts$/);
+            if (!hasIncoming && !isEntry && file.relativePath.includes("/")) {
+                unreachableFiles.push(file.relativePath);
+            }
+            for (const exp of exports) {
+                let used = false;
+                for (const edge of graph.edges) {
+                    if (edge.symbols?.includes(exp.symbol)) {
+                        used = true;
+                        break;
+                    }
+                }
+                if (!used && !exp.symbol.startsWith("_") && !exp.symbol.startsWith("I")) {
+                    deadExports.push({ ...exp, confidence: "high" });
+                }
+            }
+        }
+        if (llmVerify && unreachableFiles.length > 0 && ctx.conversation) {
+            const prompt = `These files appear to have no imports from other project files. Are any of them entry points, referenced dynamically (e.g., loaded by string path, used in config files, routing tables, or build scripts), or otherwise used indirectly?\n\n${unreachableFiles.slice(0, 10).join("\n")}\n\nReturn: { falsePositives: string[] } listing only files that are genuinely in use.`;
+            try {
+                const result = await ctx.conversation.callStructured(prompt, zod_1.z.object({ falsePositives: zod_1.z.array(zod_1.z.string()) }));
+                const fps = new Set(result.falsePositives ?? []);
+                const filtered = unreachableFiles.filter((f) => !fps.has(f));
+                return {
+                    success: true,
+                    output: JSON.stringify({
+                        summary: { totalFiles: codeFiles.length, deadExports: deadExports.length, unreachableFiles: filtered.length, falsePositivesRemoved: fps.size },
+                        deadExports: deadExports.slice(0, 50),
+                        unreachableFiles: filtered,
+                    }),
+                };
+            }
+            catch {
+            }
+        }
+        return {
+            success: true,
+            output: JSON.stringify({
+                summary: { totalFiles: codeFiles.length, deadExports: deadExports.length, unreachableFiles: unreachableFiles.length },
+                deadExports: deadExports.slice(0, 50),
+                unreachableFiles: unreachableFiles.slice(0, 20),
+            }),
+        };
+    }
+    extractExports(content, filePath) {
+        const exports = [];
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+            const match = lines[i].match(/(?:export\s+(?:async\s+)?(?:function|class|const|let|var|interface|type|enum)\s+(\w+))|(?:export\s*\{\s*([^}]+)\s*\})/);
+            if (match) {
+                const name = match[1] || match[2];
+                if (name) {
+                    exports.push({ file: filePath, symbol: name, type: "export", line: i + 1 });
+                }
+            }
+        }
+        return exports;
+    }
+}
+exports.NeuralDeadcodeTool = NeuralDeadcodeTool;
+//# sourceMappingURL=neural-deadcode.tool.js.map

package/dist/tools/neural/neural-deadcode.tool.js.map

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

package/dist/tools/neural/neural-debug.tool.d.ts

@@ -0,0 +1,12 @@
+import { ToolBase } from "../base/tool-base.class";
+import { ToolContext, ToolExecutionResult } from "../../contracts";
+export declare class NeuralDebugTool extends ToolBase {
+    readonly name = "neuralDebug";
+    readonly description = "Analyze a stack trace or error against the codebase to suggest a fix. Parses stack frames, finds relevant source files, extracts context, and uses LLM to propose solutions.";
+    readonly readonly = true;
+    constructor();
+    run(input: Record<string, unknown>, ctx: ToolContext): Promise<ToolExecutionResult>;
+    private parseStackTrace;
+    private staticAnalyzeContext;
+}
+//# sourceMappingURL=neural-debug.tool.d.ts.map

package/dist/tools/neural/neural-debug.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neural-debug.tool.d.ts","sourceRoot":"","sources":["../../../src/tools/neural/neural-debug.tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAiBnE,qBAAa,eAAgB,SAAQ,QAAQ;IAC3C,QAAQ,CAAC,IAAI,iBAAiB;IAC9B,QAAQ,CAAC,WAAW,kLAAkL;IACtM,SAAkB,QAAQ,QAAQ;;IAU5B,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAwGzF,OAAO,CAAC,eAAe;IAiCvB,OAAO,CAAC,oBAAoB;CA8B7B"}

package/dist/tools/neural/neural-debug.tool.js

@@ -0,0 +1,205 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NeuralDebugTool = void 0;
+const zod_1 = require("zod");
+const tool_base_class_1 = require("../base/tool-base.class");
+const dependency_extractor_1 = require("../../libs/codebase/graph/dependency-extractor");
+const explorer_1 = require("../../libs/codebase/indexer/explorer");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+const DebugResultSchema = zod_1.z.object({
+    errorType: zod_1.z.string(),
+    rootCause: zod_1.z.string(),
+    suggestedFix: zod_1.z.string(),
+    codeFixExample: zod_1.z.string().optional(),
+    affectedFiles: zod_1.z.array(zod_1.z.string()),
+    confidence: zod_1.z.enum(["high", "medium", "low"]),
+});
+class NeuralDebugTool extends tool_base_class_1.ToolBase {
+    name = "neuralDebug";
+    description = "Analyze a stack trace or error against the codebase to suggest a fix. Parses stack frames, finds relevant source files, extracts context, and uses LLM to propose solutions.";
+    readonly = true;
+    constructor() {
+        super(zod_1.z.object({
+            error: zod_1.z.string().describe("Stack trace or error message"),
+            projectPath: zod_1.z.string().optional(),
+            maxFrames: zod_1.z.number().optional().describe("Max stack frames to analyze"),
+        }));
+    }
+    async run(input, ctx) {
+        const { error, maxFrames } = input;
+        const rootPath = input.projectPath ?? process.cwd();
+        const max = maxFrames ?? 5;
+        const frames = this.parseStackTrace(error, rootPath);
+        const relevantFrames = frames.slice(0, max);
+        const analysis = [];
+        for (const frame of relevantFrames) {
+            const absolutePath = path.join(rootPath, frame.file);
+            if (!fs.existsSync(absolutePath))
+                continue;
+            const content = fs.readFileSync(absolutePath, "utf8");
+            const lines = content.split("\n");
+            const start = Math.max(0, frame.line - 10);
+            const end = Math.min(lines.length, frame.line + 10);
+            const context = lines.slice(start, end)
+                .map((l, i) => `${start + i + 1}: ${l}`)
+                .join("\n");
+            const suggestions = this.staticAnalyzeContext(lines, frame.line, frame.message);
+            analysis.push({ file: frame.file, line: frame.line, column: frame.column, context, suggestions });
+        }
+        const explorer = new explorer_1.CodebaseExplorer();
+        const files = explorer.explore({ rootPath });
+        const codeFiles = files.filter((f) => f.classification === "source-code")
+            .map((f) => ({ relativePath: f.relativePath, absolutePath: f.absolutePath }));
+        const depExtractor = new dependency_extractor_1.DependencyExtractor();
+        const graph = depExtractor.buildGraph(codeFiles, rootPath);
+        const affectedFiles = new Set();
+        for (const frame of relevantFrames) {
+            affectedFiles.add(frame.file);
+            const dependents = graph.edges.filter((e) => e.to === frame.file);
+            for (const dep of dependents.slice(0, 5)) {
+                affectedFiles.add(dep.from);
+            }
+        }
+        const callStructured = ctx.conversation?.callStructured;
+        if (!callStructured) {
+            return {
+                success: true,
+                output: JSON.stringify({
+                    error: error.split("\n")[0],
+                    framesAnalyzed: analysis.length,
+                    totalFrames: frames.length,
+                    affectedFiles: Array.from(affectedFiles).slice(0, 15),
+                    analysis,
+                    llmUsed: false,
+                }),
+            };
+        }
+        const codeContext = analysis
+            .map((a) => `=== ${a.file}:${a.line} ===\n${a.context}`)
+            .join("\n\n")
+            .slice(0, 8000);
+        const prompt = `You are an expert software debugger. Analyze the stack trace and source code context, then provide a structured root cause analysis, a concrete suggested fix with code example, and list of affected files.
+
+ERROR:
+${error}
+
+RELEVANT SOURCE CODE:
+${codeContext}
+
+STATIC ANALYSIS HINTS:
+${analysis.map((a) => `- ${a.file}:${a.line}: ${a.suggestions.join("; ")}`).join("\n")}`;
+        try {
+            const result = await callStructured(prompt, DebugResultSchema);
+            return {
+                success: true,
+                output: JSON.stringify({
+                    ...result,
+                    stackFrames: frames.length,
+                    relevantFiles: relevantFrames.map((f) => f.file),
+                    affectedFiles: Array.from(affectedFiles).slice(0, 15),
+                    filesAnalyzed: analysis.length,
+                    llmUsed: true,
+                }),
+            };
+        }
+        catch {
+            return {
+                success: true,
+                output: JSON.stringify({
+                    error: error.split("\n")[0],
+                    stackFrames: frames.length,
+                    relevantFiles: relevantFrames.map((f) => f.file),
+                    affectedFiles: Array.from(affectedFiles).slice(0, 15),
+                    analysis,
+                    llmUsed: false,
+                }),
+            };
+        }
+    }
+    parseStackTrace(error, rootPath) {
+        const frames = [];
+        const lines = error.split("\n");
+        const message = lines[0];
+        const patterns = [
+            /at\s+(?:async\s+)?(?:\S+\s+)?\(?(.+?):(\d+):(\d+)\)?/g,
+            /at\s+(.+?):(\d+):(\d+)/g,
+        ];
+        for (const line of lines) {
+            for (const pattern of patterns) {
+                pattern.lastIndex = 0;
+                let match;
+                while ((match = pattern.exec(line)) !== null) {
+                    const file = match[1].replace(/^file:\/\//, "");
+                    const lineNum = parseInt(match[2], 10);
+                    const col = match[3] ? parseInt(match[3], 10) : undefined;
+                    if (file.includes("node_modules") || file.includes("node:"))
+                        continue;
+                    const relative = file.startsWith(rootPath)
+                        ? path.relative(rootPath, file)
+                        : file;
+                    frames.push({ file: relative, line: lineNum, column: col, message });
+                }
+            }
+        }
+        return frames;
+    }
+    staticAnalyzeContext(lines, lineNum, errorMsg) {
+        const suggestions = [];
+        const targetLine = lines[lineNum - 1] ?? "";
+        if (targetLine.trim().startsWith("//") || targetLine.trim().startsWith("/*")) {
+            suggestions.push("Error on a comment line — check preceding/succeeding code");
+        }
+        if (targetLine.includes("undefined") || targetLine.includes("null")) {
+            suggestions.push("Possible null/undefined access — add null check or optional chaining");
+        }
+        if (targetLine.includes(".map(") || targetLine.includes(".filter(") || targetLine.includes(".find(")) {
+            suggestions.push("Array method may be called on undefined — ensure array is initialized");
+        }
+        if (targetLine.includes("await")) {
+            suggestions.push("Async operation — verify error handling with try/catch or .catch()");
+        }
+        if (targetLine.includes("import")) {
+            suggestions.push("Import resolution error — check file path, extension, and module existence");
+        }
+        if (suggestions.length === 0) {
+            suggestions.push("Review the surrounding context for variable initialization and error handling");
+        }
+        return suggestions;
+    }
+}
+exports.NeuralDebugTool = NeuralDebugTool;
+//# sourceMappingURL=neural-debug.tool.js.map

package/dist/tools/neural/neural-debug.tool.js.map

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

package/dist/tools/neural/neural-explain.tool.d.ts

@@ -0,0 +1,10 @@
+import { ToolBase } from "../base/tool-base.class";
+import { ToolContext, ToolExecutionResult } from "../../contracts";
+export declare class NeuralExplainTool extends ToolBase {
+    readonly name = "neuralExplain";
+    readonly description = "Explain any code snippet, function, or file in natural language. Uses LLM to provide clear, educational explanations of what the code does, its purpose, and how it works.";
+    readonly readonly = true;
+    constructor();
+    run(input: Record<string, unknown>, ctx: ToolContext): Promise<ToolExecutionResult>;
+}
+//# sourceMappingURL=neural-explain.tool.d.ts.map

package/dist/tools/neural/neural-explain.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neural-explain.tool.d.ts","sourceRoot":"","sources":["../../../src/tools/neural/neural-explain.tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAInE,qBAAa,iBAAkB,SAAQ,QAAQ;IAC7C,QAAQ,CAAC,IAAI,mBAAmB;IAChC,QAAQ,CAAC,WAAW,gLAAgL;IACpM,SAAkB,QAAQ,QAAQ;;IAU5B,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAgD1F"}

package/dist/tools/neural/neural-explain.tool.js

@@ -0,0 +1,100 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NeuralExplainTool = void 0;
+const zod_1 = require("zod");
+const tool_base_class_1 = require("../base/tool-base.class");
+const fs = __importStar(require("node:fs"));
+const path = __importStar(require("node:path"));
+class NeuralExplainTool extends tool_base_class_1.ToolBase {
+    name = "neuralExplain";
+    description = "Explain any code snippet, function, or file in natural language. Uses LLM to provide clear, educational explanations of what the code does, its purpose, and how it works.";
+    readonly = true;
+    constructor() {
+        super(zod_1.z.object({
+            target: zod_1.z.string().describe("File path, function name, or code snippet to explain"),
+            detail: zod_1.z.enum(["brief", "detailed", "tutorial"]).optional().describe("Level of detail (default: detailed)"),
+            projectPath: zod_1.z.string().optional(),
+        }));
+    }
+    async run(input, ctx) {
+        const { target, detail } = input;
+        const rootPath = input.projectPath ?? process.cwd();
+        const level = detail ?? "detailed";
+        let codeToExplain = target;
+        const fullPath = path.join(rootPath, target);
+        try {
+            if (fs.existsSync(fullPath) && fs.statSync(fullPath).isFile()) {
+                codeToExplain = fs.readFileSync(fullPath, "utf8").slice(0, 8000);
+            }
+        }
+        catch {
+            /* use target as-is */
+        }
+        const callStructured = ctx.conversation?.callStructured;
+        if (!callStructured) {
+            return {
+                success: true,
+                output: JSON.stringify({
+                    explanation: "LLM not available — raw code provided for manual review",
+                    code: codeToExplain.slice(0, 500),
+                    level,
+                }),
+            };
+        }
+        const prompt = level === "brief"
+            ? `Explain this code in 1-2 sentences:\n\n\`\`\`\n${codeToExplain}\n\`\`\``
+            : level === "tutorial"
+                ? `Explain this code as a step-by-step tutorial for beginners. Cover what it does, why each part exists, and how each piece works together:\n\n\`\`\`\n${codeToExplain}\n\`\`\``
+                : `Explain this code in detail — what it does, its purpose, key design decisions, and how it fits into the larger system. Cover the logic flow, data transformations, and any notable patterns:\n\n\`\`\`\n${codeToExplain}\n\`\`\``;
+        try {
+            const result = await callStructured(prompt, zod_1.z.object({ explanation: zod_1.z.string() }));
+            const data = result;
+            return { success: true, output: data.explanation ?? "No explanation generated" };
+        }
+        catch (err) {
+            return {
+                success: true,
+                output: JSON.stringify({
+                    explanation: `Failed to generate explanation: ${err instanceof Error ? err.message : "Unknown error"}`,
+                    code: codeToExplain.slice(0, 500),
+                    level,
+                }),
+            };
+        }
+    }
+}
+exports.NeuralExplainTool = NeuralExplainTool;
+//# sourceMappingURL=neural-explain.tool.js.map

package/dist/tools/neural/neural-explain.tool.js.map

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

package/dist/tools/neural/neural-optimize.tool.d.ts

@@ -0,0 +1,10 @@
+import { ToolBase } from "../base/tool-base.class";
+import { ToolContext, ToolExecutionResult } from "../../contracts";
+export declare class NeuralOptimizeTool extends ToolBase {
+    readonly name = "neuralOptimize";
+    readonly description = "AI-powered performance optimization. Combines static pattern detection (N+1 queries, sync-in-async, missing memoization) with LLM semantic analysis of hot-path inefficiencies. Provides concrete fix suggestions with estimated impact.";
+    readonly readonly = true;
+    constructor();
+    run(input: Record<string, unknown>, ctx: ToolContext): Promise<ToolExecutionResult>;
+}
+//# sourceMappingURL=neural-optimize.tool.d.ts.map

package/dist/tools/neural/neural-optimize.tool.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"neural-optimize.tool.d.ts","sourceRoot":"","sources":["../../../src/tools/neural/neural-optimize.tool.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,EAAE,WAAW,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AAanE,qBAAa,kBAAmB,SAAQ,QAAQ;IAC9C,QAAQ,CAAC,IAAI,oBAAoB;IACjC,QAAQ,CAAC,WAAW,8OAA8O;IAClQ,SAAkB,QAAQ,QAAQ;;IAS5B,GAAG,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,WAAW,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAkE1F"}

package/dist/tools/neural/neural-optimize.tool.js

@@ -0,0 +1,117 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NeuralOptimizeTool = void 0;
+const zod_1 = require("zod");
+const tool_base_class_1 = require("../base/tool-base.class");
+const explorer_1 = require("../../libs/codebase/indexer/explorer");
+const fs = __importStar(require("node:fs"));
+const OptimizeSuggestionSchema = zod_1.z.object({
+    category: zod_1.z.string(),
+    severity: zod_1.z.enum(["high", "medium", "low"]),
+    message: zod_1.z.string(),
+    fix: zod_1.z.string(),
+    estimatedImpact: zod_1.z.string(),
+});
+class NeuralOptimizeTool extends tool_base_class_1.ToolBase {
+    name = "neuralOptimize";
+    description = "AI-powered performance optimization. Combines static pattern detection (N+1 queries, sync-in-async, missing memoization) with LLM semantic analysis of hot-path inefficiencies. Provides concrete fix suggestions with estimated impact.";
+    readonly = true;
+    constructor() {
+        super(zod_1.z.object({
+            target: zod_1.z.string().optional().describe("File path or leave empty for worst offenders"),
+            projectPath: zod_1.z.string().optional(),
+        }));
+    }
+    async run(input, ctx) {
+        const rootPath = input.projectPath ?? process.cwd();
+        const target = input.target || undefined;
+        const explorer = new explorer_1.CodebaseExplorer();
+        const files = explorer.explore({ rootPath });
+        const scanFiles = target
+            ? files.filter((f) => f.relativePath.includes(target)).slice(0, 5)
+            : files.filter((f) => f.classification === "source-code").slice(0, 20);
+        const staticIssues = [];
+        for (const file of scanFiles) {
+            const content = fs.readFileSync(file.absolutePath, "utf8");
+            const lines = content.split("\n");
+            for (let i = 0; i < lines.length; i++) {
+                const surrounding = lines.slice(Math.max(0, i - 3), i + 3).join("\n");
+                if (lines[i].match(/\.findMany|\.findFirst|\.findUnique|\.query|\.execute/) && surrounding.match(/for\s*\(|forEach|\.map\s*\(/)) {
+                    staticIssues.push({ category: "n+1", severity: "high", file: file.relativePath, line: i + 1, message: "Database query inside loop — potential N+1 problem", fix: "Use batch query, eager loading (include), or DataLoader", estimatedImpact: "Can reduce DB calls from N to 1" });
+                }
+                if (lines[i].includes("await") && surrounding.match(/for\s*\(.*of/) && lines[i].match(/await\s+\w+/)) {
+                    staticIssues.push({ category: "sequential-async", severity: "medium", file: file.relativePath, line: i + 1, message: "Sequential awaits in loop — can parallelize", fix: "Use Promise.all() for independent async operations", estimatedImpact: "Can reduce total time by factor of N" });
+                }
+            }
+            if (content.match(/\.filter|\.sort|\.reduce/) && !content.includes("useMemo") && !content.includes("useCallback") && (file.relativePath.endsWith(".tsx") || file.relativePath.endsWith(".jsx"))) {
+                staticIssues.push({ category: "missing-memo", severity: "medium", file: file.relativePath, message: "Expensive computation in render without memoization", fix: "Wrap in useMemo/useCallback", estimatedImpact: "Can prevent unnecessary re-renders" });
+            }
+        }
+        const cs = ctx.conversation?.callStructured;
+        if (!cs) {
+            return { success: true, output: JSON.stringify({ filesScanned: scanFiles.length, issuesFound: staticIssues.length, issues: staticIssues }) };
+        }
+        const codeSnippets = scanFiles.filter((f) => {
+            const c = fs.readFileSync(f.absolutePath, "utf8");
+            return c.includes("await") || c.includes(".find") || c.includes(".map") || c.includes("for");
+        }).slice(0, 3).map((f) => {
+            const c = fs.readFileSync(f.absolutePath, "utf8").slice(0, 3000);
+            return `--- ${f.relativePath} ---\n${c}`;
+        }).join("\n\n");
+        if (!codeSnippets) {
+            return { success: true, output: JSON.stringify({ filesScanned: scanFiles.length, issuesFound: staticIssues.length, issues: staticIssues }) };
+        }
+        const prompt = `Analyze this code for performance optimization opportunities: N+1 queries, missing caching/memoization, unnecessary re-renders, expensive operations in hot paths, sync operations in async contexts, large dependency imports, unnecessary closures, unbatched state updates, premature materialization of large collections, missing lazy evaluation.\n\n${codeSnippets}\n\nReturn structured suggestions with severity and estimated impact.`;
+        try {
+            const result = await cs(prompt, zod_1.z.object({ suggestions: zod_1.z.array(OptimizeSuggestionSchema) }));
+            const llmIssues = (result.suggestions ?? []).map((s) => ({
+                category: s.category,
+                severity: s.severity,
+                file: target ?? "",
+                message: s.message,
+                fix: s.fix,
+                estimatedImpact: s.estimatedImpact,
+            }));
+            const allIssues = [...staticIssues, ...llmIssues];
+            return { success: true, output: JSON.stringify({ filesScanned: scanFiles.length, issuesFound: allIssues.length, issues: allIssues.slice(0, 20) }) };
+        }
+        catch {
+            return { success: true, output: JSON.stringify({ filesScanned: scanFiles.length, issuesFound: staticIssues.length, issues: staticIssues }) };
+        }
+    }
+}
+exports.NeuralOptimizeTool = NeuralOptimizeTool;
+//# sourceMappingURL=neural-optimize.tool.js.map