@openez-graph/cli 1.3.1 → 1.5.0

package/README.md

@@ -19,7 +19,7 @@ OpenEZ Graph indexes your codebase into a local SQLite database, builds a code g
 - **SQLite-first** — all data stored locally in `.openez/` per workspace, no Postgres/Redis
 - **FTS5 full-text search** — SQLite FTS5 with BM25 ranking and porter tokenizer
 - **Vector search** — optional OpenAI/Ollama/local embeddings with cosine similarity
-- **MCP-first** — exposes `code_query`, `code_context`, `graph_neighbors`, `memory_recall`, `memory_write`, `index_workspace`, `list_workspaces` tools
+- **MCP-first** — exposes `code_query`, `code_outline`, `code_context`, `graph_neighbors`, `memory_recall`, `memory_write`, `index_workspace`, `list_workspaces` tools
 - **Multi-workspace** — register and query across multiple codebases
 - **Code graph** — symbols, files, chunks, and edges (calls, imports, contains)
 - **Web dashboard** — built-in graph explorer and workspace management UI
@@ -68,6 +68,7 @@ openez serve --mcp              # start MCP server (auto-index; auto-sync opt-in
 openez serve --web              # start web dashboard (default port 17881)
 openez serve --web --port 8080  # start web dashboard on custom port
 openez status [path]            # show workspace status
+openez diff [ref]               # review git diff with affected AST symbols & callers (--staged, --json)
 openez list                     # list registered workspaces
 openez setup claude             # wire up Claude Code
 openez setup codex              # wire up Codex
@@ -79,6 +80,23 @@ openez config set <key> <value> # set embedding config value
 openez config list              # list all DB-stored config overrides
 ```
 
+### Diff scopes
+
+```bash
+openez diff          # tracked staged + unstaged changes
+git diff HEAD        # equivalent Git default: tracked staged + unstaged changes
+openez diff --staged # staged changes only
+openez diff HEAD~1   # diff against the supplied Git ref
+```
+
+For the `diff_context` MCP tool, `path`/`paths` select registered workspace
+roots, not changed files. Untracked files are not included in this Git-diff
+phase. When a blob parser is provided, `diff_context` also returns
+`oldSymbols` and `deletedSymbols` for modified and deleted files. Old source
+is loaded with `git show <rev>:<path>` and parsed in memory — historical blobs
+are never written to the workspace DB. Caller/callee edges for historical
+symbols use the current graph only (a historical graph is not reconstructed).
+
 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.
 
 ## MCP Tools
@@ -86,8 +104,10 @@ Valid config keys: `embedding.provider`, `embedding.openai_api_key`, `embedding.
 | Tool              | Description                                                                                         |
 | ----------------- | --------------------------------------------------------------------------------------------------- |
 | `list_workspaces` | List all registered workspaces                                                                      |
+| `code_outline`    | Inspect file AST structure, functions, classes, and exported symbols with line numbers (~50 tokens) |
 | `code_query`      | Hybrid FTS/vector search + graph expansion over indexed code and docs                               |
 | `code_context`    | Get budgeted symbol context with callers, callees, and related files (limit: 50/workspace, max 200) |
+| `diff_context`    | Analyze git diff changes and retrieve affected AST symbols & caller/callee dependencies             |
 | `graph_neighbors` | Traverse graph edges from a node or label                                                           |
 | `memory_recall`   | Recall active memory entries and technical decisions                                                |
 | `memory_write`    | Write a memory entry (notes, decisions, patterns)                                                   |

package/dist/CHANGELOG.md

@@ -5,6 +5,42 @@ All notable changes to OpenEZ Graph are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.5.0] - 2026-08-26
+
+### Added
+
+- **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.
+
+### Changed
+
+- **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.
+
+### Fixed
+
+- **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.
+
+## [1.4.0] - 2026-08-19
+
+### Added
+
+- **`code_outline` MCP tool** — retrieves a compact AST symbol hierarchy (functions, classes, methods, types) with line numbers and export flags for a single file, reducing token consumption by ~95% compared to full file reads. Supports TypeScript (oxc-parser), Python/Go/Rust/Ruby (tree-sitter), and fallback section chunking for Markdown/YAML/JSON/TOML. Resolves files by relative path, absolute path, dot-slash prefix, or unambiguous suffix match.
+- **`code_outline` in agent setup instructions** — `openez setup codex/claude/opencode/windsurf/devin` now injects guidance to use `code_outline` before reading full files.
+
+### Changed
+
+- **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.
+- **`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.
+- **`getFileOutline` async realpath** — replaced `fs.realpathSync` with `fs.promises.realpath` to avoid blocking the MCP event loop on absolute-path cache misses.
+- **AGENTS.md MCP Expectations** — `code_outline` classified as a single-workspace tool alongside `memory_write`, `index_workspace`, and `remove_workspace`.
+
+### Fixed
+
+- **Umami analytics ID** — reverted an unrelated `data-website-id` change introduced by the `code_outline` branch; main's Umami PRs (#27, #31) take precedence at merge time.
+- **`getFileOutline` suffix disambiguation** — returns `null` when multiple files share the same basename suffix, preventing ambiguous outline lookups.
+- **`getFileOutline` LIKE wildcard safety** — escapes `%` and `_` in suffix queries so wildcard characters in filenames don't cause false matches.
+- **`outlineText` size formatting** — uses `String(sizeBytes)` instead of `toLocaleString()` to avoid locale-dependent formatting in the outline header.
+- **Indexer `normalizeRelativePath`** — normalizes paths on document insert so Windows backslash paths are stored consistently.
+
 ## [1.3.1] - 2026-08-16
 
 ### Fixed
@@ -307,6 +343,8 @@ Remediation release — index/graph correctness, data protection, and web flow f
 - Error handling and validation for import path extraction
 - CLI npm packaging
 
+[1.5.0]: https://github.com/asta-nguyen/openez-graph/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/asta-nguyen/openez-graph/compare/v1.3.1...v1.4.0
 [1.3.1]: https://github.com/asta-nguyen/openez-graph/compare/v1.3.0...v1.3.1
 [1.2.0]: https://github.com/asta-nguyen/openez-graph/compare/v1.1.0...v1.2.0
 [1.3.0]: https://github.com/asta-nguyen/openez-graph/compare/v1.2.0...v1.3.0