@openez-graph/cli 1.4.0 → 1.6.0

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 (9) hide show
  1. package/README.md +53 -12
  2. package/dist/CHANGELOG.md +35 -0
  3. package/dist/cli.cjs +109647 -2752
  4. package/dist/native/index.darwin-arm64.node +0 -0
  5. package/dist/native/index.js +160 -134
  6. package/dist/native/index.linux-x64-gnu.node +0 -0
  7. package/dist/native/index.win32-x64-msvc.node +0 -0
  8. package/dist/node_modules/@openez-graph/native/package.json +1 -1
  9. package/package.json +4 -1
package/README.md CHANGED
@@ -9,12 +9,12 @@ OpenEZ Graph indexes your codebase into a local SQLite database, builds a code g
9
9
 
10
10
  **Zero config. No Docker. No Postgres. No Redis. Just install and go.**
11
11
 
12
- > **v1.0: Bun-powered, Rust-native parsing.** The CLI now runs exclusively on [Bun](https://bun.sh) 1.1+ with native `bun:sqlite` (no `better-sqlite3` compilation step). TS/JS parsing uses [oxc-parser](https://oxc.rs) (Rust-based, ~13x faster than Babel) instead of `ts-morph`. Python/Go/Rust/Ruby use tree-sitter (WASM) with regex fallback. Requires Bun 1.1+.
12
+ > **v1.0: Bun-powered, Rust-native parsing.** The CLI now runs exclusively on [Bun](https://bun.sh) 1.1+ with native `bun:sqlite` (no `better-sqlite3` compilation step). TS/JS parsing uses [oxc-parser](https://oxc.rs) (Rust-based, ~13x faster than Babel) instead of `ts-morph`. Python/Go/Rust/Ruby/C++/C#/Java use a bundled Rust extension where available (see [Native acceleration](#native-acceleration)), else tree-sitter (WASM); on parse failure Python/Go/Rust/Ruby fall back to regex while C++/C#/Java degrade to generic text chunks. Requires Bun 1.1+.
13
13
 
14
14
  ## Features
15
15
 
16
16
  - **Bun-powered** — native `bun:sqlite` driver, no native compilation, near-instant startup
17
- - **Rust-native parsing** — [oxc-parser](https://oxc.rs) for TS/JS (~13x faster than Babel), tree-sitter (WASM) for Python/Go/Rust/Ruby with regex fallback
17
+ - **Rust-native parsing** — [oxc-parser](https://oxc.rs) for TS/JS (~13x faster than Babel); bundled Rust extension for file scanning and Python/Go/Rust/Ruby/C++/C#/Java parsing on linux-x64, darwin-arm64, and win32-x64, with WASM tree-sitter fallback elsewhere (regex for Python/Go/Rust/Ruby, generic text chunks for C++/C#/Java)
18
18
  - **Zero-config** — auto-registers workspace, auto-indexes; opt-in auto-sync via `OPENEZ_MCP_WATCH=1`
19
19
  - **SQLite-first** — all data stored locally in `.openez/` per workspace, no Postgres/Redis
20
20
  - **FTS5 full-text search** — SQLite FTS5 with BM25 ranking and porter tokenizer
@@ -68,6 +68,7 @@ openez serve --mcp # start MCP server (auto-index; auto-sync opt-in
68
68
  openez serve --web # start web dashboard (default port 17881)
69
69
  openez serve --web --port 8080 # start web dashboard on custom port
70
70
  openez status [path] # show workspace status
71
+ openez diff [ref] # review git diff with affected AST symbols & callers (--staged, --json)
71
72
  openez list # list registered workspaces
72
73
  openez setup claude # wire up Claude Code
73
74
  openez setup codex # wire up Codex
@@ -79,6 +80,23 @@ openez config set <key> <value> # set embedding config value
79
80
  openez config list # list all DB-stored config overrides
80
81
  ```
81
82
 
83
+ ### Diff scopes
84
+
85
+ ```bash
86
+ openez diff # tracked staged + unstaged changes
87
+ git diff HEAD # equivalent Git default: tracked staged + unstaged changes
88
+ openez diff --staged # staged changes only
89
+ openez diff HEAD~1 # diff against the supplied Git ref
90
+ ```
91
+
92
+ For the `diff_context` MCP tool, `path`/`paths` select registered workspace
93
+ roots, not changed files. Untracked files are not included in this Git-diff
94
+ phase. When a blob parser is provided, `diff_context` also returns
95
+ `oldSymbols` and `deletedSymbols` for modified and deleted files. Old source
96
+ is loaded with `git show <rev>:<path>` and parsed in memory — historical blobs
97
+ are never written to the workspace DB. Caller/callee edges for historical
98
+ symbols use the current graph only (a historical graph is not reconstructed).
99
+
82
100
  Valid config keys: `embedding.provider`, `embedding.openai_api_key`, `embedding.openai_base_url`, `embedding.openai_model`, `embedding.ollama_base_url`, `embedding.ollama_model`, `embedding.local_model`. API keys are encrypted at rest with AES-256-GCM.
83
101
 
84
102
  ## MCP Tools
@@ -89,6 +107,7 @@ Valid config keys: `embedding.provider`, `embedding.openai_api_key`, `embedding.
89
107
  | `code_outline` | Inspect file AST structure, functions, classes, and exported symbols with line numbers (~50 tokens) |
90
108
  | `code_query` | Hybrid FTS/vector search + graph expansion over indexed code and docs |
91
109
  | `code_context` | Get budgeted symbol context with callers, callees, and related files (limit: 50/workspace, max 200) |
110
+ | `diff_context` | Analyze git diff changes and retrieve affected AST symbols & caller/callee dependencies |
92
111
  | `graph_neighbors` | Traverse graph edges from a node or label |
93
112
  | `memory_recall` | Recall active memory entries and technical decisions |
94
113
  | `memory_write` | Write a memory entry (notes, decisions, patterns) |
@@ -107,16 +126,38 @@ Valid config keys: `embedding.provider`, `embedding.openai_api_key`, `embedding.
107
126
 
108
127
  ## Supported languages
109
128
 
110
- | Language | Parser | Indexing depth |
111
- | ----------------------------------------------------- | ---------------------------- | ---------------------------------------------------------------------------------------- |
112
- | TypeScript / JavaScript | [oxc-parser](https://oxc.rs) | Richest — symbol extraction, imports, calls (~13x faster than Babel) |
113
- | Python | tree-sitter (WASM) | Symbol extraction, decorators, imports, calls |
114
- | Go | tree-sitter (WASM) | Symbol extraction, receiver-qualified methods, calls |
115
- | Rust | tree-sitter (WASM) | Symbol extraction, impl blocks, calls |
116
- | Ruby | tree-sitter (WASM) | Symbol extraction, `class << self` context, `self.foo` calls, `require_relative` imports |
117
- | CoffeeScript / Slim / CSS / SCSS / SASS / LESS / Haml | Fallback parser | Scanned and chunked (no symbol extraction) |
118
- | YAML / JSON / TOML | Structure-aware | Structure-aware chunking |
119
- | Markdown | Section-oriented | Section-oriented chunking |
129
+ | Language | Parser | Indexing depth |
130
+ | --------------------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
131
+ | TypeScript / JavaScript | [oxc-parser](https://oxc.rs) | Richest — symbol extraction, imports, calls (~13x faster than Babel). Call edges resolve through static ESM imports and CommonJS `require`/`exports` bindings to unique workspace exports; TypeScript additionally resolves `tsconfig` `baseUrl`/`paths` aliases, `.js`→`.ts` substitution, and honors `import type`/`export type` (no call edges). Dynamic imports and external packages produce no call edges |
132
+ | Python | native or tree-sitter (WASM) | Symbol extraction, decorators, imports, calls. Call edges resolve through static bindings only — relative imports and `src/` layouts, aliases and re-exports, enclosing-scope then module-scope lookup, `self`/`cls`/`Class` receivers, and function-local shadowing; unresolved, ambiguous, or external calls produce no edges; no Python symbol/call cap |
133
+ | Go | native or tree-sitter (WASM) | Symbol extraction (functions, methods, types, consts, vars incl. grouped declarations), receiver-qualified methods, package-aware calls resolved through `go.mod` modules and declared package names (unique in-workspace targets only; function-granular shadowing; `vendor/` files text-indexed but excluded from the graph; no Go symbol/call cap) |
134
+ | Rust | native or tree-sitter (WASM) | Symbol extraction, impl blocks, calls. Call edges resolve through Cargo crate roots and module paths — `crate`/`self`/`super` paths, `use` bindings (groups, `self`, `as`, `pub use` re-exports), and the crate's own library name bind to unique in-crate symbols; `Type::f`, `Self::f`, and `self.m()` resolve for statically known types. External crates, glob imports, unknown receivers, shadowed locals, and ambiguous or unresolved paths produce no edge; no Rust symbol/call cap |
135
+ | Ruby | native or tree-sitter (WASM) | Symbol extraction (classes, modules, instance + singleton methods, `class << self`, lambda/proc assignments), scope-aware call edges — `self.foo` and constant receivers (`Invoice.build`, `Billing::Invoice.build`) bind to a unique method of the caller's own or lexically-enclosing class/module (reopened classes included), bare calls bind to the caller's class/module then unique top-level methods; ordinary receivers (`other.tax`, `@client.get`, `user&.name`) and dynamic calls (`send`, `eval`, …) produce no edge; inherited/mixin dispatch is not resolved; `require_relative` resolves literal `.rb` paths only; no Ruby symbol/call cap |
136
+ | C / C++ headers (`.cpp/.cc/.cxx/.c++/.hpp/.hh/.hxx/.h++/.h/.C`) | native or tree-sitter (WASM) | Symbol extraction (namespaces, classes, structs, unions, enums, aliases, functions, methods, constructors/destructors, templates, out-of-line `A::f` definitions, prototypes). Call edges are translation-unit aware: quoted `#include` paths resolve importer-dir → workspace-root → unique suffix (never outside the workspace, cycles safe), declarations and definitions pair by qualified name, and only unique visible targets edge — receiver-variable types, inheritance, overload choice, template specialization, macros, and using-directives are not resolved; angle/system includes produce no edges; a `.h` file with a syntax error gets generic chunks and no graph records; lowercase `.c` is not indexed; no C++ symbol/call cap |
137
+ | C# (`.cs` / `.csx`) | native or tree-sitter (WASM) | Symbol extraction (namespaces, classes, structs, interfaces, records, enums, delegates, fields, properties, methods, constructors, destructors, nested types, partial types merged per project root via nearest `*.csproj`), usings (ordinary/alias/global/static). Call edges resolve through the C# lookup order — enclosing member types, enclosing namespaces innermost→global, then usings + the project root's global usings — to unique targets only: same-type/`this` calls, type-qualified calls, and uniquely bound using-static calls; overloads, variable receivers, inherited members, external names, and cross-root duplicates produce no edge; no C# symbol/call cap. No regex fallback — a missing grammar yields searchable text chunks |
138
+ | Java | native or tree-sitter (WASM) | Symbol extraction (package, classes, interfaces, enums, records, fields, methods, constructors — nested types as `Outer::Inner::m`). Call edges resolve through a package/type/member index only: bare and `this` calls bind to a unique method of the innermost enclosing type, `Type.m()` resolves through enclosing member types, the file's own types, explicit single-type imports, then same-package types, dotted receivers must equal the package-qualified type name, and bare calls may bind a single static import. Variable receivers, overloads, inherited members, wildcards, external imports, and anonymous-class unqualified calls produce no edge; no Java symbol/call cap. No regex fallback — a missing grammar yields searchable text chunks |
139
+ | CoffeeScript / Slim / CSS / SCSS / SASS / LESS / Haml | Fallback parser | Scanned and chunked (no symbol extraction) |
140
+ | YAML / JSON / TOML | Structure-aware | Structure-aware chunking |
141
+ | Markdown | Section-oriented | Section-oriented chunking |
142
+
143
+ ## Native acceleration
144
+
145
+ The CLI bundles a small Rust extension (N-API) that accelerates file scanning
146
+ and Python/Go/Rust/Ruby/C++/C#/Java parsing. It ships prebuilt binaries for **linux-x64 (glibc),
147
+ darwin-arm64, and win32-x64 (MSVC)**.
148
+
149
+ On every other platform — macOS x64, Linux arm64, musl-based Linux (e.g.
150
+ Alpine), Windows arm64 — the CLI automatically uses the fallback path: fast-glob
151
+ scanning plus WASM tree-sitter parsing — on failure, Python/Go/Rust/Ruby fall
152
+ back to regex while C++/C#/Java degrade to generic text chunks. Everything
153
+ works the same, just slower.
154
+
155
+ Set `OPENEZ_NATIVE=0` to force the fallback path even when a native binary is
156
+ present (useful for debugging or comparing output).
157
+
158
+ Native and fallback extraction are not guaranteed to produce byte-identical
159
+ output. The known differences are pinned by the native/WASM parity test suite
160
+ and tracked in [issue #39](https://github.com/asta-nguyen/openez-graph/issues/39).
120
161
 
121
162
  ## Retrieval quality
122
163
 
package/dist/CHANGELOG.md CHANGED
@@ -5,6 +5,38 @@ All notable changes to OpenEZ Graph are documented in this file.
5
5
  The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
6
6
  and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
7
7
 
8
+ ## [1.6.0] - 2026-10-22
9
+
10
+ ### Added
11
+
12
+ - Native Rust parser and file scanner binaries for Linux x64 GNU, macOS arm64, and Windows x64 MSVC, with tree-sitter and regex fallbacks on other platforms.
13
+ - Structured symbol extraction and workspace-aware call resolution for C++, C#, and Java.
14
+ - Binding-aware call graph resolution for TypeScript/JavaScript, Python, Go, Rust, and Ruby.
15
+
16
+ ### Changed
17
+
18
+ - Removed symbol and call graph caps for JavaScript/TypeScript, Python, Go, Rust, and Ruby to retain larger code graphs.
19
+ - Run `openez reindex <path>` after upgrading to rebuild parser rows and graph artifacts for updated language indexers.
20
+
21
+ ### Fixed
22
+
23
+ - Improved language-specific call resolution for imports, re-exports, namespaces, module paths, lexical scopes, and local shadowing; ambiguous and unresolved calls no longer create misleading edges.
24
+ - Reduced memory churn and fitting time for large MCP `diff_context` responses by avoiding tokenizer cache-hit LRU refreshes and batching structured trimming while retaining exact cl100k token budgets.
25
+
26
+ ## [1.5.0] - 2026-08-26
27
+
28
+ ### Added
29
+
30
+ - **CLI and MCP diff context** — `openez diff` and `diff_context` now report affected symbols, callers, callees, historical symbols, and deleted symbols across staged changes and Git refs.
31
+
32
+ ### Changed
33
+
34
+ - **Diff scope and workspace contracts** — supports default tracked staged + unstaged changes, staged-only changes, Git refs/ranges, workspace selectors, structured multi-workspace responses, and token-bounded MCP output.
35
+
36
+ ### Fixed
37
+
38
+ - **Diff correctness and readiness** — normalizes staged hunk coordinates, reads staged symbols from Git index blobs, avoids leaking working-tree dependency context, validates Git refs, preserves deleted-symbol counts, and surfaces structured historical-blob warnings.
39
+
8
40
  ## [1.4.0] - 2026-08-19
9
41
 
10
42
  ### Added
@@ -14,6 +46,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
14
46
 
15
47
  ### Changed
16
48
 
49
+ - **Git diff scope contract** — documented `openez diff` staged/ref behavior, clarified that MCP `path`/`paths` select registered workspace roots, and noted that untracked files are excluded from this Git-diff phase.
17
50
  - **`getFileOutline` path resolution** — uses `path.isAbsolute()` instead of `startsWith("/")` so Windows absolute paths (`C:\foo\bar.ts`) receive the same symlink realpath fallback as Unix absolute paths.
18
51
  - **`getFileOutline` async realpath** — replaced `fs.realpathSync` with `fs.promises.realpath` to avoid blocking the MCP event loop on absolute-path cache misses.
19
52
  - **AGENTS.md MCP Expectations** — `code_outline` classified as a single-workspace tool alongside `memory_write`, `index_workspace`, and `remove_workspace`.
@@ -328,6 +361,8 @@ Remediation release — index/graph correctness, data protection, and web flow f
328
361
  - Error handling and validation for import path extraction
329
362
  - CLI npm packaging
330
363
 
364
+ [1.5.0]: https://github.com/asta-nguyen/openez-graph/compare/v1.4.0...v1.5.0
365
+ [1.6.0]: https://github.com/asta-nguyen/openez-graph/compare/v1.5.0...v1.6.0
331
366
  [1.4.0]: https://github.com/asta-nguyen/openez-graph/compare/v1.3.1...v1.4.0
332
367
  [1.3.1]: https://github.com/asta-nguyen/openez-graph/compare/v1.3.0...v1.3.1
333
368
  [1.2.0]: https://github.com/asta-nguyen/openez-graph/compare/v1.1.0...v1.2.0