local-codebase-indexer 0.5.0__tar.gz → 0.7.0__tar.gz

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 (87) hide show
  1. local_codebase_indexer-0.7.0/.claude-plugin/marketplace.json +14 -0
  2. local_codebase_indexer-0.7.0/AGENTS.md +75 -0
  3. local_codebase_indexer-0.7.0/CHANGELOG.md +42 -0
  4. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/CLAUDE.md +9 -0
  5. local_codebase_indexer-0.7.0/MANIFEST.in +10 -0
  6. {local_codebase_indexer-0.5.0/local_codebase_indexer.egg-info → local_codebase_indexer-0.7.0}/PKG-INFO +94 -4
  7. local_codebase_indexer-0.7.0/README.md +186 -0
  8. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/README.zh-CN.md +34 -2
  9. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/README.zh-TW.md +51 -2
  10. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/TODO.md +4 -1
  11. local_codebase_indexer-0.7.0/benchmarks/queries_project.json +21 -0
  12. local_codebase_indexer-0.7.0/bin/indexer +11 -0
  13. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/__init__.py +1 -1
  14. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/cli.py +80 -10
  15. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/core.py +29 -2
  16. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/dataflow.py +8 -8
  17. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/db.py +34 -7
  18. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/embedder.py +45 -2
  19. local_codebase_indexer-0.7.0/local_codebase_indexer/evaluation.py +149 -0
  20. local_codebase_indexer-0.7.0/local_codebase_indexer/impact.py +206 -0
  21. local_codebase_indexer-0.7.0/local_codebase_indexer/locking.py +74 -0
  22. local_codebase_indexer-0.7.0/local_codebase_indexer/mcp_server.py +199 -0
  23. local_codebase_indexer-0.7.0/local_codebase_indexer/pagination.py +37 -0
  24. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/query.py +289 -130
  25. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/scanner.py +88 -10
  26. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/synonyms.py +68 -10
  27. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0/local_codebase_indexer.egg-info}/PKG-INFO +94 -4
  28. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer.egg-info/SOURCES.txt +16 -1
  29. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer.egg-info/requires.txt +1 -1
  30. local_codebase_indexer-0.7.0/plugins/local-codebase-indexer/.claude-plugin/plugin.json +8 -0
  31. local_codebase_indexer-0.7.0/plugins/local-codebase-indexer/.mcp.json +8 -0
  32. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/pyproject.toml +1 -1
  33. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/requirements.txt +1 -1
  34. local_codebase_indexer-0.7.0/scripts/release_assets.py +133 -0
  35. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/server.json +2 -2
  36. local_codebase_indexer-0.7.0/tests/test_evaluation.py +88 -0
  37. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/tests/test_indexer.py +6 -1
  38. local_codebase_indexer-0.7.0/tests/test_navigation_stability.py +256 -0
  39. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/tests/test_onnx_plumbing.py +59 -0
  40. local_codebase_indexer-0.7.0/tests/test_release_assets.py +94 -0
  41. local_codebase_indexer-0.7.0/tests/test_reliability.py +265 -0
  42. local_codebase_indexer-0.5.0/AGENTS.md +0 -49
  43. local_codebase_indexer-0.5.0/MANIFEST.in +0 -5
  44. local_codebase_indexer-0.5.0/README.md +0 -96
  45. local_codebase_indexer-0.5.0/local_codebase_indexer/mcp_server.py +0 -152
  46. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/README.md +0 -0
  47. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/baseline.json +0 -0
  48. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Auth/LoginService.cs +0 -0
  49. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Controllers/LotController.cs +0 -0
  50. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Controllers/ScrapController.cs +0 -0
  51. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Data/MesDbContext.cs +0 -0
  52. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Legacy/frmChangeLine.frm +0 -0
  53. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Models/DrillBreakEvent.cs +0 -0
  54. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Models/Lot.cs +0 -0
  55. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Models/ScrapRecord.cs +0 -0
  56. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Printing/LabelPrinter.cs +0 -0
  57. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Repositories/LotRepository.cs +0 -0
  58. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Repositories/ScrapRepository.cs +0 -0
  59. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Services/IScrapService.cs +0 -0
  60. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Services/InspectionService.cs +0 -0
  61. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Services/LotService.cs +0 -0
  62. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Services/ScrapService.cs +0 -0
  63. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Sql/MES_Lot.sql +0 -0
  64. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Sql/usp_Inspection_Report.sql +0 -0
  65. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Sql/usp_Lot_UpdateStatus.sql +0 -0
  66. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Sql/usp_Scrap_Insert.sql +0 -0
  67. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Utils/DateRangeHelper.cs +0 -0
  68. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Utils/PartNumberDecoder.cs +0 -0
  69. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Web/scrapForm.ts +0 -0
  70. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/Web.config +0 -0
  71. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/corpus/tools/export_report.py +0 -0
  72. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/queries_stdlib.json +0 -0
  73. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/queries_synthetic.json +0 -0
  74. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/benchmarks/run_benchmark.py +0 -0
  75. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/index.md +0 -0
  76. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/llms.txt +0 -0
  77. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/__main__.py +0 -0
  78. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/callgraph.py +0 -0
  79. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/cscalls.py +0 -0
  80. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/csdata.py +0 -0
  81. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/langparse.py +0 -0
  82. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer/sqlaccess.py +0 -0
  83. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer.egg-info/dependency_links.txt +0 -0
  84. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer.egg-info/entry_points.txt +0 -0
  85. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/local_codebase_indexer.egg-info/top_level.txt +0 -0
  86. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/setup.cfg +0 -0
  87. {local_codebase_indexer-0.5.0 → local_codebase_indexer-0.7.0}/tests/test_dataaccess.py +0 -0
@@ -0,0 +1,14 @@
1
+ {
2
+ "name": "local-codebase-indexer",
3
+ "description": "Local code index for AI coding assistants: search, call relations and SQL table/procedure access",
4
+ "owner": {
5
+ "name": "sfy257000"
6
+ },
7
+ "plugins": [
8
+ {
9
+ "name": "local-codebase-indexer",
10
+ "source": "./plugins/local-codebase-indexer",
11
+ "description": "MCP server that indexes your project locally (SQLite, no cloud) for code search, callers and SQL data access"
12
+ }
13
+ ]
14
+ }
@@ -0,0 +1,75 @@
1
+ # Instructions for AI coding assistants
2
+
3
+ This repository is **local-codebase-indexer**: a local code index (SQLite, no cloud) that you can use as an MCP server or CLI to find code, callers, and SQL table/stored-procedure access with far fewer tokens than reading files.
4
+
5
+ ## Install (pick one)
6
+
7
+ ```bash
8
+ pip install local-codebase-indexer # from PyPI (Python 3.10+)
9
+ pipx install local-codebase-indexer # isolated
10
+ pip install "git+https://github.com/sfy257000/local-codebase-indexer.git" # latest from GitHub
11
+ ```
12
+
13
+ Check: `local-codebase-indexer --help`. No API keys or network access are needed after installation.
14
+
15
+ ## Use it on a project
16
+
17
+ ```bash
18
+ local-codebase-indexer --root <project> index # build / refresh the index
19
+ local-codebase-indexer --root <project> search "natural language or identifier" --limit 5
20
+ local-codebase-indexer --root <project> relations <SymbolName> --direction both
21
+ local-codebase-indexer --root <project> data-access <TableOrProcedure> # who reads / writes / executes it, which programs and pages reach it
22
+ local-codebase-indexer --root <project> impact [base] # what a diff touches: symbols, tables, programs, pages
23
+ local-codebase-indexer --root <project> context <file> --lines 120 --padding 15
24
+ local-codebase-indexer --root <project> status # is the index fresh?
25
+ ```
26
+
27
+ Put `--json` before or after the subcommand for JSON output. The index lives in `<project>/.ai_context/` (git-ignored automatically).
28
+
29
+ ## Install as a Claude Code plugin
30
+
31
+ ```text
32
+ /plugin marketplace add sfy257000/local-codebase-indexer
33
+ /plugin install local-codebase-indexer@local-codebase-indexer
34
+ ```
35
+
36
+ Needs `uv` (`pip install uv`). Then restart Claude Code.
37
+
38
+ ## Register as an MCP server (Claude Code)
39
+
40
+ ```bash
41
+ claude mcp add local-indexer -- local-codebase-indexer --root <project> serve
42
+ ```
43
+
44
+ Tools: `codebase_semantic_search`, `codebase_get_symbol_relations`, `codebase_get_optimized_context`, `codebase_get_data_access`, `codebase_impact_analysis`, `codebase_index_status`, `codebase_index_doctor`.
45
+
46
+ ## Reading the results
47
+
48
+ - Relations and data-access entries carry a confidence: `confirmed`, `probable`, `candidate` / `uncertain`. Treat `candidate` and `uncertain` (dynamic SQL) as leads to verify in the source, not facts.
49
+ - If `status` reports `stale`, run `index`.
50
+
51
+ ## Working on this repo itself
52
+
53
+ ```bash
54
+ pip install -e ".[dev,onnx]" onnx && python -m pytest -q
55
+ python benchmarks/run_benchmark.py --compare benchmarks/baseline.json
56
+ ```
57
+
58
+ The package is `local_codebase_indexer/`. See `README.md` for design notes and known limits, `TODO.md` for planned work.
59
+
60
+ ## Diagnostics and bounded results (0.6.0)
61
+
62
+ - `local-codebase-indexer --root <project> doctor --path <file>` explains exclusions.
63
+ - `search <query> --file '*Repository*.cs' --language csharp --limit 5 --offset 5` filters before ranking. Follow `pagination.next_offset` in JSON.
64
+ - `data-access <table> --confidence confirmed --limit 20 --offset 20` pages each section independently. JSON has section totals and next offsets; `--full` really lists every entry.
65
+ - `impact` includes historical accesses and callers for removed code. `snapshot=before` line numbers refer to the base revision. Historical indexes are cached in `.ai_context/impact/`; deleting that cache is safe.
66
+ - A missing root is an error; an empty or failed indexing run returns exit status 3. `--json` and `--root` work before or after the subcommand.
67
+
68
+ ## Development improvements (0.7.0)
69
+
70
+ - Prefer `search <query> --cursor <pagination.next_cursor>` for subsequent pages; retain query/filters. Cursor errors require a new search. `--explain` / MCP `explain=true` adds matched terms, expansion sources, layer ranks and SQL evidence.
71
+ - `evaluate --queries .ai_context/eval.json --save .ai_context/report.json` measures your own verified navigation questions. Optional recall/latency/token budgets fail with exit status 3. Do not change gold answers or lower thresholds merely to make a run pass.
72
+ - Exit status 4 means the index is busy; retry after the other process finishes. Configure `INDEXER_LOCK_TIMEOUT` and `INDEXER_BUSY_TIMEOUT` only when needed. Do not delete active lock files.
73
+ - `impact A..B` and `A...B` use both Git snapshots and label target lines `after`; a single base revision compares with the working tree.
74
+ - Context clipping keeps focus lines. Synonym configuration hot-reloads. ONNX identities include model/tokenizer/configuration fingerprints.
75
+ - Future Release events validate and build once, then use the same files for PyPI and GitHub attachments. Validate locally with `python scripts/release_assets.py --tag v<package-version> --dist <directory>`; add `--upload` only when publishing was requested.
@@ -0,0 +1,42 @@
1
+ # Changelog
2
+
3
+ ## 0.7.0
4
+
5
+ - Stable search ranking across page sizes/offsets, with query- and revision-bound continuation cursors.
6
+ - Historical Git ranges analyze both requested snapshots instead of mixing in the current working tree.
7
+ - ONNX identities fingerprint model/tokenizer/external weights and inference settings, triggering rebuilds when contents change.
8
+ - Process-safe indexing, consistent query snapshots, bounded busy responses (CLI exit 4), and interrupted-batch recovery.
9
+ - Context clipping preserves focus lines and reports omitted/clipped content.
10
+ - Project synonyms reload on queries; malformed settings warn once per content version and recover after correction.
11
+ - Opt-in search explanations show matched terms, expansion provenance, layer ranks/contributions and SQL evidence.
12
+ - Project evaluation datasets, per-query reports, retrieval/latency/token metrics, baseline comparison and enforceable budgets.
13
+ - Future Release events test and build once, validate versions, and upload the same artifacts to PyPI/GitHub with SHA256SUMS. Upload retries are idempotent and do not overwrite conflicting assets.
14
+
15
+
16
+ ## 0.6.0
17
+
18
+ ### Fixed
19
+
20
+ - Impact analysis reports all methods in a changed hunk and retains removed methods/files, historical SQL accesses and callers. Current and historical line numbers are labeled separately.
21
+ - Malformed JSON-RPC messages and invalid tool arguments return errors without terminating the MCP session.
22
+ - Nested `.gitignore` negations correctly override parent file patterns.
23
+ - Missing project roots fail before creating directories; empty or partially failed indexing returns exit status 3 with diagnostics.
24
+ - Search strictly honors its result limit, including queries routed to SQL data access.
25
+ - Generated packaging metadata is no longer tracked; source distributions exclude generated benchmark indexes.
26
+ - CI explicitly installs and imports `onnx`, `onnxruntime` and `tokenizers`, so ONNX plumbing tests cannot silently skip for missing dependencies.
27
+
28
+ ### Added
29
+
30
+ - `doctor --path <file>` and the `codebase_index_doctor` MCP tool explain indexing exclusions and report index health.
31
+ - Search file/language filters, offset pagination, similar-name suggestions and actionable no-result hints.
32
+ - Data-access confidence filtering, per-section pagination, totals and next offsets. `--full` / `detail=true` no longer silently truncates at 40 displayed or 200 queried entries.
33
+ - General English/Chinese paraphrases for common operations and password terminology. Keyword expansion is separated from vector expansion to preserve existing rankings.
34
+ - Cached historical impact indexes under `.ai_context/impact/`, reusable per base revision and package/index version.
35
+ - `--json` and `--root` also work after the subcommand.
36
+
37
+ ### Validation and limits
38
+
39
+ - Full tests include ONNX plumbing and regression coverage for deleted code, multi-method hunks, Chinese paths, cached historical indexes, invalid MCP messages, ignore negations, filters and pagination beyond 200 entries.
40
+ - Python 3.12 comparison against 0.5.0, with unchanged benchmark queries and baseline: synthetic Recall@5 0.893 → 0.917; noisy synthetic 0.857 → 0.881; synonym Recall@5 0.30 → 0.50 in both synthetic suites. Standard-library retrieval metrics are unchanged. These small author-written suites do not establish general semantic understanding.
41
+ - First-time historical impact analysis indexes the Git archive and may take time on large projects. External `extra_roots` cannot be reconstructed historically. Existing call-graph and dynamic-SQL limitations remain.
42
+ - Pagination assumes the index remains unchanged between requests.
@@ -26,6 +26,15 @@ local-codebase-indexer --root <project> status # is the inde
26
26
 
27
27
  Put `--json` before the subcommand for JSON output. The index lives in `<project>/.ai_context/` (git-ignored automatically).
28
28
 
29
+ ## Install as a Claude Code plugin
30
+
31
+ ```text
32
+ /plugin marketplace add sfy257000/local-codebase-indexer
33
+ /plugin install local-codebase-indexer@local-codebase-indexer
34
+ ```
35
+
36
+ Needs `uv` (`pip install uv`). Then restart Claude Code.
37
+
29
38
  ## Register as an MCP server (Claude Code)
30
39
 
31
40
  ```bash
@@ -0,0 +1,10 @@
1
+ include server.json CHANGELOG.md README*.md TODO.md AGENTS.md CLAUDE.md llms.txt index.md requirements.txt
2
+ graft scripts
3
+ graft tests
4
+ graft plugins
5
+ graft .claude-plugin
6
+ graft benchmarks
7
+ prune benchmarks/__pycache__
8
+ global-exclude __pycache__ *.py[cod]
9
+ prune benchmarks/corpus/.ai_context
10
+ include bin/indexer
@@ -1,6 +1,6 @@
1
1
  Metadata-Version: 2.4
2
2
  Name: local-codebase-indexer
3
- Version: 0.5.0
3
+ Version: 0.7.0
4
4
  Summary: Local codebase indexer and context provider for AI coding assistants: MCP server and CLI with SQL data-access and C# call relations. No cloud, no server.
5
5
  Author: sfy257000
6
6
  Project-URL: Homepage, https://github.com/sfy257000/local-codebase-indexer
@@ -26,7 +26,7 @@ Requires-Dist: tree-sitter-python
26
26
  Requires-Dist: tree-sitter-javascript
27
27
  Requires-Dist: tree-sitter-typescript
28
28
  Requires-Dist: numpy
29
- Requires-Dist: pathspec
29
+ Requires-Dist: pathspec>=0.12.1
30
30
  Provides-Extra: onnx
31
31
  Requires-Dist: onnxruntime; extra == "onnx"
32
32
  Requires-Dist: tokenizers; extra == "onnx"
@@ -54,6 +54,15 @@ From a clone: `pip install -e .` (the `bin/indexer` launcher still works in a ch
54
54
 
55
55
  If you are an AI coding assistant asked to set this up: run `pip install local-codebase-indexer`, then `claude mcp add local-indexer -- local-codebase-indexer --root <project> serve` (Claude Code) or use the CLI commands below. Full instructions are in [`AGENTS.md`](AGENTS.md).
56
56
 
57
+ ### As a Claude Code plugin
58
+
59
+ ```text
60
+ /plugin marketplace add sfy257000/local-codebase-indexer
61
+ /plugin install local-codebase-indexer@local-codebase-indexer
62
+ ```
63
+
64
+ This registers the MCP server for the project you open (it runs `uvx local-codebase-indexer --root <project> serve`, so [uv](https://docs.astral.sh/uv/) must be installed: `pip install uv`). Restart Claude Code afterwards.
65
+
57
66
  ## Usage (CLI)
58
67
 
59
68
  ```bash
@@ -68,7 +77,7 @@ local-codebase-indexer status # is the ind
68
77
  ```
69
78
 
70
79
  - Without `--root` the current directory is used; `INDEXER_ROOT` also works.
71
- - Put `--json` before the subcommand to get JSON output.
80
+ - Put `--json` before or after the subcommand to get JSON output.
72
81
  - `search`, `relations` and `context` run an incremental refresh first (mtime check, then md5 only when mtime changed).
73
82
  - The tool names from the spec also work as subcommands: `codebase_semantic_search`, `codebase_get_symbol_relations`, `codebase_get_optimized_context` (options `--query`, `--symbol_name --relation_direction`, `--file_path --focus_lines --padding_lines`).
74
83
 
@@ -79,7 +88,88 @@ claude mcp add local-indexer -- local-codebase-indexer --root /path/to/project s
79
88
  # without installing: claude mcp add local-indexer -- uvx local-codebase-indexer --root /path/to/project serve
80
89
  ```
81
90
 
82
- `serve` speaks JSON-RPC (MCP) over stdio and exposes six tools: `codebase_semantic_search`, `codebase_get_symbol_relations`, `codebase_get_optimized_context`, `codebase_get_data_access`, `codebase_impact_analysis`, `codebase_index_status`. A long-lived server re-checks the index before a query when the last check is older than 15 s (a no-op check takes about a second on a few thousand files). `codebase_get_data_access` returns a summary (5 entries per section, every program) unless `detail` is set; `codebase_semantic_search` lists dependency-graph neighbours only with `related`.
91
+ `serve` speaks JSON-RPC (MCP) over stdio and exposes seven tools: `codebase_semantic_search`, `codebase_get_symbol_relations`, `codebase_get_optimized_context`, `codebase_get_data_access`, `codebase_impact_analysis`, `codebase_index_status`, `codebase_index_doctor`. A long-lived server re-checks the index before a query when the last check is older than 15 s (a no-op check takes about a second on a few thousand files). `codebase_get_data_access` returns a summary (5 entries per section, every program) unless `detail` is set; `codebase_semantic_search` lists dependency-graph neighbours only with `related`.
92
+
93
+ ## Diagnose missing code and control output
94
+
95
+ ```bash
96
+ local-codebase-indexer --root <project> doctor
97
+ local-codebase-indexer --root <project> doctor --path src/Service.cs
98
+ local-codebase-indexer --root <project> search "retrieve invoice" --file '*.py' --language python --limit 5
99
+ local-codebase-indexer --root <project> search "retrieve invoice" --file '*.py' --language python --limit 5 --offset 5
100
+ local-codebase-indexer --root <project> data-access MES_Lot --confidence confirmed --limit 20 --offset 0
101
+ local-codebase-indexer --root <project> data-access MES_Lot --full
102
+ ```
103
+
104
+ `doctor` reports supported text files, ignore rules, excluded directories, unsupported extensions, files over 5 MB, binary files and index health. `--path` explains a specific file, including a parent directory that prevents indexing. Directory counts are counts of excluded directories, not all the files hidden inside them. Nested `.gitignore` negations override parent file patterns; an excluded parent directory must first be re-included, just as with Git. Built-in excluded directories such as `node_modules` remain excluded.
105
+
106
+ Search filters apply **before** ranking. `--file` is a case-sensitive glob over the complete project-relative path (`*` also matches `/`); languages are `csharp`, `python`, `javascript`, `typescript`, `tsx`, and `text`. The JSON `pagination` object has `has_more` and `next_offset`; keep the same query and filters for subsequent pages. Offset pages assume the index remains unchanged; cursor pages reject a changed index or configuration. No-result responses suggest similar symbols where available and explain useful next steps. General verb paraphrases expand keyword/symbol matching without diluting vector queries; project-specific jargon still belongs in `.ai_context/synonyms.json`.
107
+
108
+ Data-access `--confidence` selects an exact level (`confirmed`, `probable`, or `uncertain`). `--limit` and `--offset` apply independently to each section, including programs and procedure accesses. JSON includes `pagination.sections` with totals and next offsets. MCP accepts the same `limit`, `offset`, and `confidence` fields; search uses `file_pattern` and `language`. `--full` / MCP `detail=true` lists all entries when no explicit page size is supplied. The old 40-entry display and 200-entry query caps have been removed.
109
+
110
+ `impact` includes both current symbols and affected symbols/accesses/callers from the base revision, so deleting a method or file remains visible. `snapshot: before` means its line numbers refer to the base revision, not the current file. The first request for a base revision builds a temporary historical index, which can take time on a large repository; a complete baseline is cached under `.ai_context/impact/` for reuse. Remove this directory to reclaim space. Historical analysis covers files in the Git archive; external `extra_roots` are not reconstructed. Static call-graph confidence and known language limitations still apply.
111
+
112
+ A nonexistent `--root` is rejected without creating it. `index` returns exit status 3 for an empty or partially failed run; use `doctor` and `status` to diagnose it. Invalid MCP inputs return an error while keeping the server available for the next request.
113
+
114
+ ## Stable navigation and search explanations
115
+
116
+ Search ranking is independent of `--limit` and `--offset`. To continue a search safely, use the opaque `pagination.next_cursor` returned in JSON, or the cursor printed by the text/MCP response:
117
+
118
+ ```bash
119
+ local-codebase-indexer --root <project> search "retrieve invoice" --limit 5 --explain --json
120
+ local-codebase-indexer --root <project> search "retrieve invoice" --limit 5 --cursor '<next_cursor>' --json
121
+ ```
122
+
123
+ Keep the same query, file glob and language when using a cursor; the page size may change. Cursors are bound to a completed index revision, the embedding model, and synonym settings. A no-op refresh keeps them valid; a changed index or configuration rejects the cursor with an instruction to start again. `--offset` remains supported but has no revision guard. MCP search accepts `cursor` and `explain` too.
124
+
125
+ `--explain` adds matched query terms, matched synonym expansions with their built-in/project/mined-comment sources, and each retrieval layer's rank and RRF contribution. Data-access hits also carry SQL evidence, confidence, access mechanism and procedure chains. Existing `relations` output includes caller resolution reasons and confidence. These are static-analysis/retrieval explanations, not proof that a runtime path executes or a score is a probability. Explanations are omitted by default to keep responses compact.
126
+
127
+ Project synonym settings reload on subsequent queries, including deletion and replacement of the settings file. Invalid settings log a warning and fall back to built-in groups; the same invalid contents are not repeatedly logged. ONNX identities include a streamed content fingerprint of the model directory (including tokenizer and external weights), pooling, dimensions and query prefix. Use a dedicated model directory: changing other files in that directory can also cause a rebuild. Generated `.ai_context`, environment and cache directories are excluded from the fingerprint. Changes to loaded model files are rejected; restart the server to load the updated model. Processes sharing an index must use the same model/settings.
128
+
129
+ Large context requests retain focus lines first, fit neighboring lines within the character budget, and clip individual oversized lines. Returned ranges describe the content actually returned; `omitted_lines` and `truncated_lines` explain clipping. An entirely out-of-file focus request is an error.
130
+
131
+ Git ranges such as `A..B` and `A...B` analyze the actual target commit, even when HEAD or the working tree differs. Range results use `snapshot=after`; `revisions` identifies both commits. A single revision still compares that revision against the working tree. Historical line numbers always belong to their labeled snapshot.
132
+
133
+ ## Evaluate your own project questions
134
+
135
+ Keep questions collected from real navigation work in `.ai_context/eval.json` (ignored by Git and the index):
136
+
137
+ ```json
138
+ {
139
+ "version": 1,
140
+ "queries": [
141
+ {
142
+ "id": "invoice-read",
143
+ "query": "Where do we retrieve an invoice?",
144
+ "language": "python",
145
+ "relevant": [{"file": "src/invoices.py", "symbol": "load_invoice"}]
146
+ }
147
+ ]
148
+ }
149
+ ```
150
+
151
+ Replace the example with verified file paths and optional qualified-symbol suffixes from your project. Each question needs a unique ID and at least one expected answer. `file_pattern` and `language` are optional query filters. Avoid copying question text into the source corpus or authoring only questions that already rank well.
152
+
153
+ ```bash
154
+ local-codebase-indexer --root <project> evaluate --queries <project>/.ai_context/eval.json --save <project>/.ai_context/baseline.json
155
+ local-codebase-indexer --root <project> evaluate --queries <project>/.ai_context/eval.json --baseline <project>/.ai_context/baseline.json --min-recall 0.8 --max-recall-drop 0.02 --max-p95-ms 500 --max-mean-tokens 1500 --save <project>/.ai_context/current.json
156
+ ```
157
+
158
+ The report includes Recall@k, hit rate, MRR, p50/p95 latency, estimated output tokens, per-question answers and the index/model/configuration identity. Indexing time is separate from search latency. Tokens are estimated as `ceil(rendered characters / 4)`, not counted by a specific model tokenizer. Empty/invalid datasets fail; breached quality or performance budgets return exit status 3. Baseline comparisons require the same questions, answers, filters and result limit. Reports cannot overwrite their input questions or baseline.
159
+
160
+ `benchmarks/queries_project.json` supplies 15 curated questions about this repository's actual implementation. They are navigation smoke examples, not collected user queries or an independent quality benchmark. Run them with `local-codebase-indexer --root . evaluate --queries benchmarks/queries_project.json --save .ai_context/project-report.json`; use your own recorded questions for representative quality gates.
161
+
162
+ ## Multiple local processes
163
+
164
+ Index initialization and writes are coordinated with an OS lock. Query reads use a consistent SQLite snapshot and wait for a writer to finish its batches. POSIX readers share a lock; Windows readers serialize. Locks are automatically released on process exit; do not delete `.lock` files while processes are running.
165
+
166
+ `INDEXER_LOCK_TIMEOUT` controls the maximum process-lock wait (default 10 seconds), and `INDEXER_BUSY_TIMEOUT` controls SQLite's wait for writers that do not use the indexer's lock (default 5 seconds). Both accept finite nonnegative seconds. CLI contention returns exit status 4 with a retry hint; MCP reports a tool error while keeping the session available. Interrupted batch indexing is reported as degraded and automatically forces a complete refresh on the next indexing run. Separate `CodebaseTools` instances/connections are required for separate threads.
167
+
168
+ ## Release automation
169
+
170
+ Publishing a future GitHub Release runs tests, builds distributions once, validates package/tag/registry versions, and generates `SHA256SUMS`. PyPI and GitHub attachments receive the same validated artifacts. The attachment job uses GitHub Actions' built-in token with `contents: write`; no personal upload token is needed. Repeating the attachment job skips identical assets and refuses to overwrite conflicting checksums.
171
+
172
+ For local validation without publishing: `python scripts/release_assets.py --tag v<package-version> --dist <build-directory>`. The explicit `--upload --repo owner/name` flags perform uploads. Existing releases are not modified by editing this workflow.
83
173
 
84
174
  ## Three-layer index
85
175
 
@@ -0,0 +1,186 @@
1
+ # Local Codebase Indexer
2
+
3
+ **English** | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
4
+
5
+ A local codebase indexer and context provider for AI coding assistants (Claude Code via MCP, GitHub Copilot / Codex via CLI). It helps them navigate large legacy codebases with far fewer tokens. Everything is stored in `.ai_context/indexer.db` inside your project, with no cloud services involved. The design follows [`index.md`](index.md).
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ pip install local-codebase-indexer # Python 3.10+
11
+ # or, isolated from your other packages:
12
+ pipx install local-codebase-indexer
13
+ # optional real embeddings (see below): pip install "local-codebase-indexer[onnx]"
14
+ ```
15
+
16
+ From a clone: `pip install -e .` (the `bin/indexer` launcher still works in a checkout).
17
+
18
+ ## For AI assistants
19
+
20
+ If you are an AI coding assistant asked to set this up: run `pip install local-codebase-indexer`, then `claude mcp add local-indexer -- local-codebase-indexer --root <project> serve` (Claude Code) or use the CLI commands below. Full instructions are in [`AGENTS.md`](AGENTS.md).
21
+
22
+ ### As a Claude Code plugin
23
+
24
+ ```text
25
+ /plugin marketplace add sfy257000/local-codebase-indexer
26
+ /plugin install local-codebase-indexer@local-codebase-indexer
27
+ ```
28
+
29
+ This registers the MCP server for the project you open (it runs `uvx local-codebase-indexer --root <project> serve`, so [uv](https://docs.astral.sh/uv/) must be installed: `pip install uv`). Restart Claude Code afterwards.
30
+
31
+ ## Usage (CLI)
32
+
33
+ ```bash
34
+ local-codebase-indexer --root <project> index # build / incrementally refresh the index (--force rebuilds all)
35
+ local-codebase-indexer search "database mapping for LotNo" --limit 5
36
+ local-codebase-indexer relations IExistOpenHandleService --direction both # upstream | downstream | both
37
+ local-codebase-indexer context Services/LotService.cs --lines 120 --padding 15 # alias: slice
38
+ local-codebase-indexer data-access MES_Lot # who reads / writes / executes a table or procedure; what a procedure touches (--full: every entry)
39
+ local-codebase-indexer impact main...HEAD # symbols, tables, programs and pages a change touches (no argument: uncommitted work)
40
+ local-codebase-indexer stats
41
+ local-codebase-indexer status # is the index fresh? failed files, git commit, consistency checks
42
+ ```
43
+
44
+ - Without `--root` the current directory is used; `INDEXER_ROOT` also works.
45
+ - Put `--json` before or after the subcommand to get JSON output.
46
+ - `search`, `relations` and `context` run an incremental refresh first (mtime check, then md5 only when mtime changed).
47
+ - The tool names from the spec also work as subcommands: `codebase_semantic_search`, `codebase_get_symbol_relations`, `codebase_get_optimized_context` (options `--query`, `--symbol_name --relation_direction`, `--file_path --focus_lines --padding_lines`).
48
+
49
+ ## Usage (Claude Code / MCP)
50
+
51
+ ```bash
52
+ claude mcp add local-indexer -- local-codebase-indexer --root /path/to/project serve
53
+ # without installing: claude mcp add local-indexer -- uvx local-codebase-indexer --root /path/to/project serve
54
+ ```
55
+
56
+ `serve` speaks JSON-RPC (MCP) over stdio and exposes seven tools: `codebase_semantic_search`, `codebase_get_symbol_relations`, `codebase_get_optimized_context`, `codebase_get_data_access`, `codebase_impact_analysis`, `codebase_index_status`, `codebase_index_doctor`. A long-lived server re-checks the index before a query when the last check is older than 15 s (a no-op check takes about a second on a few thousand files). `codebase_get_data_access` returns a summary (5 entries per section, every program) unless `detail` is set; `codebase_semantic_search` lists dependency-graph neighbours only with `related`.
57
+
58
+ ## Diagnose missing code and control output
59
+
60
+ ```bash
61
+ local-codebase-indexer --root <project> doctor
62
+ local-codebase-indexer --root <project> doctor --path src/Service.cs
63
+ local-codebase-indexer --root <project> search "retrieve invoice" --file '*.py' --language python --limit 5
64
+ local-codebase-indexer --root <project> search "retrieve invoice" --file '*.py' --language python --limit 5 --offset 5
65
+ local-codebase-indexer --root <project> data-access MES_Lot --confidence confirmed --limit 20 --offset 0
66
+ local-codebase-indexer --root <project> data-access MES_Lot --full
67
+ ```
68
+
69
+ `doctor` reports supported text files, ignore rules, excluded directories, unsupported extensions, files over 5 MB, binary files and index health. `--path` explains a specific file, including a parent directory that prevents indexing. Directory counts are counts of excluded directories, not all the files hidden inside them. Nested `.gitignore` negations override parent file patterns; an excluded parent directory must first be re-included, just as with Git. Built-in excluded directories such as `node_modules` remain excluded.
70
+
71
+ Search filters apply **before** ranking. `--file` is a case-sensitive glob over the complete project-relative path (`*` also matches `/`); languages are `csharp`, `python`, `javascript`, `typescript`, `tsx`, and `text`. The JSON `pagination` object has `has_more` and `next_offset`; keep the same query and filters for subsequent pages. Offset pages assume the index remains unchanged; cursor pages reject a changed index or configuration. No-result responses suggest similar symbols where available and explain useful next steps. General verb paraphrases expand keyword/symbol matching without diluting vector queries; project-specific jargon still belongs in `.ai_context/synonyms.json`.
72
+
73
+ Data-access `--confidence` selects an exact level (`confirmed`, `probable`, or `uncertain`). `--limit` and `--offset` apply independently to each section, including programs and procedure accesses. JSON includes `pagination.sections` with totals and next offsets. MCP accepts the same `limit`, `offset`, and `confidence` fields; search uses `file_pattern` and `language`. `--full` / MCP `detail=true` lists all entries when no explicit page size is supplied. The old 40-entry display and 200-entry query caps have been removed.
74
+
75
+ `impact` includes both current symbols and affected symbols/accesses/callers from the base revision, so deleting a method or file remains visible. `snapshot: before` means its line numbers refer to the base revision, not the current file. The first request for a base revision builds a temporary historical index, which can take time on a large repository; a complete baseline is cached under `.ai_context/impact/` for reuse. Remove this directory to reclaim space. Historical analysis covers files in the Git archive; external `extra_roots` are not reconstructed. Static call-graph confidence and known language limitations still apply.
76
+
77
+ A nonexistent `--root` is rejected without creating it. `index` returns exit status 3 for an empty or partially failed run; use `doctor` and `status` to diagnose it. Invalid MCP inputs return an error while keeping the server available for the next request.
78
+
79
+ ## Stable navigation and search explanations
80
+
81
+ Search ranking is independent of `--limit` and `--offset`. To continue a search safely, use the opaque `pagination.next_cursor` returned in JSON, or the cursor printed by the text/MCP response:
82
+
83
+ ```bash
84
+ local-codebase-indexer --root <project> search "retrieve invoice" --limit 5 --explain --json
85
+ local-codebase-indexer --root <project> search "retrieve invoice" --limit 5 --cursor '<next_cursor>' --json
86
+ ```
87
+
88
+ Keep the same query, file glob and language when using a cursor; the page size may change. Cursors are bound to a completed index revision, the embedding model, and synonym settings. A no-op refresh keeps them valid; a changed index or configuration rejects the cursor with an instruction to start again. `--offset` remains supported but has no revision guard. MCP search accepts `cursor` and `explain` too.
89
+
90
+ `--explain` adds matched query terms, matched synonym expansions with their built-in/project/mined-comment sources, and each retrieval layer's rank and RRF contribution. Data-access hits also carry SQL evidence, confidence, access mechanism and procedure chains. Existing `relations` output includes caller resolution reasons and confidence. These are static-analysis/retrieval explanations, not proof that a runtime path executes or a score is a probability. Explanations are omitted by default to keep responses compact.
91
+
92
+ Project synonym settings reload on subsequent queries, including deletion and replacement of the settings file. Invalid settings log a warning and fall back to built-in groups; the same invalid contents are not repeatedly logged. ONNX identities include a streamed content fingerprint of the model directory (including tokenizer and external weights), pooling, dimensions and query prefix. Use a dedicated model directory: changing other files in that directory can also cause a rebuild. Generated `.ai_context`, environment and cache directories are excluded from the fingerprint. Changes to loaded model files are rejected; restart the server to load the updated model. Processes sharing an index must use the same model/settings.
93
+
94
+ Large context requests retain focus lines first, fit neighboring lines within the character budget, and clip individual oversized lines. Returned ranges describe the content actually returned; `omitted_lines` and `truncated_lines` explain clipping. An entirely out-of-file focus request is an error.
95
+
96
+ Git ranges such as `A..B` and `A...B` analyze the actual target commit, even when HEAD or the working tree differs. Range results use `snapshot=after`; `revisions` identifies both commits. A single revision still compares that revision against the working tree. Historical line numbers always belong to their labeled snapshot.
97
+
98
+ ## Evaluate your own project questions
99
+
100
+ Keep questions collected from real navigation work in `.ai_context/eval.json` (ignored by Git and the index):
101
+
102
+ ```json
103
+ {
104
+ "version": 1,
105
+ "queries": [
106
+ {
107
+ "id": "invoice-read",
108
+ "query": "Where do we retrieve an invoice?",
109
+ "language": "python",
110
+ "relevant": [{"file": "src/invoices.py", "symbol": "load_invoice"}]
111
+ }
112
+ ]
113
+ }
114
+ ```
115
+
116
+ Replace the example with verified file paths and optional qualified-symbol suffixes from your project. Each question needs a unique ID and at least one expected answer. `file_pattern` and `language` are optional query filters. Avoid copying question text into the source corpus or authoring only questions that already rank well.
117
+
118
+ ```bash
119
+ local-codebase-indexer --root <project> evaluate --queries <project>/.ai_context/eval.json --save <project>/.ai_context/baseline.json
120
+ local-codebase-indexer --root <project> evaluate --queries <project>/.ai_context/eval.json --baseline <project>/.ai_context/baseline.json --min-recall 0.8 --max-recall-drop 0.02 --max-p95-ms 500 --max-mean-tokens 1500 --save <project>/.ai_context/current.json
121
+ ```
122
+
123
+ The report includes Recall@k, hit rate, MRR, p50/p95 latency, estimated output tokens, per-question answers and the index/model/configuration identity. Indexing time is separate from search latency. Tokens are estimated as `ceil(rendered characters / 4)`, not counted by a specific model tokenizer. Empty/invalid datasets fail; breached quality or performance budgets return exit status 3. Baseline comparisons require the same questions, answers, filters and result limit. Reports cannot overwrite their input questions or baseline.
124
+
125
+ `benchmarks/queries_project.json` supplies 15 curated questions about this repository's actual implementation. They are navigation smoke examples, not collected user queries or an independent quality benchmark. Run them with `local-codebase-indexer --root . evaluate --queries benchmarks/queries_project.json --save .ai_context/project-report.json`; use your own recorded questions for representative quality gates.
126
+
127
+ ## Multiple local processes
128
+
129
+ Index initialization and writes are coordinated with an OS lock. Query reads use a consistent SQLite snapshot and wait for a writer to finish its batches. POSIX readers share a lock; Windows readers serialize. Locks are automatically released on process exit; do not delete `.lock` files while processes are running.
130
+
131
+ `INDEXER_LOCK_TIMEOUT` controls the maximum process-lock wait (default 10 seconds), and `INDEXER_BUSY_TIMEOUT` controls SQLite's wait for writers that do not use the indexer's lock (default 5 seconds). Both accept finite nonnegative seconds. CLI contention returns exit status 4 with a retry hint; MCP reports a tool error while keeping the session available. Interrupted batch indexing is reported as degraded and automatically forces a complete refresh on the next indexing run. Separate `CodebaseTools` instances/connections are required for separate threads.
132
+
133
+ ## Release automation
134
+
135
+ Publishing a future GitHub Release runs tests, builds distributions once, validates package/tag/registry versions, and generates `SHA256SUMS`. PyPI and GitHub attachments receive the same validated artifacts. The attachment job uses GitHub Actions' built-in token with `contents: write`; no personal upload token is needed. Repeating the attachment job skips identical assets and refuses to overwrite conflicting checksums.
136
+
137
+ For local validation without publishing: `python scripts/release_assets.py --tag v<package-version> --dist <build-directory>`. The explicit `--upload --repo owner/name` flags perform uploads. Existing releases are not modified by editing this workflow.
138
+
139
+ ## Three-layer index
140
+
141
+ | Layer | Implementation |
142
+ |---|---|
143
+ | Syntactic | tree-sitter for C#, Python, JavaScript, TypeScript/TSX; regex for SQL (PROCEDURE / VIEW / FUNCTION / TABLE); other text files (VB6 `.frm`, `.config`, `.md`, ...) are split into windowed chunks |
144
+ | Topology | `using` / `import` resolved to file dependencies, inheritance (base lists) and type usage (`invocation`), stored in the `dependencies` table |
145
+ | Semantic | 384-dim chunk embeddings in `vss_chunks`; queries fuse FTS5 keyword, symbol-name and vector rankings with Reciprocal Rank Fusion, then expand to the dependency neighbours of the top 3 files |
146
+
147
+ Encodings: UTF-8 first, then Big5, then cp1252. Files over 5MB are skipped. Root and nested `.gitignore` files are respected, and `.git`, `bin`, `obj`, `node_modules` and similar directories are always skipped. `*.min.js` / `*.min.css` are skipped too. Third-party or generated code that is committed to the repo can be excluded with `.ai_context/ignore` (gitignore syntax), e.g. `Scripts/*`, `!Scripts/Custom/`, `Web References/` (keep generated EF database-first models: their DbContext declares the DbSets).
148
+
149
+ ## Differences from the spec
150
+
151
+ - **Vector storage**: `sqlite-vss` needs a native extension and is no longer maintained, so `vss_chunks` stores float32 BLOBs and cosine similarity is computed with numpy. No extension to install.
152
+ - **Embedding model**: the default is a built-in hashing embedder (identifier sub-words, bigrams, CJK character bigrams). It is fast and reproducible but **does not understand synonyms**. For real transformer embeddings, export `all-MiniLM-L6-v2` or `bge-small-en-v1.5` to ONNX, install `onnxruntime` and `tokenizers`, and set `INDEXER_ONNX_MODEL=<folder with model.onnx and tokenizer.json>` (mean pooling suits MiniLM, bge models recommend CLS pooling). Switching embedders triggers a full re-index. Measured (0.4.0): `all-MiniLM-L6-v2` raises benchmark MRR by 0.08-0.13, but on a real 30k-chunk C# / Chinese-comment codebase it scored lower than hashing on paraphrased queries (MRR 0.29 vs 0.48; multilingual MiniLM-L12: 0.41) while a full index took 35-43 minutes instead of 2. Hashing stays the default; for domain jargon, `.ai_context/synonyms.json` helps more than a general model.
153
+ - **Call relations** for C# are resolved with limited type inference (using / namespaces, field and constructor-injected types, `Lazy<T>.Value`, locals, `foreach (var x in items.Where(..))` element types, interface to implementation), and every edge carries a confidence: `confirmed` (the receiver type is known), `probable` (reached through an interface or a single candidate) or `candidate` (name match only). There is no Roslyn: no overload resolution by argument type, no delegates / lambdas / extension methods, and call chains are followed one level. Inheritance edges come from the AST and are reliable.
154
+ - Extra schema additions: `symbols.qualified_name`, `chunk_metadata.symbol_id`, and the `raw_refs`, `chunks_fts` and `meta` tables.
155
+
156
+ ## Data access (SQL)
157
+
158
+ `data-access <table-or-procedure>` answers "what writes / reads / executes X". It is built from T-SQL (INSERT / UPDATE / DELETE / MERGE / TRUNCATE / SELECT INTO / FROM / JOIN / EXEC, with alias resolution; CTEs, temp tables and system objects excluded), from C# SQL strings (literals, `+`, interpolation, `string.Format`, consts, locals, `StringBuilder.Append` / `AppendLine` / `AppendFormat`) passed to Dapper, `SqlCommand` or EF `FromSql`, from stored-procedure names used with `CommandType.StoredProcedure`, from EF LINQ on `DbSet<T>` members (`ctx.Orders.Where(..)` / `.Add(..)` / `.Remove(..)`, `from o in ctx.Orders`; `probable`, since only the member name is matched) and from EF `ToTable` / `[Table]` mappings. A procedure's callers are indirect writers of the tables it writes (followed up to 4 hops). `programs` (USED BY PROGRAMS) follows confirmed / probable C# calls upward from those accessors to `*Controller` methods (up to 8 hops) (including from an implementation to the callers of the interface method it implements, for `foreach (var step in steps) step.Run()` pipelines) and groups them per controller file, with the Razor pages (`.cshtml`) whose `Url.Action("Action"[, "Controller"])` or AngularJS `ControllerPath + 'Action'` (controller from `$scope.Controller = 'X'`) targets those actions, so a table maps to the screens that touch it. A method that reads a DbSet and calls `SaveChanges` without an explicit `Add` / `Remove` may update tracked entities; it is listed as a possible (`uncertain`) writer. Each entry has a confidence; **dynamic SQL (`EXEC(@sql)`, `sp_executesql`, SQL built from unknown values) cannot be resolved and is listed separately as `uncertain`**, never mixed into the confirmed lists. EF accesses are `confirmed` when the context variable (`using (var db = new X())`, a field or property, or `this`) is typed as a class that declares or inherits the DbSet, `probable` otherwise. Methods on the way up that have no confirmed / probable caller at all are listed under NO KNOWN CALLER: entry points such as API endpoints, jobs or `Main`, or calls the graph could not resolve. Known gaps: `FROM a JOIN b ON ..., c` loses `c`, and a stored-procedure name passed to a non-database method is not seen.
159
+
160
+ Stored procedures that live only in the database can be exported to a folder outside the repo and listed in `.ai_context/extra_roots` (one folder per line, absolute or relative to the root); their files are indexed under their absolute paths.
161
+
162
+ Natural-language search routes questions such as "who modifies MES_ScrapRecord" or "哪些程式會寫入 MES_Lot" to this index first.
163
+
164
+ ## Query expansion
165
+
166
+ Queries are expanded with a small synonym dictionary (`SP` / `預存程序` / `stored procedure` / `usp`, table, lot, scrap, ...; `local_codebase_indexer/synonyms.py`). Add or disable groups per project in `.ai_context/synonyms.json`: `{"groups": [["wpnlot", "在製批"]], "disable": ["sp"]}`. This helps abbreviations and Chinese/English terms, not free paraphrase.
167
+
168
+ The index also mines its own dictionary: Chinese bigrams in the comments right above a symbol are paired with the sub-words of its name (`/// 收帳` above `ReceiveLotAsync` gives 收帳 = receive). A pair is kept when at least 5 symbols support it, it covers at least 15% of the symbols commented with the bigram (smoothed) and the word is at least 15x likelier there than overall. On a 30k-chunk C# codebase this yields about 350 pairs (收帳 -> receive, 拆批 -> divide, 油墨 -> ink, 底片 -> film) and raised MRR on paraphrased queries from 0.57 to 0.64.
169
+
170
+ ## Index health
171
+
172
+ `status` (also the MCP tool `codebase_index_status`) reports whether the index can be trusted without refreshing it: `fresh`, `stale` (files changed or git HEAD moved since the last update), `degraded` (failed files or an inconsistent database) or `not_indexed`. A file that fails to parse is removed from the index, listed with its error, and retried on every update, so search never returns stale lines for it. `index --force` rebuilds everything. Status also shows the running version and warns when the package's code changed on disk after the process started (restart the MCP server, i.e. open a new Claude Code session, to run it).
173
+
174
+ Speed (2.3k files, 30k chunks, hashing embedder): full build about 36 s into an empty database, a branch switch that rewrites 400 files about 10 s, a no-op check about 1 s. Each file is written inside a savepoint (atomic), and commits are batched every 500 files.
175
+
176
+ ## Benchmark
177
+
178
+ `python benchmarks/run_benchmark.py` measures Recall@5, Recall@10 and MRR on fixed queries. See [`benchmarks/README.md`](benchmarks/README.md).
179
+
180
+ ## Tests
181
+
182
+ ```bash
183
+ python -m pytest -q
184
+ ```
185
+
186
+ <!-- mcp-name: io.github.sfy257000/local-codebase-indexer -->
@@ -15,6 +15,15 @@ pipx install local-codebase-indexer
15
15
 
16
16
  从源码:`pip install -e .`(在 clone 下 `bin/indexer` 仍可使用)。
17
17
 
18
+ ### 作为 Claude Code plugin 安装
19
+
20
+ ```text
21
+ /plugin marketplace add sfy257000/local-codebase-indexer
22
+ /plugin install local-codebase-indexer@local-codebase-indexer
23
+ ```
24
+
25
+ 会为你打开的项目注册 MCP 服务器(实际运行 `uvx local-codebase-indexer --root <项目> serve`,所以要先装 [uv](https://docs.astral.sh/uv/):`pip install uv`)。安装后重启 Claude Code。
26
+
18
27
  ## 使用(CLI)
19
28
 
20
29
  ```bash
@@ -29,7 +38,7 @@ local-codebase-indexer status # 索引是
29
38
  ```
30
39
 
31
40
  - 不指定 `--root` 时使用当前目录,也可用环境变量 `INDEXER_ROOT`。
32
- - 加 `--json`(放在子命令前)输出 JSON。
41
+ - 加 `--json`(可放在子命令前后)输出 JSON。
33
42
  - `search`、`relations`、`context` 执行前会自动做一次增量更新(先比较 mtime,mtime 变了才计算 md5)。
34
43
  - 规格中的工具名称也可以直接作为子命令:`codebase_semantic_search`、`codebase_get_symbol_relations`、`codebase_get_optimized_context`(参数 `--query`、`--symbol_name --relation_direction`、`--file_path --focus_lines --padding_lines`)。
35
44
 
@@ -40,7 +49,30 @@ claude mcp add local-indexer -- local-codebase-indexer --root /path/to/project s
40
49
  # 不安装直接运行:claude mcp add local-indexer -- uvx local-codebase-indexer --root /path/to/project serve
41
50
  ```
42
51
 
43
- `serve` 通过 stdio 提供 JSON-RPC(MCP),暴露六个工具:`codebase_semantic_search`、`codebase_get_symbol_relations`、`codebase_get_optimized_context`、`codebase_get_data_access`、`codebase_impact_analysis`、`codebase_index_status`。常驻的 server 在距离上次检查超过 15 秒时,查询前会重新检查索引(几千个文件无变动约 1 秒)。`codebase_get_data_access` 默认返回摘要(每区 5 条、程序全列),加 `detail` 才列全部;`codebase_semantic_search` 加 `related` 才附依赖文件。
52
+ `serve` 通过 stdio 提供 JSON-RPC(MCP),暴露七个工具:`codebase_semantic_search`、`codebase_get_symbol_relations`、`codebase_get_optimized_context`、`codebase_get_data_access`、`codebase_impact_analysis`、`codebase_index_status`、`codebase_index_doctor`。常驻的 server 在距离上次检查超过 15 秒时,查询前会重新检查索引(几千个文件无变动约 1 秒)。`codebase_get_data_access` 默认返回摘要(每区 5 条、程序全列),加 `detail` 才列全部;`codebase_semantic_search` 加 `related` 才附依赖文件。
53
+
54
+ ## 0.7.0:稳定导航与项目评测
55
+
56
+ 搜索排序不再随页数变化;`pagination.next_cursor` 可用于 `--cursor`/MCP `cursor`,索引或同义词变化时要求重新搜索。`--explain` 显示命中词、扩展来源、排序贡献及 SQL 证据。上下文裁剪优先保留焦点行;同义词自动重载,ONNX 模型和 tokenizer 使用内容指纹。
57
+
58
+ `impact A..B` 和 `A...B` 使用指定版本的快照;多进程索引使用系统锁和一致性读取,繁忙时 CLI 返回退出码 4。`INDEXER_LOCK_TIMEOUT` 与 `INDEXER_BUSY_TIMEOUT` 控制等待秒数,中断批次会在下次索引时恢复。
59
+
60
+ `evaluate --queries .ai_context/eval.json --save .ai_context/report.json` 支持项目问题集、Recall@k、MRR、延迟和估计 token,以及基准比较和质量门槛。数据格式为 `{"version":1,"queries":[{"id":"invoice","query":"读取发票","relevant":[{"file":"src/invoices.py","symbol":"load_invoice"}]}]}`。未达到 `--min-recall`/`--max-p95-ms`/`--max-mean-tokens` 门槛返回退出码 3。`benchmarks/queries_project.json` 是本仓库的人工导航示例,不是独立的真实用户评测。
61
+
62
+ 后续 Release workflow 使用同一份经过验证的构建产物发布到 PyPI 和 GitHub,自动生成 SHA256SUMS;使用 Actions 内置令牌,重复运行跳过相同附件,拒绝覆盖不同内容。修改 workflow 不会变更现有 Release。
63
+
64
+ ## 诊断、筛选与分页(0.6.0)
65
+
66
+ ```bash
67
+ local-codebase-indexer --root <项目> doctor --path src/Service.cs
68
+ local-codebase-indexer --root <项目> search "读取发票" --file '*.py' --language python --limit 5 --offset 0
69
+ local-codebase-indexer --root <项目> data-access MES_Lot --confidence confirmed --limit 20 --offset 20
70
+ local-codebase-indexer --root <项目> data-access MES_Lot --full
71
+ ```
72
+
73
+ `doctor` 解释忽略规则、不支持的扩展名、过大和二进制文件以及索引状态。搜索先筛选再排名;文件 glob 区分大小写,`*` 可以跨 `/`。JSON 提供 `pagination.next_offset`。数据访问支持精确信心等级筛选和每个区段独立分页;`--full`/MCP `detail=true` 不再受旧有 40/200 条上限限制。MCP 搜索使用 `file_pattern`、`language`、`limit`、`offset`,数据访问使用 `confidence`、`limit`、`offset`,新增诊断工具 `codebase_index_doctor`。
74
+
75
+ `impact` 保留删除代码及历史调用、数据表影响;`snapshot=before` 的行号属于基准版本。历史索引首次建立后缓存在 `.ai_context/impact/`,可安全删除以释放空间;不会重建外部 `extra_roots`,静态分析限制仍适用。不存在的根目录会报错,空索引或部分失败返回退出码 3;MCP 参数错误不会结束服务。新增常见中英文同义词,项目术语仍可配置在 `.ai_context/synonyms.json`。
44
76
 
45
77
  ## 三层索引
46
78