milens 0.2.0 → 0.2.1

package/README.md

@@ -3,11 +3,19 @@
   <em>Lightweight Code Intelligence Engine</em>
 </p>
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/milens"><img src="https://img.shields.io/npm/v/milens" alt="npm version"></a>
+  <a href="https://github.com/fuze210699/milens/blob/develop/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue" alt="License: MIT"></a>
+  <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js >= 20"></a>
+</p>
+
 <p align="center">
   <a href="#features">Features</a> •
+  <a href="#installation">Install</a> •
   <a href="#quick-start">Quick Start</a> •
   <a href="#cli-commands">CLI</a> •
   <a href="#mcp-server">MCP Server</a> •
+  <a href="#editor-integration">Editors</a> •
   <a href="#architecture">Architecture</a> •
   <a href="#adding-a-language">Extend</a>
 </p>
@@ -16,41 +24,75 @@
 
 Parse codebases into **knowledge graphs** — symbols, imports, calls, inheritance — and serve them to **AI agents** via the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
 
+```bash
+npx milens analyze          # index any codebase
+npx milens serve            # start MCP server for AI agents
+```
+
 ## Features
 
 - **8 languages** — TypeScript, JavaScript, Python, Java, Go, Rust, PHP, Vue
-- **Declarative grammars** — add a new language by writing a config object, not extraction code
+- **Declarative grammars** — add a new language by writing a config object, not code
+- **10 MCP tools** — query, context, impact, status, detect_changes, explain_relationship, find_dead_code, get_file_symbols, get_type_hierarchy
 - **SQLite + FTS5** — full-text symbol search + recursive CTE graph traversal
-- **Token-compact MCP** — 4 tools with minimal output, saving 40-60% tokens for AI agents
+- **Token-compact output** — minimal structured text, saving 40-60% tokens for AI agents
 - **Incremental indexing** — file-hash based, only re-parses changed files
 - **Multi-repo registry** — manage multiple codebases from `~/.milens/`
 - **Dual transport** — MCP over stdio (VS Code / Cursor) or HTTP (remote agents)
+- **Skills generation** — auto-generate context files for Copilot, Cursor, Claude, and Codex
 
-## Quick Start
+## Installation
 
 ```bash
-# Install dependencies
-npm install
+# Use directly (no install needed)
+npx milens analyze -p .
 
-# Index the current project
-npx tsx src/cli.ts analyze -p . --verbose
+# Or install globally
+npm install -g milens
+```
+
+## Quick Start
+
+```bash
+# Index a codebase
+milens analyze -p /path/to/repo --verbose
 
 # Search for symbols
-npx tsx src/cli.ts search "UserService"
+milens search "UserService"
+
+# 360° symbol context
+milens inspect "AuthService"
+
+# Blast radius — what breaks if this changes?
+milens impact "createUser" --depth 3
+
+# Start MCP server (stdio for editors)
+milens serve -p /path/to/repo
 
-# Start MCP server for AI agents
-npx tsx src/cli.ts serve --http --port 3100
+# Start MCP server (HTTP for remote agents)
+milens serve --http --port 3100
 ```
 
 ## CLI Commands
 
-### `analyze` — Index a codebase
+| Command | Description |
+|---|---|
+| `analyze` | Index a codebase into a knowledge graph |
+| `search` | Full-text symbol search (FTS5) |
+| `inspect` | 360° symbol context — incoming refs + outgoing deps |
+| `impact` | Blast radius analysis via recursive CTE |
+| `serve` | Start MCP server (stdio or HTTP) |
+| `status` | Show index stats |
+| `list` | List all indexed repositories |
+| `clean` | Remove index for a repository |
+
+### `analyze`
 
 ```bash
-milens analyze -p /path/to/repo --verbose --force
+milens analyze -p /path/to/repo --verbose --force --skills
 ```
 
-Scans source files, parses symbols using tree-sitter, resolves imports/calls/inheritance, and stores everything in a local SQLite database at `.milens/milens.db`.
+Scans source files, parses symbols with tree-sitter, resolves imports/calls/inheritance, and stores everything in `.milens/milens.db`.
 
 | Flag | Description |
 |---|---|
@@ -58,81 +100,155 @@ Scans source files, parses symbols using tree-sitter, resolves imports/calls/inh
 | `-o, --output` | Custom output directory for the database |
 | `-v, --verbose` | Show detailed progress |
 | `-f, --force` | Force full re-index (skip hash check) |
+| `-s, --skills` | Generate SKILL.md files for Copilot, Cursor, Claude |
 
-### `search` — Find symbols
+### `search`
 
 ```bash
 milens search "createUser" --limit 10
 ```
 
-Full-text search across all indexed symbol names using FTS5.
-
-### `inspect` — 360° symbol context
+### `inspect`
 
 ```bash
 milens inspect "AuthService"
 ```
 
-Shows a symbol's incoming references (who calls/uses it) and outgoing dependencies (what it calls/imports/extends).
+Shows incoming references (who calls/uses it) and outgoing dependencies (what it calls/imports/extends).
 
-### `impact` — Blast radius analysis
+### `impact`
 
 ```bash
 milens impact "UserModel" --direction upstream --depth 3
 ```
 
-Answers: *"What breaks if this symbol changes?"* Uses recursive CTEs to traverse the dependency graph up to N levels deep.
+*"What breaks if this symbol changes?"* — traverses the dependency graph via recursive CTEs.
 
 | Flag | Description |
 |---|---|
 | `-d, --direction` | `upstream` (default) or `downstream` |
 | `--depth` | Max traversal depth (default: `3`) |
 
-### `status` — Index stats
+### `serve`
 
 ```bash
-milens status -p /path/to/repo
+milens serve -p /path/to/repo              # stdio (for editors)
+milens serve -p /path/to/repo --http --port 3100  # HTTP
 ```
 
-Shows symbol count, link count, file count, and last indexed time.
-
-### `serve` — Start MCP server
+### `list`
 
 ```bash
-# stdio transport (for VS Code / Cursor)
-milens serve -p /path/to/repo
+milens list    # show all indexed repositories
+```
 
-# HTTP transport (for remote agents)
-milens serve -p /path/to/repo --http --port 3100
+### `clean`
+
+```bash
+milens clean -p /path/to/repo    # remove index for one repo
+milens clean --all               # remove all indexes
 ```
 
 ## MCP Server
 
-milens exposes 4 tools via the Model Context Protocol:
+milens exposes **10 tools** via the Model Context Protocol:
 
 | Tool | Description | Key params |
 |---|---|---|
-| `search` | Find symbols by name/keyword (FTS5) | `query`, `limit` |
-| `inspect` | Incoming refs, outgoing deps, hierarchy | `name` |
+| `query` | Search symbols by name/keyword (FTS5) | `query`, `limit` |
+| `context` | 360° symbol view — incoming refs, outgoing deps | `name` |
 | `impact` | Blast radius with depth grouping | `target`, `direction`, `depth` |
 | `status` | Index stats for a repository | `repo` |
+| `detect_changes` | Git diff → affected symbols + dependents | `ref` |
+| `explain_relationship` | Shortest path between two symbols | `from`, `to` |
+| `find_dead_code` | Exported symbols with zero references | `kind`, `limit` |
+| `get_file_symbols` | All symbols in a specific file | `file` |
+| `get_type_hierarchy` | Inheritance/implementation tree | `name` |
 
-### VS Code / Cursor Integration
+> When only one repo is indexed, the `repo` parameter is optional on all tools.
 
-Add to your MCP settings (`mcp.json`):
+### Tool Examples
+
+```
+# Search
+query({query: "auth"})
+→ AuthService [class] src/auth/service.ts:10
+  validateUser [function] src/auth/validate.ts:15
+
+# Context
+context({name: "validateUser"})
+→ incoming:
+    calls: handleLogin (src/api/auth.ts)
+  outgoing:
+    calls: checkPassword (src/auth/hash.ts)
+
+# Impact
+impact({target: "UserService", direction: "upstream"})
+→ depth 1:
+    handleLogin [function] src/api/auth.ts:45 (calls)
+    UserController [class] src/controllers/user.ts:12 (calls)
+  depth 2:
+    authRouter [module] src/routes/auth.ts (imports)
+
+# Detect changes
+detect_changes({ref: "HEAD"})
+→ changed: src/auth/service.ts
+  affected: handleLogin, UserController
+
+# Dead code
+find_dead_code({kind: "function"})
+→ legacyHash [function] src/utils/hash.ts:42 (0 refs)
+```
+
+## Editor Integration
+
+### VS Code / GitHub Copilot
+
+Add to `.vscode/mcp.json`:
 
 ```json
 {
   "servers": {
     "milens": {
       "command": "npx",
-      "args": ["tsx", "/path/to/milens/src/cli.ts", "serve", "-p", "/path/to/repo"]
+      "args": ["-y", "milens", "serve", "-p", "."]
     }
   }
 }
 ```
 
-### HTTP Mode
+### Cursor
+
+Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):
+
+```json
+{
+  "mcpServers": {
+    "milens": {
+      "command": "npx",
+      "args": ["-y", "milens", "serve"]
+    }
+  }
+}
+```
+
+### Claude Code
+
+```bash
+claude mcp add milens -- npx -y milens serve
+```
+
+### Codex
+
+Add to `.codex/config.toml`:
+
+```toml
+[mcp_servers.milens]
+command = "npx"
+args = ["-y", "milens", "serve"]
+```
+
+### HTTP Mode (remote agents)
 
 ```bash
 milens serve --http --port 3100
@@ -140,43 +256,91 @@ milens serve --http --port 3100
 
 Endpoint: `POST http://localhost:3100/mcp`
 
+## Skills Generation
+
+Generate editor-specific context files from your codebase's knowledge graph:
+
+```bash
+milens analyze -p . --skills
+```
+
+This creates:
+
+| Path | For |
+|---|---|
+| `.github/instructions/*.instructions.md` | GitHub Copilot |
+| `.cursor/rules/*.mdc` | Cursor |
+| `.claude/skills/generated/*/SKILL.md` | Claude Code |
+
+Each skill file contains: key symbols, entry points, cross-area dependencies, and file listings — so AI agents get targeted context for the area of code you're working in.
+
 ## Architecture
 
 ```
 src/
-  cli.ts              — CLI entry point (commander)
-  types.ts            — Shared type definitions
+  cli.ts              — CLI entry point (commander, 8 commands)
+  types.ts            — Shared types (CodeSymbol, SymbolLink, etc.)
+  skills.ts           — Skills/context file generator
   parser/
-    loader.ts         — Tree-sitter WASM loading
+    loader.ts         — Tree-sitter WASM loading + caching
     extract.ts        — Universal extractor + LangSpec interface
-    lang-*.ts         — Declarative grammar per language
+    lang-ts.ts        — TypeScript (+ .tsx)
+    lang-js.ts        — JavaScript (+ .jsx, .mjs, .cjs)
+    lang-py.ts        — Python
+    lang-java.ts      — Java
+    lang-go.ts        — Go
+    lang-rust.ts      — Rust
+    lang-php.ts       — PHP
+    lang-vue.ts       — Vue (extracts <script>, delegates to TS)
     languages.ts      — Language registry
   analyzer/
     scanner.ts        — File discovery (.gitignore aware)
     resolver.ts       — Import + call + heritage resolution
-    engine.ts         — Pipeline orchestrator
+    engine.ts         — Pipeline orchestrator (6 phases)
   store/
-    schema.sql        — SQLite schema with FTS5
-    db.ts             — Database adapter with recursive CTE queries
+    schema.sql        — SQLite schema (FTS5, triggers, indexes)
+    db.ts             — Database adapter (30+ methods, recursive CTEs)
     registry.ts       — Multi-repo registry (~/.milens/)
   server/
-    mcp.ts            — MCP server (stdio + HTTP transports)
+    mcp.ts            — MCP server (10 tools, stdio + HTTP)
 ```
 
 ### How It Works
 
-1. **Scan** — Discover source files respecting `.gitignore`
-2. **Parse** — Extract symbols (functions, classes, interfaces, ...) via tree-sitter WASM grammars
-3. **Resolve** — Link imports → symbols, calls → definitions, inheritance chains
-4. **Store** — Write symbols + links to SQLite with FTS5 search index
-5. **Serve** — Expose the knowledge graph via MCP tools or CLI
+```
+Source Files → [Scan] → [Parse] → [Resolve] → [Store] → [Serve]
+                 │         │          │           │          │
+            .gitignore  tree-sitter  imports   SQLite     MCP
+             filter      WASM AST    calls     FTS5      stdio/HTTP
+                                    heritage   CTE
+```
+
+1. **Scan** — Walk file tree respecting `.gitignore`, skip `node_modules`/`dist`/`build`/etc.
+2. **Parse** — Extract symbols (functions, classes, methods, interfaces, enums, structs, traits) via tree-sitter WASM grammars
+3. **Resolve** — Link imports → symbols, calls → definitions, inheritance chains. Confidence-scored.
+4. **Store** — Write symbols + links to SQLite with FTS5 search index in a single transaction
+5. **Serve** — Expose the knowledge graph via 10 MCP tools or CLI commands
 
 ### Design Decisions
 
-- **Declarative `LangSpec`**: Each language is a config object with tree-sitter queries. One universal extractor processes all languages — no per-language extraction code.
-- **SQLite recursive CTE**: Impact analysis traverses the graph inside the database. No need to load the full graph into memory.
-- **Token-compact output**: MCP responses use minimal structured text, not verbose descriptions.
-- **Incremental by default**: File content is hashed; only changed files get re-parsed on subsequent runs.
+- **Declarative `LangSpec`**: Each language is a config object with tree-sitter queries. One universal extractor processes all — no per-language extraction code.
+- **SQLite recursive CTE**: Impact analysis (upstream/downstream) runs entirely in the database. No need to load the full graph into memory.
+- **Token-compact output**: MCP responses use `name [kind] file:line` format. Saves 40-60% tokens for AI agents.
+- **Incremental by default**: File content is SHA-256 hashed; only changed files get re-parsed.
+- **Lazy DB pools**: MCP server opens database connections on demand and evicts them after 5 minutes of inactivity.
+
+## Supported Languages
+
+| Language | Extensions | Symbols | Imports | Calls | Heritage |
+|---|---|---|---|---|---|
+| TypeScript | `.ts`, `.tsx` | functions, classes, methods, interfaces, enums | ✓ | ✓ | ✓ |
+| JavaScript | `.js`, `.jsx`, `.mjs`, `.cjs` | functions, classes, methods | ✓ | ✓ | ✓ |
+| Python | `.py` | functions, classes, methods | ✓ | ✓ | ✓ |
+| Java | `.java` | classes, interfaces, methods, enums | ✓ | ✓ | ✓ |
+| Go | `.go` | functions, methods, structs, interfaces | ✓ | ✓ | — |
+| Rust | `.rs` | functions, structs, enums, traits, methods | ✓ | ✓ | ✓ |
+| PHP | `.php` | functions, classes, interfaces, methods | ✓ | ✓ | ✓ |
+| Vue | `.vue` | (delegates to TypeScript on `<script>` block) | ✓ | ✓ | ✓ |
 
 ## Adding a Language
 
@@ -204,6 +368,17 @@ export default spec;
 
 Then register it in `src/parser/languages.ts`.
 
+## Development
+
+```bash
+npm install            # install dependencies
+npm run build          # tsc → dist/
+npm test               # vitest
+npm run lint           # tsc --noEmit
+npm run self-analyze   # index this repo
+npm run self-serve     # start MCP server on port 3100
+```
+
 ## Requirements
 
 - Node.js >= 20.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "milens",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Lightweight Code Intelligence Platform — analyze codebases and build knowledge graphs",
   "type": "module",
   "bin": {