ai-first-cli 1.2.3 → 1.3.0

package/src/commands/ai-first.ts

@@ -8,6 +8,7 @@ import { generateIndex, IncrementalIndexer, EXAMPLE_QUERIES } from "../core/inde
 import { generateAIContext } from "../core/aiContextGenerator.js";
 import { generateHierarchy } from "../core/hierarchyGenerator.js";
 import { ensureDir, writeFile } from "../utils/fileUtils.js";
+import { AI_CONTEXT_DIR, getIndexDbPath, getHierarchyPath } from "../utils/constants.js";
 import { analyzeArchitecture, generateArchitectureFile } from "../analyzers/architecture.js";
 import { detectTechStack, generateTechStackFile } from "../analyzers/techStack.js";
 import { discoverEntrypoints, generateEntrypointsFile } from "../analyzers/entrypoints.js";
@@ -416,7 +417,7 @@ Usage: ai-first index [options]
 
 Options:
   -r, --root <dir>      Root directory to scan (default: current directory)
-  -o, --output <path>  Output path for index.db (default: ./ai/index.db)
+  -o, --output <path>  Output path for index.db (default: ./ai-context/index.db)
   -s, --semantic       Force semantic indexing
   -h, --help           Show help message
 
@@ -435,7 +436,7 @@ Example queries (for AI agents):
     }
 
     if (!outputPath) {
-      outputPath = path.join(rootDir, "ai", "index.db");
+      outputPath = getIndexDbPath(rootDir);
     }
 
     const aiDir = path.join(rootDir, "ai-context");
@@ -489,7 +490,7 @@ Example queries (for AI agents):
     const modules: Record<string, { path: string; files: string[] }> = {};
     for (const file of scanResult.files) {
       const parts = file.relativePath.split('/');
-      if (parts.length > 1 && parts[0] !== 'ai') {
+      if (parts.length > 1 && parts[0] !== AI_CONTEXT_DIR && parts[0] !== 'ai') {
         if (!modules[parts[0]]) modules[parts[0]] = { path: parts[0], files: [] };
         modules[parts[0]].files.push(file.relativePath);
       }
@@ -543,7 +544,7 @@ Example queries (for AI agents):
             
             const initSqlJs = (await import("sql.js")).default;
             const SQL = await initSqlJs();
-            const dbPath = outputPath || path.join(rootDir, "ai", "index.db");
+            const dbPath = outputPath || getIndexDbPath(rootDir);
             let db: Database;
             if (fs.existsSync(dbPath)) {
               const fileBuffer = fs.readFileSync(dbPath);
@@ -577,7 +578,7 @@ Example queries (for AI agents):
     // Watch command - incremental indexing
     args.shift();
     let rootDir = process.cwd();
-    let outputPath = path.join(rootDir, "ai", "index.db");
+    let outputPath = getIndexDbPath(rootDir);
     let semanticMode = false;
     let debounceMs = 300;
 
@@ -605,7 +606,7 @@ Usage: ai-first watch [options]
 
 Options:
   -r, --root <dir>       Root directory to watch (default: current directory)
-  -o, --output <path>   Output path for index.db (default: ./ai/index.db)
+  -o, --output <path>   Output path for index.db (default: ./ai-context/index.db)
   -d, --debounce <ms>   Debounce delay in ms (default: 300)
   -h, --help            Show help message
 
@@ -701,7 +702,7 @@ Arguments:
 
 Options:
   -r, --root <dir>        Root directory (default: current directory)
-  -o, --output <dir>     Output directory (default: ./ai)
+  -o, --output <dir>     Output directory (default: ./ai-context)
   -d, --depth <n>        Graph traversal depth (default: 1)
   -m, --max-symbols <n>  Max related symbols (default: 50)
   -f, --format <fmt>      Output format: json, markdown, text (default: json)
@@ -781,7 +782,7 @@ Examples:
     // Summarize command - generate hierarchical repository summaries
     args.shift();
     let rootDir = process.cwd();
-    let outputPath = path.join(rootDir, "ai", "hierarchy.json");
+    let outputPath = getHierarchyPath(rootDir);
 
     for (let i = 0; i < args.length; i++) {
       const arg = args[i];
@@ -803,7 +804,7 @@ Usage: ai-first summarize [options]
 
 Options:
   -r, --root <dir>      Root directory (default: current directory)
-  -o, --output <path>   Output path (default: ./ai/hierarchy.json)
+  -o, --output <path>   Output path (default: ./ai-context/hierarchy.json)
   -h, --help            Show help message
 
 Output:
@@ -834,7 +835,7 @@ Output:
     args.shift();
     const queryType = args.shift();
     let rootDir = process.cwd();
-    let dbPath = path.join(rootDir, "ai", "index.db");
+    let dbPath = getIndexDbPath(rootDir);
 
     for (let i = 0; i < args.length; i++) {
       const arg = args[i];
@@ -842,7 +843,7 @@ Output:
         case "--root":
         case "-r":
           rootDir = args[++i];
-          dbPath = path.join(rootDir, "ai", "index.db");
+          dbPath = getIndexDbPath(rootDir);
           break;
         case "--db":
         case "-d":
@@ -867,7 +868,7 @@ Subcommands:
 
 Options:
   -r, --root <dir>   Root directory (default: current directory)
-  -d, --db <path>    Database path (default: ./ai/index.db)
+  -d, --db <path>    Database path (default: ./ai-context/index.db)
   -h, --help         Show help message
 `);
       process.exit(0);
@@ -1111,7 +1112,7 @@ Commands:
 
 Options:
   -r, --root <dir>      Root directory to scan (default: current directory)
-  -o, --output <dir>   Output directory (default: ./ai)
+  -o, --output <dir>   Output directory (default: ./ai-context)
   -h, --help           Show help message
 `);
           process.exit(0);

package/src/core/analysis/architectureDetector.ts

@@ -0,0 +1,487 @@
+export interface ArchitecturePattern {
+  name: string;
+  confidence: number;
+  evidence: string[];
+}
+
+export interface Layer {
+  name: string;
+  files: string[];
+  symbols: string[];
+  responsibility: string;
+}
+
+export interface ArchitectureAnalysis {
+  primary: ArchitecturePattern | null;
+  secondary: ArchitecturePattern[];
+  layers: Layer[];
+  entryPoints: string[];
+}
+
+interface PatternMatcher {
+  name: string;
+  analyze(
+    symbols: Array<{
+      id: string;
+      name: string;
+      type: string;
+      file: string;
+    }>,
+    dependencyGraph: {
+      edges: Array<{ from: string; to: string; type: string }>;
+    }
+  ): { confidence: number; evidence: string[] };
+}
+
+export class ArchitectureDetector {
+  private patterns: PatternMatcher[] = [
+    {
+      name: "MVC (Model-View-Controller)",
+      analyze: (symbols, graph) => {
+        const evidence: string[] = [];
+        let score = 0;
+
+        const controllers = symbols.filter(
+          (s) =>
+            s.name.toLowerCase().includes("controller") ||
+            s.file.toLowerCase().includes("controller")
+        );
+        const models = symbols.filter(
+          (s) =>
+            s.name.toLowerCase().includes("model") ||
+            s.file.toLowerCase().includes("model")
+        );
+        const views = symbols.filter(
+          (s) =>
+            s.name.toLowerCase().includes("view") ||
+            s.file.toLowerCase().includes("view")
+        );
+
+        if (controllers.length > 0) {
+          evidence.push(`Found ${controllers.length} controllers`);
+          score += 0.3;
+        }
+        if (models.length > 0) {
+          evidence.push(`Found ${models.length} models`);
+          score += 0.3;
+        }
+        if (views.length > 0) {
+          evidence.push(`Found ${views.length} views`);
+          score += 0.2;
+        }
+
+        const controllerToModel = graph.edges.some(
+          (e) =>
+            e.from.toLowerCase().includes("controller") &&
+            e.to.toLowerCase().includes("model")
+        );
+        if (controllerToModel) {
+          evidence.push("Controllers import Models");
+          score += 0.2;
+        }
+
+        return { confidence: Math.min(score, 1), evidence };
+      },
+    },
+    {
+      name: "Layered Architecture",
+      analyze: (symbols, graph) => {
+        const evidence: string[] = [];
+        let score = 0;
+
+        const layers = {
+          api: symbols.filter(
+            (s) =>
+              s.name.toLowerCase().includes("controller") ||
+              s.name.toLowerCase().includes("route") ||
+              s.name.toLowerCase().includes("handler") ||
+              s.file.toLowerCase().includes("controller") ||
+              s.file.toLowerCase().includes("routes")
+          ),
+          service: symbols.filter(
+            (s) =>
+              s.name.toLowerCase().includes("service") ||
+              s.name.toLowerCase().includes("usecase") ||
+              s.file.toLowerCase().includes("service") ||
+              s.file.toLowerCase().includes("usecase")
+          ),
+          data: symbols.filter(
+            (s) =>
+              s.name.toLowerCase().includes("repository") ||
+              s.name.toLowerCase().includes("dao") ||
+              s.name.toLowerCase().includes("model") ||
+              s.file.toLowerCase().includes("repository") ||
+              s.file.toLowerCase().includes("model")
+          ),
+        };
+
+        if (layers.api.length > 0) {
+          evidence.push(`API layer: ${layers.api.length} components`);
+          score += 0.25;
+        }
+        if (layers.service.length > 0) {
+          evidence.push(`Service layer: ${layers.service.length} components`);
+          score += 0.25;
+        }
+        if (layers.data.length > 0) {
+          evidence.push(`Data layer: ${layers.data.length} components`);
+          score += 0.25;
+        }
+
+        const hasFlow =
+          layers.api.some((api) =>
+            graph.edges.some(
+              (e) =>
+                e.from === api.id &&
+                layers.service.some((s) => s.id === e.to)
+            )
+          ) ||
+          layers.service.some((svc) =>
+            graph.edges.some(
+              (e) =>
+                e.from === svc.id &&
+                layers.data.some((d) => d.id === e.to)
+            )
+          );
+
+        if (hasFlow) {
+          evidence.push("Layer flow detected: API → Service → Data");
+          score += 0.25;
+        }
+
+        return { confidence: Math.min(score, 1), evidence };
+      },
+    },
+    {
+      name: "Clean Architecture",
+      analyze: (symbols, graph) => {
+        const evidence: string[] = [];
+        let score = 0;
+
+        const entities = symbols.filter(
+          (s) =>
+            s.file.toLowerCase().includes("entity") ||
+            s.file.toLowerCase().includes("domain")
+        );
+        const useCases = symbols.filter(
+          (s) =>
+            s.file.toLowerCase().includes("usecase") ||
+            s.file.toLowerCase().includes("interactor")
+        );
+        const interfaces = symbols.filter(
+          (s) =>
+            s.file.toLowerCase().includes("interface") ||
+            s.file.toLowerCase().includes("adapter")
+        );
+
+        if (entities.length > 0) {
+          evidence.push(`Entities layer: ${entities.length} components`);
+          score += 0.3;
+        }
+        if (useCases.length > 0) {
+          evidence.push(`Use Cases layer: ${useCases.length} components`);
+          score += 0.3;
+        }
+        if (interfaces.length > 0) {
+          evidence.push(`Interface Adapters: ${interfaces.length} components`);
+          score += 0.2;
+        }
+
+        const dependencyRule =
+          !graph.edges.some(
+            (e) =>
+              entities.some((ent) => ent.id === e.from) &&
+              useCases.some((uc) => uc.id === e.to)
+          );
+
+        if (dependencyRule && entities.length > 0) {
+          evidence.push("Dependency Rule: Entities have no external dependencies");
+          score += 0.2;
+        }
+
+        return { confidence: Math.min(score, 1), evidence };
+      },
+    },
+    {
+      name: "Hexagonal Architecture (Ports & Adapters)",
+      analyze: (symbols, graph) => {
+        const evidence: string[] = [];
+        let score = 0;
+
+        const ports = symbols.filter(
+          (s) =>
+            s.name.toLowerCase().includes("port") ||
+            s.file.toLowerCase().includes("port")
+        );
+        const adapters = symbols.filter(
+          (s) =>
+            s.name.toLowerCase().includes("adapter") ||
+            s.file.toLowerCase().includes("adapter")
+        );
+        const domain = symbols.filter(
+          (s) =>
+            s.file.toLowerCase().includes("domain") ||
+            (!s.file.toLowerCase().includes("adapter") &&
+              !s.file.toLowerCase().includes("port"))
+        );
+
+        if (ports.length > 0) {
+          evidence.push(`Ports: ${ports.length} interfaces`);
+          score += 0.3;
+        }
+        if (adapters.length > 0) {
+          evidence.push(`Adapters: ${adapters.length} implementations`);
+          score += 0.3;
+        }
+        if (domain.length > 0) {
+          evidence.push(`Domain: ${domain.length} components`);
+          score += 0.2;
+        }
+
+        const portImplementations = adapters.some((adapter) =>
+          graph.edges.some(
+            (e) =>
+              e.from === adapter.id &&
+              ports.some((p) => e.to.includes(p.name))
+          )
+        );
+
+        if (portImplementations) {
+          evidence.push("Adapters implement Ports");
+          score += 0.2;
+        }
+
+        return { confidence: Math.min(score, 1), evidence };
+      },
+    },
+    {
+      name: "Microservices",
+      analyze: (symbols, graph) => {
+        const evidence: string[] = [];
+        let score = 0;
+
+        const services = symbols.filter(
+          (s) =>
+            s.name.toLowerCase().includes("service") ||
+            s.file.toLowerCase().includes("service")
+        );
+
+        const independentServices = services.filter((svc) => {
+          const dependencies = graph.edges.filter((e) => e.from === svc.id);
+          return dependencies.length <= 3;
+        });
+
+        if (services.length >= 3) {
+          evidence.push(`Found ${services.length} services`);
+          score += 0.3;
+        }
+
+        if (independentServices.length / services.length > 0.5) {
+          evidence.push("Services are loosely coupled");
+          score += 0.3;
+        }
+
+        const noCycles = this.hasNoCircularDependencies(graph);
+        if (noCycles && services.length > 0) {
+          evidence.push("No circular dependencies between services");
+          score += 0.2;
+        }
+
+        return { confidence: Math.min(score, 1), evidence };
+      },
+    },
+  ];
+
+  detect(
+    symbols: Array<{
+      id: string;
+      name: string;
+      type: string;
+      file: string;
+    }>,
+    dependencyGraph: {
+      edges: Array<{ from: string; to: string; type: string }>;
+    }
+  ): ArchitectureAnalysis {
+    const results: ArchitecturePattern[] = [];
+
+    for (const pattern of this.patterns) {
+      const result = pattern.analyze(symbols, dependencyGraph);
+      if (result.confidence > 0.3) {
+        results.push({
+          name: pattern.name,
+          confidence: result.confidence,
+          evidence: result.evidence,
+        });
+      }
+    }
+
+    results.sort((a, b) => b.confidence - a.confidence);
+
+    return {
+      primary: results[0] || null,
+      secondary: results.slice(1),
+      layers: this.detectLayers(symbols),
+      entryPoints: this.detectEntryPoints(symbols),
+    };
+  }
+
+  private detectLayers(
+    symbols: Array<{
+      id: string;
+      name: string;
+      type: string;
+      file: string;
+    }>
+  ): Layer[] {
+    const layers: Layer[] = [];
+
+    const apiLayer = {
+      name: "API / Presentation",
+      files: [] as string[],
+      symbols: [] as string[],
+      responsibility: "HTTP request handling, routing, validation",
+    };
+
+    const serviceLayer = {
+      name: "Service / Business Logic",
+      files: [] as string[],
+      symbols: [] as string[],
+      responsibility: "Business rules, use cases, workflows",
+    };
+
+    const dataLayer = {
+      name: "Data / Persistence",
+      files: [] as string[],
+      symbols: [] as string[],
+      responsibility: "Database access, queries, caching",
+    };
+
+    for (const symbol of symbols) {
+      const name = symbol.name.toLowerCase();
+      const file = symbol.file.toLowerCase();
+
+      if (
+        name.includes("controller") ||
+        name.includes("route") ||
+        name.includes("handler") ||
+        name.includes("endpoint") ||
+        file.includes("controller") ||
+        file.includes("routes") ||
+        file.includes("api")
+      ) {
+        if (!apiLayer.files.includes(symbol.file)) {
+          apiLayer.files.push(symbol.file);
+        }
+        apiLayer.symbols.push(symbol.id);
+      } else if (
+        name.includes("service") ||
+        name.includes("usecase") ||
+        name.includes("manager") ||
+        name.includes("handler") ||
+        file.includes("service") ||
+        file.includes("usecase") ||
+        file.includes("business")
+      ) {
+        if (!serviceLayer.files.includes(symbol.file)) {
+          serviceLayer.files.push(symbol.file);
+        }
+        serviceLayer.symbols.push(symbol.id);
+      } else if (
+        name.includes("repository") ||
+        name.includes("dao") ||
+        name.includes("model") ||
+        name.includes("entity") ||
+        file.includes("repository") ||
+        file.includes("model") ||
+        file.includes("data") ||
+        file.includes("db")
+      ) {
+        if (!dataLayer.files.includes(symbol.file)) {
+          dataLayer.files.push(symbol.file);
+        }
+        dataLayer.symbols.push(symbol.id);
+      }
+    }
+
+    if (apiLayer.symbols.length > 0) layers.push(apiLayer);
+    if (serviceLayer.symbols.length > 0) layers.push(serviceLayer);
+    if (dataLayer.symbols.length > 0) layers.push(dataLayer);
+
+    return layers;
+  }
+
+  private detectEntryPoints(
+    symbols: Array<{
+      id: string;
+      name: string;
+      type: string;
+      file: string;
+    }>
+  ): string[] {
+    const entryPoints: string[] = [];
+
+    const patterns = [
+      /main$/i,
+      /index$/i,
+      /init$/i,
+      /start$/i,
+      /server$/i,
+      /app$/i,
+      /bootstrap$/i,
+      /handler$/i,
+      /controller$/i,
+    ];
+
+    for (const symbol of symbols) {
+      const name = symbol.name.toLowerCase();
+      const file = symbol.file.toLowerCase();
+
+      if (
+        patterns.some((p) => p.test(name)) ||
+        file.includes("main.") ||
+        file.includes("index.") ||
+        file.includes("app.") ||
+        file.includes("server.")
+      ) {
+        entryPoints.push(symbol.id);
+      }
+    }
+
+    return [...new Set(entryPoints)];
+  }
+
+  private hasNoCircularDependencies(graph: {
+    edges: Array<{ from: string; to: string; type: string }>;
+  }): boolean {
+    const nodes = [...new Set(graph.edges.flatMap((e) => [e.from, e.to]))];
+    const visited = new Set<string>();
+    const recursionStack = new Set<string>();
+
+    const dfs = (node: string): boolean => {
+      if (recursionStack.has(node)) return false;
+      if (visited.has(node)) return true;
+
+      visited.add(node);
+      recursionStack.add(node);
+
+      const outgoing = graph.edges.filter((e) => e.from === node);
+      for (const edge of outgoing) {
+        if (!dfs(edge.to)) return false;
+      }
+
+      recursionStack.delete(node);
+      return true;
+    };
+
+    for (const node of nodes) {
+      if (!visited.has(node)) {
+        if (!dfs(node)) return false;
+      }
+    }
+
+    return true;
+  }
+}
+
+export const architectureDetector = new ArchitectureDetector();