@thoughtflow/codebase 0.2.0

package/src/tools/neural/neural-security.tool.ts

@@ -0,0 +1,226 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+import { CodebaseExplorer } from "../../libs/codebase/indexer/explorer";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const SecurityIssueSchema = z.object({
+  severity: z.enum(["critical", "high", "medium", "low"]),
+  cwe: z.string(),
+  category: z.string(),
+  message: z.string(),
+  remediation: z.string(),
+});
+
+const SecurityResultSchema = z.object({
+  summary: z.string(),
+  findings: z.array(SecurityIssueSchema),
+  riskLevel: z.enum(["critical", "high", "medium", "low", "none"]),
+});
+
+type SecurityFinding = z.infer<typeof SecurityIssueSchema>;
+
+export class NeuralSecurityTool extends ToolBase {
+  readonly name = "neuralSecurity";
+  readonly description = "Scan source code for security vulnerabilities: hardcoded secrets, injection risks, unsafe crypto, XSS, CSRF, path traversal. LLM-powered deep analysis with CWE references.";
+  readonly = true;
+
+  constructor() {
+    super(z.object({
+      target: z.string().optional().describe("File or directory to scan"),
+      scope: z.enum(["all", "secrets", "injection", "crypto", "xss", "auth"]).optional(),
+      projectPath: z.string().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, ctx: ToolContext): Promise<ToolExecutionResult> {
+    const rootPath = (input.projectPath as string) ?? process.cwd();
+    const scope = (input.scope as string) ?? "all";
+    const target = (input.target as string) || undefined;
+
+    const explorer = new CodebaseExplorer();
+    const files = explorer.explore({ rootPath });
+
+    const scanFiles = target
+      ? files.filter((f) => f.relativePath.includes(target) || f.absolutePath.includes(target))
+      : files.filter((f) => f.classification === "source-code" || f.classification === "config");
+
+    const staticFindings: SecurityFinding[] = [];
+
+    for (const file of scanFiles.slice(0, 100)) {
+      try {
+        const content = fs.readFileSync(file.absolutePath, "utf8");
+        const lines = content.split("\n");
+        for (let i = 0; i < lines.length; i++) {
+          const line = lines[i];
+          if (scope === "all" || scope === "secrets") this.scanSecrets(line, file.relativePath, i + 1, staticFindings);
+          if (scope === "all" || scope === "injection") this.scanInjection(line, file.relativePath, i + 1, staticFindings);
+          if (scope === "all" || scope === "crypto") this.scanCrypto(line, file.relativePath, i + 1, staticFindings);
+          if (scope === "all" || scope === "xss") this.scanXss(line, file.relativePath, i + 1, staticFindings);
+          if (scope === "all" || scope === "auth") this.scanAuth(line, file.relativePath, i + 1, content, staticFindings);
+        }
+      } catch {
+        continue;
+      }
+    }
+
+    const cs = ctx.conversation?.callStructured;
+    if (!cs) {
+      const severityCounts = this.countBySeverity(staticFindings);
+      return {
+        success: true,
+        output: JSON.stringify({
+          summary: `Static scan: ${staticFindings.length} findings across ${scanFiles.length} files`,
+          filesScanned: scanFiles.length,
+          severityCounts,
+          findings: staticFindings.slice(0, 30),
+          riskLevel: this.computeRiskLevel(staticFindings),
+        }),
+      };
+    }
+
+    const suspiciousFiles = scanFiles.filter((f) => {
+      try {
+        const c = fs.readFileSync(f.absolutePath, "utf8");
+        return c.includes("secret") || c.includes("token") || c.includes("password") || c.includes("eval") || c.includes("innerHTML") || c.includes("sql") || c.includes("crypto");
+      } catch { return false; }
+    }).slice(0, 5);
+
+    if (suspiciousFiles.length === 0) {
+      const severityCounts = this.countBySeverity(staticFindings);
+      return {
+        success: true,
+        output: JSON.stringify({
+          summary: "No suspicious files for deep scan",
+          filesScanned: scanFiles.length,
+          severityCounts,
+          findings: staticFindings.slice(0, 30),
+          riskLevel: this.computeRiskLevel(staticFindings),
+        }),
+      };
+    }
+
+    const codeSnippets = suspiciousFiles
+      .map((f) => {
+        try {
+          return `=== ${f.relativePath} ===\n${fs.readFileSync(f.absolutePath, "utf8").slice(0, 4000)}`;
+        } catch { return ""; }
+      })
+      .filter(Boolean)
+      .join("\n\n");
+
+    const staticHints = staticFindings
+      .slice(0, 20)
+      .map((f) => `${f.severity.toUpperCase()}: ${f.cwe} - ${f.message}`)
+      .join("\n");
+
+    const prompt = `You are a security auditor specializing in OWASP Top 10 vulnerabilities. Analyze the provided source code and return structured findings with CWE references, severity ratings, and actionable remediation steps.\n\nScan the following source code for security vulnerabilities. Focus on: ${scope}.\n\nSTATIC SCAN HIGHLIGHTS (use these as hints, but perform your own deeper analysis):\n${staticHints || "No static findings"}\n\nSOURCE CODE:\n${codeSnippets.slice(0, 12000)}`;
+
+    try {
+      const result = await cs(prompt, SecurityResultSchema);
+
+      const allFindings = [...staticFindings, ...(result.findings ?? [])];
+      const severityCounts = this.countBySeverity(allFindings);
+
+      return {
+        success: true,
+        output: JSON.stringify({
+          summary: result.summary ?? `${allFindings.length} total findings`,
+          filesScanned: scanFiles.length,
+          severityCounts,
+          findings: allFindings.slice(0, 50),
+          riskLevel: result.riskLevel ?? this.computeRiskLevel(allFindings),
+        }),
+      };
+    } catch {
+      const severityCounts = this.countBySeverity(staticFindings);
+      return {
+        success: true,
+        output: JSON.stringify({
+          summary: "LLM scan failed — static analysis only",
+          filesScanned: scanFiles.length,
+          severityCounts,
+          findings: staticFindings.slice(0, 30),
+          riskLevel: this.computeRiskLevel(staticFindings),
+        }),
+      };
+    }
+  }
+
+  private scanSecrets(line: string, file: string, lineNum: number, findings: SecurityFinding[]): void {
+    if (line.match(/(api[_-]?key|secret|password|token|auth)\s*[:=]\s*['"][^$`{].{6,}['"]/i) && !line.includes("process.env") && !line.includes("import")) {
+      if (!line.trim().startsWith("//") && !line.trim().startsWith("/*")) {
+        findings.push({ severity: "critical", cwe: "CWE-798", category: "secrets", message: `Hardcoded credential in ${file}:${lineNum}`, remediation: "Move to environment variable or secret manager" });
+      }
+    }
+    if (line.match(/['"]((?:sk-[A-Za-z0-9]{20,})|(?:ghp_[A-Za-z0-9]{20,})|(?:xox[bpras]-[A-Za-z0-9-]{10,}))['"]/)) {
+      findings.push({ severity: "critical", cwe: "CWE-798", category: "secrets", message: `API key detected in ${file}:${lineNum}`, remediation: "Use environment variables or a secrets vault — revoke the exposed key immediately" });
+    }
+  }
+
+  private scanInjection(line: string, file: string, lineNum: number, findings: SecurityFinding[]): void {
+    if (line.match(/eval\s*\(/)) findings.push({ severity: "critical", cwe: "CWE-95", category: "injection", message: `eval() usage in ${file}:${lineNum}`, remediation: "Remove eval() — use JSON.parse or safer alternatives" });
+    if (line.match(/exec\s*\(\s*['"`][^'"]*\$\{/)) findings.push({ severity: "critical", cwe: "CWE-78", category: "injection", message: `Command injection risk in ${file}:${lineNum}`, remediation: "Use execFile() with argument arrays, or sanitize inputs" });
+    if (line.match(/(?:execute|query|run)\s*\(\s*['"`][^'"]*\$/) && !line.includes("?") && !line.includes("$1")) {
+      findings.push({ severity: "high", cwe: "CWE-89", category: "injection", message: `Potential SQL injection in ${file}:${lineNum}`, remediation: "Use parameterized queries or an ORM with input binding" });
+    }
+    if (line.match(/new Function\s*\(/)) findings.push({ severity: "critical", cwe: "CWE-95", category: "injection", message: `new Function() in ${file}:${lineNum}`, remediation: "Avoid new Function() — refactor to use proper logic constructs" });
+    if (line.match(/require\s*\(\s*.+\s*\+\s*.+/) || line.match(/import\s*\(\s*.+\s*\+\s*.+\)/)) {
+      findings.push({ severity: "high", cwe: "CWE-641", category: "injection", message: `Dynamic import with concatenation in ${file}:${lineNum}`, remediation: "Use a static import map instead of dynamic concatenation" });
+    }
+  }
+
+  private scanCrypto(line: string, file: string, lineNum: number, findings: SecurityFinding[]): void {
+    if (line.match(/Math\.random\s*\(\s*\)/) && (line.includes("token") || line.includes("password") || line.includes("secret") || line.includes("nonce"))) {
+      findings.push({ severity: "high", cwe: "CWE-338", category: "crypto", message: `Math.random() for security in ${file}:${lineNum}`, remediation: "Use crypto.randomBytes() or crypto.randomUUID()" });
+    }
+    if (line.match(/md5|crc32|sha1(?!256|512)/i) && !line.includes("import") && !line.includes("type")) {
+      findings.push({ severity: "medium", cwe: "CWE-328", category: "crypto", message: `Weak hash (MD5/SHA1/CRC32) in ${file}:${lineNum}`, remediation: "Use SHA-256, SHA-512, or bcrypt/scrypt for passwords" });
+    }
+    if (line.match(/crypto\.createCipher\s*\(/) || line.match(/new\s+Cipher\s*\(/)) {
+      findings.push({ severity: "medium", cwe: "CWE-327", category: "crypto", message: `Insecure cipher usage in ${file}:${lineNum}`, remediation: "Use AES-256-GCM or ChaCha20-Poly1305 with authenticated encryption" });
+    }
+  }
+
+  private scanXss(line: string, file: string, lineNum: number, findings: SecurityFinding[]): void {
+    if (line.match(/innerHTML\s*=|dangerouslySetInnerHTML|v-html/)) {
+      findings.push({ severity: "high", cwe: "CWE-79", category: "xss", message: `Potential XSS in ${file}:${lineNum}`, remediation: "Sanitize input with DOMPurify or use textContent instead" });
+    }
+    if (line.match(/document\.write\s*\(/)) {
+      findings.push({ severity: "high", cwe: "CWE-79", category: "xss", message: `document.write() in ${file}:${lineNum}`, remediation: "Use DOM manipulation methods like appendChild or innerHTML with sanitization" });
+    }
+    if (line.match(/setAttribute\s*\(\s*['"]on\w+['"]/) || line.match(/\.on\w+\s*=\s*/)) {
+      findings.push({ severity: "medium", cwe: "CWE-79", category: "xss", message: `Inline event handler in ${file}:${lineNum}`, remediation: "Use addEventListener instead of inline handlers" });
+    }
+  }
+
+  private scanAuth(line: string, file: string, lineNum: number, content: string, findings: SecurityFinding[]): void {
+    if (line.match(/http\.createServer|app\.listen|express\s*\(/) && !line.includes("https")) {
+      if (!content.includes("https") && !content.includes("ssl") && !content.includes("tls") && !content.includes("secure")) {
+        findings.push({ severity: "medium", cwe: "CWE-319", category: "auth", message: `Server without HTTPS in ${file}:${lineNum}`, remediation: "Configure TLS/SSL with a valid certificate" });
+      }
+    }
+    if (line.match(/jwt\.sign\(/) || line.match(/jsonwebtoken\.sign/)) {
+      if (!content.includes("expiresIn") && !content.includes("expires")) {
+        findings.push({ severity: "medium", cwe: "CWE-307", category: "auth", message: `JWT without expiration in ${file}:${lineNum}`, remediation: "Set expiresIn option when signing JWTs" });
+      }
+    }
+  }
+
+  private countBySeverity(findings: SecurityFinding[]): Record<string, number> {
+    return {
+      critical: findings.filter((f) => f.severity === "critical").length,
+      high: findings.filter((f) => f.severity === "high").length,
+      medium: findings.filter((f) => f.severity === "medium").length,
+      low: findings.filter((f) => f.severity === "low").length,
+    };
+  }
+
+  private computeRiskLevel(findings: SecurityFinding[]): string {
+    if (findings.some((f) => f.severity === "critical")) return "critical";
+    if (findings.some((f) => f.severity === "high")) return "high";
+    if (findings.some((f) => f.severity === "medium")) return "medium";
+    if (findings.length > 0) return "low";
+    return "none";
+  }
+}

package/src/tools/neural/neural-similar.tool.ts

@@ -0,0 +1,113 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult, MemoryVectorStore, MockEmbeddingProvider } from "@thoughtflow/core";
+import { CodebaseExplorer } from "../../libs/codebase/indexer/explorer";
+import { CodeChunker } from "../../libs/codebase/indexer/chunker";
+import * as fs from "node:fs";
+
+export class NeuralSimilarTool extends ToolBase {
+  readonly name = "neuralSimilar";
+  readonly description = "Find semantically similar or duplicate code fragments. Uses embeddings to detect copy-pasted code that text-based diff tools would miss.";
+  override readonly readonly = true;
+
+  constructor() {
+    super(z.object({
+      target: z.string().optional().describe("File to compare against codebase"),
+      projectPath: z.string().optional(),
+      threshold: z.number().optional().describe("Similarity threshold (0-1, default 0.85)"),
+      limit: z.number().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const target = (input.target as string) || undefined;
+    const rootPath = (input.projectPath as string) ?? process.cwd();
+    const threshold = (input.threshold as number) ?? 0.85;
+    const limit = (input.limit as number) ?? 10;
+
+    const vectorStore = new MemoryVectorStore();
+    await vectorStore.initialize();
+
+    const embedder = new MockEmbeddingProvider();
+
+    const explorer = new CodebaseExplorer();
+    const files = explorer.explore({ rootPath });
+
+    const codeFiles = files.filter((f) => f.classification === "source-code" || f.classification === "test");
+    const filesToIndex = codeFiles;
+
+    const chunker = new CodeChunker();
+    const allChunks: Array<{ id: string; text: string; file: string; lines: [number, number] }> = [];
+    const results: Array<{ file1: string; file2: string; lines1: string; lines2: string; score: number; snippet1: string; snippet2: string }> = [];
+
+    for (const file of filesToIndex) {
+      const content = fs.readFileSync(file.absolutePath, "utf8");
+      const result = await chunker.chunkFile(file, content);
+      for (const chunk of result.chunks) {
+        const vec = await embedder.embedQuery(chunk.text);
+        const id = `${file.relativePath}:${chunk.startLine}-${chunk.endLine}`;
+        await vectorStore.insert([{
+          id,
+          vector: vec,
+          text: chunk.text.slice(0, 500),
+          metadata: {
+            projectPath: rootPath,
+            filePath: file.relativePath,
+            startLine: chunk.startLine,
+            endLine: chunk.endLine,
+            chunkType: "code",
+          },
+        }]);
+        allChunks.push({
+          id,
+          text: chunk.text,
+          file: file.relativePath,
+          lines: [chunk.startLine, chunk.endLine],
+        });
+      }
+    }
+
+    const pairs = new Set<string>();
+    for (const chunk of allChunks) {
+      const vec = await embedder.embedQuery(chunk.text);
+      const similar = await vectorStore.search(vec, { limit: limit * 2 });
+
+      for (const match of similar) {
+        if (match.item.id === chunk.id) continue;
+        if (match.score < threshold) continue;
+
+        const pairKey = [chunk.file, match.item.metadata.filePath].sort().join("||") +
+          "||" +
+          [chunk.id, match.item.id].sort().join("::");
+        if (pairs.has(pairKey)) continue;
+        pairs.add(pairKey);
+
+        results.push({
+          file1: chunk.file,
+          file2: match.item.metadata.filePath,
+          lines1: `${chunk.lines[0]}-${chunk.lines[1]}`,
+          lines2: `${match.item.metadata.startLine}-${match.item.metadata.endLine}`,
+          score: Math.round(match.score * 100) / 100,
+          snippet1: chunk.text.slice(0, 100),
+          snippet2: match.item.text?.slice(0, 100) ?? "",
+        });
+      }
+
+      if (results.length >= limit) break;
+    }
+
+    results.sort((a, b) => b.score - a.score);
+    const top = results.slice(0, limit);
+
+    return {
+      success: true,
+      output: JSON.stringify({
+        filesScanned: codeFiles.length,
+        chunksAnalyzed: allChunks.length,
+        duplicatesFound: top.length,
+        threshold,
+        embeddingModel: embedder.modelName,
+        duplicates: top,
+      }),
+    };
+  }
+}

package/src/tools/neural/neural-smells.tool.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+import { CodebaseExplorer } from "../../libs/codebase/indexer/explorer";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+const SmellSchema = z.object({
+  smell: z.string(),
+  severity: z.enum(["critical", "warning", "info"]),
+  location: z.string().optional(),
+  description: z.string(),
+  refactoring: z.string(),
+});
+
+export class NeuralSmellsTool extends ToolBase {
+  readonly name = "neuralSmells";
+  readonly description = "Detect code smells using static analysis and LLM-powered semantic review: God class, long method, feature envy, primitive obsession, switch statements, deep nesting, duplicate code, and more. Returns structured findings with refactoring suggestions.";
+  override readonly readonly = true;
+
+  constructor() {
+    super(z.object({
+      target: z.string().optional().describe("File path or leave empty for whole project"),
+      projectPath: z.string().optional(),
+      limit: z.number().optional().describe("Max smells to return"),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, ctx: ToolContext): Promise<ToolExecutionResult> {
+    const rootPath = (input.projectPath as string) ?? process.cwd();
+    const target = (input.target as string) || undefined;
+    const limit = (input.limit as number) ?? 15;
+
+    const explorer = new 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 staticSmells: Array<{ smell: string; severity: string; file: string; line: number; description: string; refactoring: string }> = [];
+
+    for (const file of scanFiles) {
+      const content = fs.readFileSync(file.absolutePath, "utf8");
+      const lines = content.split("\n");
+
+      if (lines.length > 500) {
+        staticSmells.push({ smell: "large-file", severity: "warning", file: file.relativePath, line: 1, description: `${lines.length} lines — consider splitting`, refactoring: "Split into smaller modules by concern" });
+      }
+
+      let maxDepth = 0;
+      let depth = 0;
+      for (const line of lines) {
+        if (line.match(/^\s*(if|for|while|switch)\s*[({]/)) depth++;
+        if (line.trim() === "}" || line.trim() === "});") depth = Math.max(0, depth - 1);
+        maxDepth = Math.max(maxDepth, depth);
+      }
+      if (maxDepth > 4) {
+        staticSmells.push({ smell: "deep-nesting", severity: "warning", file: file.relativePath, line: 1, description: `Max nesting depth: ${maxDepth}`, refactoring: "Use early returns, guard clauses, or extract to functions" });
+      }
+
+      const anyCount = (content.match(/\bany\b/g) || []).length;
+      if (anyCount > 10) {
+        staticSmells.push({ smell: "excessive-any", severity: "warning", file: file.relativePath, line: 1, description: `${anyCount} 'any' type usages`, refactoring: "Replace with explicit types or 'unknown'" });
+      }
+    }
+
+    const cs = ctx.conversation?.callStructured;
+    if (!cs) {
+      return { success: true, output: JSON.stringify({ filesScanned: scanFiles.length, smellsFound: staticSmells.length, smells: staticSmells }) };
+    }
+
+    const codeSnippets = scanFiles.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, smellsFound: staticSmells.length, smells: staticSmells.slice(0, limit) }) };
+    }
+
+    const prompt = `Analyze this code for design smells: God class, long method, feature envy, primitive obsession, switch statement abuse, refused bequest, shotgun surgery, divergent change, data clumps, lazy class, speculative generality, middle man, inappropriate intimacy, message chains, duplicate code.\n\n${codeSnippets}\n\nReturn structured findings with specific file locations and refactoring suggestions. Be specific about file path and line number.`;
+
+    try {
+      const result = await cs(prompt, z.object({ smells: z.array(SmellSchema) }));
+      const llmSmells = (result.smells ?? []).map((s) => ({
+        smell: s.smell,
+        severity: s.severity,
+        file: s.location ?? target ?? "",
+        line: 1,
+        description: s.description,
+        refactoring: s.refactoring,
+      }));
+      const allSmells = [...staticSmells, ...llmSmells];
+      return { success: true, output: JSON.stringify({ filesScanned: scanFiles.length, smellsFound: allSmells.length, smells: allSmells.slice(0, limit) }) };
+    } catch {
+      return { success: true, output: JSON.stringify({ filesScanned: scanFiles.length, smellsFound: staticSmells.length, smells: staticSmells }) };
+    }
+  }
+}

package/src/tools/neural/neural-suggest.tool.ts

@@ -0,0 +1,65 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+import { DependencyExtractor } from "../../libs/codebase/graph/dependency-extractor";
+import { CodebaseExplorer } from "../../libs/codebase/indexer/explorer";
+
+export class NeuralSuggestTool extends ToolBase {
+  readonly name = "neuralSuggest";
+  readonly description = "Suggest the best files/modules to implement a given feature. Uses dependency graph, codebase structure, and LLM reasoning to rank candidates.";
+  override readonly readonly = true;
+
+  constructor() {
+    super(z.object({
+      feature: z.string().describe("Description of the feature to implement"),
+      projectPath: z.string().optional(),
+      maxSuggestions: z.number().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, ctx: ToolContext): Promise<ToolExecutionResult> {
+    const { feature, maxSuggestions } = input as { feature: string; maxSuggestions?: number };
+    const rootPath = (input.projectPath as string) ?? process.cwd();
+    const limit = maxSuggestions ?? 5;
+
+    const explorer = new 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 DependencyExtractor();
+    const graph = await depExtractor.buildGraph(codeFiles, rootPath);
+
+    const featureTokens = feature.toLowerCase().split(/\s+/);
+    const scored = codeFiles.map((f) => {
+      const rel = f.relativePath.toLowerCase();
+      let score = 0;
+      for (const token of featureTokens) {
+        if (rel.includes(token)) score += 3;
+        if (rel.split("/").some((p) => p.includes(token))) score += 2;
+      }
+      const inEdges = graph.edges.filter((e) => e.to === f.relativePath).length;
+      score += Math.min(inEdges, 5);
+      const outEdges = graph.edges.filter((e) => e.from === f.relativePath).length;
+      score += Math.min(outEdges, 3);
+      return { path: f.relativePath, score };
+    });
+
+    scored.sort((a, b) => b.score - a.score);
+    const top = scored.slice(0, limit);
+
+    const cs = ctx.conversation?.callStructured;
+    if (cs && top.length > 0) {
+      const topList = top.map((t) => `- ${t.path}`).join("\n");
+      const prompt = `Given the feature: "${feature}", these are the top file candidates:\n${topList}\n\nSuggest which file(s) would be the best starting point and explain why. Return JSON: { reasoning: string, recommended: string[] }`;
+      try {
+        const llmResult = await cs(prompt, z.object({ reasoning: z.string(), recommended: z.array(z.string()) }));
+        const data = llmResult as { reasoning?: string; recommended?: string[] };
+        return { success: true, output: JSON.stringify({ feature, suggestions: top, llmReasoning: data.reasoning, llmRecommended: data.recommended }) };
+      } catch {
+        /* fall back to static output */
+      }
+    }
+
+    return { success: true, output: JSON.stringify({ feature, suggestions: top, totalFiles: codeFiles.length }) };
+  }
+}

package/src/tools/quality/index.ts

@@ -0,0 +1,7 @@
+export * from "./quality-complexity.tool";
+export * from "./quality-coupling.tool";
+export * from "./quality-coverage.tool";
+export * from "./quality-deps.tool";
+export * from "./quality-duplication.tool";
+export * from "./quality-size.tool";
+export * from "./quality-types.tool";

package/src/tools/quality/quality-complexity.tool.ts

@@ -0,0 +1,132 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+import { CodebaseExplorer } from "../../libs/codebase/indexer/explorer";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export class QualityComplexityTool extends ToolBase {
+  readonly name = "qualityComplexity";
+  readonly description = "Calculate cyclomatic complexity per file and function. Identifies complex code that is hard to test and maintain. Returns rankings and risk levels.";
+  override readonly readonly = true;
+
+  constructor() {
+    super(z.object({
+      target: z.string().optional(),
+      projectPath: z.string().optional(),
+      limit: z.number().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const target = (input.target as string) || undefined;
+    const rootPath = (input.projectPath as string) ?? process.cwd();
+    const limit = (input.limit as number) ?? 20;
+
+    let filesToScan: Array<{ relativePath: string; absolutePath: string }>;
+    if (target) {
+      const abs = path.join(rootPath, target);
+      filesToScan = fs.existsSync(abs) ? [{ relativePath: target, absolutePath: abs }] : [];
+    } else {
+      const explorer = new CodebaseExplorer();
+      filesToScan = explorer.explore({ rootPath })
+        .filter((f) => f.classification === "source-code")
+        .map((f) => ({ relativePath: f.relativePath, absolutePath: f.absolutePath }));
+    }
+
+    const results: Array<{ file: string; complexity: number; risk: string; topFunctions: Array<{ name: string; complexity: number; line: number }> }> = [];
+
+    for (const file of filesToScan) {
+      const content = fs.readFileSync(file.absolutePath, "utf8");
+      const fileComplexity = this.calculateFileComplexity(content);
+      const functions = this.calculateFunctionComplexity(content);
+
+      if (fileComplexity > 5 || functions.some((f) => f.complexity > 5)) {
+        results.push({
+          file: file.relativePath,
+          complexity: fileComplexity,
+          risk: fileComplexity > 50 ? "critical" : fileComplexity > 20 ? "high" : fileComplexity > 10 ? "medium" : "low",
+          topFunctions: functions.filter((f) => f.complexity > 5).sort((a, b) => b.complexity - a.complexity).slice(0, 5),
+        });
+      }
+    }
+
+    results.sort((a, b) => b.complexity - a.complexity);
+
+    return {
+      success: true,
+      output: JSON.stringify({
+        filesScanned: filesToScan.length,
+        highComplexityFiles: results.length,
+        topComplexFiles: results.slice(0, limit),
+      }),
+    };
+  }
+
+  private calculateFileComplexity(content: string): number {
+    let complexity = 1;
+    const patterns = [
+      /\bif\s*\(/g, /\belse\s+if\b/g, /\bwhile\s*\(/g,
+      /\bfor\s*\(/g, /\bcase\b/g, /\bcatch\s*\(/g,
+      /\?\s*\w/g, /\&\&/g, /\|\|/g,
+    ];
+
+    for (const pattern of patterns) {
+      const matches = content.match(pattern);
+      if (matches) complexity += matches.length;
+    }
+
+    return complexity;
+  }
+
+  private calculateFunctionComplexity(content: string): Array<{ name: string; complexity: number; line: number }> {
+    const functions: Array<{ name: string; complexity: number; line: number }> = [];
+    const lines = content.split("\n");
+
+    const fnPattern = /(?:export\s+)?(?:async\s+)?function\s+(\w+)\s*\([^)]*\)/;
+    const methodPattern = /(?:public|private|protected|static|async)?\s+(\w+)\s*\([^)]*\)\s*\{/;
+    const arrowPattern = /(?:const|let|var)\s+(\w+)\s*=\s*(?:async\s*)?\([^)]*\)\s*=>\s*\{/;
+
+    let inFunction = false;
+    let fnName = "";
+    let fnStart = 0;
+    let fnComplexity = 1;
+    let braceDepth = 0;
+
+    for (let i = 0; i < lines.length; i++) {
+      const line = lines[i];
+      const fnMatch = line.match(fnPattern);
+      const methodMatch = line.match(methodPattern);
+      const arrowMatch = line.match(arrowPattern);
+
+      if (!inFunction && (fnMatch || methodMatch || arrowMatch)) {
+        inFunction = true;
+        fnName = (fnMatch?.[1] ?? methodMatch?.[1] ?? arrowMatch?.[1] ?? "anonymous");
+        fnStart = i + 1;
+        fnComplexity = 1;
+      }
+
+      if (inFunction) {
+        braceDepth += (line.match(/\{/g) || []).length;
+        braceDepth -= (line.match(/\}/g) || []).length;
+
+        const complexityAdders = [
+          /\bif\s*\(/g, /\belse\s+if\b/g, /\bwhile\s*\(/g,
+          /\bfor\s*\(/g, /\bcase\b/g, /\bcatch\s*\(/g,
+          /\?\s*\w/g, /\&\&/g, /\|\|/g,
+        ];
+        for (const pattern of complexityAdders) {
+          const matches = line.match(pattern);
+          if (matches) fnComplexity += matches.length;
+        }
+
+        if (braceDepth <= 0 && inFunction) {
+          functions.push({ name: fnName, complexity: fnComplexity, line: fnStart });
+          inFunction = false;
+          braceDepth = 0;
+        }
+      }
+    }
+
+    return functions;
+  }
+}