@thoughtflow/codebase 0.2.0

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

@@ -0,0 +1,57 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+import { DependencyExtractor, DependencyGraph } from "../../libs/codebase/graph/dependency-extractor";
+import { CodebaseExplorer } from "../../libs/codebase/indexer/explorer";
+import { ImpactAnalyzer } from "../../libs/codebase/graph/graph-analysis";
+
+export class QualityCouplingTool extends ToolBase {
+  readonly name = "qualityCoupling";
+  readonly description = "Analyze afferent/efferent coupling per module. Identifies highly coupled modules (instability metric), god modules, and architectural hotspots.";
+  readonly = true;
+
+  constructor() {
+    super(z.object({
+      projectPath: z.string().optional(),
+      limit: z.number().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const rootPath = (input.projectPath as string) ?? process.cwd();
+    const limit = (input.limit as number) ?? 15;
+
+    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 coupling: Array<{ file: string; afferent: number; efferent: number; instability: number; risk: string }> = [];
+
+    for (const file of codeFiles) {
+      const ca = graph.edges.filter((e) => e.to === file.relativePath && !e.to.startsWith(".")).length +
+                graph.edges.filter((e) => e.to === file.relativePath && e.to.startsWith(".")).length;
+      const ce = graph.edges.filter((e) => e.from === file.relativePath).length;
+      const instability = ce > 0 ? ce / (ca + ce) : 0;
+
+      if (ca > 2 || ce > 3) {
+        coupling.push({
+          file: file.relativePath,
+          afferent: ca,
+          efferent: ce,
+          instability: Math.round(instability * 100) / 100,
+          risk: ca > 10 ? "hotspot" : instability > 0.7 ? "unstable" : instability < 0.3 ? "rigid" : "balanced",
+        });
+      }
+    }
+
+    coupling.sort((a, b) => b.afferent - a.afferent);
+
+    return {
+      success: true,
+      output: JSON.stringify({ filesAnalyzed: codeFiles.length, couplingResults: coupling.slice(0, limit), summary: { hotspots: coupling.filter((c) => c.risk === "hotspot").length, unstable: coupling.filter((c) => c.risk === "unstable").length, rigid: coupling.filter((c) => c.risk === "rigid").length } }),
+    };
+  }
+}

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

@@ -0,0 +1,78 @@
+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 QualityCoverageTool extends ToolBase {
+  readonly name = "qualityCoverage";
+  readonly description = "Analyze test coverage gaps. For each source file, checks if a corresponding test file exists and estimates untested code paths.";
+  readonly = true;
+
+  constructor() {
+    super(z.object({
+      projectPath: z.string().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const rootPath = (input.projectPath as string) ?? process.cwd();
+
+    const explorer = new CodebaseExplorer();
+    const files = explorer.explore({ rootPath });
+
+    const sourceFiles = files.filter((f) => f.classification === "source-code");
+    const testFiles = files.filter((f) => f.classification === "test");
+
+    const testPatterns = [
+      (f: string) => f.replace(/\.ts$/, ".test.ts").replace(/\.tsx$/, ".test.tsx"),
+      (f: string) => f.replace(/\.ts$/, ".spec.ts").replace(/\.tsx$/, ".spec.tsx"),
+      (f: string) => f.replace(/^src\//, "__tests__/").replace(/\.ts$/, ".test.ts"),
+    ];
+
+    const uncovered: string[] = [];
+    const covered: string[] = [];
+
+    for (const src of sourceFiles) {
+      const rel = src.relativePath;
+      let hasTest = false;
+
+      for (const pattern of testPatterns) {
+        const testPath = pattern(rel);
+        if (testFiles.some((t) => t.relativePath === testPath || t.relativePath.endsWith(testPath.replace(/^.*\//, "")))) {
+          hasTest = true;
+          break;
+        }
+      }
+
+      if (hasTest) {
+        covered.push(rel);
+      } else {
+        uncovered.push(rel);
+      }
+    }
+
+    const coverage = sourceFiles.length > 0
+      ? Math.round((covered.length / sourceFiles.length) * 10000) / 100
+      : 0;
+
+    const uncoveredByDir = new Map<string, string[]>();
+    for (const f of uncovered) {
+      const dir = path.dirname(f);
+      if (!uncoveredByDir.has(dir)) uncoveredByDir.set(dir, []);
+      uncoveredByDir.get(dir)!.push(path.basename(f));
+    }
+
+    return {
+      success: true,
+      output: JSON.stringify({
+        totalSourceFiles: sourceFiles.length,
+        filesWithTests: covered.length,
+        filesWithoutTests: uncovered.length,
+        estimatedCoverage: coverage,
+        uncoveredByDirectory: Array.from(uncoveredByDir.entries()).map(([dir, files]) => ({ directory: dir, untestedCount: files.length, files: files.slice(0, 5) })),
+        uncoveredFiles: uncovered.slice(0, 30),
+      }),
+    };
+  }
+}

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

@@ -0,0 +1,89 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+import * as fs from "node:fs";
+import * as path from "node:path";
+
+export class QualityDepsTool extends ToolBase {
+  readonly name = "qualityDeps";
+  readonly description = "Check dependencies: outdated packages, unused dependencies, vulnerable versions, and license compliance. Reads package.json and lock files.";
+  readonly = true;
+
+  constructor() {
+    super(z.object({
+      projectPath: z.string().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const rootPath = (input.projectPath as string) ?? process.cwd();
+
+    const packageJsonPath = path.join(rootPath, "package.json");
+    const lockPath = path.join(rootPath, "package-lock.json");
+
+    if (!fs.existsSync(packageJsonPath)) {
+      return { success: true, output: JSON.stringify({ error: "No package.json found" }) };
+    }
+
+    const pkg = JSON.parse(fs.readFileSync(packageJsonPath, "utf8"));
+    const allDeps = { ...(pkg.dependencies ?? {}), ...(pkg.devDependencies ?? {}) };
+
+    const projectFiles = this.collectSourceFiles(rootPath);
+    const depsUsage = new Map<string, number>();
+
+    for (const dep of Object.keys(allDeps)) {
+      depsUsage.set(dep, 0);
+      for (const file of projectFiles) {
+        const content = fs.readFileSync(file, "utf8");
+        if (content.includes(`"${dep}"`) || content.includes(`'${dep}'`) || content.includes(`from "${dep}"`) || content.includes(`from '${dep}'`)) {
+          depsUsage.set(dep, (depsUsage.get(dep) ?? 0) + 1);
+        }
+      }
+    }
+
+    const unused: string[] = [];
+    for (const [dep, count] of depsUsage) {
+      if (count === 0) unused.push(dep);
+    }
+
+    const allDepsList = Object.entries(allDeps).map(([name, version]) => {
+      const versionStr = (version as string).replace(/^[\^~]/, "");
+      return { name, version: versionStr, usedIn: depsUsage.get(name) ?? 0, isUnused: (depsUsage.get(name) ?? 0) === 0 };
+    });
+
+    return {
+      success: true,
+      output: JSON.stringify({
+        totalDeps: allDepsList.length,
+        dependencies: Object.keys(pkg.dependencies ?? {}).length,
+        devDependencies: Object.keys(pkg.devDependencies ?? {}).length,
+        unusedDeps: unused.length,
+        unusedDepList: unused,
+        deps: allDepsList.slice(0, 50),
+        recommendations: this.generateRecs(allDepsList, unused),
+      }),
+    };
+  }
+
+  private collectSourceFiles(rootPath: string): string[] {
+    const results: string[] = [];
+    const walk = (dir: string) => {
+      const entries = fs.readdirSync(dir, { withFileTypes: true });
+      for (const e of entries) {
+        if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+        const full = path.join(dir, e.name);
+        if (e.isDirectory()) { walk(full); }
+        else if (e.name.endsWith(".ts") || e.name.endsWith(".tsx") || e.name.endsWith(".js") || e.name.endsWith(".jsx")) {
+          results.push(full);
+        }
+      }
+    };
+    walk(rootPath);
+    return results;
+  }
+
+  private generateRecs(deps: Array<{ name: string; version: string; usedIn: number; isUnused: boolean }>, unused: string[]): string[] {
+    const recs: string[] = [];
+    if (unused.length > 0) recs.push(`Remove ${unused.length} unused dependencies: ${unused.join(", ")}`);
+    return recs;
+  }
+}

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

@@ -0,0 +1,71 @@
+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 crypto from "node:crypto";
+
+export class QualityDuplicationTool extends ToolBase {
+  readonly name = "qualityDuplication";
+  readonly description = "Detect duplicated code blocks using content hashing. Finds copy-pasted code across files and within files. Reports exact and near-duplicate matches.";
+  readonly = true;
+
+  constructor() {
+    super(z.object({
+      projectPath: z.string().optional(),
+      minLines: z.number().optional().describe("Minimum duplicate block size in lines"),
+      limit: z.number().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const rootPath = (input.projectPath as string) ?? process.cwd();
+    const minLines = (input.minLines as number) ?? 6;
+    const limit = (input.limit as number) ?? 20;
+
+    const explorer = new CodebaseExplorer();
+    const files = explorer.explore({ rootPath })
+      .filter((f) => f.classification === "source-code");
+
+    const hashMap = new Map<string, Array<{ file: string; startLine: number; endLine: number }>>();
+
+    for (const file of files) {
+      const content = fs.readFileSync(file.absolutePath, "utf8");
+      const lines = content.split("\n");
+
+      for (let i = 0; i < lines.length - minLines; i++) {
+        const block = lines.slice(i, i + minLines).map((l) => l.trim()).join("\n");
+        if (block.length < 20) continue;
+        const hash = crypto.createHash("md5").update(block).digest("hex");
+
+        if (!hashMap.has(hash)) hashMap.set(hash, []);
+        hashMap.get(hash)!.push({ file: file.relativePath, startLine: i + 1, endLine: i + minLines });
+      }
+    }
+
+    const duplicates: Array<{ snippet: string; occurrences: number; locations: Array<{ file: string; lines: string }> }> = [];
+
+    for (const [hash, locs] of hashMap) {
+      if (locs.length < 2) continue;
+      const uniqueFiles = new Set(locs.map((l) => l.file));
+      if (uniqueFiles.size < 2) continue;
+
+      duplicates.push({
+        snippet: locs[0].file + ":" + locs[0].startLine,
+        occurrences: locs.length,
+        locations: locs.map((l) => ({ file: l.file, lines: `${l.startLine}-${l.endLine}` })),
+      });
+    }
+
+    duplicates.sort((a, b) => b.occurrences - a.occurrences);
+
+    return {
+      success: true,
+      output: JSON.stringify({
+        filesScanned: files.length,
+        duplicateBlocks: duplicates.length,
+        topDuplicates: duplicates.slice(0, limit),
+        summary: `Found ${duplicates.length} duplicate code blocks across ${new Set(duplicates.flatMap((d) => d.locations.map((l) => l.file))).size} files`,
+      }),
+    };
+  }
+}

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

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+import { CodebaseExplorer } from "../../libs/codebase/indexer/explorer";
+import * as fs from "node:fs";
+
+export class QualitySizeTool extends ToolBase {
+  readonly name = "qualitySize";
+  readonly description = "Analyze file and directory sizes. Find oversized files, largest modules, and bundle size hotspots.";
+  readonly = true;
+
+  constructor() {
+    super(z.object({
+      projectPath: z.string().optional(),
+      limit: z.number().optional(),
+      threshold: z.number().optional().describe("Max recommended lines per file"),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const rootPath = (input.projectPath as string) ?? process.cwd();
+    const limit = (input.limit as number) ?? 20;
+    const threshold = (input.threshold as number) ?? 300;
+
+    const explorer = new CodebaseExplorer();
+    const files = explorer.explore({ rootPath });
+
+    const fileSizes: Array<{ file: string; lines: number; bytes: number; dir: string; risk: string }> = [];
+
+    for (const file of files) {
+      const content = fs.readFileSync(file.absolutePath, "utf8");
+      const lines = content.split("\n").length;
+
+      if (lines > 50) {
+        fileSizes.push({
+          file: file.relativePath,
+          lines,
+          bytes: file.sizeBytes,
+          dir: file.relativePath.split("/").slice(0, -1).join("/") || ".",
+          risk: lines > threshold * 2 ? "critical" : lines > threshold ? "high" : lines > threshold / 2 ? "medium" : "low",
+        });
+      }
+    }
+
+    fileSizes.sort((a, b) => b.lines - a.lines);
+    const oversized = fileSizes.filter((f) => f.risk !== "low");
+
+    const byDir = new Map<string, number>();
+    for (const f of fileSizes) {
+      byDir.set(f.dir, (byDir.get(f.dir) ?? 0) + f.lines);
+    }
+    const dirSizes = Array.from(byDir.entries())
+      .map(([dir, lines]) => ({ dir, totalLines: lines, fileCount: fileSizes.filter((f) => f.dir === dir).length }))
+      .sort((a, b) => b.totalLines - a.totalLines);
+
+    return {
+      success: true,
+      output: JSON.stringify({
+        totalFiles: files.length,
+        oversizedFiles: oversized.length,
+        largestFiles: fileSizes.slice(0, limit),
+        directorySizes: dirSizes.slice(0, 15),
+        recommendations: oversized.length > 5 ? [`${oversized.length} files exceed ${threshold} lines — consider splitting`] : [],
+      }),
+    };
+  }
+}

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

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { ToolBase, ToolContext, ToolExecutionResult } from "@thoughtflow/core";
+import { CodebaseExplorer } from "../../libs/codebase/indexer/explorer";
+import * as fs from "node:fs";
+
+export class QualityTypesTool extends ToolBase {
+  readonly name = "qualityTypes";
+  readonly description = "TypeScript strictness audit. Finds files missing type annotations, using 'any', @ts-ignore directives, implicit return types, and untyped parameters.";
+  readonly = true;
+
+  constructor() {
+    super(z.object({
+      projectPath: z.string().optional(),
+    }));
+  }
+
+  async run(input: Record<string, unknown>, _ctx: ToolContext): Promise<ToolExecutionResult> {
+    const rootPath = (input.projectPath as string) ?? process.cwd();
+
+    const explorer = new CodebaseExplorer();
+    const files = explorer.explore({ rootPath })
+      .filter((f) => f.extension === ".ts" || f.extension === ".tsx");
+
+    const stats = { totalFiles: files.length, anyUsages: 0, tsIgnores: 0, typeAssertions: 0, untypedFunctions: 0, untypedParams: 0 };
+
+    const fileReports: Array<{ file: string; anyCount: number; tsIgnores: number; asAssertions: number; issues: string[] }> = [];
+
+    for (const file of files) {
+      const content = fs.readFileSync(file.absolutePath, "utf8");
+      const anyCount = (content.match(/\bany\b/g) || []).length;
+      const tsIgnores = (content.match(/@ts-ignore/g) || []).length;
+      const asAssertions = (content.match(/\bas\s+\w+/g) || []).length;
+
+      const issues: string[] = [];
+      if (anyCount > 0) issues.push(`${anyCount} 'any' usages`);
+      if (tsIgnores > 0) issues.push(`${tsIgnores} @ts-ignore directives`);
+      if (asAssertions > 5) issues.push(`${asAssertions} type assertions`);
+
+      const lines = content.split("\n");
+      for (let i = 0; i < lines.length; i++) {
+        const fnMatch = lines[i].match(/(?:function|const\s+\w+\s*=\s*(?:async\s*)?)\s*\w*\s*\(([^)]*)\)\s*(?!:)/);
+        if (fnMatch && !lines[i].includes(":") && !lines[i].includes("=>")) {
+          stats.untypedParams++;
+        }
+      }
+
+      if (issues.length > 0) {
+        stats.anyUsages += anyCount;
+        stats.tsIgnores += tsIgnores;
+        stats.typeAssertions += asAssertions;
+        fileReports.push({ file: file.relativePath, anyCount, tsIgnores, asAssertions, issues });
+      }
+    }
+
+    fileReports.sort((a, b) => b.anyCount - a.anyCount);
+
+    return {
+      success: true,
+      output: JSON.stringify({
+        stats,
+        typeQualityScore: files.length > 0 ? Math.max(0, 100 - (stats.anyUsages * 2 + stats.tsIgnores * 5 + stats.typeAssertions)) : 100,
+        worstFiles: fileReports.slice(0, 15),
+      }),
+    };
+  }
+}