ai-first-cli 1.1.1 → 1.1.2

package/docs/guide/adapters.md

@@ -0,0 +1,225 @@
+# Analysis Adapters
+
+AI-First uses an adapter system to support multiple languages and frameworks without modifying the core analysis engine.
+
+## Overview
+
+Adapters customize how AI-First detects:
+- **Feature roots**: Where to look for business features
+- **Entrypoints**: Files that represent entry points
+- **Layers**: Architectural layers in the codebase
+- **Ignored folders**: Technical directories to skip
+
+## Supported Adapters
+
+| Adapter | Detection Signals |
+|---------|-------------------|
+| JavaScript/TypeScript | `package.json`, `tsconfig.json`, `vite.config.ts` |
+| NestJS | `nest-cli.json`, `main.ts` |
+| Django | `manage.py`, `settings.py` |
+| Flask/FastAPI | `app.py`, `main.py`, `requirements.txt` |
+| FastAPI | `main.py`, `app.py` |
+| Ruby on Rails | `Gemfile`, `config.ru` |
+| Laravel | `artisan`, `composer.json` |
+| Elixir Phoenix | `mix.exs`, `phoenix` |
+| Spring Boot | `pom.xml`, `build.gradle`, `application.java` |
+| Salesforce | `sfdx-project.json`, `force-app/` |
+| .NET | `*.csproj`, `Program.cs` |
+| ASP.NET Core | `Startup.cs`, `Program.cs` |
+| Blazor | `_Imports.razor`, `@page` |
+
+| Adapter | Detection Signals |
+|---------|------------------|
+| JavaScript/TypeScript | `package.json`, `tsconfig.json`, `vite.config.ts` |
+| Django | `manage.py`, `settings.py` |
+| Flask/FastAPI | `app.py`, `main.py` |
+| Ruby on Rails | `Gemfile`, `config.ru` |
+| Salesforce | `sfdx-project.json`, `force-app/` |
+| .NET | `*.csproj`, `Program.cs` |
+| ASP.NET Core | `Startup.cs`, `Program.cs` |
+| Blazor | `_Imports.razor`, `@page` |
+
+## Architecture
+
+```
+analysis/
+adapters/
+  baseAdapter.ts      # Interface definition
+  javascriptAdapter.ts
+  pythonAdapter.ts
+  railsAdapter.ts
+  salesforceAdapter.ts
+  dotnetAdapter.ts
+  adapterRegistry.ts  # Detection logic
+```
+
+## Adapter Interface
+
+```typescript
+interface AnalysisAdapter {
+  name: string;
+  displayName: string;
+  detectionSignals: DetectionSignal[];
+  featureRoots: string[];
+  ignoredFolders: string[];
+  entrypointPatterns: string[];
+  layerRules: LayerRule[];
+  supportedExtensions: string[];
+  flowEntrypointPatterns: string[];
+  flowExcludePatterns: string[];
+}
+```
+
+## Detection Signals
+
+Adapters are detected using signals:
+
+```typescript
+interface DetectionSignal {
+  type: 'file' | 'directory' | 'content';
+  pattern: string;
+  contentPattern?: string;
+}
+```
+
+Example:
+```typescript
+detectionSignals: [
+  { type: 'file', pattern: 'package.json' },
+  { type: 'file', pattern: 'tsconfig.json' },
+  { type: 'directory', pattern: 'src' }
+]
+```
+
+## Layer Rules
+
+Each adapter defines architectural layers:
+
+```typescript
+layerRules: [
+  { name: 'api', priority: 1, patterns: ['controller', 'handler', 'route'] },
+  { name: 'service', priority: 2, patterns: ['service', 'usecase'] },
+  { name: 'data', priority: 3, patterns: ['repository', 'model'] }
+]
+```
+
+## Usage
+
+```typescript
+import { detectAdapter, getAdapter } from './core/adapters/index.js';
+
+// Auto-detect project type
+const adapter = detectAdapter('/path/to/project');
+console.log(adapter.name); // 'javascript', 'django', etc.
+
+// Get specific adapter
+const jsAdapter = getAdapter('javascript');
+```
+
+## Creating Custom Adapters
+
+1. Create a new file in `src/core/adapters/`
+2. Define your adapter:
+
+```typescript
+import { AnalysisAdapter } from './baseAdapter.js';
+
+export const myAdapter: AnalysisAdapter = {
+  name: 'myframework',
+  displayName: 'My Framework',
+  detectionSignals: [
+    { type: 'file', pattern: 'my-framework.config.js' }
+  ],
+  featureRoots: ['src', 'lib'],
+  ignoredFolders: ['node_modules', 'dist'],
+  entrypointPatterns: ['controller', 'service'],
+  layerRules: [
+    { name: 'api', priority: 1, patterns: ['controller'] },
+    { name: 'service', priority: 2, patterns: ['service'] },
+    { name: 'data', priority: 3, patterns: ['model'] }
+  ],
+  supportedExtensions: ['.ts', '.js'],
+  flowEntrypointPatterns: ['controller'],
+  flowExcludePatterns: ['test', 'spec']
+};
+3. Register in `adapterRegistry.ts`
+4. Add tests
+
+## Using the Adapter SDK
+
+AI-First provides a developer-friendly SDK for creating custom adapters:
+
+```typescript
+import { createAdapter, validateAdapter, fileSignal, directorySignal } from './core/adapters/sdk.js';
+
+// Create adapter with sensible defaults
+export const myAdapter = createAdapter({
+  name: 'myframework',
+  displayName: 'My Framework',
+  detectionSignals: [
+    fileSignal('my-framework.config.js'),
+    directorySignal('src')
+  ],
+  featureRoots: ['src', 'lib', 'app'],
+  entrypointPatterns: ['Controller', 'Service', 'Handler']
+});
+
+// Validate your adapter
+const result = validateAdapter(myAdapter);
+if (!result.valid) {
+  console.error('Adapter errors:', result.errors);
+}
+```
+
+### SDK Functions
+
+- `createAdapter(config)` - Create adapter with defaults
+- `validateAdapter(adapter)` - Validate adapter configuration
+- `fileSignal(pattern)` - Create file detection signal
+- `directorySignal(pattern)` - Create directory detection signal
+- `contentSignal(pattern, contentPattern?)` - Create content-based signal
+- `layerRule(name, priority, patterns)` - Create layer rule
+
+## Community Adapters
+
+Community adapters are located in `src/core/adapters/community/`:
+
+- **Laravel** - PHP Laravel framework
+- **NestJS** - Node.js progressive framework
+- **Spring Boot** - Java/Kotlin framework
+- **Phoenix** - Elixir web framework
+- **FastAPI** - Python modern framework
+
+### Listing Available Adapters
+
+```bash
+ai-first adapters
+```
+
+Output:
+```
+📦 Available adapters:
+
+Name                | Display Name
+--------------------|---
+javascript        | JavaScript / TypeScript
+nestjs            | NestJS
+django            | Django
+...
+```
+
+## Integration
+
+3. Register in `adapterRegistry.ts`
+4. Add tests
+
+## Integration
+
+Adapters integrate with feature and flow detection:
+
+- `featureRoots` → where to find features
+- `ignoredFolders` → what to skip
+- `entrypointPatterns` → business logic entry points
+- `layerRules` → flow chain layers
+
+This allows AI-First to understand any codebase structure.

package/docs/guide/ai-repository-schema.md

@@ -0,0 +1,119 @@
+# AI Repository Schema
+
+The AI Repository Schema standardizes how AI-First stores and manages repository metadata, enabling AI agents to understand project structure and maintain compatibility across versions.
+
+## Overview
+
+AI-First generates three core schema files that define the project structure:
+
+- `schema.json` - Schema version and metadata
+- `project.json` - Project information (features, flows, languages, frameworks)
+- `tools.json` - Compatible AI tools and agents
+
+## Schema Files
+
+### schema.json
+
+Contains schema version and generation metadata:
+
+```json
+{
+  "schemaVersion": "1.0",
+  "generatedBy": "ai-first",
+  "generatedAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### project.json
+
+Contains project-specific information:
+
+```json
+{
+  "name": "my-project",
+  "rootDir": "/path/to/project",
+  "features": ["auth", "users", "payments"],
+  "flows": ["login", "checkout", "registration"],
+  "languages": ["TypeScript", "Python"],
+  "frameworks": ["Express", "React"],
+  "generatedAt": "2024-01-15T10:30:00.000Z"
+}
+```
+
+### tools.json
+
+Defines compatible AI agents:
+
+```json
+{
+  "compatibleAgents": ["ai-first-bridge", "opencode", "cursor", "windsurf", "cline"],
+  "schemaVersion": "1.0"
+}
+```
+
+## Auto-Detection
+
+AI-First automatically detects:
+
+- **Features**: From `ai/context/features/*.json` files
+- **Flows**: From `ai/context/flows/*.json` files
+- **Languages**: From `ai/tech_stack.md` (Languages section)
+- **Frameworks**: From `ai/tech_stack.md` (Frameworks section)
+
+## Version Compatibility
+
+The schema uses semantic versioning. AI-First validates compatibility:
+
+- Same major version = compatible
+- Different major version = incompatible
+
+## CLI Commands
+
+### Generate Schema
+
+Schema is automatically generated with `ai-first init`:
+
+```bash
+ai-first init
+```
+
+### Validate Schema
+
+Check if your repository has a valid schema:
+
+```javascript
+import { validateSchema } from 'ai-first';
+
+const result = validateSchema('./ai');
+console.log(result.valid);  // true/false
+console.log(result.errors); // []
+```
+
+### Load Schema
+
+Load schema programmatically:
+
+```javascript
+import { loadFullSchema } from 'ai-first';
+
+const schema = loadFullSchema('./ai');
+if (schema) {
+  console.log(schema.project.name);
+  console.log(schema.schema.schemaVersion);
+}
+```
+
+## Integration
+
+The schema is integrated into the AI-First CLI:
+
+1. `ai-first init` - Generates schema files
+2. `ai-first validate` - Validates schema (coming soon)
+3. `ai-first doctor` - Checks schema health
+
+## Benefits
+
+- **Version Safety**: AI agents know which schema version to expect
+- **Project Discovery**: Features and flows are automatically detected
+- **Agent Compatibility**: Clear list of supported AI tools
+- **Extensibility**: Schema can be extended for custom agents

package/docs/guide/architecture.md

@@ -209,4 +209,72 @@ AI-First is designed to be extensible:
 
 - Add new analyzers in `src/analyzers/`
 - Custom rules in `ai_rules.md`
-- Configuration file support (planned)
+---
+
+## Feature Detection (`src/core/semanticContexts.ts`)
+
+AI-First automatically detects business features and flows from your codebase structure.
+
+### Feature Detection Rules
+
+**1. Candidate Roots**
+
+Features are scanned inside:
+- `src/*`
+- `app/*`
+- `packages/*`
+- `services/*`
+- `modules/*`
+- `features/*`
+
+**2. Ignored Folders**
+
+Technical folders are excluded:
+- `utils`, `helpers`, `types`, `interfaces`, `constants`
+- `config`, `dto`, `models`, `common`, `shared`
+
+**3. Feature Requirements**
+
+A valid feature must:
+- Contain at least 3 source files
+- Contain at least one entrypoint (Controller, Route, Handler, Command, Service)
+- Exist at depth 1 or 2: `src/auth`, `src/modules/auth`
+
+### Feature Output Format
+
+```json
+{
+  "name": "auth",
+  "path": "src/auth",
+  "files": [
+    "src/auth/authController.ts",
+    "src/auth/authService.ts",
+    "src/auth/authRepository.ts"
+  ],
+  "entrypoints": [
+    "src/auth/authController.ts"
+  ],
+  "dependencies": ["users", "payments"]
+}
+```
+
+### Flow Detection
+
+Flows represent business execution chains starting from entrypoints:
+
+- **Minimum 3 files** per flow
+- **Minimum 2 architectural layers** (api → service → data)
+- Entry points: Controller, Route, Handler, Command
+
+Flows are generated using three fallback methods:
+1. **Symbol Graph** - Uses call/import relationships
+2. **Folder Structure** - Groups by feature prefix
+3. **Import Analysis** - Follows dependency chains
+
+### Output Location
+
+Features and flows are written to:
+```
+ai/context/features/<feature>.json
+ai/context/flows/<flow>.json
+```

package/docs/guide/flows.md

@@ -0,0 +1,134 @@
+# Flow Detection
+
+Flows represent business execution chains that traverse multiple architectural layers in your codebase.
+
+## Overview
+
+Flow detection identifies how data flows through your application from entrypoints to data access layers.
+
+### Example Flow
+
+```
+LoginController → AuthService → UserRepository
+```
+
+This represents the typical three-tier architecture:
+1. **API Layer**: LoginController (entrypoint)
+2. **Service Layer**: AuthService (business logic)
+3. **Data Layer**: UserRepository (persistence)
+
+## Detection Methods
+
+AI-First uses multiple fallback methods to detect flows:
+
+### 1. Symbol Graph (Primary)
+
+When symbol relationships are strong, flows are detected by analyzing:
+- Function calls (`calls`)
+- Module imports (`imports`)
+- Symbol references (`references`)
+
+**Requirements:**
+- Symbol graph density ≥ 0.5
+- At least 10 relationships
+
+### 2. Folder Structure (Fallback)
+
+When symbol graph is weak, flows are inferred from:
+- File naming conventions (e.g., `authController.ts`, `authService.ts`)
+- Grouping by feature prefix
+
+**Example:**
+- `authController.ts` → feature: `auth`
+- `authService.ts` → belongs to `auth` flow
+- `authRepository.ts` → belongs to `auth` flow
+
+### 3. Import Analysis (Fallback)
+
+Uses dependency analysis to trace execution paths:
+1. Start from entrypoint files
+2. Follow import statements
+3. Build chain up to MAX_FLOW_DEPTH
+
+## Configuration
+
+### Limits
+
+| Parameter | Value | Description |
+|-----------|-------|-------------|
+| `MAX_FLOW_DEPTH` | 5 | Maximum traversal depth |
+| `MAX_FLOW_FILES` | 30 | Maximum files per flow |
+
+### Entrypoints
+
+Flows must start from one of these file types:
+- Controller
+- Route
+- Handler
+- Command
+
+### Layers
+
+Supported architectural layers:
+| Layer | Patterns |
+|-------|----------|
+| api | controller, handler, route, router, endpoint |
+| service | service, services, usecase, interactor |
+| data | repository, repo, dal, dao, data, persistence |
+| domain | model, entity, schema, domain |
+
+## Requirements
+
+A valid flow must have:
+- **Minimum 3 files**
+- **Minimum 2 architectural layers**
+
+## Output Format
+
+Flows are written to: `ai/context/flows/<flow-name>.json`
+
+```json
+{
+  "name": "auth",
+  "entrypoint": "api/authController.js",
+  "files": [
+    "api/authController.js",
+    "services/authService.js",
+    "data/authRepository.js"
+  ],
+  "depth": 3,
+  "layers": ["api", "service", "data"]
+}
+```
+
+### Output Fields
+
+| Field | Description |
+|-------|-------------|
+| `name` | Flow identifier (derived from entrypoint) |
+| `entrypoint` | Starting file (Controller/Route/Handler/Command) |
+| `files` | All files in the flow chain |
+| `depth` | Actual traversal depth |
+| `layers` | Unique layers traversed |
+
+## Usage
+
+Flows are automatically generated when running:
+
+```bash
+ai-first map
+# or
+ai-first init
+```
+
+## Integration
+
+Flows work with Features to provide complete context:
+
+- **Features**: Identify business modules (auth, users, payments)
+- **Flows**: Identify how code executes within features
+
+Together they enable AI agents to:
+1. Understand business domain structure
+2. Trace execution paths
+3. Locate relevant code for modifications

package/docs/guide/git-intelligence.md

@@ -0,0 +1,170 @@
+# Git Intelligence
+
+AI-First can analyze your git repository to provide AI agents with context about recent activity, helping them prioritize relevant files and understand what's been recently changed.
+
+## Why Git Intelligence?
+
+When working with AI coding assistants, knowing which files have been recently modified helps the AI:
+
+- **Prioritize review** - Focus on recently changed files when suggesting modifications
+- **Understand context** - Know which features/flows are actively being developed
+- **Avoid conflicts** - Identify files that were recently modified to prevent overwrite
+- **Trace changes** - See commit patterns and activity frequency
+
+## How It Works
+
+Git Intelligence analyzes your git history to generate metadata about recent repository activity:
+
+1. **Detects git repository** - Checks if the project is a git repository
+2. **Analyzes recent commits** - Extracts commit data (default: last 50 commits, last 30 days)
+3. **Maps to features/flows** - Correlates changed files with detected features and flows
+4. **Generates metadata** - Outputs JSON files for AI consumption
+
+## Generated Files
+
+When you run `ai-first git`, the following files are created in `ai/git/`:
+
+### recent-files.json
+
+List of recently changed files:
+
+```json
+[
+  "src/auth/loginController.ts",
+  "src/auth/sessionService.ts",
+  "src/payments/checkoutFlow.ts"
+]
+```
+
+### recent-features.json
+
+Features that have been recently modified:
+
+```json
+["auth", "payments"]
+```
+
+### recent-flows.json
+
+Flows that have been recently modified:
+
+```json
+["login", "checkout"]
+```
+
+### commit-activity.json
+
+Detailed commit frequency data:
+
+```json
+{
+  "totalCommits": 50,
+  "dateRange": {
+    "start": "2026-02-01",
+    "end": "2026-03-10"
+  },
+  "files": {
+    "src/auth/loginController.ts": 5,
+    "src/auth/sessionService.ts": 3
+  },
+  "features": {
+    "auth": 8,
+    "payments": 12
+  },
+  "flows": {
+    "login": 4,
+    "checkout": 7
+  }
+}
+```
+
+## Usage
+
+### CLI Command
+
+```bash
+# Analyze git activity
+ai-first git
+
+# Analyze with more commits
+ai-first git --limit 100
+
+# Show detailed activity
+ai-first git --activity
+
+# Output as JSON
+ai-first git --json
+```
+
+### Options
+
+| Option | Alias | Description |
+|--------|-------|-------------|
+| `--root` | `-r` | Root directory (default: current) |
+| `--limit` | `-n` | Number of commits (default: 50) |
+| `--activity` | `-a` | Show detailed activity |
+| `--json` | | Output as JSON |
+| `--help` | `-h` | Show help |
+
+### Programmatic Usage
+
+```typescript
+import { 
+  detectGitRepository,
+  getRecentCommits,
+  analyzeGitActivity,
+  generateGitContext 
+} from 'ai-first';
+
+// Check if git repo
+if (detectGitRepository('/path/to/project')) {
+  // Get recent commits
+  const commits = getRecentCommits('/path/to/project');
+  
+  // Analyze activity
+  const activity = analyzeGitActivity('/path/to/project');
+  
+  // Generate context files
+  const context = generateGitContext('/path/to/project');
+}
+```
+
+## API Reference
+
+### detectGitRepository(rootDir: string): boolean
+
+Checks if a directory is a git repository.
+
+### getRecentCommits(rootDir: string, limit?: number): GitCommit[]
+
+Returns recent commits with file changes.
+
+### extractChangedFiles(commits: GitCommit[]): RecentFile[]
+
+Extracts and counts changed files from commits.
+
+### mapFilesToFeatures(rootDir: string, files: string[]): string[]
+
+Maps changed files to detected features.
+
+### mapFilesToFlows(rootDir: string, files: string[]): string[]
+
+Maps changed files to detected flows.
+
+### analyzeGitActivity(rootDir: string): GitActivity | null
+
+Analyzes git activity and returns aggregated data.
+
+### generateGitContext(rootDir: string, aiDir?: string): GitContext
+
+Generates all git context files in `ai/git/`.
+
+## Integration with AI Context
+
+Git intelligence integrates with the AI context system:
+
+1. Run `ai-first init` to generate features and flows
+2. Run `ai-first git` to analyze git activity
+3. AI agents can read `ai/git/` files to understand recent changes
+
+This provides a complete picture of both your codebase structure and its development activity.