@getmikk/ai-context 1.7.1 → 1.9.0

package/README.md

@@ -1,329 +1,100 @@
-# @getmikk/ai-context
+# @getmikk/ai-context
 
-> Token-budgeted, graph-traced AI context — the difference between an LLM that guesses your architecture and one that actually knows it.
+> Token-budgeted AI context builder and claude.md / AGENTS.md generator.
 
 [![npm](https://img.shields.io/npm/v/@getmikk/ai-context)](https://www.npmjs.com/package/@getmikk/ai-context)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](../../LICENSE)
 
-`@getmikk/ai-context` solves the AI context window problem at the architectural level. Instead of dumping your entire codebase into a prompt and hoping the LLM figures it out, it walks the dependency graph from task-relevant seed functions, scores every reachable function by relevance, and packs the highest-signal functions into a token budget — giving your AI exactly what it needs and nothing it doesn't.
+Two things: a graph-traced context builder that packs the most relevant functions into a token budget for any given task, and a documentation generator that produces always-accurate `claude.md` and `AGENTS.md` files from the lock file.
 
-It also generates `claude.md` and `AGENTS.md` — tiered architecture summaries that let AI agents understand your entire project structure from a single file.
-
-> Part of [Mikk](../../README.md) — the codebase nervous system for AI-assisted development.
+> Part of [Mikk](../../README.md) — live architectural context for your AI agent.
 
 ---
 
-## Installation
-
-```bash
-npm install @getmikk/ai-context
-# or
-bun add @getmikk/ai-context
-```
+## Context Builder
 
-**Peer dependencies:** `@getmikk/core`, `@getmikk/intent-engine`
+Given a task description, BFS-traces the dependency graph from matched seed functions and returns the most relevant context within a configurable token budget.
 
----
-
-## Quick Start
-
-### Context Queries
+### Usage
 
 ```typescript
 import { ContextBuilder, getProvider } from '@getmikk/ai-context'
-import { ContractReader, LockReader } from '@getmikk/core'
-
-const contract = await new ContractReader().read('./mikk.json')
-const lock = await new LockReader().read('./mikk.lock.json')
 
 const builder = new ContextBuilder(contract, lock)
-const context = builder.build({
-  task: 'Add rate limiting to the authentication endpoints',
-  tokenBudget: 8000,
-  maxHops: 3,
+
+const ctx = builder.build({
+  task: 'Add rate limiting to all API routes',
+  maxHops: 4,
+  tokenBudget: 6000,
+  focusModules: ['api-gateway'],
   includeCallGraph: true,
+  includeBodies: true,
+  projectRoot: '/path/to/project',
 })
 
-// Format for a specific AI provider
-const provider = getProvider('claude')
-const formatted = provider.formatContext(context)
-// Send `formatted` as part of your AI prompt
-```
-
-### Claude.md / AGENTS.md Generation
-
-```typescript
-import { ClaudeMdGenerator } from '@getmikk/ai-context'
-
-const generator = new ClaudeMdGenerator(contract, lock, /* tokenBudget */ 4000)
-const markdown = generator.generate()
+// Format for your AI client
+const formatter = getProvider('claude')   // XML tags
+// const formatter = getProvider('generic')  // plain text
+// const formatter = getProvider('compact')  // minimal tokens
 
-// Write to project root
-await writeFile('./claude.md', markdown)
-await writeFile('./AGENTS.md', markdown)
+const output = formatter.formatContext(ctx)
 ```
 
----
-
-## How Context Building Works
-
-The `ContextBuilder` uses a 6-step algorithm:
-
-```
-1. Resolve Seeds
-   └─ Parse task → extract keywords → match against lock file functions/modules
+### How context is built
 
-2. BFS Proximity Walk
-   └─ Walk the call graph outward from seed functions (up to maxHops)
+1. **Seed** — match task keywords against function names, module descriptions, and file paths
+2. **Walk** — BFS from seed nodes, following call graph edges outward up to `maxHops` depth
+3. **Score** — each function scored by: proximity to seed (depth penalty), keyword match bonus, entry-point bonus
+4. **Budget** — greedy knapsack: highest-scoring functions added until token budget is consumed
+5. **Format** — serialized with function bodies, params, return types, call graph, and file locations
 
-3. Score Functions
-   └─ Each function gets a relevance score:
-      • Proximity score (closer to seed = higher)
-      • Keyword match score (task keywords in function name)
-      • Entry-point bonus (exported functions score higher)
-
-4. Sort by Score
-   └─ Descending relevance
-
-5. Fill Token Budget
-   └─ Greedily add functions until budget is exhausted
-      (each function's token cost ≈ line count × 4)
-
-6. Group by Module
-   └─ Organize selected functions into module-level context
-```
+The result is surgical — agents get exactly the functions relevant to their task, not the entire codebase.
 
 ---
 
-## API Reference
+## claude.md / AGENTS.md Generator
 
-### ContextBuilder
+Generates `claude.md` and `AGENTS.md` automatically during `mikk init` and `mikk analyze`. Every piece of content is derived from the AST-parsed lock file — never hand-authored, never stale.
 
-The main entry point for building task-specific context.
-
-```typescript
-import { ContextBuilder } from '@getmikk/ai-context'
-
-const builder = new ContextBuilder(contract, lock)
-const context = builder.build(query)
-```
-
-**`ContextQuery`:**
-
-| Field | Type | Default | Description |
-|-------|------|---------|-------------|
-| `task` | `string` | — | Natural-language description of the task |
-| `focusFiles` | `string[]` | `[]` | Specific files to prioritize |
-| `focusModules` | `string[]` | `[]` | Specific modules to prioritize |
-| `maxFunctions` | `number` | `50` | Maximum functions to include |
-| `maxHops` | `number` | `3` | BFS depth limit from seed functions |
-| `tokenBudget` | `number` | `8000` | Maximum estimated tokens |
-| `includeCallGraph` | `boolean` | `true` | Include `calls[]` and `calledBy[]` per function |
-
-**`AIContext` (returned):**
-
-```typescript
-type AIContext = {
-  project: string              // Project name from contract
-  modules: ContextModule[]     // Relevant modules with their functions
-  constraints: string[]        // Active architectural constraints
-  decisions: string[]          // Relevant ADRs
-  prompt: string               // Original task
-  meta: {
-    seedCount: number          // How many seed functions were found
-    totalFunctionsConsidered: number
-    selectedFunctions: number  // Functions that fit in the budget
-    estimatedTokens: number    // Approximate token count
-    keywords: string[]         // Extracted keywords from the task
-  }
-}
-```
-
-**`ContextModule`:**
-
-```typescript
-type ContextModule = {
-  id: string
-  name: string
-  description?: string
-  intent?: string              // Module's purpose from mikk.json
-  functions: ContextFunction[]
-  files: string[]
-}
-```
-
-**`ContextFunction`:**
-
-```typescript
-type ContextFunction = {
-  name: string
-  file: string
-  startLine: number
-  endLine: number
-  calls: string[]              // Functions this one calls
-  calledBy: string[]           // Functions that call this one
-  purpose?: string             // Inferred purpose
-  errorHandling?: string       // Error patterns detected
-  edgeCases?: string           // Edge cases noted
-}
-```
-
----
-
-### ClaudeMdGenerator
-
-Generates tiered markdown documentation files for AI agents.
+### Usage
 
 ```typescript
 import { ClaudeMdGenerator } from '@getmikk/ai-context'
 
-const generator = new ClaudeMdGenerator(contract, lock, tokenBudget)
-const markdown = generator.generate()
-```
-
-**Tiered output structure:**
-
-| Tier | Content | Budget |
-|------|---------|--------|
-| **Tier 1** | Project summary — name, module count, total functions, architecture overview | ~500 tokens |
-| **Tier 2** | Module details — each module's intent, public API, file list, key functions | ~300 tokens/module |
-| **Tier 3** | Constraints & decisions — all architectural rules and ADRs | Remaining budget |
-
-**All data is sourced from the AST-derived lock file** — no hallucinated descriptions. Module intents come from `mikk.json`, function lists and call graphs come from `mikk.lock.json`.
+const generator = new ClaudeMdGenerator(
+  contract,
+  lock,
+  12000,   // token budget
+  {        // from package.json
+    description: 'Multi-channel AI gateway',
+    scripts: { build: 'bun run build', test: 'vitest' },
+    dependencies: { ... },
+  },
+  projectRoot
+)
 
-**Example output:**
-
-```markdown
-# Project: my-app
-
-## Architecture Overview
-- **Modules:** 5
-- **Total Functions:** 87
-- **Total Files:** 23
-
-## Modules
-
-### auth
-**Intent:** Handle user authentication and session management
-**Public API:** `login`, `logout`, `validateToken`, `refreshSession`
-**Files:** auth/login.ts, auth/session.ts, auth/middleware.ts
-**Key Functions:**
-- `validateToken` (auth/middleware.ts:15-42) → calls: `decodeJWT`, `checkExpiry`
-- `login` (auth/login.ts:8-35) → calls: `validateCredentials`, `createSession`
-
-### payments
-...
-
-## Constraints
-- auth: no-import from payments
-- payments: must-use stripe-sdk
-
-## Decisions
-- ADR-001: Use JWT for stateless auth (2024-01-15)
-```
-
----
-
-### Providers
-
-Providers format the `AIContext` object into a string optimized for a specific AI model.
-
-```typescript
-import { getProvider, ClaudeProvider, GenericProvider } from '@getmikk/ai-context'
-
-// Factory
-const provider = getProvider('claude')   // or 'generic'
-
-// Format context for the provider
-const formatted = provider.formatContext(context)
-```
-
-#### ClaudeProvider
-
-Formats with structured XML tags optimized for Anthropic Claude:
-
-```xml
-<architecture>
-  <module name="auth" intent="Handle authentication">
-    <function name="validateToken" file="auth/middleware.ts" lines="15-42">
-      <calls>decodeJWT, checkExpiry</calls>
-      <calledBy>authMiddleware</calledBy>
-    </function>
-  </module>
-</architecture>
-<constraints>
-  auth: no-import from payments
-</constraints>
-```
-
-#### GenericProvider
-
-Clean plain-text format for any AI model:
-
-```
-## Module: auth
-Intent: Handle authentication
-
-### validateToken (auth/middleware.ts:15-42)
-Calls: decodeJWT, checkExpiry
-Called by: authMiddleware
+const content = generator.generate()
+// Write to claude.md and AGENTS.md
 ```
 
----
-
-## Usage Examples
-
-### "What breaks if I change this file?"
+### Tiered output
 
-```typescript
-const context = builder.build({
-  task: `Impact analysis for changes to src/auth/login.ts`,
-  focusFiles: ['src/auth/login.ts'],
-  maxHops: 5,
-  tokenBudget: 4000,
-})
-// Returns all functions transitively affected by login.ts
-```
-
-### "Get context for adding a feature"
-
-```typescript
-const context = builder.build({
-  task: 'Add two-factor authentication to the login flow',
-  focusModules: ['auth'],
-  tokenBudget: 12000,
-  includeCallGraph: true,
-})
-// Returns auth module functions + related cross-module calls
-```
+Content is generated in priority order until the token budget (default 12,000) is consumed:
 
-### "Focused context for a specific module"
+| Tier | Content | Always included? |
+|------|---------|-----------------|
+| 1 | Project summary — name, description, module list with function counts, stats, critical constraints | Yes |
+| — | Tech stack — detected frameworks, runtime, build tool | If detectable |
+| — | Build/test/run commands — from package.json scripts | If present |
+| 2 | Per-module detail — exported API, key functions, internal call summary (~300 tokens/module) | Until budget |
+| — | Context files — discovered schemas, configs, data models | If budget allows |
+| — | Import graph — cross-file import relationships per module | If budget allows |
+| — | HTTP routes — detected routes with method, path, handler | If budget allows |
+| 3 | Constraints — all declared constraint rules | If budget allows |
+| — | ADR decisions — architectural decisions with reasons | If budget allows |
 
-```typescript
-const context = builder.build({
-  task: 'Refactor the payment processing pipeline',
-  focusModules: ['payments'],
-  maxFunctions: 30,
-  tokenBudget: 6000,
-})
-```
-
----
-
-## Types
-
-```typescript
-import type {
-  AIContext,
-  ContextModule,
-  ContextFunction,
-  ContextQuery,
-  ContextProvider,
-} from '@getmikk/ai-context'
-```
-
----
+Modules with zero functions are skipped entirely.
 
-## License
+### Token estimation
 
-[Apache-2.0](../../LICENSE)
+Uses a ~4 chars/token approximation. The generator stops adding sections the moment adding the next section would exceed the budget, so the output always fits within the specified window.

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@getmikk/ai-context",
-    "version": "1.7.1",
+    "version": "1.9.0",
     "license": "Apache-2.0",
     "repository": {
         "type": "git",
@@ -21,8 +21,8 @@
         "dev": "tsc --watch"
     },
     "dependencies": {
-        "@getmikk/core": "^1.7.1",
-        "@getmikk/intent-engine": "^1.7.1"
+        "@getmikk/core": "^1.9.0",
+        "@getmikk/intent-engine": "^1.9.0"
     },
     "devDependencies": {
         "typescript": "^5.7.0",