ai-first-cli 1.1.0

package/.netlify/netlify.toml

@@ -0,0 +1,25 @@
+plugins = []
+headers = []
+redirects = []
+
+[functions]
+
+[functions."*"]
+
+[build]
+publish = "/mnt/m2/Código/opencode-ai-first"
+publishOrigin = "default"
+
+[build.environment]
+
+[build.processing]
+
+[build.processing.css]
+
+[build.processing.html]
+
+[build.processing.images]
+
+[build.processing.js]
+
+[build.services]

package/.netlify/state.json

@@ -0,0 +1,3 @@
+{
+	"siteId": "61bf2f52-7f91-4732-92d1-7e1942542f8a"
+}

package/CHANGELOG.md

@@ -0,0 +1,192 @@
+# Changelog & Roadmap
+
+All notable changes to `ai-first` will be documented in this file.
+
+---
+
+## [Unreleased]
+
+### Added
+- Enhanced symbol indexing with `filePath#symbolName` IDs
+- Extended symbol graph relationships: calls, called_by, imports, references, instantiates, extends, implements, exports
+- Reverse symbol references (`ai/graph/symbol-references.json`)
+- File index with symbol mappings (`ai/files.json`)
+- Code Context Packets (CCP) with depth, ranking, and multiple formats
+- Context CLI flags: `--depth`, `--max-symbols`, `--format`, `--save`
+- Incremental indexing with file hash cache (`ai/cache.json`)
+- Context ranking system based on graph distance and relationships
+- Documentation: Architecture guide and Commands reference updated
+
+---
+
+## [1.1.0] - 2026-03-09
+
+All notable changes to `ai-first` will be documented in this file.
+
+---
+
+## [Unreleased]
+
+### Added
+- `ai-first context <symbol>` - Generate context packet for specific symbol
+- `ai/graph/symbol-graph.json` - Symbol-level dependency graph with bidirectional relationships
+- `ai/context/<symbol>.json` - Code Context Packets (CCP) for AI agents
+- Unique symbol IDs (format: `module.symbolName`)
+- Symbol relationships: calls, called_by, imports, references
+
+---
+
+## [1.1.0] - 2026-03-09
+
+### Added
+- `ai-first doctor` - Health check command for repository readiness
+- `ai-first explore <module>` - Navigate module dependencies
+- `ai-first map` - Generate repository architecture map
+- `ai-first index --semantic` - Semantic indexing with embeddings
+- `index-state.json` - Track file changes for incremental indexing
+- `files.json` - List of all indexed files with metadata
+- `modules.json` - Detected modules and their structure
+- `module-graph.json` - Module dependency graph
+- `embeddings.json` - Semantic embeddings for code search
+- SQLite index with adaptive sizing for large repos
+
+### New Generated Files
+- `ai/files.json` - File inventory with hash, size, line count
+- `ai/modules.json` - Module detection and hierarchy
+- `ai/module-graph.json` - Import-based dependency graph
+- `ai/embeddings.json` - Vector embeddings for semantic search
+
+---
+
+## [1.0.0] - 2026-03-08
+
+### Added
+- feat: Add VitePress documentation site with SEO optimization (e0b3e35)
+- fix: Add permissions and GITHUB_TOKEN to changelog workflow (062d952)
+- chore: Update CHANGELOG with all new features (8c1f6d9)
+- fix: Update roadmap to match planned features from CHANGELOG (7eca761)
+- fix: Remove hash ID markers from README (d05db53)
+- feat: Add incremental indexing and semantic search pipeline (e294a2c)
+- feat: Add improved indexing with adaptive sizing, map command, incremental state (d0a172b)
+- feat: Add doctor, explore commands and semantic indexing (50011da)
+- fix: Correct YAML syntax in changelog workflow (5a1c819)
+- Improve documentation with Quick Start, Why AI-First, Architecture diagram, Languages (7cc8f44)
+
+# Changelog & Roadmap
+
+All notable changes to `ai-first` will be documented in this file.
+
+---
+
+## [Unreleased]
+
+### Added
+- `ai-first doctor` - Health check command for repository readiness
+- `ai-first explore <module>` - Navigate module dependencies
+- `ai-first map` - Generate repository architecture map
+- `ai-first index --semantic` - Semantic indexing with embeddings
+- `index-state.json` - Track file changes for incremental indexing
+- `files.json` - List of all indexed files with metadata
+- `modules.json` - Detected modules and their structure
+- `module-graph.json` - Module dependency graph
+- `embeddings.json` - Semantic embeddings for code search
+- SQLite index with adaptive sizing for large repos
+
+### New Generated Files
+- `ai/files.json` - File inventory with hash, size, line count
+- `ai/modules.json` - Module detection and hierarchy
+- `ai/module-graph.json` - Import-based dependency graph
+- `ai/embeddings.json` - Vector embeddings for semantic search
+
+---
+
+## [1.0.0] - 2026-03-08
+
+### Added
+- Initial release
+- Core analyzers:
+  - `repo_map.md` - Repository structure tree view
+  - `summary.md` - Files by extension and directory
+  - `architecture.md` - Pattern detection (MVC, Clean Architecture, etc.)
+  - `tech_stack.md` - Languages, frameworks, libraries
+  - `entrypoints.md` - CLI, API, server entry points
+  - `conventions.md` - Naming, testing, linting conventions
+  - `ai_context.md` - Unified AI context
+- `symbols.json` - Extracts functions, classes, interfaces from code
+- `dependencies.json` - Analyzes import/require dependencies between files
+- `ai_rules.md` - Generates guidelines for AI assistants
+- `repo_map.json` - Machine-readable repository structure
+- `index.db` - SQLite database for fast queries (`ai-first index`)
+
+### Features
+- Multi-language support (TypeScript, Python, Go, Rust, Java, C#, etc.)
+- Deterministic analysis (no AI/LLM required)
+- Works offline
+- CLI interface with `--root` and `--output` options
+---
+
+## 📋 Roadmap
+
+See [CHANGELOG.md](./CHANGELOG.md) for the complete roadmap:
+- **Unreleased** section shows what's being worked on
+- Version sections show completed features
+- Future planned features are listed under each phase
+
+---
+
+## How to Update
+
+After each feature release:
+1. Update this changelog with new changes
+2. Update version in `package.json` (semver)
+3. Commit and push
+
+```bash
+git add CHANGELOG.md package.json
+git commit -m "Release v1.x.x"
+git push
+```
+---
+
+## Roadmap
+
+### Phase 1 (Done ✅)
+- [x] Core CLI structure
+- [x] Basic analyzers (architecture, tech stack, entrypoints, conventions)
+- [x] Unified context generation
+
+### Phase 2 (Done ✅)
+- [x] Symbol extraction (functions, classes, interfaces)
+- [x] Dependency analysis
+- [x] AI rules generation
+- [x] Machine-readable outputs (JSON)
+
+### Phase 3 (In Progress)
+- [x] Health check command (`ai-first doctor`)
+- [x] Module exploration (`ai-first explore`)
+- [x] Repository mapping (`ai-first map`)
+- [x] Semantic indexing with embeddings
+- [x] Incremental indexing (track file changes)
+- [ ] Configuration file support (`ai-first.config.json`)
+- [ ] Custom rules/plugins system
+
+### Phase 4 (Future)
+- [ ] Git integration (analyze recent changes)
+- [ ] Diff-aware context (what changed since last run)
+- [ ] Interactive mode
+- [ ] VS Code extension
+
+---
+
+## How to Update
+
+After each push to GitHub:
+1. Update this changelog with new changes
+2. Update version if needed (semver)
+3. Push changes
+
+```bash
+git add CHANGELOG.md
+git commit -m "Update changelog"
+git push
+```

package/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to ai-first
+
+Thank you for your interest in contributing!
+
+## Development Setup
+
+```bash
+# Clone the repository
+git clone https://github.com/julianperezpesce/ai-first.git
+cd ai-first
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Run
+npm run run
+# or
+node dist/commands/ai-first.js
+```
+
+## Project Structure
+
+```
+ai-first/
+├── src/
+│   ├── analyzers/        # Analysis modules
+│   │   ├── architecture.ts
+│   │   ├── conventions.ts
+│   │   ├── entrypoints.ts
+│   │   └── techStack.ts
+│   ├── commands/        # CLI commands
+│   │   └── ai-first.ts
+│   ├── core/            # Core functionality
+│   │   ├── repoMapper.ts
+│   │   └── repoScanner.ts
+│   └── utils/           # Utilities
+│       └── fileUtils.ts
+├── dist/                # Compiled JavaScript
+├── package.json
+└── tsconfig.json
+```
+
+## Adding New Analyzers
+
+To add a new analyzer:
+
+1. Create a new file in `src/analyzers/`
+2. Export functions for detection and file generation
+3. Import and use in `src/commands/ai-first.ts`
+
+Example:
+```typescript
+// src/analyzers/myAnalyzer.ts
+import { FileInfo } from "../core/repoScanner.js";
+
+export interface MyAnalysis {
+  // Define your output type
+}
+
+export function analyzeMyFeature(files: FileInfo[]): MyAnalysis {
+  // Your analysis logic
+  return { /* ... */ };
+}
+
+export function generateMyFeatureFile(analysis: MyAnalysis): string {
+  return "# My Analysis\n" + /* ... */;
+}
+```
+
+## Running Tests
+
+Currently there are no tests. Contributions with tests are welcome!
+
+## Publishing to npm
+
+```bash
+# Update version in package.json
+npm version patch
+
+# Publish
+npm publish
+```
+
+## License
+
+MIT

package/FLOW.md

@@ -0,0 +1,129 @@
+# Flow Diagram
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                        ai-first CLI                         │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  1. scanRepo(rootDir)                                       │
+│     - Recursively scan directory                            │
+│     - Filter by includeExtensions                           │
+│     - Return: FileInfo[]                                    │
+└─────────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+┌─────────────────────────────────────────────────────────────┐
+│  2. Create output directory (default: ./ai)                │
+└─────────────────────────────────────────────────────────────┘
+                              │
+              ┌───────────────┼───────────────┐
+              ▼               ▼               ▼
+    ┌─────────────────┐ ┌───────────┐ ┌─────────────┐
+    │ 3a. repoMapper  │ │3b. techStack│ │3c. architecture│
+    │ - repo_map.md   │ │ - tech_stack│ │ - architecture│
+    │ - repo_map.json │ │    .md     │ │    .md       │
+    │ - summary.md    │ │             │ │               │
+    └─────────────────┘ └─────────────┘ └─────────────┘
+              │               │               │
+              └───────────────┼───────────────┘
+                              ▼
+    ┌─────────────────────────────────────────────────────────┐
+    │ 4. Analyzers Pipeline                                   │
+    │ ┌──────────────┐ ┌──────────────┐ ┌──────────────────┐  │
+    │ │entrypoints   │ │conventions   │ │symbols (NEW)    │  │
+    │ │.md           │ │.md           │ │.json (NEW)      │  │
+    └──────────────┘ └──────────────┘ └──────────────────┘  │
+    ┌──────────────────┐ ┌──────────────┐                    │
+    │dependencies (NEW)│ │ai_rules (NEW)│                    │
+    │.json             │ │.md           │                    │
+    └──────────────────┘ └──────────────┘                    │
+                              │
+                              ▼
+    ┌─────────────────────────────────────────────────────────┐
+    │ 5. generateUnifiedContext()                             │
+    │    - Combines all analysis into ai_context.md           │
+    └─────────────────────────────────────────────────────────┘
+                              │
+                              ▼
+    ┌─────────────────────────────────────────────────────────┐
+    │ 6. Output Files                                          │
+    │   ai/                                                    │
+    │   ├── ai_context.md      ← UNIFIED (most important!)    │
+    │   ├── repo_map.md                                        │
+    │   ├── repo_map.json     ← NEW                            │
+    │   ├── summary.md                                        │
+    │   ├── architecture.md                                    │
+    │   ├── tech_stack.md                                      │
+    │   ├── entrypoints.md                                     │
+    │   ├── conventions.md                                     │
+    │   ├── symbols.json       ← NEW                           │
+    │   ├── dependencies.json  ← NEW                           │
+    │   └── ai_rules.md       ← NEW                           │
+    └─────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Execution Flow
+
+```
+User runs: ai-first init
+
+    │
+    ▼
+┌────────────────────────────────────┐
+│ CLI Entry Point                     │
+│ - Parse args (--root, --output)    │
+│ - Handle 'init' command            │
+└────────────────────────────────────┘
+    │
+    ▼
+┌────────────────────────────────────┐
+│ runAIFirst(options)                │
+│ - rootDir: process.cwd()           │
+│ - outputDir: ./ai                  │
+└────────────────────────────────────┘
+    │
+    ▼
+┌────────────────────────────────────┐
+│ scanRepo(rootDir)                   │
+│ Returns: { files: FileInfo[] }      │
+└────────────────────────────────────┘
+    │
+    ▼
+┌────────────────────────────────────┐
+│ For each analyzer:                  │
+│ 1. analyze(files, rootDir)         │
+│ 2. generateXxxFile(result)        │
+│ 3. writeFile(outputPath, content)  │
+└────────────────────────────────────┘
+    │
+    ▼
+┌────────────────────────────────────┐
+│ generateUnifiedContext()            │
+│ - Combines all results             │
+│ - Creates ai_context.md            │
+└────────────────────────────────────┘
+    │
+    ▼
+┌────────────────────────────────────┐
+│ Return: { success, filesCreated }  │
+└────────────────────────────────────┘
+```
+
+---
+
+## Analyzer Details
+
+| Analyzer | Output | Description |
+|----------|--------|-------------|
+| `repoMapper` | repo_map.md, repo_map.json, summary.md | Directory tree & file stats |
+| `techStack` | tech_stack.md | Languages, frameworks, package managers |
+| `architecture` | architecture.md | MVC, Clean Architecture, Hexagonal, etc. |
+| `entrypoints` | entrypoints.md | CLI, API, server entry points |
+| `conventions` | conventions.md | Naming, testing, linting conventions |
+| `symbols` | symbols.json | Functions, classes, interfaces (NEW) |
+| `dependencies` | dependencies.json | Import graph (NEW) |
+| `aiRules` | ai_rules.md | Guidelines for AI (NEW) |