ai-first-cli 1.1.5 → 1.2.0

package/src/core/incrementalAnalyzer.ts

@@ -86,7 +86,7 @@ function detectChangesWithGit(rootDir: string): ChangedFile[] {
 
 function detectChangesWithTimestamps(rootDir: string): ChangedFile[] {
   const changes: ChangedFile[] = [];
-  const aiDir = path.join(rootDir, "ai");
+  const aiDir = path.join(rootDir, "ai-context");
   const state = loadIndexState(aiDir);
   
   if (!state) return [];
@@ -114,18 +114,56 @@ function detectChangesWithTimestamps(rootDir: string): ChangedFile[] {
 
 export function updateSymbols(rootDir: string, changedFiles: ChangedFile[], aiDir: string): number {
   const symbolsPath = path.join(aiDir, "symbols.json");
-  let existingSymbols: Array<{name: string; file: string; type?: string}> = [];
+  
+  // Read existing symbols.json structure
+  interface SymbolsIndex {
+    [id: string]: { name: string; type: string; file: string; line?: number; module?: string; export?: boolean };
+  }
+  interface SymbolsData {
+    symbols: SymbolsIndex;
+    total: number;
+    byType: { [type: string]: Array<{ id: string; name: string; type: string; file: string; line?: number; export?: boolean }> };
+    byFile: { [file: string]: Array<{ id: string; name: string; type: string; file: string; line?: number; export?: boolean }> };
+    exported: Array<{ id: string; name: string; type: string; file: string; line?: number; export?: boolean }>;
+  }
+  
+  let symbolsData: SymbolsData | null = null;
   
   if (fs.existsSync(symbolsPath)) {
     try {
       const raw = readJsonFile(symbolsPath);
-      if (Array.isArray(raw)) existingSymbols = raw as typeof existingSymbols;
-    } catch { existingSymbols = []; }
+      if (!Array.isArray(raw) && raw && typeof raw === 'object') {
+        symbolsData = raw as unknown as SymbolsData;
+      }
+    } catch { }
+  }
+  
+  // If no valid symbols.json exists, nothing to update
+  if (!symbolsData) {
+    return 0;
   }
   
   const changedPaths = new Set(changedFiles.map(f => f.path));
-  existingSymbols = existingSymbols.filter(s => !changedPaths.has(s.file));
   
+  // Remove symbols from changed files
+  for (const filePath of changedPaths) {
+    delete symbolsData.byFile[filePath];
+    for (const type of Object.keys(symbolsData.byType)) {
+      symbolsData.byType[type] = symbolsData.byType[type].filter(
+        sym => sym.file !== filePath
+      );
+    }
+    symbolsData.exported = symbolsData.exported.filter(sym => sym.file !== filePath);
+    // Remove from symbols index
+    const keysToDelete = Object.keys(symbolsData.symbols).filter(
+      id => id.startsWith(filePath + '#')
+    );
+    for (const key of keysToDelete) {
+      delete symbolsData.symbols[key];
+    }
+  }
+  
+  // Extract and add new symbols from changed files
   for (const changed of changedFiles) {
     if (changed.status === "deleted") continue;
     const fullPath = path.join(rootDir, changed.path);
@@ -133,20 +171,72 @@ export function updateSymbols(rootDir: string, changedFiles: ChangedFile[], aiDi
     
     try {
       const fileInfo: FileInfo = {
-        path: changed.path,
+        path: fullPath,
         relativePath: changed.path,
         extension: path.extname(changed.path),
         name: path.basename(changed.path, path.extname(changed.path))
       };
       const symbols = extractSymbols([fileInfo]);
+      
       for (const symbol of symbols.symbols || []) {
-        existingSymbols.push({ name: symbol.name, file: changed.path, type: symbol.type });
+        const id = `${changed.path}#${symbol.name}`;
+        
+        // Add to symbols index
+        symbolsData.symbols[id] = {
+          name: symbol.name,
+          type: symbol.type,
+          file: changed.path,
+          line: symbol.line,
+          module: changed.path.split('/')[0],
+          export: symbol.export
+        };
+        
+        // Add to byFile
+        if (!symbolsData.byFile[changed.path]) {
+          symbolsData.byFile[changed.path] = [];
+        }
+        symbolsData.byFile[changed.path].push({
+          id,
+          name: symbol.name,
+          type: symbol.type,
+          file: changed.path,
+          line: symbol.line,
+          export: symbol.export
+        });
+        
+        // Add to byType
+        if (!symbolsData.byType[symbol.type]) {
+          symbolsData.byType[symbol.type] = [];
+        }
+        symbolsData.byType[symbol.type].push({
+          id,
+          name: symbol.name,
+          type: symbol.type,
+          file: changed.path,
+          line: symbol.line,
+          export: symbol.export
+        });
+        
+        // Add to exported if applicable
+        if (symbol.export) {
+          symbolsData.exported.push({
+            id,
+            name: symbol.name,
+            type: symbol.type,
+            file: changed.path,
+            line: symbol.line,
+            export: symbol.export
+          });
+        }
       }
     } catch { /* skip */ }
   }
   
-  writeFile(symbolsPath, JSON.stringify(existingSymbols, null, 2));
-  return existingSymbols.length;
+  // Update total
+  symbolsData.total = Object.keys(symbolsData.symbols).length;
+  
+  writeFile(symbolsPath, JSON.stringify(symbolsData, null, 2));
+  return symbolsData.total;
 }
 
 // ============================================================
@@ -282,7 +372,7 @@ export function updateKnowledgeGraph(rootDir: string, aiDir: string): boolean {
 // ============================================================
 
 export function runIncrementalUpdate(rootDir: string, aiDir?: string): IncrementalUpdateResult {
-  const targetAiDir = aiDir || path.join(rootDir, "ai");
+  const targetAiDir = aiDir || path.join(rootDir, "ai-context");
   const errors: string[] = [];
   
   if (!fs.existsSync(targetAiDir)) {
@@ -346,7 +436,7 @@ export function runIncrementalUpdate(rootDir: string, aiDir?: string): Increment
 }
 
 function updateIndexState(rootDir: string, changedFiles: ChangedFile[]): void {
-  const aiDir = path.join(rootDir, "ai");
+  const aiDir = path.join(rootDir, "ai-context");
   let state = loadIndexState(aiDir);
   
   if (!state) {

package/src/core/knowledgeGraphBuilder.ts

@@ -147,7 +147,7 @@ export function createEdges(aiDir: string): KnowledgeEdge[] {
 }
 
 export function buildKnowledgeGraph(rootDir: string, aiDir?: string): KnowledgeGraph {
-  const targetAiDir = aiDir || path.join(rootDir, "ai");
+  const targetAiDir = aiDir || path.join(rootDir, "ai-context");
   const graphDir = path.join(targetAiDir, "graph");
   ensureDir(graphDir);
   const nodes = createNodes(targetAiDir);

package/src/core/semanticContexts.ts

@@ -99,6 +99,15 @@ const SOURCE_EXTENSIONS = new Set([
 // HELPER FUNCTIONS
 // ============================================================
 
+function sanitizeFlowName(name: string): string {
+  return name
+    .replace(/\.\.+/g, ".")
+    .replace(/_+$/g, "")
+    .replace(/[^\w\-]/g, "_")
+    .replace(/_+/g, "_")
+    .replace(/^_+|_+$/g, "") || "unnamed";
+}
+
 function isSourceFile(filePath: string): boolean {
   const ext = path.extname(filePath).toLowerCase();
   return SOURCE_EXTENSIONS.has(ext);
@@ -370,7 +379,7 @@ function flowsFromGraph(graphData: any): Flow[] {
     // Must have at least 3 files and 2 layers
     if (fileSet.size >= 3 && layerSet.size >= 2) {
       flows.push({
-        name: path.basename(ep.file || ""),
+        name: sanitizeFlowName(path.basename(ep.file || "").replace(/\.[^.]+$/, "")),
         entrypoint: ep.file || "",
         files: Array.from(fileSet).slice(0, MAX_FLOW_FILES),
         depth: Math.min(MAX_FLOW_DEPTH, [...visited].length),
@@ -421,7 +430,7 @@ function flowsFromFolders(files: string[]): Flow[] {
     const entrypoint = sorted.find(isFlowEntrypoint) || sorted[0];
     
     flows.push({
-      name: feature,
+      name: sanitizeFlowName(feature),
       entrypoint,
       files: sorted.slice(0, MAX_FLOW_FILES),
       depth: layers.size,
@@ -486,7 +495,7 @@ function flowsFromImports(
     
     if (fileSet.size >= 3 && layerSet.size >= 2) {
       flows.push({
-        name: path.basename(ep, path.extname(ep)),
+        name: sanitizeFlowName(path.basename(ep, path.extname(ep))),
         entrypoint: ep,
         files: Array.from(fileSet),
         depth: Math.min(MAX_FLOW_DEPTH, [...visited].length),
@@ -592,7 +601,8 @@ export function generateSemanticContexts(aiDir: string): SemanticContexts {
   // Write flows
   ensureDir(flowsDir);
   for (const flow of flows) {
-    const filePath = path.join(flowsDir, `${flow.name}.json`);
+    const safeName = sanitizeFlowName(flow.name);
+    const filePath = path.join(flowsDir, `${safeName}.json`);
     writeFile(filePath, JSON.stringify(flow, null, 2));
   }
   

package/test-projects/django-app/.ai-dev/ai_context.md

@@ -0,0 +1,92 @@
+# AI Context
+
+> This file provides a comprehensive overview of the repository for AI coding assistants.
+
+---
+
+## Quick Overview
+
+- **Pattern**: Flat / Simple Structure
+- **Languages**: Markdown, JSON, Python
+- **Frameworks**: None
+- **Total Files**: 41
+
+---
+
+## Table of Contents
+
+1. [Tech Stack](#tech-stack)
+2. [Architecture](#architecture)
+3. [Key Entrypoints](#key-entrypoints)
+4. [Code Conventions](#code-conventions)
+5. [AI Rules](#ai-rules)
+6. [Repository Map](#repository-map)
+
+---
+
+## Tech Stack
+
+**Languages**: Markdown, JSON, Python
+
+---
+
+## Architecture
+
+## Architectural Pattern
+**Primary**: Flat / Simple Structure
+
+## Key Modules
+| Module | Responsibility |
+|--------|----------------|
+| `README.md` | Contains 0 files |
+| `ai` | Contains 23 files |
+| `blog` | Contains 6 files |
+| `django_app` | Contains 4 files |
+| `manage.py` | Contains 0 files |
+| `users` | Contains 6 files |
+
+
+---
+
+## Key Entrypoints
+
+---
+
+## Code Conventions
+
+## Naming Conventions
+- **Files**: PascalCase
+
+## Project Structure
+
+## Code Style
+- **Semicolons**: Required
+
+
+---
+
+## AI Rules
+
+- Language: Use Markdown, JSON, Python
+- Architecture: Follow Flat / Simple Structure pattern
+- File naming: PascalCase
+
+---
+
+## Repository Map
+
+See repo_map.md for the full structure.
+
+---
+
+## Notes for AI Assistants
+
+1. Follow the established naming conventions (see conventions.md)
+2. Use the detected frameworks and libraries
+3. Target the correct entrypoints for modifications
+4. Maintain the detected architecture patterns
+5. Follow AI rules in ai_rules.md
+
+---
+
+*Generated by ai-first*

package/test-projects/django-app/.ai-dev/ai_rules.md

@@ -0,0 +1,47 @@
+# AI Rules
+
+> Guidelines for AI assistants working on this project
+
+---
+
+## Guidelines
+
+- Language: Use Markdown, JSON, Python
+- Architecture: Follow Flat / Simple Structure pattern
+- File naming: PascalCase
+
+## Patterns
+
+- Layer structure: 
+
+## Constraints
+
+- Always use semicolons
+
+---
+
+## Quick Reference
+
+| Category | Value |
+|----------|-------|
+| Language | Markdown, JSON, Python |
+| Framework | N/A |
+| Architecture | Flat / Simple Structure |
+| Naming | PascalCase |
+| Indentation | unknown |
+
+---
+
+## Best Practices
+
+1. Follow the established naming conventions
+2. Keep functions small and focused
+3. Write tests for new features
+4. Use descriptive variable names
+5. Keep the architecture consistent
+6. Document complex logic
+7. Review code before committing
+
+---
+
+*Generated by ai-first*

package/test-projects/django-app/.ai-dev/architecture.md

@@ -0,0 +1,57 @@
+# Architecture
+
+## Architectural Pattern
+**Primary**: Flat / Simple Structure
+
+## Key Modules
+| Module | Responsibility |
+|--------|----------------|
+| `README.md` | Contains 0 files |
+| `ai` | Contains 23 files |
+| `blog` | Contains 6 files |
+| `django_app` | Contains 4 files |
+| `manage.py` | Contains 0 files |
+| `users` | Contains 6 files |
+
+
+## Module Details
+
+### README.md
+- **Path**: `README.md`
+- **Responsibility**: Contains 0 files
+
+
+### ai
+- **Path**: `ai`
+- **Responsibility**: Contains 23 files
+
+
+### blog
+- **Path**: `blog`
+- **Responsibility**: Contains 6 files
+
+
+### django_app
+- **Path**: `django_app`
+- **Responsibility**: Contains 4 files
+
+
+### manage.py
+- **Path**: `manage.py`
+- **Responsibility**: Contains 0 files
+
+
+### users
+- **Path**: `users`
+- **Responsibility**: Contains 6 files
+
+
+
+## Recommendations
+
+- Keep the architecture consistent as the project grows
+- Follow the established layer structure
+- Use dependency injection to manage module relationships
+
+---
+*Generated by ai-first*

package/test-projects/django-app/.ai-dev/cache.json

@@ -0,0 +1,169 @@
+{
+  "files": {
+    "README.md": {
+      "hash": "2b099275e8f719d2a008071b600752a7",
+      "mtime": 1773847503082.22
+    },
+    "ai/ai_context.md": {
+      "hash": "80d8f629165bedf465c5a4c6f835331f",
+      "mtime": 1773861708617.3313
+    },
+    "ai/ai_rules.md": {
+      "hash": "d2b7ddc70e63ad287b892635b384f5ae",
+      "mtime": 1773861708617.3313
+    },
+    "ai/architecture.md": {
+      "hash": "83ecb99ada1f854a47092136f1e3375a",
+      "mtime": 1773861708608.3313
+    },
+    "ai/cache.json": {
+      "hash": "29106f930a901a1723c2c25d22e43f31",
+      "mtime": 1773847532764.63
+    },
+    "ai/context/flows/views.json": {
+      "hash": "a914f6473aa639c9261d9491913a5440",
+      "mtime": 1773861708619.3315
+    },
+    "ai/conventions.md": {
+      "hash": "d11ac646a8916e3c6cc376f610368317",
+      "mtime": 1773861708611.3313
+    },
+    "ai/dependencies.json": {
+      "hash": "ef1c6db344eea60efd35525d7edfbdc5",
+      "mtime": 1773861708615.3313
+    },
+    "ai/entrypoints.md": {
+      "hash": "34c8965a66697d9f1d428bb0904f5d8d",
+      "mtime": 1773861708610.3313
+    },
+    "ai/files.json": {
+      "hash": "41fa4833d5f289c1eeb59d8cf9a39e47",
+      "mtime": 1773861708707.3328
+    },
+    "ai/graph/module-graph.json": {
+      "hash": "b226564aa5093d79889b9d70969a7018",
+      "mtime": 1773861708697.3328
+    },
+    "ai/graph/symbol-graph.json": {
+      "hash": "b1bd34e7d1007ce43b7fe133c1c2ba93",
+      "mtime": 1773861708707.3328
+    },
+    "ai/graph/symbol-references.json": {
+      "hash": "99914b932bd37a50b983c5e7c90ae93b",
+      "mtime": 1773861708707.3328
+    },
+    "ai/index-state.json": {
+      "hash": "bfc0668aa599dec27819bd72c7bfe674",
+      "mtime": 1773854929728.3672
+    },
+    "ai/modules.json": {
+      "hash": "cba831f3ad2e9f04973d35fad2f07b55",
+      "mtime": 1773861708687.3325
+    },
+    "ai/project.json": {
+      "hash": "4998af676768b4699bde7b0f13a209bb",
+      "mtime": 1773861708619.3315
+    },
+    "ai/repo-map.json": {
+      "hash": "aebfe0546551a708a7d16f89c5da2c7b",
+      "mtime": 1773861708688.3325
+    },
+    "ai/repo_map.json": {
+      "hash": "71959a6f4c6326dc065661e0ee89bd43",
+      "mtime": 1773861708607.3313
+    },
+    "ai/repo_map.md": {
+      "hash": "3a12588f63d086c3f93d5a1c559e6b1b",
+      "mtime": 1773861708606.3313
+    },
+    "ai/schema.json": {
+      "hash": "64d7066e2b581ecad488b78bf5f2a248",
+      "mtime": 1773861708619.3315
+    },
+    "ai/summary.md": {
+      "hash": "456491ddfdf18af4e2258c280a63fc8d",
+      "mtime": 1773861708607.3313
+    },
+    "ai/symbols.json": {
+      "hash": "a5f3112d44cfa4dc256b75bda253df0e",
+      "mtime": 1773861708613.3313
+    },
+    "ai/tech_stack.md": {
+      "hash": "876902a6b64c33c4d65f658e9fd2bb27",
+      "mtime": 1773861708610.3313
+    },
+    "ai/tools.json": {
+      "hash": "b1356e52c74e9b3b6a0d397b790a4968",
+      "mtime": 1773861708619.3315
+    },
+    "blog/__init__.py": {
+      "hash": "d41d8cd98f00b204e9800998ecf8427e",
+      "mtime": 1773847262320.9067
+    },
+    "blog/admin.py": {
+      "hash": "ef8b15c55e00e9ef835b4cc1a3ae8307",
+      "mtime": 1773847452965.5286
+    },
+    "blog/models.py": {
+      "hash": "11cf32800211bc954798a3775a0c1429",
+      "mtime": 1773847281082.164
+    },
+    "blog/serializers.py": {
+      "hash": "efb817010fdd412250c980c9d7b738a2",
+      "mtime": 1773847304708.4883
+    },
+    "blog/urls.py": {
+      "hash": "235d6b0d52e581825c76a37dba5d46f4",
+      "mtime": 1773847343339.019
+    },
+    "blog/views.py": {
+      "hash": "b51bcfc62e8a9cc4e36d6e04d0d66ac2",
+      "mtime": 1773847331379.8545
+    },
+    "django_app/__init__.py": {
+      "hash": "d41d8cd98f00b204e9800998ecf8427e",
+      "mtime": 1773847262320.9067
+    },
+    "django_app/settings.py": {
+      "hash": "ec0ff12dd114d0f70b04dee4e6753ded",
+      "mtime": 1773847230399.4692
+    },
+    "django_app/urls.py": {
+      "hash": "646e11e6cbfc20b5a1c457bd04058b6f",
+      "mtime": 1773847241419.62
+    },
+    "django_app/wsgi.py": {
+      "hash": "8997e7b6236b6d5cc5ab76625293b138",
+      "mtime": 1773847252217.768
+    },
+    "manage.py": {
+      "hash": "557480f24dd7cddb10ad7fdcf39b6c79",
+      "mtime": 1773847204930.1206
+    },
+    "users/__init__.py": {
+      "hash": "d41d8cd98f00b204e9800998ecf8427e",
+      "mtime": 1773847262320.9067
+    },
+    "users/admin.py": {
+      "hash": "3a42200ccb8543463198e6df6bbf3601",
+      "mtime": 1773847468180.7383
+    },
+    "users/models.py": {
+      "hash": "861e708ed26ccbcb76365faf6d540ac6",
+      "mtime": 1773847363660.2983
+    },
+    "users/serializers.py": {
+      "hash": "709f852da00f6f58d0b9cdb84bb7fe24",
+      "mtime": 1773847389572.655
+    },
+    "users/urls.py": {
+      "hash": "c331ed123fa4e1121d48eead9befbb0d",
+      "mtime": 1773847438434.3281
+    },
+    "users/views.py": {
+      "hash": "91fa1403cd82ec70898d487250d9673b",
+      "mtime": 1773847426896.1692
+    }
+  },
+  "lastIndexed": "2026-03-18T19:21:48.709Z"
+}

package/test-projects/django-app/.ai-dev/context/flows/views.json

@@ -0,0 +1,10 @@
+{
+  "name": "views",
+  "entrypoint": "blog/views.py",
+  "files": [
+    "blog/views.py",
+    "users/views.py"
+  ],
+  "depth": 0,
+  "layers": []
+}