ai-first-cli 1.1.1 → 1.1.3

package/docs/guide/incremental-analysis.md

@@ -0,0 +1,131 @@
+# Incremental Analysis
+
+AI-First supports incremental updates that refresh only changed files without requiring a full repository analysis. This enables self-healing context for AI agents.
+
+## Why Incremental Updates?
+
+Running `ai-first init` analyzes the entire repository, which can be slow for large codebases. Incremental updates:
+
+- **Fast**: Only analyzes changed files
+- **Efficient**: Updates only affected metadata
+- **Continuous**: Keeps context fresh between analysis runs
+
+## How It Works
+
+1. **Detect Changes**: Uses `git diff` or filesystem timestamps
+2. **Re-analyze**: Extracts symbols/dependencies from changed files
+3. **Update Metadata**: Updates symbols, dependencies, features, flows
+4. **Rebuild Graph**: Updates knowledge graph with changes
+
+## Usage
+
+### CLI Command
+
+```bash
+# Incremental update (uses git)
+ai-first update
+
+# Use filesystem timestamps instead of git
+ai-first update --no-git
+
+# Custom root directory
+ai-first update --root /path/to/project
+
+# JSON output
+ai-first update --json
+```
+
+### Programmatic Usage
+
+```typescript
+import { 
+  runIncrementalUpdate,
+  detectChangedFiles,
+  updateSymbols,
+  updateFeatures,
+  updateFlows
+} from 'ai-first';
+
+// Full incremental update
+const result = runIncrementalUpdate('/path/to/project');
+
+console.log(result.changedFiles);
+console.log(result.updatedSymbols);
+console.log(result.updatedFeatures);
+
+// Or use individual functions
+const changes = detectChangedFiles('/path/to/project');
+const updated = updateSymbols('/path/to/project', changes, aiDir);
+```
+
+## Output
+
+```
+🔄 Running incremental update in: /path/to/project
+
+📁 Changed files: 5
+   modified: src/auth/login.ts
+   modified: src/auth/userService.ts
+   added: src/payments/checkout.ts
+   deleted: src/old/legacy.ts
+
+🔧 Updated:
+   Symbols: 12
+   Dependencies: 2
+   Features: auth
+   Flows: login
+   Knowledge Graph: ✅
+```
+
+## API Reference
+
+### runIncrementalUpdate(rootDir, aiDir?)
+
+Performs full incremental update. Returns:
+
+```typescript
+{
+  changedFiles: ChangedFile[];
+  updatedSymbols: number;
+  updatedDependencies: number;
+  updatedFeatures: string[];
+  updatedFlows: string[];
+  graphUpdated: boolean;
+  errors: string[];
+}
+```
+
+### detectChangedFiles(rootDir, useGit?)
+
+Detects changed files using git (default) or filesystem timestamps.
+
+### updateSymbols(rootDir, changes, aiDir)
+
+Re-extracts symbols from changed files and updates `ai/symbols.json`.
+
+### updateDependencies(rootDir, changes, aiDir)
+
+Re-extracts dependencies from changed package files.
+
+### updateFeatures(rootDir, changes, aiDir)
+
+Updates features that contain changed files.
+
+### updateFlows(rootDir, changes, aiDir)
+
+Updates flows that contain changed files.
+
+### updateKnowledgeGraph(rootDir, aiDir)
+
+Rebuilds the knowledge graph with current data.
+
+## Self-Healing Context
+
+Incremental updates enable self-healing context for AI agents:
+
+1. Agent makes changes to codebase
+2. Developer runs `ai-first update` 
+3. AI context is refreshed with new/changed files
+4. Agent's next query uses updated context
+
+This creates a feedback loop where the AI context stays fresh without manual full re-analysis.

package/docs/guide/knowledge-graph.md

@@ -0,0 +1,135 @@
+# Knowledge Graph
+
+The Knowledge Graph unifies all repository intelligence into a single navigable graph that AI agents can use to understand codebase structure and relationships.
+
+## Why a Knowledge Graph?
+
+Traditional code analysis produces separate outputs (symbols, dependencies, features, flows, git activity). The Knowledge Graph connects everything:
+
+- **Feature → Flow → File**: Understand what features exist and how they connect to code
+- **File → Symbol → File**: Navigate code relationships
+- **Commit → File**: See what was changed and by whom
+
+## Graph Structure
+
+### Nodes
+
+| Type | Description | Example |
+|------|-------------|---------|
+| `feature` | Business feature | `auth`, `payments` |
+| `flow` | Execution flow | `login`, `checkout` |
+| `file` | Source file | `src/auth/login.ts` |
+| `symbol` | Code symbol | `src/auth/login.ts#login` |
+| `commit` | Git commit | `commit:src/auth/login.ts` |
+
+### Edges
+
+| Type | From | To | Description |
+|------|------|-----|-------------|
+| `contains` | feature | flow | Feature contains this flow |
+| `implements` | flow | file | Flow implemented in file |
+| `declares` | file | symbol | File declares symbol |
+| `references` | symbol | file | Symbol references file |
+| `modifies` | commit | file | Commit modified file |
+
+## Usage
+
+### CLI Command
+
+```bash
+# Generate knowledge graph
+ai-first graph
+
+# Show statistics
+ai-first graph --stats
+
+# Output as JSON
+ai-first graph --json
+
+# Custom root directory
+ai-first graph --root /path/to/project
+```
+
+### Programmatic Usage
+
+```typescript
+import {
+  buildKnowledgeGraph,
+  loadKnowledgeGraph,
+  getNodesByType,
+  getEdgesByType,
+  getNeighbors
+} from 'ai-first';
+
+// Build graph
+const graph = buildKnowledgeGraph('/path/to/project');
+
+// Load existing graph
+const graph = loadKnowledgeGraph('/path/to/ai');
+
+// Query by type
+const features = getNodesByType(graph, 'feature');
+const flows = getNodesByType(graph, 'flow');
+
+// Query by edge type
+const modifications = getEdgesByType(graph, 'modifies');
+
+// Navigate neighbors
+const related = getNeighbors(graph, 'auth');
+```
+
+## Output
+
+Generates `ai/graph/knowledge-graph.json`:
+
+```json
+{
+  "nodes": [
+    { "id": "auth", "type": "feature", "label": "auth" },
+    { "id": "login", "type": "flow", "label": "login" },
+    { "id": "src/auth/login.ts", "type": "file", "label": "login.ts" }
+  ],
+  "edges": [
+    { "from": "auth", "to": "login", "type": "contains" },
+    { "from": "login", "to": "src/auth/login.ts", "type": "implements" }
+  ],
+  "metadata": {
+    "generated": "2026-03-11T12:00:00.000Z",
+    "sources": ["features", "flows", "git", "symbols"],
+    "nodeCount": 150,
+    "edgeCount": 450
+  }
+}
+```
+
+## Integration
+
+The Knowledge Graph works with other AI-First outputs:
+
+1. **Features** from `ai/context/features/`
+2. **Flows** from `ai/context/flows/`
+3. **Git activity** from `ai/git/`
+4. **Symbols** from `ai/symbols.json`
+5. **Dependencies** from `ai/dependencies.json`
+
+## API Reference
+
+### buildKnowledgeGraph(rootDir, aiDir?)
+
+Builds and saves the knowledge graph.
+
+### loadKnowledgeGraph(aiDir)
+
+Loads an existing knowledge graph.
+
+### getNodesByType(graph, type)
+
+Filter nodes by type (feature, flow, file, symbol, commit).
+
+### getEdgesByType(graph, type)
+
+Filter edges by type (contains, implements, declares, references, modifies).
+
+### getNeighbors(graph, nodeId)
+
+Find all nodes connected to a given node.

package/docs/guide/lazy-indexing.md

@@ -0,0 +1,144 @@
+# Lazy Context Generation
+
+Lazy context generation improves CLI startup time by generating repository context in stages, only analyzing what's needed when it's needed.
+
+## How It Works
+
+### Stage 1: Minimal Index (Fast Startup)
+
+When you run `ai-first init`, only essential metadata is generated:
+
+- **repo-map**: Directory structure
+- **languages**: Detected programming languages
+- **frameworks**: Detected frameworks
+- **entrypoints**: Application entry points
+
+This stage is optimized for **fast startup** - typically under 1 second for most repositories.
+
+### Stage 2: Full Context (On Demand)
+
+Additional context is generated only when requested:
+
+- **symbols**: Functions, classes, interfaces
+- **dependencies**: Import relationships
+- **features**: Business feature modules
+- **flows**: Execution chains
+- **knowledge graph**: Full repository graph
+
+Trigger conditions:
+- When a specific feature is accessed
+- When the plugin requests detailed context
+- When a CCP (Context Control Pack) is generated
+
+## Performance Benefits
+
+| Repository Size | Full Index | Lazy Index (Stage 1) |
+|----------------|------------|----------------------|
+| Small (50 files) | ~0.5s | ~0.1s |
+| Medium (200 files) | ~2s | ~0.3s |
+| Large (1000 files) | ~10s | ~1s |
+| Huge (5000 files) | ~30s | ~3s |
+
+**Time saved**: 70-90% for initial CLI startup
+
+## Usage
+
+### Default Behavior (Lazy)
+
+```bash
+ai-first init
+# Generates minimal index only (~1s)
+```
+
+### Full Index (When Needed)
+
+```bash
+# Expand full context on demand
+ai-first map
+# or
+ai-first context <symbol>
+```
+
+### Check Index State
+
+```javascript
+import { getLazyIndexState, hasMinimalIndex } from 'ai-first';
+
+const aiDir = './ai';
+console.log('Has minimal:', hasMinimalIndex(aiDir));
+
+const state = getLazyIndexState(aiDir);
+console.log('Stage 1:', state?.stage1Complete);
+console.log('Stage 2:', state?.stage2Complete);
+```
+
+## API
+
+### buildMinimalIndex(rootDir, aiDir)
+
+Build Stage 1 minimal index:
+
+```javascript
+import { buildMinimalIndex } from 'ai-first';
+
+const minimal = buildMinimalIndex('/path/to/project', '/path/to/project/ai');
+console.log(minimal.languages); // ['TypeScript', 'JavaScript']
+```
+
+### expandFeatureContext(rootDir, aiDir, featureName)
+
+Expand context for a specific feature:
+
+```javascript
+import { expandFeatureContext } from 'ai-first';
+
+const result = expandFeatureContext('/path', '/path/ai', 'auth');
+if (result.success) {
+  console.log('Feature expanded:', result.files);
+}
+```
+
+### expandFlowContext(rootDir, aiDir, flowName)
+
+Expand context for a specific flow:
+
+```javascript
+import { expandFlowContext } from 'ai-first';
+
+const result = expandFlowContext('/path', '/path/ai', 'login');
+```
+
+### expandFullContext(rootDir, aiDir)
+
+Expand all context (Stage 2):
+
+```javascript
+import { expandFullContext } from 'ai-first';
+
+const stats = expandFullContext('/path', '/path/ai');
+console.log(stats);
+// { symbols: 150, dependencies: 80, features: 5, flows: 3 }
+```
+
+## State Management
+
+Lazy index state is stored in `ai/lazy-index-state.json`:
+
+```json
+{
+  "stage1Complete": true,
+  "stage2Complete": false,
+  "featuresExpanded": ["auth", "users"],
+  "flowsExpanded": ["login"],
+  "lastUpdated": "2024-01-15T10:30:00.000Z"
+}
+```
+
+## Integration
+
+The lazy analyzer integrates with existing CLI commands:
+
+- `ai-first init` - Stage 1 only (fast)
+- `ai-first map` - Triggers Stage 2
+- `ai-first context` - Expands specific context on demand
+- `ai-first update` - Incremental updates maintain lazy state

package/docs/guide/performance.md

@@ -0,0 +1,125 @@
+# Performance Optimization
+
+AI-First is optimized to handle large repositories efficiently through incremental analysis and smart caching.
+
+## Incremental Indexing
+
+AI-First tracks file changes to avoid reprocessing the entire repository on each run.
+
+### How It Works
+
+1. **File Hash Tracking**: Each file's content is hashed (MD5)
+2. **State Storage**: Hashes stored in `ai/index-state.json`
+3. **Change Detection**: On each run, only modified files are re-indexed
+
+### State File Format
+
+```json
+{
+  "version": "1.0.0",
+  "lastIndexed": "2026-03-10T12:00:00.000Z",
+  "totalFiles": 150,
+  "files": {
+    "src/auth/AuthService.ts": {
+      "path": "src/auth/AuthService.ts",
+      "hash": "abc123...",
+      "mtime": 1699531200000,
+      "size": 1024,
+      "indexedAt": "2026-03-10T12:00:00.000Z"
+    }
+  }
+}
+```
+
+### CLI Output Example
+
+```
+🗄️  Generating index for: /project
+
+   Total files: 150
+   To index: 5
+   Unchanged: 145
+   New: 2
+   Deleted: 0
+```
+
+## Semantic Contexts
+
+Semantic contexts (features and flows) are regenerated based on the current module structure:
+
+- **Features**: Derived from `modules.json` - regenerated when module structure changes
+- **Flows**: Derived from `symbol-graph.json` - regenerated when symbol relationships change
+
+These are lightweight computations compared to full symbol extraction.
+
+## Performance Tips
+
+### 1. Use Incremental Mode
+
+The default behavior is incremental. Don't use `--force` unless necessary.
+
+```bash
+# Incremental (default)
+ai-first map
+
+# Force full rebuild
+ai-first map --force
+```
+
+### 2. Exclude Unnecessary Files
+
+Use `.aiignore` to exclude large or irrelevant directories:
+
+```
+# .aiignore
+node_modules/
+dist/
+build/
+coverage/
+*.log
+```
+
+### 3. Large Repositories
+
+For repositories with >2000 files, semantic indexing is automatically enabled:
+
+```bash
+ai-first map
+# Automatically uses semantic mode for large repos
+```
+
+### 4. Git Integration
+
+AI-First can use Git to detect changed files:
+
+```bash
+# Only analyze changed files
+git commit -am "update" && ai-first map
+```
+
+## Benchmarks
+
+| Repository Size | Files | Time (First) | Time (Incremental) |
+|----------------|-------|--------------|---------------------|
+| Small          | 50    | 0.3s        | 0.1s                |
+| Medium         | 200   | 1.2s        | 0.3s                |
+| Large          | 1000  | 5.5s        | 1.2s                |
+| Huge           | 5000  | 28s         | 5s                  |
+
+## Troubleshooting
+
+### Slow Performance
+
+1. **Check file count**: `ai-first doctor`
+2. **Exclude directories**: Add to `.aiignore`
+3. **Clear cache**: Delete `ai/index-state.json`
+
+### Memory Issues
+
+For very large repositories (>10k files):
+
+```bash
+ai-first map --semantic
+```
+
+This uses streaming analysis to reduce memory usage.

package/package.json

@@ -1,7 +1,6 @@
 {
   "name": "ai-first-cli",
-
-  "version": "1.1.1",
+  "version": "1.1.3",
   "description": "CLI tool that prepares any repository to be used effectively by AI coding agents",
   "main": "dist/index.js",
   "type": "module",
@@ -12,6 +11,8 @@
     "build": "tsc",
     "run": "node dist/commands/ai-first.js",
     "dev": "node --loader ts-node/esm src/commands/ai-first.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "docs:dev": "vitepress dev docs",
     "docs:build": "vitepress build docs",
     "docs:preview": "vitepress preview docs",
@@ -43,10 +44,12 @@
     "@vitejs/plugin-vue": "^6.0.4",
     "typescript": "^5.0.0",
     "vitepress": "^1.6.4",
+    "vitest": "^2.0.0",
     "vue": "^3.5.30"
   },
   "dependencies": {
     "chokidar": "^5.0.0",
+    "ora": "^9.3.0",
     "sql.js": "^1.10.0"
   },
   "optionalDependencies": {

package/src/analyzers/androidResources.ts

@@ -0,0 +1,113 @@
+import { FileInfo } from "../core/repoScanner.js";
+import path from "path";
+
+export interface AndroidResource {
+  type: "layout" | "drawable" | "values" | "menu" | "mipmap" | "anim" | "xml" | "other";
+  name: string;
+  path: string;
+}
+
+export interface AndroidResourcesAnalysis {
+  isAndroid: boolean;
+  resources: AndroidResource[];
+  layouts: string[];
+  drawables: string[];
+  values: string[];
+  totalResources: number;
+}
+
+/**
+ * Analyze Android resources in res/ directory
+ */
+export function analyzeAndroidResources(files: FileInfo[]): AndroidResourcesAnalysis {
+  const resFiles = files.filter(f => f.relativePath.startsWith("res/"));
+  
+  if (resFiles.length === 0) {
+    return {
+      isAndroid: false,
+      resources: [],
+      layouts: [],
+      drawables: [],
+      values: [],
+      totalResources: 0,
+    };
+  }
+  
+  const resources: AndroidResource[] = [];
+  const layouts: string[] = [];
+  const drawables: string[] = [];
+  const values: string[] = [];
+  
+  for (const file of resFiles) {
+    const relativePath = file.relativePath;
+    const parts = relativePath.split("/");
+    
+    // res/layout/*.xml -> layout
+    // res/drawable-*/*.{png,xml} -> drawable
+    // res/values/*.xml -> values
+    // res/menu/*.xml -> menu
+    // res/mipmap-*/*.png -> mipmap
+    // res/anim/*.xml -> anim
+    // res/xml/*.xml -> xml
+    
+    let type: AndroidResource["type"] = "other";
+    let resourceName = file.name;
+    
+    if (parts[1] === "layout") {
+      type = "layout";
+      layouts.push(resourceName);
+    } else if (parts[1]?.startsWith("drawable")) {
+      type = "drawable";
+      drawables.push(resourceName);
+    } else if (parts[1] === "values") {
+      type = "values";
+      values.push(resourceName);
+    } else if (parts[1] === "menu") {
+      type = "menu";
+    } else if (parts[1]?.startsWith("mipmap")) {
+      type = "mipmap";
+    } else if (parts[1] === "anim") {
+      type = "anim";
+    } else if (parts[1] === "xml") {
+      type = "xml";
+    }
+    
+    resources.push({
+      type,
+      name: resourceName,
+      path: relativePath,
+    });
+  }
+  
+  return {
+    isAndroid: true,
+    resources,
+    layouts,
+    drawables,
+    values,
+    totalResources: resources.length,
+  };
+}
+
+/**
+ * Generate android-resources.json content
+ */
+export function generateAndroidResourcesJson(analysis: AndroidResourcesAnalysis): string {
+  const output = {
+    isAndroid: analysis.isAndroid,
+    totalResources: analysis.totalResources,
+    layouts: analysis.layouts,
+    drawables: analysis.drawables,
+    values: analysis.values,
+    byType: {
+      layout: analysis.resources.filter(r => r.type === "layout").map(r => r.path),
+      drawable: analysis.resources.filter(r => r.type === "drawable").map(r => r.path),
+      values: analysis.resources.filter(r => r.type === "values").map(r => r.path),
+      menu: analysis.resources.filter(r => r.type === "menu").map(r => r.path),
+      mipmap: analysis.resources.filter(r => r.type === "mipmap").map(r => r.path),
+      anim: analysis.resources.filter(r => r.type === "anim").map(r => r.path),
+      xml: analysis.resources.filter(r => r.type === "xml").map(r => r.path),
+    },
+  };
+  return JSON.stringify(output, null, 2);
+}