ai-first-cli 1.2.3 → 1.3.1

package/src/core/generation/flowGenerator.ts

@@ -0,0 +1,238 @@
+export interface EnrichedFlow {
+  name: string;
+  entrypoint: string;
+  type: string;
+  responsibility: string;
+  files: Array<{
+    path: string;
+    responsibility: string;
+    symbols: string[];
+  }>;
+  layers: string[];
+  dependencies: {
+    imports: string[];
+    calls: string[];
+    implementsInterfaces: string[];
+  };
+  complexity: "low" | "medium" | "high";
+  depth: number;
+}
+
+export class FlowGenerator {
+  generateFlows(
+    entryPoints: string[],
+    symbols: Array<{
+      id: string;
+      name: string;
+      type: string;
+      file: string;
+    }>,
+    dependencyGraph: {
+      edges: Array<{ from: string; to: string; type: string }>;
+    },
+    callGraph: {
+      edges: Array<{ caller: string; callee: string }>;
+    },
+    inheritanceGraph: {
+      edges: Array<{ child: string; parent: string; type: string }>;
+    }
+  ): EnrichedFlow[] {
+    const flows: EnrichedFlow[] = [];
+
+    for (const entryPoint of entryPoints) {
+      const flow = this.analyzeFlow(
+        entryPoint,
+        symbols,
+        dependencyGraph,
+        callGraph,
+        inheritanceGraph
+      );
+      flows.push(flow);
+    }
+
+    return flows;
+  }
+
+  private analyzeFlow(
+    entryPoint: string,
+    symbols: Array<{
+      id: string;
+      name: string;
+      type: string;
+      file: string;
+    }>,
+    dependencyGraph: {
+      edges: Array<{ from: string; to: string; type: string }>;
+    },
+    callGraph: {
+      edges: Array<{ caller: string; callee: string }>;
+    },
+    inheritanceGraph: {
+      edges: Array<{ child: string; parent: string; type: string }>;
+    }
+  ): EnrichedFlow {
+    const entrySymbol = symbols.find((s) => s.id === entryPoint);
+    const visited = new Set<string>();
+    const files = new Map<string, string[]>();
+    const layers = new Set<string>();
+
+    const traverse = (symbolId: string, depth: number = 0) => {
+      if (visited.has(symbolId) || depth > 10) return;
+      visited.add(symbolId);
+
+      const symbol = symbols.find((s) => s.id === symbolId);
+      if (symbol) {
+        const fileSymbols = files.get(symbol.file) || [];
+        fileSymbols.push(symbol.name);
+        files.set(symbol.file, fileSymbols);
+
+        const layer = this.detectLayer(symbol);
+        if (layer) layers.add(layer);
+      }
+
+      const outgoingCalls = callGraph.edges.filter((e) => e.caller === symbolId);
+      for (const call of outgoingCalls) {
+        traverse(call.callee, depth + 1);
+      }
+
+      const outgoingDeps = dependencyGraph.edges.filter(
+        (e) => e.from === symbolId && e.type === "import"
+      );
+      for (const dep of outgoingDeps) {
+        if (symbols.some((s) => s.id === dep.to)) {
+          traverse(dep.to, depth + 1);
+        }
+      }
+    };
+
+    traverse(entryPoint);
+
+    const imports = dependencyGraph.edges
+      .filter((e) => e.from === entryPoint && e.type === "import")
+      .map((e) => e.to);
+
+    const calls = callGraph.edges
+      .filter((e) => e.caller === entryPoint)
+      .map((e) => e.callee);
+
+    const implementsInterfaces = inheritanceGraph.edges
+      .filter((e) => e.child === entryPoint && e.type === "implements")
+      .map((e) => e.parent);
+
+    return {
+      name: entrySymbol?.name || entryPoint.split("#")[1] || "unknown",
+      entrypoint: entryPoint,
+      type: this.classifyFlowType(entrySymbol),
+      responsibility: this.inferResponsibility(entrySymbol),
+      files: Array.from(files.entries()).map(([path, syms]) => ({
+        path,
+        responsibility: this.describeFile(path, syms),
+        symbols: syms,
+      })),
+      layers: Array.from(layers),
+      dependencies: {
+        imports: [...new Set(imports)],
+        calls: [...new Set(calls)],
+        implementsInterfaces: [...new Set(implementsInterfaces)],
+      },
+      complexity: this.calculateComplexity(visited.size, files.size),
+      depth: visited.size,
+    };
+  }
+
+  private detectLayer(symbol: {
+    name: string;
+    file: string;
+  }): string | null {
+    const name = symbol.name.toLowerCase();
+    const file = symbol.file.toLowerCase();
+
+    if (
+      name.includes("controller") ||
+      name.includes("route") ||
+      name.includes("handler") ||
+      file.includes("controller") ||
+      file.includes("routes")
+    ) {
+      return "api";
+    }
+    if (
+      name.includes("service") ||
+      name.includes("usecase") ||
+      file.includes("service") ||
+      file.includes("usecase")
+    ) {
+      return "service";
+    }
+    if (
+      name.includes("repository") ||
+      name.includes("model") ||
+      file.includes("repository") ||
+      file.includes("model")
+    ) {
+      return "data";
+    }
+    if (name.includes("component") || file.includes("component")) {
+      return "ui";
+    }
+    return null;
+  }
+
+  private classifyFlowType(symbol?: {
+    name: string;
+    type: string;
+  }): string {
+    if (!symbol) return "unknown";
+
+    const name = symbol.name.toLowerCase();
+
+    if (name.includes("auth")) return "Authentication Flow";
+    if (name.includes("user")) return "User Management Flow";
+    if (name.includes("payment")) return "Payment Processing Flow";
+    if (name.includes("order")) return "Order Processing Flow";
+    if (name.includes("notification")) return "Notification Flow";
+    if (name.includes("report")) return "Reporting Flow";
+    if (symbol.type === "function") return "API Endpoint";
+    if (symbol.type === "class") return "Service Handler";
+
+    return "Business Flow";
+  }
+
+  private inferResponsibility(symbol?: { name: string }): string {
+    if (!symbol) return "Unknown responsibility";
+
+    const name = symbol.name.toLowerCase();
+
+    if (name.includes("create")) return "Creation and initialization";
+    if (name.includes("get") || name.includes("find")) return "Data retrieval";
+    if (name.includes("update")) return "Data modification";
+    if (name.includes("delete") || name.includes("remove")) return "Data deletion";
+    if (name.includes("validate")) return "Data validation";
+    if (name.includes("process")) return "Business logic processing";
+    if (name.includes("handle")) return "Event/request handling";
+
+    return `Manages ${symbol.name} operations`;
+  }
+
+  private describeFile(path: string, symbols: string[]): string {
+    if (path.includes("controller")) return "API endpoint definitions";
+    if (path.includes("service")) return "Business logic implementation";
+    if (path.includes("repository")) return "Data access layer";
+    if (path.includes("model")) return "Data models and entities";
+    if (path.includes("route")) return "URL routing configuration";
+    if (path.includes("middleware")) return "Request/response middleware";
+    if (path.includes("component")) return "UI component";
+    return `Contains ${symbols.length} symbols`;
+  }
+
+  private calculateComplexity(
+    symbolCount: number,
+    fileCount: number
+  ): "low" | "medium" | "high" {
+    if (symbolCount < 5 && fileCount <= 2) return "low";
+    if (symbolCount > 15 || fileCount > 5) return "high";
+    return "medium";
+  }
+}
+
+export const flowGenerator = new FlowGenerator();

package/src/core/generation/index.ts

@@ -0,0 +1,16 @@
+export {
+  AIContextGenerator,
+  aiContextGenerator,
+  type EnrichedContext,
+} from "./aiContextGenerator.js";
+
+export {
+  FlowGenerator,
+  flowGenerator,
+  type EnrichedFlow,
+} from "./flowGenerator.js";
+
+export {
+  ArchitectureGenerator,
+  architectureGenerator,
+} from "./architectureGenerator.js";

package/src/core/hierarchyGenerator.ts

@@ -1,6 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { readFile, DEFAULT_EXCLUDE_PATTERNS, getAllFiles as scanFiles, getRelativePath } from "../utils/fileUtils.js";
+import { AI_CONTEXT_DIR, getHierarchyPath } from "../utils/constants.js";
 
 /**
  * Hierarchy result
@@ -299,11 +300,11 @@ function summarizeFile(filePath: string, content: string): string {
  */
 export async function generateHierarchy(
   rootDir: string,
-  outputPath: string = "ai/hierarchy.json"
+  outputPath: string = getHierarchyPath(rootDir)
 ): Promise<HierarchyResult> {
   try {
     // Get all files
-    const allFiles = scanFiles(rootDir, [...DEFAULT_EXCLUDE_PATTERNS, "ai", "node_modules"]);
+    const allFiles = scanFiles(rootDir, [...DEFAULT_EXCLUDE_PATTERNS, AI_CONTEXT_DIR, "ai", "node_modules"]);
 
     // Get files for analysis
     const files: { path: string; relativePath: string }[] = [];

package/src/core/parsers/index.ts

@@ -0,0 +1,99 @@
+import { typescriptParser, ParsedFile as ParsedTSFile } from "./typescriptParser.js";
+import { pythonParser, ParsedPythonFile } from "./pythonParser.js";
+import type { Symbol as CodeSymbol } from "../../analyzers/symbols.js";
+
+export type ParsedResult = ParsedTSFile | ParsedPythonFile;
+
+export interface BaseParser {
+  parseFile(filePath: string, sourceText: string): ParsedResult;
+}
+
+export class ParserRegistry {
+  private parsers: Map<string, BaseParser> = new Map();
+
+  constructor() {
+    this.registerParsers();
+  }
+
+  private registerParsers(): void {
+    this.parsers.set(".ts", typescriptParser);
+    this.parsers.set(".tsx", typescriptParser);
+    this.parsers.set(".js", typescriptParser);
+    this.parsers.set(".jsx", typescriptParser);
+    this.parsers.set(".mjs", typescriptParser);
+    this.parsers.set(".cjs", typescriptParser);
+
+    this.parsers.set(".py", pythonParser);
+    this.parsers.set(".pyw", pythonParser);
+  }
+
+  getParser(extension: string): BaseParser | undefined {
+    return this.parsers.get(extension.toLowerCase());
+  }
+
+  hasParser(extension: string): boolean {
+    return this.parsers.has(extension.toLowerCase());
+  }
+
+  getSupportedExtensions(): string[] {
+    return Array.from(this.parsers.keys());
+  }
+
+  parse(filePath: string, sourceText: string, extension?: string): ParsedResult | null {
+    const ext = extension || this.getExtension(filePath);
+    const parser = this.getParser(ext);
+
+    if (!parser) {
+      return null;
+    }
+
+    try {
+      return parser.parseFile(filePath, sourceText);
+    } catch {
+      return null;
+    }
+  }
+
+  private getExtension(filePath: string): string {
+    const lastDot = filePath.lastIndexOf(".");
+    if (lastDot === -1) return "";
+    return filePath.slice(lastDot);
+  }
+}
+
+export const parserRegistry = new ParserRegistry();
+
+export function createSymbolFromParsed(
+  parsed: ParsedResult,
+  filePath: string
+): CodeSymbol[] {
+  const symbols: CodeSymbol[] = [];
+
+  if ("symbols" in parsed) {
+    for (const sym of parsed.symbols) {
+      symbols.push({
+        id: `${filePath}#${sym.name}`,
+        name: sym.name,
+        type: sym.type as CodeSymbol['type'],
+        file: filePath,
+        line: sym.line,
+        export: sym.isExported ?? false,
+      });
+
+      if ('members' in sym && sym.members) {
+        for (const member of sym.members) {
+          symbols.push({
+            id: `${filePath}#${sym.name}.${member.name}`,
+            name: `${sym.name}.${member.name}`,
+            type: member.type as CodeSymbol['type'],
+            file: filePath,
+            line: member.line,
+            export: false,
+          });
+        }
+      }
+    }
+  }
+
+  return symbols;
+}

package/src/core/parsers/pythonParser.ts

@@ -0,0 +1,302 @@
+export interface PythonSymbol {
+  name: string;
+  type: "class" | "function" | "method" | "variable" | "import";
+  line: number;
+  decorators?: string[];
+  parameters?: {
+    name: string;
+    type?: string;
+    default?: string;
+  }[];
+  inheritance?: string[];
+  docstring?: string;
+  isAsync?: boolean;
+  isExported?: boolean;
+}
+
+export interface ParsedPythonFile {
+  filePath: string;
+  symbols: PythonSymbol[];
+  imports: {
+    module: string;
+    names?: string[];
+    alias?: string;
+    isFromImport: boolean;
+  }[];
+}
+
+export class PythonParser {
+  parseFile(filePath: string, sourceText: string): ParsedPythonFile {
+    const lines = sourceText.split("\n");
+    const symbols: PythonSymbol[] = [];
+    const imports: ParsedPythonFile["imports"] = [];
+
+    let currentClass: PythonSymbol | null = null;
+    let i = 0;
+
+    while (i < lines.length) {
+      const line = lines[i];
+      const trimmedLine = line.trim();
+      const lineNumber = i + 1;
+
+      // Skip empty lines and comments
+      if (!trimmedLine || trimmedLine.startsWith("#")) {
+        i++;
+        continue;
+      }
+
+      // Parse imports
+      if (trimmedLine.startsWith("import ") || trimmedLine.startsWith("from ")) {
+        const importInfo = this.parseImport(trimmedLine);
+        if (importInfo) {
+          imports.push(importInfo);
+        }
+        i++;
+        continue;
+      }
+
+      // Check for decorators
+      const decorators: string[] = [];
+      let j = i;
+      while (j < lines.length && lines[j].trim().startsWith("@")) {
+        decorators.push(lines[j].trim().substring(1).split("(")[0]);
+        j++;
+      }
+
+      if (decorators.length > 0) {
+        i = j;
+        const nextLine = lines[i]?.trim() || "";
+
+        // Class with decorators
+        if (nextLine.startsWith("class ")) {
+          const classSymbol = this.parseClass(nextLine, lineNumber, decorators, lines, i);
+          if (classSymbol) {
+            symbols.push(classSymbol);
+            currentClass = classSymbol;
+          }
+          i = this.findClassEnd(lines, i);
+          continue;
+        }
+
+        // Function with decorators
+        if (nextLine.startsWith("def ") || nextLine.startsWith("async def ")) {
+          const funcSymbol = this.parseFunction(nextLine, lineNumber, decorators);
+          if (funcSymbol) {
+            if (currentClass && this.isMethodOfClass(funcSymbol.name, lines, i, currentClass)) {
+              funcSymbol.type = "method";
+            }
+            symbols.push(funcSymbol);
+          }
+        }
+
+        i++;
+        continue;
+      }
+
+      // Parse class
+      if (trimmedLine.startsWith("class ")) {
+        const classSymbol = this.parseClass(trimmedLine, lineNumber, [], lines, i);
+        if (classSymbol) {
+          symbols.push(classSymbol);
+          currentClass = classSymbol;
+        }
+        i = this.findClassEnd(lines, i);
+        continue;
+      }
+
+      // Parse function
+      if (trimmedLine.startsWith("def ") || trimmedLine.startsWith("async def ")) {
+        const funcSymbol = this.parseFunction(trimmedLine, lineNumber, []);
+        if (funcSymbol) {
+          if (currentClass && this.isMethodOfClass(funcSymbol.name, lines, i, currentClass)) {
+            funcSymbol.type = "method";
+          }
+          symbols.push(funcSymbol);
+        }
+        i++;
+        continue;
+      }
+
+      // Detect class end by indentation
+      if (currentClass && !line.startsWith(" ") && !line.startsWith("\t") && trimmedLine) {
+        currentClass = null;
+      }
+
+      i++;
+    }
+
+    return {
+      filePath,
+      symbols,
+      imports,
+    };
+  }
+
+  private parseImport(line: string): ParsedPythonFile["imports"][0] | null {
+    // from module import name1, name2
+    const fromMatch = line.match(/from\s+(\S+)\s+import\s+(.+)/);
+    if (fromMatch) {
+      const module = fromMatch[1];
+      const namesPart = fromMatch[2];
+      const names = namesPart.split(",").map(n => n.trim().split(" ")[0]);
+      return { module, names, isFromImport: true };
+    }
+
+    // import module or import module as alias
+    const importMatch = line.match(/import\s+(.+)/);
+    if (importMatch) {
+      const modules = importMatch[1].split(",").map(m => {
+        const parts = m.trim().split(/\s+as\s+/);
+        return { module: parts[0], alias: parts[1] };
+      });
+      return { module: modules[0].module, alias: modules[0].alias, isFromImport: false };
+    }
+
+    return null;
+  }
+
+  private parseClass(
+    line: string,
+    lineNumber: number,
+    decorators: string[],
+    lines: string[],
+    startIndex: number
+  ): PythonSymbol | null {
+    const match = line.match(/class\s+(\w+)(?:\(([^)]+)\))?/);
+    if (!match) return null;
+
+    const name = match[1];
+    const inheritance = match[2] ? match[2].split(",").map(s => s.trim()) : [];
+
+    // Extract docstring
+    const docstring = this.extractDocstring(lines, startIndex);
+
+    return {
+      name,
+      type: "class",
+      line: lineNumber,
+      decorators: decorators.length > 0 ? decorators : undefined,
+      inheritance: inheritance.length > 0 ? inheritance : undefined,
+      docstring,
+      isExported: true,
+    };
+  }
+
+  private parseFunction(
+    line: string,
+    lineNumber: number,
+    decorators: string[]
+  ): PythonSymbol | null {
+    const isAsync = line.startsWith("async ");
+    const defKeyword = isAsync ? "async def" : "def";
+    const match = line.match(new RegExp(`${defKeyword}\\s+(\\w+)\\s*\\(([^)]*)\\)`));
+
+    if (!match) return null;
+
+    const name = match[1];
+    const paramsStr = match[2];
+    const parameters = this.parseParameters(paramsStr);
+
+    return {
+      name,
+      type: "function",
+      line: lineNumber,
+      decorators: decorators.length > 0 ? decorators : undefined,
+      parameters: parameters.length > 0 ? parameters : [],
+      isAsync,
+      isExported: true,
+    };
+  }
+
+  private parseParameters(paramsStr: string): { name: string; type?: string; default?: string }[] {
+    if (!paramsStr.trim()) return [];
+
+    return paramsStr.split(",").map(param => {
+      const trimmed = param.trim();
+      if (!trimmed || trimmed === "self" || trimmed === "cls") return null;
+
+      // Handle type hints and defaults
+      const parts = trimmed.split("=");
+      const nameAndType = parts[0].trim();
+      const defaultValue = parts[1]?.trim();
+
+      const typeMatch = nameAndType.match(/(.+):\s*(.+)/);
+      if (typeMatch) {
+        return {
+          name: typeMatch[1].trim(),
+          type: typeMatch[2].trim(),
+          default: defaultValue,
+        };
+      }
+
+      return {
+        name: nameAndType,
+        default: defaultValue,
+      };
+    }).filter((p): p is NonNullable<typeof p> => p !== null);
+  }
+
+  private extractDocstring(lines: string[], startIndex: number): string | undefined {
+    // Look for docstring in next few lines
+    for (let i = startIndex + 1; i < Math.min(startIndex + 5, lines.length); i++) {
+      const line = lines[i].trim();
+      if (line.startsWith('"""') || line.startsWith("'''")) {
+        const quote = line.startsWith('"""') ? '"""' : "'''";
+        if (line.endsWith(quote) && line.length > 6) {
+          return line.slice(3, -3);
+        }
+        // Multi-line docstring
+        let docstring = line.slice(3);
+        for (let j = i + 1; j < lines.length; j++) {
+          const nextLine = lines[j];
+          if (nextLine.includes(quote)) {
+            docstring += "\n" + nextLine.slice(0, nextLine.indexOf(quote));
+            return docstring.trim();
+          }
+          docstring += "\n" + nextLine;
+        }
+      }
+    }
+    return undefined;
+  }
+
+  private findClassEnd(lines: string[], startIndex: number): number {
+    const baseIndent = lines[startIndex].match(/^(\s*)/)?.[1].length || 0;
+    let i = startIndex + 1;
+
+    while (i < lines.length) {
+      const line = lines[i];
+      const trimmed = line.trim();
+
+      if (!trimmed || trimmed.startsWith("#")) {
+        i++;
+        continue;
+      }
+
+      const indent = line.match(/^(\s*)/)?.[1].length || 0;
+
+      // Check if we've exited the class (less or equal indentation)
+      if (indent <= baseIndent && trimmed) {
+        // Check if it's a new class or function at same level
+        if (trimmed.startsWith("class ") || trimmed.startsWith("def ") || trimmed.startsWith("async def ") || trimmed.startsWith("@")) {
+          return i;
+        }
+      }
+
+      i++;
+    }
+
+    return i;
+  }
+
+  private isMethodOfClass(funcName: string, lines: string[], funcIndex: number, classSymbol: PythonSymbol): boolean {
+    // Check if function is indented within the class
+    const classLineIndex = classSymbol.line - 1;
+    const classIndent = lines[classLineIndex].match(/^(\s*)/)?.[1].length || 0;
+    const funcIndent = lines[funcIndex].match(/^(\s*)/)?.[1].length || 0;
+
+    return funcIndent > classIndent;
+  }
+}
+
+export const pythonParser = new PythonParser();