ai-first-cli 1.2.2 → 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/adapters/baseAdapter.ts

@@ -60,23 +60,72 @@ export interface LayerRule {
 }
 
 /**
- * Default adapter configuration
+ * Universal entrypoint patterns - work across ALL languages and frameworks
+ */
+const UNIVERSAL_ENTRYPOINTS = [
+  // CLI/Tool entrypoints
+  'main', 'cli', 'cmd', 'command', 'run', 'exec', 'task', 'runner',
+  
+  // App/Plugin/Extension entrypoints
+  'app', 'plugin', 'extension', 'entrypoint', 'bootstrap', 'setup',
+  'initialize', 'init', 'start', 'launch',
+  
+  // Module entrypoints
+  'index', '__main__', 'main',
+  
+  // API/Server entrypoints
+  'api', 'server', 'router', 'gateway',
+  
+  // Web framework entrypoints
+  'controller', 'handler', 'endpoint', 'view', 'page', 'screen', 'component',
+  'route', 'routes', 'resource',
+  
+  // Business logic entrypoints
+  'service', 'usecase', 'interactor', 'action', 'actor',
+  
+  // Async/Distributed entrypoints
+  'job', 'worker', 'consumer', 'producer', 'queue', 'cron', 'schedule',
+  
+  // Framework-agnostic patterns
+  'serializer', 'mutation', 'query', 'resolver',
+  'management', 'admin',
+  
+  // Mobile entrypoints
+  'activity', 'fragment', 'viewcontroller',
+  
+  // Database entrypoints
+  'repository', 'dao', 'mapper',
+];
+
+/**
+ * Universal feature roots - directories that typically contain business features
+ */
+const UNIVERSAL_FEATURE_ROOTS = [
+  'src', 'app', 'lib', 'source', 'sources', 'modules', 'features',
+  'services', 'internal', 'core', 'domain', 'business',
+  'packages', 'components', 'pages', 'screens', 'views',
+  'handlers', 'controllers', 'routes', 'api', 'api/src',
+  'cmd', 'commands', 'scripts',
+];
+
+/**
+ * Default adapter configuration - works for ANY project type
  */
 export const DEFAULT_ADAPTER: AnalysisAdapter = {
   name: 'default',
   displayName: 'Default',
   detectionSignals: [],
-  featureRoots: ['src', 'app', 'lib', 'modules'],
-  ignoredFolders: ['utils', 'helpers', 'types', 'interfaces', 'constants', 'config', 'dto', 'models', 'common', 'shared', 'node_modules', '.git'],
-  entrypointPatterns: ['controller', 'route', 'handler', 'command', 'service'],
+  featureRoots: UNIVERSAL_FEATURE_ROOTS,
+  ignoredFolders: ['utils', 'helpers', 'types', 'interfaces', 'constants', 'config', 'dto', 'models', 'common', 'shared', 'node_modules', '.git', 'dist', 'build', 'coverage', '__tests__', 'test', 'tests', '.next', '.nuxt', '.vite', '__pycache__', '.venv', 'venv', 'scripts', 'docs', 'migrations', 'spec', 'test'],
+  entrypointPatterns: UNIVERSAL_ENTRYPOINTS,
   layerRules: [
-    { name: 'api', priority: 1, patterns: ['controller', 'handler', 'route', 'router', 'api', 'endpoint'] },
-    { name: 'service', priority: 2, patterns: ['service', 'services', 'usecase', 'interactor'] },
-    { name: 'data', priority: 3, patterns: ['repository', 'repo', 'dal', 'dao', 'data', 'persistence'] },
-    { name: 'domain', priority: 4, patterns: ['model', 'entity', 'schema', 'domain'] },
-    { name: 'util', priority: 5, patterns: ['util', 'helper', 'lib', 'common'] }
+    { name: 'api', priority: 1, patterns: ['controller', 'handler', 'route', 'router', 'api', 'endpoint', 'page', 'screen', 'view', 'component', 'gateway', 'resource'] },
+    { name: 'service', priority: 2, patterns: ['service', 'services', 'usecase', 'interactor', 'action', 'actor', 'mutation', 'query', 'resolver'] },
+    { name: 'data', priority: 3, patterns: ['repository', 'repo', 'dal', 'dao', 'data', 'persistence', 'mapper', 'dto'] },
+    { name: 'domain', priority: 4, patterns: ['model', 'entity', 'schema', 'domain', 'event'] },
+    { name: 'util', priority: 5, patterns: ['util', 'helper', 'lib', 'common', 'static', 'constants'] }
   ],
-  supportedExtensions: ['.ts', '.tsx', '.js', '.jsx', '.py', '.java', '.kt', '.go', '.rs', '.rb', '.php', '.cs', '.vue', '.svelte'],
-  flowEntrypointPatterns: ['controller', 'route', 'handler', 'command'],
-  flowExcludePatterns: ['repository', 'repo', 'utils', 'helper', 'model', 'entity', 'dto', 'type', 'interface', 'constant', 'config']
+  supportedExtensions: ['.ts', '.tsx', '.js', '.jsx', '.mjs', '.cjs', '.py', '.java', '.kt', '.go', '.rs', '.rb', '.php', '.cs', '.vue', '.svelte', '.swift', '.h', '.m', '.fs', '.fsx', '.rake', '.erb', '.html', '.css', '.scss', '.sass', '.less'],
+  flowEntrypointPatterns: UNIVERSAL_ENTRYPOINTS,
+  flowExcludePatterns: ['repository', 'repo', 'utils', 'helper', 'model', 'entity', 'dto', 'type', 'interface', 'constant', 'config', 'spec', 'test', 'tests', '__init__', '__pycache__', 'migrations']
 };

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();