milens 0.5.0 → 0.5.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +14 -322
  2. package/package.json +1 -1
package/README.md CHANGED
@@ -1,138 +1,7 @@
1
- <p align="center">
2
- <strong>milens</strong><br>
3
- <em>Code Intelligence Engine for AI Agents</em>
4
- </p>
5
-
6
- <p align="center">
7
- <a href="https://www.npmjs.com/package/milens"><img src="https://img.shields.io/npm/v/milens" alt="npm version"></a>
8
- <a href="https://github.com/fuze210699/milens/blob/develop/LICENSE"><img src="https://img.shields.io/badge/license-PolyForm--Noncommercial-blue" alt="License: PolyForm Noncommercial"></a>
9
- <a href="https://nodejs.org"><img src="https://img.shields.io/badge/node-%3E%3D20-brightgreen" alt="Node.js >= 20"></a>
10
- <img src="https://img.shields.io/badge/languages-11-orange" alt="11 Languages">
11
- <img src="https://img.shields.io/badge/MCP_tools-19-purple" alt="19 MCP Tools">
12
- </p>
13
-
14
- <p align="center">
15
- <strong>Index any codebase → Knowledge graph → AI agents that never miss code</strong>
16
- </p>
17
-
18
- <p align="center">
19
- <a href="#the-problem">Why?</a> •
20
- <a href="#quick-start">Quick Start</a> •
21
- <a href="#what-your-ai-agent-gets">Agent Tools</a> •
22
- <a href="#editor-setup">Editors</a> •
23
- <a href="#supported-languages">Languages</a> •
24
- <a href="#architecture">Architecture</a>
25
- </p>
26
-
27
- ---
28
-
29
- ## The Problem
30
-
31
- AI agents are blind to structure. They see files as text, not as a connected graph of dependencies.
32
-
33
- **A real scenario:**
34
-
35
- 1. You ask your agent to refactor `resolveLinks()` in your codebase
36
- 2. The agent searches for `"resolveLinks"` — finds matches in code, tests, comments, and docs
37
- 3. It renames the function, but misses that `resolveLinksWithStats` wraps it and `analyze()` calls the wrapper — a chain invisible to text search
38
- 4. **Your pipeline breaks. The agent didn't know the call graph.**
39
-
40
- The root cause: text search can't distinguish a caller from a comment from a type annotation. It has no concept of "what actually depends on this at the code level."
41
-
42
- ### How milens Solves This
43
-
44
- <p align="center">
45
- <img src="docs/diagram1.svg" alt="Without milens vs With milens comparison" width="700">
46
- </p>
47
-
48
- milens builds a **pre-indexed knowledge graph** at analysis time — resolving every import, call, and inheritance chain — so that any tool query returns the full dependency picture instantly, without multi-step exploration.
49
-
50
- ---
51
-
52
- ## Quick Start
53
-
54
- **2 commands. That's it.**
55
-
56
- ```bash
57
- npx milens analyze # index your codebase
1
+ <div align="center"><h1>milens</h1>Code Intelligence Engine for AI AgentsIndex any codebase → Knowledge graph → AI agents that never miss codeWhy? •Quick Start •Agent Tools •Editors •Languages •Architecture</div>🛑 The ProblemAI agents are blind to structure. They see files as text, not as a connected graph of dependencies.A real scenario:You ask your agent to refactor resolveLinks() in your codebase.The agent searches for "resolveLinks" — finds matches in code, tests, comments, and docs.It renames the function, but misses that resolveLinksWithStats wraps it and analyze() calls the wrapper — a chain invisible to text search.Your pipeline breaks. The agent didn't know the call graph.[!IMPORTANT]The root cause: text search can't distinguish a caller from a comment from a type annotation. It has no concept of "what actually depends on this at the code level."✨ How milens Solves This<p align="center"><img src="docs/diagram1.svg" alt="Without milens vs With milens comparison" width="700"></p>milens builds a pre-indexed knowledge graph at analysis time — resolving every import, call, and inheritance chain — so that any tool query returns the full dependency picture instantly, without multi-step exploration.🚀 Quick Start2 commands. That's it.npx milens analyze # index your codebase
58
2
  npx milens analyze --skills # + generate AI skill files
59
- ```
60
-
61
- Then add the MCP server to your editor ([setup below](#editor-setup)) and your agent immediately gets 19 tools + 4 resources + 3 prompts — with built-in instructions that teach it how to use them.
62
-
63
- > **No config files needed.** milens sends tool usage guidance via the MCP protocol `initialize` response — every connected agent automatically learns the workflows.
64
-
65
- ---
66
-
67
- ## What Your AI Agent Gets
68
-
69
- ### 19 MCP Tools
70
-
71
- | Tool | What It Does |
72
- |---|---|
73
- | **Search & Navigate** | |
74
- | `query` | Symbol search (FTS5 full-text) |
75
- | `grep` | Text search ALL files — templates, SCSS, configs, docs. Scoped: `all`, `code`, `imports`, `definitions` |
76
- | `context` | 360° symbol view — incoming refs + outgoing deps |
77
- | `get_file_symbols` | All symbols in a file with ref/dep counts |
78
- | `get_type_hierarchy` | Inheritance/implementation tree |
79
- | **Impact & Safety** | |
80
- | `impact` | Blast radius: what breaks if this changes? Depth-grouped |
81
- | `edit_check` | Pre-edit safety: callers + exports + re-export chains + test coverage + ⚠ warnings |
82
- | `detect_changes` | `git diff` → affected symbols + direct dependents |
83
- | `find_dead_code` | Exported symbols with zero references |
84
- | **Understanding** | |
85
- | `smart_context` | Intent-aware context: `understand` / `edit` / `debug` / `test` — returns only what matters |
86
- | `trace` | Execution flow: call chains from entrypoints to a target (or downstream) |
87
- | `routes` | Detect framework routes/endpoints (Express, FastAPI, NestJS, Flask, Go, PHP, Rails) |
88
- | `explain_relationship` | Shortest dependency path between two symbols |
89
- | **Codebase Overview** | |
90
- | `overview` | Combined context + impact + grep in ONE call (saves 2-3 round trips) |
91
- | `domains` | Domain clusters — groups of files forming logical modules |
92
- | `repos` | List all indexed repositories with summary stats |
93
- | `status` | Index stats, domains, test coverage, staleness |
94
-
95
- ### 4 MCP Resources
96
-
97
- | Resource | What It Returns |
98
- |---|---|
99
- | `milens://overview` | Index overview: stats, domains, coverage, staleness |
100
- | `milens://symbol/{name}` | Symbol definition + relationships |
101
- | `milens://file/{path}` | All symbols in a file |
102
- | `milens://domain/{name}` | Domain cluster details |
103
-
104
- ### 3 Guided Prompts
105
-
106
- | Prompt | Workflow |
107
- |---|---|
108
- | `delete-feature` | grep → impact → context → full deletion plan |
109
- | `refactor-symbol` | context → impact → grep → hierarchy → every file to update |
110
- | `explore-symbol` | query → context → impact (both directions) → grep → summary |
111
-
112
- ### Built-in Agent Instructions
113
-
114
- The MCP server sends **tool usage guidance** on every `initialize` — agents automatically learn:
115
-
116
- - When to combine `impact` + `grep` (code deps + text references)
117
- - Pre-edit workflow (`edit_check` or `smart_context intent=edit`)
118
- - `query` for code identifiers vs `grep` for display text
119
- - Impact depth meaning: 1 = WILL BREAK, 2 = LIKELY AFFECTED, 3 = MAY NEED TESTING
120
- - ⚠ unresolved markers vs ✓ external (expected) classification
121
-
122
- ---
123
-
124
- ## Editor Setup
125
-
126
- ### VS Code / GitHub Copilot (recommended)
127
-
128
- ```bash
129
- npx milens analyze -p . # index your repo (run once)
130
- ```
131
-
132
- Add to `.vscode/mcp.json`:
133
-
134
- ```json
135
- {
3
+ Then add the MCP server to your editor (setup below) and your agent immediately gets 19 tools, 4 resources, and 3 prompts — with built-in instructions that teach it how to use them.[!NOTE]No config files needed. milens sends tool usage guidance via the MCP protocol initialize response — every connected agent automatically learns the workflows.🛠️ What Your AI Agent Gets19 MCP ToolsToolWhat It Does🔍 Search & NavigatequerySymbol search (FTS5 full-text)grepText search ALL files — templates, SCSS, configs, docs. Scoped: all, code, imports, definitionscontext360° symbol view — incoming refs + outgoing depsget_file_symbolsAll symbols in a file with ref/dep countsget_type_hierarchyInheritance/implementation tree🛡️ Impact & SafetyimpactBlast radius: what breaks if this changes? Depth-groupededit_checkPre-edit safety: callers + exports + re-export chains + test coverage + ⚠ warningsdetect_changesgit diff → affected symbols + direct dependentsfind_dead_codeExported symbols with zero references🧠 Understandingsmart_contextIntent-aware context: understand / edit / debug / test — returns only what matterstraceExecution flow: call chains from entrypoints to a target (or downstream)routesDetect framework routes/endpoints (Express, FastAPI, NestJS, Flask, Go, PHP, Rails)explain_relationshipShortest dependency path between two symbols📊 Codebase OverviewoverviewCombined context + impact + grep in ONE call (saves 2-3 round trips)domainsDomain clusters — groups of files forming logical modulesreposList all indexed repositories with summary statsstatusIndex stats, domains, test coverage, staleness4 MCP ResourcesResourceWhat It Returns📈 milens://overviewIndex overview: stats, domains, coverage, staleness🧩 milens://symbol/{name}Symbol definition + relationships📄 milens://file/{path}All symbols in a file🗂️ milens://domain/{name}Domain cluster details3 Guided PromptsPromptWorkflow🗑️ delete-featuregrep → impact → context → full deletion plan🏗️ refactor-symbolcontext → impact → grep → hierarchy → every file to update🧭 explore-symbolquery → context → impact (both directions) → grep → summary💻 Editor SetupVS Code / GitHub Copilot (Recommended)First, run the indexer once:npx milens analyze -p .
4
+ Then, add this to .vscode/mcp.json:{
136
5
  "servers": {
137
6
  "milens": {
138
7
  "type": "stdio",
@@ -141,19 +10,7 @@ Add to `.vscode/mcp.json`:
141
10
  }
142
11
  }
143
12
  }
144
- ```
145
-
146
- **Done.** Copilot now has access to 19 code intelligence tools.
147
-
148
- <details>
149
- <summary><strong>Other Editors</strong></summary>
150
-
151
- #### Cursor
152
-
153
- Add to `.cursor/mcp.json`:
154
-
155
- ```json
156
- {
13
+ Done. Copilot now has access to 19 code intelligence tools.<details><summary><strong>👉 Show setup for other editors (Cursor, Claude Code, Windsurf, etc.)</strong></summary>CursorAdd to .cursor/mcp.json:{
157
14
  "mcpServers": {
158
15
  "milens": {
159
16
  "command": "npx",
@@ -161,20 +18,8 @@ Add to `.cursor/mcp.json`:
161
18
  }
162
19
  }
163
20
  }
164
- ```
165
-
166
- #### Claude Code
167
-
168
- ```bash
169
- claude mcp add milens -- npx -y milens serve -p .
170
- ```
171
-
172
- #### Windsurf
173
-
174
- Add to `~/.codeium/windsurf/mcp_config.json`:
175
-
176
- ```json
177
- {
21
+ Claude Codeclaude mcp add milens -- npx -y milens serve -p .
22
+ WindsurfAdd to ~/.codeium/windsurf/mcp_config.json:{
178
23
  "mcpServers": {
179
24
  "milens": {
180
25
  "command": "npx",
@@ -182,61 +27,17 @@ Add to `~/.codeium/windsurf/mcp_config.json`:
182
27
  }
183
28
  }
184
29
  }
185
- ```
186
-
187
- #### Codex
188
-
189
- Add to `.codex/config.toml`:
190
-
191
- ```toml
192
- [mcp_servers.milens]
30
+ CodexAdd to .codex/config.toml:[mcp_servers.milens]
193
31
  command = "npx"
194
32
  args = ["-y", "milens", "serve", "-p", "."]
195
- ```
196
-
197
- #### HTTP Mode (remote agents)
198
-
199
- ```bash
200
- npx milens serve --http --port 3100 # localhost only, no auth needed
201
- ```
202
-
203
- Endpoint: `POST http://localhost:3100/mcp`
204
-
205
- </details>
206
-
207
- ---
208
-
209
- ## Skills Generation
210
-
211
- Generate editor-specific context files from your knowledge graph:
212
-
213
- ```bash
214
- npx milens analyze -p . --skills # all editors at once
33
+ HTTP Mode (Remote Agents)npx milens serve --http --port 3100 # localhost only, no auth needed
34
+ Endpoint: POST http://localhost:3100/mcp</details>🧠 Skills GenerationGenerate editor-specific context files from your knowledge graph:npx milens analyze -p . --skills # all editors at once
215
35
  npx milens analyze -p . --skills-copilot # GitHub Copilot only
216
36
  npx milens analyze -p . --skills-cursor # Cursor only
217
37
  npx milens analyze -p . --skills-claude # Claude Code only
218
38
  npx milens analyze -p . --skills-agents # AGENTS.md only
219
39
  npx milens analyze -p . --skills-windsurf # Windsurf only
220
- ```
221
-
222
- This generates per-area skill files with: key symbols, entry points, cross-area dependencies, and **MCP tool usage instructions** — so agents know both the codebase structure and how to use milens tools.
223
-
224
- | Output Path | Editor |
225
- |---|---|
226
- | `.github/instructions/*.instructions.md` + `.github/copilot-instructions.md` | GitHub Copilot |
227
- | `.cursor/rules/*.mdc` + `.cursor/index.mdc` | Cursor |
228
- | `.claude/skills/generated/*/SKILL.md` + `.claude/rules/*.md` + `CLAUDE.md` | Claude Code |
229
- | `.agents/skills/*/SKILL.md` + `AGENTS.md` | 40+ agents |
230
- | `.windsurfrules` | Windsurf |
231
-
232
- > Root config files use `<!-- milens:start/end -->` markers for **idempotent injection** — re-running replaces the milens section without overwriting your custom content.
233
-
234
- ---
235
-
236
- ## CLI Commands
237
-
238
- ```bash
239
- # ── Index & Explore ──
40
+ This generates per-area skill files with: key symbols, entry points, cross-area dependencies, and MCP tool usage instructions — so agents know both the codebase structure and how to use milens tools.EditorOutput PathGitHub Copilot.github/instructions/*.instructions.md + .github/copilot-instructions.mdCursor.cursor/rules/*.mdc + .cursor/index.mdcClaude Code.claude/skills/generated/*/SKILL.md + .claude/rules/*.md + CLAUDE.mdGeneral Agents.agents/skills/*/SKILL.md + AGENTS.mdWindsurf.windsurfrules[!TIP]Root config files use <!-- milens:start/end --> markers for idempotent injection — re-running replaces the milens section without overwriting your custom content.⌨️ CLI Commands# ── Index & Explore ──
240
41
  npx milens analyze -p . # index current directory
241
42
  npx milens analyze -p . --force --verbose # full re-index with progress
242
43
  npx milens search "UserService" # search symbols (FTS5)
@@ -259,80 +60,7 @@ npx milens clean --all # remove all indexes
259
60
  # ── Dashboard ──
260
61
  npx milens dashboard # usage analytics on port 3200
261
62
  npx milens dashboard --port 8080 # custom port
262
- ```
263
-
264
- ---
265
-
266
- ## Supported Languages
267
-
268
- | Language | Extensions | Imports | Calls | Heritage | Frameworks |
269
- |---|---|---|---|---|---|
270
- | TypeScript | `.ts` `.tsx` | ✓ ESM + require | ✓ + decorators | ✓ extends/implements | NestJS, React JSX |
271
- | JavaScript | `.js` `.jsx` `.mjs` `.cjs` | ✓ ESM + require | ✓ | ✓ | React JSX, Express |
272
- | Python | `.py` | ✓ | ✓ + decorators | ✓ | FastAPI, Flask |
273
- | Java | `.java` | ✓ + static | ✓ + annotations, new | ✓ | Spring |
274
- | Go | `.go` | ✓ | ✓ | — | net/http |
275
- | Rust | `.rs` | ✓ | ✓ + macros | ✓ | — |
276
- | PHP | `.php` | ✓ + include | ✓ + static, new | ✓ + traits | Laravel |
277
- | Ruby | `.rb` | ✓ | ✓ | ✓ | Rails |
278
- | Vue | `.vue` | ✓ | ✓ template refs | ✓ | Vue 3 SFC |
279
- | HTML | `.html` `.htm` | ✓ `<script src>` `<link>` | ✓ inline `<script>` | — | — |
280
- | CSS | `.css` | ✓ `@import` | — | — | Custom properties |
281
-
282
- ---
283
-
284
- ## Architecture
285
-
286
- <p align="center">
287
- <img src="docs/diagram2.svg" alt="milens architecture: Indexing Pipeline → MCP Server → AI Agent" width="700">
288
- </p>
289
-
290
- ### Multi-Repo Architecture
291
-
292
- milens uses a **global registry** — one MCP server serves all indexed repos. No per-project server config needed.
293
-
294
- <p align="center">
295
- <img src="docs/diagram3.svg" alt="Multi-repo architecture: CLI → Registry → Per-Repo DBs → MCP Server" width="500">
296
- </p>
297
-
298
- > With a single indexed repo, all tools work without specifying `repo`. When multiple repos are registered, pass `repo` to target a specific one.
299
-
300
- ### Design Decisions
301
-
302
- | Decision | Rationale |
303
- |---|---|
304
- | **Declarative LangSpec** | Each language = 1 config object with tree-sitter queries. One universal extractor for all 11 languages |
305
- | **SQLite + recursive CTE** | Impact analysis runs entirely in the database — no full graph in memory |
306
- | **Token-compact output** | `name [kind] file:line` format — saves 40-60% tokens for AI |
307
- | **Incremental by hash** | SHA-256 file hashing — only changed files get re-parsed |
308
- | **Union-Find domains** | Graph-based clustering (files with ≥2 mutual links = same domain) — smarter than directory-based |
309
- | **External-aware resolution** | Separates internal unresolved (⚠ data quality) from external packages (✓ expected) |
310
- | **Lazy DB pools** | Connections opened on demand, evicted after 5min idle |
311
- | **Localhost-only HTTP** | Binds `127.0.0.1` — no network exposure without explicit intent |
312
-
313
- ---
314
-
315
- ## Security & Privacy
316
-
317
- milens is **offline by design** — zero network calls, zero telemetry. Everything executes on your machine.
318
-
319
- | Layer | Protection |
320
- |---|---|
321
- | **Data locality** | Index lives in `.milens/` per repo (gitignored). Global registry (`~/.milens/`) stores only file paths — no source code |
322
- | **HTTP transport** | Binds to `127.0.0.1` only — requires explicit `--http` flag, never auto-exposed |
323
- | **User-supplied regex** | Validated against ReDoS patterns before execution |
324
- | **FTS5 queries** | Each search token quoted as a literal — no query injection |
325
- | **File access** | All reads bounded to the repo root — no path traversal |
326
- | **Git integration** | Uses `execFileSync` with argument arrays — no shell interpolation |
327
-
328
- ---
329
-
330
- ## Tool Examples
331
-
332
- These examples are from **milens indexing itself** (`npx milens analyze -p .`):
333
-
334
- ```
335
- # Pre-edit safety check — real output from milens self-index
63
+ 🌍 Supported LanguagesLanguageExtensionsImportsCallsHeritageFrameworksTypeScript.ts .tsx✓✓✓NestJS, React JSXJavaScript.js .jsx .mjs .cjs✓✓✓React JSX, ExpressPython.py✓✓✓FastAPI, FlaskJava.java✓✓✓SpringGo.go✓✓—net/httpRust.rs✓✓✓—PHP.php✓✓✓LaravelRuby.rb✓✓✓RailsVue.vue✓✓✓Vue 3 SFCHTML.html .htm✓✓——CSS.css✓——Custom properties🏗️ Architecture<p align="center"><img src="docs/diagram2.svg" alt="milens architecture: Indexing Pipeline → MCP Server → AI Agent" width="700"></p>Multi-Repo Architecturemilens uses a global registry — one MCP server serves all indexed repos. No per-project server config needed.<p align="center"><img src="docs/diagram3.svg" alt="Multi-repo architecture: CLI → Registry → Per-Repo DBs → MCP Server" width="500"></p>Security & Privacymilens is offline by design — zero network calls, zero telemetry. Everything executes on your machine.LayerProtectionData localityIndex lives in .milens/ per repo (gitignored). Global registry (~/.milens/) stores only file paths — no source code.HTTP transportBinds to 127.0.0.1 only — requires explicit --http flag, never auto-exposed.File accessAll reads bounded to the repo root — no path traversal.🔍 Tool ExamplesThese examples are from milens indexing itself (npx milens analyze -p .):# Pre-edit safety check — real output from milens self-index
336
64
  edit_check({name: "createMcpServer"})
337
65
  → createMcpServer [function] src/server/mcp.ts:272 {utility,heat:70} (exported)
338
66
  callers (2):
@@ -360,26 +88,7 @@ impact({target: "searchSymbols", direction: "upstream"})
360
88
  depth 2:
361
89
  startStdio [function] src/server/mcp.ts:1475 (calls)
362
90
  startHttp [function] src/server/mcp.ts:1483 (calls)
363
-
364
- # File symbols — what's inside a file?
365
- get_file_symbols({file: "src/store/db.ts"})
366
- → src/store/db.ts: 45 symbols
367
- Database [class] L10-461 (exported) ← 0 refs, → 0 deps
368
- searchSymbols [method] L150-165 ← 3 refs, → 0 deps
369
- findUpstream [method] L192-195 ← 3 refs, → 1 deps
370
- traceToEntrypoints [method] L346-388 ← 2 refs, → 2 deps
371
- getDomainStats [method] L406-417 ← 3 refs, → 0 deps
372
- ... (40 more)
373
- ```
374
-
375
- ---
376
-
377
- ## Adding a Language
378
-
379
- Create `src/parser/lang-xxx.ts`:
380
-
381
- ```typescript
382
- import type { LangSpec } from './extract.js';
91
+ 🤝 Adding a LanguageCreate src/parser/lang-xxx.ts:import type { LangSpec } from './extract.js';
383
92
 
384
93
  const spec: LangSpec = {
385
94
  id: 'xxx',
@@ -395,28 +104,11 @@ const spec: LangSpec = {
395
104
  };
396
105
 
397
106
  export default spec;
398
- ```
399
-
400
- Then register it in `src/parser/languages.ts`.
401
-
402
- ---
403
-
404
- ## Development
405
-
406
- ```bash
407
- npm install # install dependencies
107
+ Then register it in src/parser/languages.ts.💻 Developmentnpm install # install dependencies
408
108
  npm run build # tsc → dist/
409
109
  npm test # vitest (43 tests)
410
110
  npm run lint # tsc --noEmit
411
111
  npm run self-analyze # index this repo
412
112
  npm run self-serve # start MCP server on port 3100
413
113
  npx milens dashboard # open usage analytics dashboard
414
- ```
415
-
416
- ---
417
-
418
- ## License
419
-
420
- [PolyForm Noncommercial 1.0.0](LICENSE)
421
-
422
- Architectural inspiration from [GitNexus](https://github.com/abhigyanpatwari/GitNexus) by Abhigyan Patwari.
114
+ 📜 LicensePolyForm Noncommercial 1.0.0Architectural inspiration from GitNexus by Abhigyan Patwari.
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "milens",
3
- "version": "0.5.0",
3
+ "version": "0.5.1",
4
4
  "description": "Lightweight Code Intelligence Platform — analyze codebases and build knowledge graphs",
5
5
  "type": "module",
6
6
  "bin": {