local-codebase-indexer 0.9.0__tar.gz → 1.0.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.
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/AGENTS.md +20 -2
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/CHANGELOG.md +28 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/CONTRIBUTING.md +12 -1
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/PKG-INFO +35 -5
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/README.md +30 -3
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/README.zh-CN.md +29 -2
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/README.zh-TW.md +29 -2
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/TODO.md +6 -2
- local_codebase_indexer-1.0.0/assets/impact-report.html +384 -0
- local_codebase_indexer-1.0.0/assets/impact-report.png +0 -0
- local_codebase_indexer-1.0.0/benchmarks/README.md +61 -0
- local_codebase_indexer-1.0.0/benchmarks/client-compatibility.json +34 -0
- local_codebase_indexer-1.0.0/benchmarks/codex-tool-events.json +389 -0
- local_codebase_indexer-1.0.0/benchmarks/compare_tools.py +296 -0
- local_codebase_indexer-1.0.0/benchmarks/maintainer-acceptance.json +188 -0
- local_codebase_indexer-1.0.0/benchmarks/maintainer-project-results.json +1251 -0
- local_codebase_indexer-1.0.0/benchmarks/maintainer-project.json +136 -0
- local_codebase_indexer-1.0.0/benchmarks/navigation_task.json +11 -0
- local_codebase_indexer-1.0.0/benchmarks/performance-results.json +441 -0
- local_codebase_indexer-1.0.0/benchmarks/performance.py +281 -0
- local_codebase_indexer-1.0.0/benchmarks/real-project-results.json +9572 -0
- local_codebase_indexer-1.0.0/benchmarks/real-projects.json +1034 -0
- local_codebase_indexer-1.0.0/benchmarks/real_projects.py +279 -0
- local_codebase_indexer-1.0.0/benchmarks/tool-comparison-queries.jsonl +96 -0
- local_codebase_indexer-1.0.0/benchmarks/tool-comparison.json +148 -0
- local_codebase_indexer-1.0.0/benchmarks/v1-tool-comparison-queries.jsonl +96 -0
- local_codebase_indexer-1.0.0/benchmarks/v1-tool-comparison.json +148 -0
- local_codebase_indexer-1.0.0/docs/comparison-evidence.json +54 -0
- local_codebase_indexer-1.0.0/docs/contracts/codebase_get_data_access.json +412 -0
- local_codebase_indexer-1.0.0/docs/contracts/codebase_get_optimized_context.json +52 -0
- local_codebase_indexer-1.0.0/docs/contracts/codebase_get_symbol_relations.json +48 -0
- local_codebase_indexer-1.0.0/docs/contracts/codebase_impact_analysis.json +52 -0
- local_codebase_indexer-1.0.0/docs/contracts/codebase_index_doctor.json +48 -0
- local_codebase_indexer-1.0.0/docs/contracts/codebase_index_status.json +48 -0
- local_codebase_indexer-1.0.0/docs/contracts/codebase_semantic_search.json +95 -0
- local_codebase_indexer-1.0.0/docs/mcp-tools.json +1038 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/docs/reference.md +17 -2
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/docs/reference.zh-CN.md +18 -3
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/docs/reference.zh-TW.md +19 -4
- local_codebase_indexer-1.0.0/docs/tool-comparison.md +108 -0
- local_codebase_indexer-1.0.0/docs/v1-readiness.md +137 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/__init__.py +1 -1
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/cli.py +64 -11
- local_codebase_indexer-1.0.0/local_codebase_indexer/contracts.py +169 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/core.py +44 -26
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/cscalls.py +5 -4
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/csdata.py +85 -31
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/dataflow.py +174 -59
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/db.py +6 -2
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/impact.py +9 -4
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/langparse.py +20 -4
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/mcp_server.py +78 -21
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/pagination.py +3 -3
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/query.py +39 -17
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/relations.py +16 -4
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/rendering.py +3 -0
- local_codebase_indexer-1.0.0/local_codebase_indexer/reports.py +201 -0
- local_codebase_indexer-1.0.0/local_codebase_indexer/setup_project.py +98 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/sqlaccess.py +129 -25
- local_codebase_indexer-1.0.0/local_codebase_indexer/sqlidentity.py +121 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/vbdata.py +44 -6
- local_codebase_indexer-1.0.0/local_codebase_indexer/vector_cache.py +68 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer.egg-info/PKG-INFO +35 -5
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer.egg-info/SOURCES.txt +43 -1
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer.egg-info/requires.txt +5 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/pyproject.toml +3 -2
- local_codebase_indexer-1.0.0/scripts/check_mcp_clients.py +437 -0
- local_codebase_indexer-1.0.0/scripts/export_contracts.py +54 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/server.json +2 -2
- local_codebase_indexer-1.0.0/tests/test_provenance_boundaries.py +220 -0
- local_codebase_indexer-1.0.0/tests/test_tool_comparison.py +69 -0
- local_codebase_indexer-1.0.0/tests/test_v1_cache.py +77 -0
- local_codebase_indexer-1.0.0/tests/test_v1_contracts.py +191 -0
- local_codebase_indexer-1.0.0/tests/test_v1_scope.py +329 -0
- local_codebase_indexer-1.0.0/tests/test_v1_workflows.py +136 -0
- local_codebase_indexer-0.9.0/benchmarks/README.md +0 -35
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/.claude-plugin/marketplace.json +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/CLAUDE.md +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/LICENSE +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/MANIFEST.in +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/assets/demo-output.txt +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/assets/demo-preview.png +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/assets/demo-report.json +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/assets/demo.gif +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/baseline.json +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Auth/LoginService.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Controllers/LotController.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Controllers/ScrapController.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Data/MesDbContext.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Legacy/frmChangeLine.frm +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Models/DrillBreakEvent.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Models/Lot.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Models/ScrapRecord.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Printing/LabelPrinter.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Repositories/LotRepository.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Repositories/ScrapRepository.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Services/IScrapService.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Services/InspectionService.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Services/LotService.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Services/ScrapService.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Sql/MES_Lot.sql +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Sql/usp_Inspection_Report.sql +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Sql/usp_Lot_UpdateStatus.sql +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Sql/usp_Scrap_Insert.sql +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Utils/DateRangeHelper.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Utils/PartNumberDecoder.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Web/scrapForm.ts +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/Web.config +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/corpus/tools/export_report.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/queries_project.json +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/queries_stdlib.json +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/queries_synthetic.json +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/benchmarks/run_benchmark.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/bin/indexer +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/docs/case-study.md +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/docs/discovery.md +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/docs/launch/community.en.md +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/docs/launch/community.zh-TW.md +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/docs/launch/directory-entry.md +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/docs/sql-legacy-support.md +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/index.md +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/llms.txt +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/__main__.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/callgraph.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/context.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/demo.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/demo_project/Controllers/OrdersController.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/demo_project/Data/OrderRepository.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/demo_project/Models/Order.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/demo_project/README.md +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/demo_project/Services/IOrderService.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/demo_project/Services/OrderService.cs +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/demo_project/Sql/Sales_OrderHeader.sql +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/demo_project/Sql/usp_ApproveOrder.sql +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/demo_project/Views/Orders/Details.cshtml +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/embedder.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/evaluation.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/locking.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/query_common.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/scanner.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/synonyms.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer/textdecode.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer.egg-info/dependency_links.txt +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer.egg-info/entry_points.txt +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/local_codebase_indexer.egg-info/top_level.txt +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/plugins/local-codebase-indexer/.claude-plugin/plugin.json +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/plugins/local-codebase-indexer/.mcp.json +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/scripts/release_assets.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/scripts/render_demo.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/setup.cfg +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/tests/test_dataaccess.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/tests/test_demo.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/tests/test_evaluation.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/tests/test_indexer.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/tests/test_navigation_stability.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/tests/test_onnx_plumbing.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/tests/test_release_assets.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/tests/test_reliability.py +0 -0
- {local_codebase_indexer-0.9.0 → local_codebase_indexer-1.0.0}/tests/test_sql_regressions.py +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Instructions for AI coding assistants
|
|
2
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
|
|
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 source locations, confidence labels, and bounded context.
|
|
4
4
|
|
|
5
5
|
## Install (pick one)
|
|
6
6
|
|
|
@@ -80,10 +80,28 @@ Run `local-codebase-indexer demo` without a database or model. It uses a tempora
|
|
|
80
80
|
|
|
81
81
|
## SQL and legacy-source correctness (0.9.0)
|
|
82
82
|
|
|
83
|
-
- Run `python -m ruff check local_codebase_indexer scripts`, `python -m mypy`, and the full pytest suite before publishing. CI covers Linux and Windows on Python 3.10, 3.12, and 3.13.
|
|
83
|
+
- Run `python -m ruff check local_codebase_indexer scripts benchmarks/compare_tools.py benchmarks/real_projects.py benchmarks/performance.py tests/test_v1_*.py`, `python -m mypy`, and the full pytest suite before publishing. CI covers Linux and Windows on Python 3.10, 3.11, 3.12, and 3.13.
|
|
84
84
|
- Dependency declarations live in `pyproject.toml`; `requirements.txt` was removed to avoid drift.
|
|
85
85
|
- Source decoding and context extraction handle BOM-tagged UTF-16/UTF-32. True binary files are excluded consistently by scanning and status.
|
|
86
86
|
- `data-access` has additive `schema_changes` entries (`access=schema`) for table/index DDL. They are not row writers. File-level SQL changes appear in impact with before/current/after labels and source evidence.
|
|
87
87
|
- VB6 `.frm`/`.bas`/`.cls` SQL strings get procedure owners. Complete SQL at known ADO/DAO receivers may be confirmed; unknown receivers or incomplete concatenation remain probable/uncertain. No VB6 call graph or runtime execution proof is implied.
|
|
88
88
|
- Explicit negations in `.ai_context/ignore` can include default source directories such as `!bin/` and `!bin/**`, overriding `.gitignore`. Include excluded parents first. `.git`, `.svn`, `.hg`, and `.ai_context` remain excluded.
|
|
89
89
|
- Keep `query.py` as the facade/search implementation; navigation, source context, and rendering live in `relations.py`, `context.py`, and `rendering.py`. Legacy public imports from `query` remain supported.
|
|
90
|
+
|
|
91
|
+
## SQL provenance and tool comparison (0.9.1)
|
|
92
|
+
|
|
93
|
+
- SQL statement/batch boundaries and lexical bindings must not manufacture confirmed access from unrelated literals or shadowed parameters. Keep regression coverage in `tests/test_provenance_boundaries.py`.
|
|
94
|
+
- SQL object definitions come only from SQL sources; application symbol navigation still includes Python/JS functions.
|
|
95
|
+
- Index format 10 invalidates older parsed edges and rebuilds them on the first update. Keep package and Registry versions synchronized when preparing a release.
|
|
96
|
+
- Tool comparisons live in `docs/tool-comparison.md`; keep language READMEs in sync, cite upstream capabilities, and distinguish a literal-search baseline from a full Claude workflow. Do not claim measured speed/token/accuracy superiority without a corresponding experiment.
|
|
97
|
+
|
|
98
|
+
## SQL evidence and stable contracts (1.0.0)
|
|
99
|
+
|
|
100
|
+
- Index format 11 preserves SQL identity as lossless JSON components. Keep the last-segment key only as an indexed lookup accelerator; never use it alone to identify an object or expand procedure dependencies. Ambiguous short names must not combine confirmed accessors.
|
|
101
|
+
- C# symbol/SQL ownership uses AST byte ranges; same-line methods and overloads must remain separate. Symbol IDs are opaque revision-bound values.
|
|
102
|
+
- `path`, action-specific `programs[].paths`, and `coverage.warnings` explain representative static chains and SQL/C# cutoffs. Never claim complete runtime coverage from `complete_within_limits`.
|
|
103
|
+
- Preserve text MCP responses and the seven names. Structured outputs and corresponding CLI JSON use schema_version 1; keep MCP defaults bounded (5 data-access entries per section, exact pagination, nested truncation metadata) and only unbound nested data for explicit detail=true; export/check docs/contracts with `python scripts/export_contracts.py --check`. Supported old protocol versions must negotiate correctly.
|
|
104
|
+
- `init` writes project-local client configuration only, preserves unrelated settings, rejects conflicts/symlink escapes, and leaves client trust prompts intact. Report export must escape source text, work without remote assets, and require explicit overwrite.
|
|
105
|
+
- Cache vectors only within a configured budget and a committed index revision/embedder identity; scoped searches and other-process updates must not reuse stale/wrong rows. Lexical mode skips vectors and SQL routing; bind cursors to mode.
|
|
106
|
+
- Keep benchmarks/real-projects.json frozen; it has 100 project-authored development questions over three real pinned repositories, not independent user validation. Never edit gold or lower a regression budget to hide a failure. Preserve losses, workload boundaries and raw observations.
|
|
107
|
+
- Actual Claude/Codex transport tests use a deterministic local model stub, not hosted reasoning. Recorded native Codex events verify a prior tool round trip; automatic CI runs SDK + Claude. Review client configuration and normal state-directory/network needs before invoking optional real-client checks.
|
|
@@ -1,5 +1,33 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 1.0.0 — 2026-11-20
|
|
4
|
+
|
|
5
|
+
- Simplify all three READMEs: remove development-stage notes, repeated benchmarks, and maintainer-specific acceptance narratives; retain practical setup/report commands and source-backed tool comparisons.
|
|
6
|
+
|
|
7
|
+
- Keep BOM-tagged UTF-16/UTF-32 SQL eligible in doctor, matching indexing/status; add separate maintainer-supplied Python workflow/retrieval acceptance.
|
|
8
|
+
|
|
9
|
+
- Preserve four-part SQL identities, delimited dots, explicit USE context, EF schema mappings, and quoted C# stored-procedure names. Return qualified candidates for ambiguous short names; keep unresolved scope under possible instead of confirmed.
|
|
10
|
+
- Use AST byte ranges for compact C# source ownership and distinct same-line overload IDs; preserve differently qualified SQL accesses on the same source line.
|
|
11
|
+
- Add representative source-evidence paths, action-specific page locations, bounded SQL/C# depth controls, and visible cutoff/unavailable-definition warnings, including Git impact metadata.
|
|
12
|
+
- Negotiate supported MCP protocol versions; provide structured results/output schemas and matching CLI JSON metadata while retaining legacy text. Add seven checked-in contracts, a full tool manifest, bounded structured defaults with exact truncation/pagination, retryable busy errors, and official-SDK tests.
|
|
13
|
+
- Add project-local init/configuration, stderr indexing progress, and offline escaped HTML/SVG, Mermaid and JSON impact reports with explicit overwrite handling.
|
|
14
|
+
- Add optional lexical search, soft file diversity, and a bounded revision-aware in-process vector cache; bind cursors to retrieval mode/algorithm.
|
|
15
|
+
- Add 100 frozen navigation questions on three pinned public C# projects, baseline/candidate records, real-client transport evidence using a local mock model, and 10k/50k/100k scaling/update/Git-switch measurements. Preserve retrieval losses and limits on interpretation.
|
|
16
|
+
- Extend Linux/Windows CI to Python 3.11, package the new tests/dependencies, check contracts, run public-code/performance smoke evaluations, and test Claude transport automatically. Codex native tool events are recorded from a manual transport run.
|
|
17
|
+
- Synchronize English/Traditional Chinese/Simplified Chinese README and reference additions; correct obsolete JOIN and index-format guidance.
|
|
18
|
+
- Index format 11 rebuilds older parsed data on the first update. Package and MCP Registry versions are synchronized at 1.0.0.
|
|
19
|
+
|
|
20
|
+
## 0.9.1
|
|
21
|
+
|
|
22
|
+
- Bound dynamic `sp_executesql` analysis to its SQL argument and statement; preserve uncertainty for quoted procedure names and exclude unrelated literals/column names.
|
|
23
|
+
- Scope CTE exclusions to one consuming statement/batch, including omitted semicolons and UNION/INSERT SELECT and stop UPDATE/DELETE alias lookup at the next command, including commands without semicolons.
|
|
24
|
+
- Preserve comma sources following JOIN predicates that use qualified `go` columns; recognize GO only as a batch separator line.
|
|
25
|
+
- Restrict SQL object definitions/suggestions to SQL source files so application functions do not become tables/procedures or redirect SQL search routing.
|
|
26
|
+
- Respect C#/VB6 parameter and local shadowing, invalidate overwritten SQL, and avoid interpreting query parameters as SQL. Preserve earlier valid execution evidence and known ADO declarations.
|
|
27
|
+
- Add English/Traditional Chinese/Simplified Chinese tool comparisons with documented trade-offs, pinned upstream sources, and a reproducible literal-search/relation-report example.
|
|
28
|
+
- Quantify those comparisons with a reproducible ripgrep + BM25 baseline, unchanged retrieval questions, raw per-query records, file-level recall/MRR, exact character denominators, and CLI evidence coverage/latency. Show stdlib losses and tiny-file output overhead alongside MES gains in all three READMEs. Add benchmark protocol regression tests and a CI artifact smoke run.
|
|
29
|
+
- Index format 10 rebuilds stale parsing results on the first update. Package and Registry versions remain unchanged until a release is prepared.
|
|
30
|
+
|
|
3
31
|
## 0.9.0
|
|
4
32
|
|
|
5
33
|
- Fix a first-run Windows lock-file initialization race found by concurrent-process CI; serialize index ignore-file creation.
|
|
@@ -8,7 +8,7 @@ Use Python 3.10+ in a virtual environment:
|
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
10
|
python -m pip install -e ".[dev,onnx]" onnx build twine
|
|
11
|
-
python -m ruff check local_codebase_indexer scripts
|
|
11
|
+
python -m ruff check local_codebase_indexer scripts benchmarks/compare_tools.py benchmarks/real_projects.py benchmarks/performance.py
|
|
12
12
|
python -m mypy
|
|
13
13
|
python -m pytest -q
|
|
14
14
|
python -m build
|
|
@@ -33,3 +33,14 @@ Add verified questions and expected source locations when a new behavior needs c
|
|
|
33
33
|
Public documentation and Release notes use English, with Traditional/Simplified Chinese README translations. Keep generated demo assets in sync by running `python scripts/render_demo.py` after installing `.[media]`.
|
|
34
34
|
|
|
35
35
|
Contributions are under this repository's [MIT license](LICENSE).
|
|
36
|
+
|
|
37
|
+
## v1 readiness checks
|
|
38
|
+
|
|
39
|
+
Run `python scripts/export_contracts.py --check` and the full tests, including official MCP client schema validation. Optional evaluations:
|
|
40
|
+
|
|
41
|
+
```bash
|
|
42
|
+
python benchmarks/real_projects.py --baseline-source /path/to/0.9.1-checkout --save /tmp/real-projects.json
|
|
43
|
+
python benchmarks/performance.py --sizes 10000 50000 100000 --save /tmp/performance.json
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
Use paths suitable for your OS. Questions, pinned sources, gold and budgets are fixed; report losses and failed questions. These are development/public-code/scaling workloads, not independent production accuracy or human investigation studies. Client CLI checks use a deterministic local model; review their configuration/network behavior and normal state-directory needs before running them. See [v1 evidence and limitations](docs/v1-readiness.md).
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: local-codebase-indexer
|
|
3
|
-
Version: 0.
|
|
3
|
+
Version: 1.0.0
|
|
4
4
|
Summary: Trace SQL Server tables to C# callers and Razor pages locally. MCP server and CLI for code search and change impact.
|
|
5
5
|
Author: sfy257000
|
|
6
6
|
License-Expression: MIT
|
|
@@ -10,7 +10,7 @@ Project-URL: Issues, https://github.com/sfy257000/local-codebase-indexer/issues
|
|
|
10
10
|
Project-URL: Documentation, https://github.com/sfy257000/local-codebase-indexer/blob/main/docs/reference.md
|
|
11
11
|
Project-URL: Case study, https://github.com/sfy257000/local-codebase-indexer/blob/main/docs/case-study.md
|
|
12
12
|
Keywords: mcp,model-context-protocol,claude-code,code-search,semantic-search,codebase-index,tree-sitter,sqlite,stored-procedure,csharp,dapper,t-sql,call-graph,ai-coding-assistant
|
|
13
|
-
Classifier: Development Status ::
|
|
13
|
+
Classifier: Development Status :: 5 - Production/Stable
|
|
14
14
|
Classifier: Environment :: Console
|
|
15
15
|
Classifier: Intended Audience :: Developers
|
|
16
16
|
Classifier: Programming Language :: Python :: 3
|
|
@@ -31,6 +31,7 @@ Requires-Dist: tree-sitter-javascript
|
|
|
31
31
|
Requires-Dist: tree-sitter-typescript
|
|
32
32
|
Requires-Dist: numpy
|
|
33
33
|
Requires-Dist: pathspec>=0.12.1
|
|
34
|
+
Requires-Dist: tomli>=2; python_version < "3.11"
|
|
34
35
|
Provides-Extra: onnx
|
|
35
36
|
Requires-Dist: onnxruntime; extra == "onnx"
|
|
36
37
|
Requires-Dist: tokenizers; extra == "onnx"
|
|
@@ -38,13 +39,15 @@ Provides-Extra: dev
|
|
|
38
39
|
Requires-Dist: pytest; extra == "dev"
|
|
39
40
|
Requires-Dist: ruff>=0.9; extra == "dev"
|
|
40
41
|
Requires-Dist: mypy>=1.14; extra == "dev"
|
|
42
|
+
Requires-Dist: jsonschema>=4; extra == "dev"
|
|
43
|
+
Requires-Dist: mcp<2,>=1.12; extra == "dev"
|
|
41
44
|
Provides-Extra: media
|
|
42
45
|
Requires-Dist: Pillow>=10; extra == "media"
|
|
43
46
|
Dynamic: license-file
|
|
44
47
|
|
|
45
48
|
# Local Codebase Indexer
|
|
46
49
|
|
|
47
|
-
**English** | [繁體中文](
|
|
50
|
+
**English** | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
|
|
48
51
|
|
|
49
52
|
**Which C# code and pages reach this SQL Server table?**
|
|
50
53
|
|
|
@@ -54,6 +57,31 @@ Trace tables and stored procedures to repositories, controller actions, and Razo
|
|
|
54
57
|
|
|
55
58
|
[Case study and raw results](https://github.com/sfy257000/local-codebase-indexer/blob/main/docs/case-study.md) · [CLI reference](https://github.com/sfy257000/local-codebase-indexer/blob/main/docs/reference.md) · [PyPI](https://pypi.org/project/local-codebase-indexer/) · [MIT license](https://github.com/sfy257000/local-codebase-indexer/blob/main/LICENSE)
|
|
56
59
|
|
|
60
|
+
## How it compares with Claude's Grep and similar tools
|
|
61
|
+
|
|
62
|
+
**Measured on our MES fixtures: +9.5–13.1 percentage points in relevant-file recall versus `rg + BM25`.** For the bundled SQL → C# → page investigation, the relation report covers **5/5 required evidence files**, versus **3/5** from one literal table-name search (**+40 points**).
|
|
63
|
+
|
|
64
|
+
| Fixed retrieval suite | `rg + BM25` file Recall@5 | This project | Difference |
|
|
65
|
+
|---|---:|---:|---:|
|
|
66
|
+
| MES-style synthetic: 42 questions, 24 files | 81.0% | **94.0%** | **+13.1 pp** |
|
|
67
|
+
| Same 42 questions with distractors: 109 files | 81.0% | **90.5%** | **+9.5 pp** |
|
|
68
|
+
| Python stdlib: 12 questions, 85 real source files | **100.0%** | 79.2% | −20.8 pp |
|
|
69
|
+
|
|
70
|
+
Recall is averaged over 54 project-authored questions (96 executions including the noisy rerun). The indexer returns 5 chunks; `rg + BM25` returns 5 files, and both are scored by file. This is a fixed-fixture comparison, not a complete Claude agent benchmark.
|
|
71
|
+
|
|
72
|
+
The richer relation report is slower than a single literal search: **228.5 ms versus 18.8 ms** on the bundled scenario (three-run medians). Controller reachability is `probable`, not runtime proof. [Protocol](docs/v1-readiness.md#candidate-versus-the-literal-search-baseline) · [Raw results](benchmarks/v1-tool-comparison.json) · [Per-query records](benchmarks/v1-tool-comparison-queries.jsonl).
|
|
73
|
+
|
|
74
|
+
**The extra value is an indexed SQL → C# → page relation report.** For supported patterns, one `data-access` query returns direct/procedure-mediated access, controller actions, page links, and confidence labels. Claude can also follow these links through multiple Grep searches and file reads; this tool packages that investigation into a repeatable CLI/MCP result.
|
|
75
|
+
|
|
76
|
+
| Tool / workflow | Strong fit | Trade-off and where this project helps |
|
|
77
|
+
|---|---|---|
|
|
78
|
+
| Claude + Grep / ripgrep | Exact identifiers, strings, and regex; no index setup | Keep it for direct text checks. This project's SQL/call/page relations go beyond the literal table-name matches. |
|
|
79
|
+
| [Serena](https://github.com/oraios/serena) with LSP / JetBrains | Backend-driven symbols, references, and editing/refactoring | Prefer compiler/IDE semantics for accurate renames and overloads. This project provides a focused SQL maintenance report without a language-server backend. |
|
|
80
|
+
| [Claude Context](https://github.com/zilliztech/claude-context) | Natural-language hybrid BM25 + dense-vector retrieval | Its documented setup uses an embedding provider and Milvus/Zilliz configuration; local providers are supported. This project's default needs no embedding API or vector server, but identifier-oriented hashing can miss paraphrases. |
|
|
81
|
+
| Local Codebase Indexer | SQL Server table/procedure → C# accessors → actions/pages; schema and Git impact | Approximate static analysis with visible confidence; no Roslyn overload resolution or semantic rename. |
|
|
82
|
+
|
|
83
|
+
The controller and Razor page in the demo contain no literal table name; the relation report reaches them through the stored procedure and C# calls. All **4 built-in relationship checks pass**. See [source evidence and upstream feature references](docs/tool-comparison.md).
|
|
84
|
+
|
|
57
85
|
## Try it in three steps
|
|
58
86
|
|
|
59
87
|
Python **3.10+**. Run these in a virtual environment; no SQL Server, .NET runtime, model download, or API key is needed for the demo.
|
|
@@ -99,10 +127,11 @@ Replace the path and table name. The first query builds the index; subsequent qu
|
|
|
99
127
|
|
|
100
128
|
## Give the same evidence to your assistant
|
|
101
129
|
|
|
102
|
-
|
|
130
|
+
After installation, choose your client to create project-local MCP configuration:
|
|
103
131
|
|
|
104
132
|
```bash
|
|
105
|
-
|
|
133
|
+
local-codebase-indexer --root "/absolute/path/to/project" init --client claude
|
|
134
|
+
local-codebase-indexer --root "/absolute/path/to/project" init --client codex
|
|
106
135
|
```
|
|
107
136
|
|
|
108
137
|
Ask: “Which code writes `YourTable`, and which controller actions and pages reach it? Show paths and confidence levels.” Restart/reconnect the MCP client if needed. For other stdio MCP clients, use command `local-codebase-indexer` and arguments `--root`, your absolute project path, `serve`.
|
|
@@ -116,6 +145,7 @@ local-codebase-indexer --root "/path/to/project" relations OrderRepository.Appro
|
|
|
116
145
|
local-codebase-indexer --root "/path/to/project" impact main...HEAD
|
|
117
146
|
local-codebase-indexer --root "/path/to/project" search "order approval" --explain --limit 5
|
|
118
147
|
local-codebase-indexer --root "/path/to/project" doctor
|
|
148
|
+
local-codebase-indexer --root "/path/to/project" report dbo.YourTable --output table-impact.html
|
|
119
149
|
```
|
|
120
150
|
|
|
121
151
|
Relations show callers; impact compares Git snapshots; search combines identifiers, text, and local embeddings. C#, Python, JavaScript, and TypeScript have symbol parsing; T-SQL and C# have additional data-access analysis. Add `--json` for structured output.
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Local Codebase Indexer
|
|
2
2
|
|
|
3
|
-
**English** | [繁體中文](
|
|
3
|
+
**English** | [繁體中文](README.zh-TW.md) | [简体中文](README.zh-CN.md)
|
|
4
4
|
|
|
5
5
|
**Which C# code and pages reach this SQL Server table?**
|
|
6
6
|
|
|
@@ -10,6 +10,31 @@ Trace tables and stored procedures to repositories, controller actions, and Razo
|
|
|
10
10
|
|
|
11
11
|
[Case study and raw results](https://github.com/sfy257000/local-codebase-indexer/blob/main/docs/case-study.md) · [CLI reference](https://github.com/sfy257000/local-codebase-indexer/blob/main/docs/reference.md) · [PyPI](https://pypi.org/project/local-codebase-indexer/) · [MIT license](https://github.com/sfy257000/local-codebase-indexer/blob/main/LICENSE)
|
|
12
12
|
|
|
13
|
+
## How it compares with Claude's Grep and similar tools
|
|
14
|
+
|
|
15
|
+
**Measured on our MES fixtures: +9.5–13.1 percentage points in relevant-file recall versus `rg + BM25`.** For the bundled SQL → C# → page investigation, the relation report covers **5/5 required evidence files**, versus **3/5** from one literal table-name search (**+40 points**).
|
|
16
|
+
|
|
17
|
+
| Fixed retrieval suite | `rg + BM25` file Recall@5 | This project | Difference |
|
|
18
|
+
|---|---:|---:|---:|
|
|
19
|
+
| MES-style synthetic: 42 questions, 24 files | 81.0% | **94.0%** | **+13.1 pp** |
|
|
20
|
+
| Same 42 questions with distractors: 109 files | 81.0% | **90.5%** | **+9.5 pp** |
|
|
21
|
+
| Python stdlib: 12 questions, 85 real source files | **100.0%** | 79.2% | −20.8 pp |
|
|
22
|
+
|
|
23
|
+
Recall is averaged over 54 project-authored questions (96 executions including the noisy rerun). The indexer returns 5 chunks; `rg + BM25` returns 5 files, and both are scored by file. This is a fixed-fixture comparison, not a complete Claude agent benchmark.
|
|
24
|
+
|
|
25
|
+
The richer relation report is slower than a single literal search: **228.5 ms versus 18.8 ms** on the bundled scenario (three-run medians). Controller reachability is `probable`, not runtime proof. [Protocol](docs/v1-readiness.md#candidate-versus-the-literal-search-baseline) · [Raw results](benchmarks/v1-tool-comparison.json) · [Per-query records](benchmarks/v1-tool-comparison-queries.jsonl).
|
|
26
|
+
|
|
27
|
+
**The extra value is an indexed SQL → C# → page relation report.** For supported patterns, one `data-access` query returns direct/procedure-mediated access, controller actions, page links, and confidence labels. Claude can also follow these links through multiple Grep searches and file reads; this tool packages that investigation into a repeatable CLI/MCP result.
|
|
28
|
+
|
|
29
|
+
| Tool / workflow | Strong fit | Trade-off and where this project helps |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| Claude + Grep / ripgrep | Exact identifiers, strings, and regex; no index setup | Keep it for direct text checks. This project's SQL/call/page relations go beyond the literal table-name matches. |
|
|
32
|
+
| [Serena](https://github.com/oraios/serena) with LSP / JetBrains | Backend-driven symbols, references, and editing/refactoring | Prefer compiler/IDE semantics for accurate renames and overloads. This project provides a focused SQL maintenance report without a language-server backend. |
|
|
33
|
+
| [Claude Context](https://github.com/zilliztech/claude-context) | Natural-language hybrid BM25 + dense-vector retrieval | Its documented setup uses an embedding provider and Milvus/Zilliz configuration; local providers are supported. This project's default needs no embedding API or vector server, but identifier-oriented hashing can miss paraphrases. |
|
|
34
|
+
| Local Codebase Indexer | SQL Server table/procedure → C# accessors → actions/pages; schema and Git impact | Approximate static analysis with visible confidence; no Roslyn overload resolution or semantic rename. |
|
|
35
|
+
|
|
36
|
+
The controller and Razor page in the demo contain no literal table name; the relation report reaches them through the stored procedure and C# calls. All **4 built-in relationship checks pass**. See [source evidence and upstream feature references](docs/tool-comparison.md).
|
|
37
|
+
|
|
13
38
|
## Try it in three steps
|
|
14
39
|
|
|
15
40
|
Python **3.10+**. Run these in a virtual environment; no SQL Server, .NET runtime, model download, or API key is needed for the demo.
|
|
@@ -55,10 +80,11 @@ Replace the path and table name. The first query builds the index; subsequent qu
|
|
|
55
80
|
|
|
56
81
|
## Give the same evidence to your assistant
|
|
57
82
|
|
|
58
|
-
|
|
83
|
+
After installation, choose your client to create project-local MCP configuration:
|
|
59
84
|
|
|
60
85
|
```bash
|
|
61
|
-
|
|
86
|
+
local-codebase-indexer --root "/absolute/path/to/project" init --client claude
|
|
87
|
+
local-codebase-indexer --root "/absolute/path/to/project" init --client codex
|
|
62
88
|
```
|
|
63
89
|
|
|
64
90
|
Ask: “Which code writes `YourTable`, and which controller actions and pages reach it? Show paths and confidence levels.” Restart/reconnect the MCP client if needed. For other stdio MCP clients, use command `local-codebase-indexer` and arguments `--root`, your absolute project path, `serve`.
|
|
@@ -72,6 +98,7 @@ local-codebase-indexer --root "/path/to/project" relations OrderRepository.Appro
|
|
|
72
98
|
local-codebase-indexer --root "/path/to/project" impact main...HEAD
|
|
73
99
|
local-codebase-indexer --root "/path/to/project" search "order approval" --explain --limit 5
|
|
74
100
|
local-codebase-indexer --root "/path/to/project" doctor
|
|
101
|
+
local-codebase-indexer --root "/path/to/project" report dbo.YourTable --output table-impact.html
|
|
75
102
|
```
|
|
76
103
|
|
|
77
104
|
Relations show callers; impact compares Git snapshots; search combines identifiers, text, and local embeddings. C#, Python, JavaScript, and TypeScript have symbol parsing; T-SQL and C# have additional data-access analysis. Add `--json` for structured output.
|
|
@@ -10,6 +10,31 @@
|
|
|
10
10
|
|
|
11
11
|
[可复现案例及完整输出](docs/case-study.md) · [进阶手册](docs/reference.zh-CN.md) · [PyPI](https://pypi.org/project/local-codebase-indexer/) · [MIT 许可](LICENSE)
|
|
12
12
|
|
|
13
|
+
## 与 Claude 的 Grep 及类似工具比较
|
|
14
|
+
|
|
15
|
+
**在本项目的 MES 测试集,相关文件召回率比 `rg + BM25` 高 9.5~13.1 个百分点。** 内置 SQL → C# → 页面调查场景中,关系报告覆盖 **5/5 个必要证据文件**,单次表名字面搜索为 **3/5**,覆盖率 **60% → 100%(+40 个百分点)**。
|
|
16
|
+
|
|
17
|
+
| 固定搜索测试集 | `rg + BM25` 文件 Recall@5 | 本项目 | 差异 |
|
|
18
|
+
|---|---:|---:|---:|
|
|
19
|
+
| MES 风格合成数据:42 题、24 个文件 | 81.0% | **94.0%** | **+13.1 个百分点** |
|
|
20
|
+
| 相同 42 题加入干扰来源:109 个文件 | 81.0% | **90.5%** | **+9.5 个百分点** |
|
|
21
|
+
| Python 标准库:12 题、85 个真实源代码文件 | **100.0%** | 79.2% | −20.8 个百分点 |
|
|
22
|
+
|
|
23
|
+
召回率取 54 道项目自编题目的平均(含噪声集重跑共 96 次)。本工具取 5 个代码块,`rg + BM25` 取 5 个文件,双方按文件评分。这是固定案例比较,并非完整 Claude agent 流程的评测。
|
|
24
|
+
|
|
25
|
+
关系报告比单次字面搜索慢:示例中为 **228.5 ms 对 18.8 ms**(各 3 次中位数)。Controller 路径标为 `probable`,不代表运行时证明。[方法](docs/v1-readiness.md#candidate-versus-the-literal-search-baseline) · [原始数据](benchmarks/v1-tool-comparison.json) · [逐题记录](benchmarks/v1-tool-comparison-queries.jsonl)。
|
|
26
|
+
|
|
27
|
+
**这个项目多提供的是 SQL → C# → 页面的索引关系报告。** 在支持的代码模式中,一次 `data-access` 查询就能列出直接/通过存储过程的访问、Controller Action、页面与置信度标签。Claude 也能通过多轮 Grep 和读文件追踪关系;该工具将这段调查整理成可重复执行的 CLI/MCP 结果。
|
|
28
|
+
|
|
29
|
+
| 工具/流程 | 适合用途 | 取舍与本项目的用途 |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| Claude+Grep/ripgrep | 精确标识符、字符串和正则表达式,无需建立索引 | 直接核对文本仍优先使用。该项目另提供字面表名以外的 SQL/调用/页面关系。 |
|
|
32
|
+
| [Serena](https://github.com/oraios/serena)+LSP/JetBrains | 后端提供的符号、引用和编辑/重构 | 精确 rename、重载解析优先使用编译器/IDE 语义。本项目聚焦 SQL 维护报告,无需配置语言服务器。 |
|
|
33
|
+
| [Claude Context](https://github.com/zilliztech/claude-context) | 自然语言的 BM25+dense vector 混合搜索 | 官方配置包含 embedding provider 和 Milvus/Zilliz,也支持本地 provider。本项目默认无需 embedding API 或向量服务器,但 hashing 仍可能遗漏自然语言改写。 |
|
|
34
|
+
| Local Codebase Indexer | SQL Server 表/存储过程 → C# 访问者 → Action/页面,以及 schema、Git impact | 带有置信度标签的近似静态分析,没有 Roslyn 重载解析或语义 rename。 |
|
|
35
|
+
|
|
36
|
+
示例的 Controller 和 Razor 页面不含该表名字符串;关系报告通过存储过程和 C# 调用追踪到它们,**4 项内置关系检查通过**。[源代码证据与上游功能资料](docs/tool-comparison.md)。
|
|
37
|
+
|
|
13
38
|
## 三步开始
|
|
14
39
|
|
|
15
40
|
需要 **Python 3.10+**,建议在虚拟环境执行。内置 demo 不需要 SQL Server、.NET 运行环境、模型下载或 API key。
|
|
@@ -55,10 +80,11 @@ local-codebase-indexer --root "/path/to/project" data-access YourTable
|
|
|
55
80
|
|
|
56
81
|
## 接入 AI 助手
|
|
57
82
|
|
|
58
|
-
|
|
83
|
+
安装软件包后,按使用的客户端选择一个命令,创建项目内 MCP 配置:
|
|
59
84
|
|
|
60
85
|
```bash
|
|
61
|
-
|
|
86
|
+
local-codebase-indexer --root "/absolute/path/to/project" init --client claude
|
|
87
|
+
local-codebase-indexer --root "/absolute/path/to/project" init --client codex
|
|
62
88
|
```
|
|
63
89
|
|
|
64
90
|
可以问:“哪些代码写入 `YourTable`?哪些 Controller Action 和页面会到达它?请列出路径和置信度。”必要时重新连接或重启 MCP 客户端。
|
|
@@ -72,6 +98,7 @@ local-codebase-indexer --root "/path/to/project" relations OrderRepository.Appro
|
|
|
72
98
|
local-codebase-indexer --root "/path/to/project" impact main...HEAD
|
|
73
99
|
local-codebase-indexer --root "/path/to/project" search "order approval" --explain --limit 5
|
|
74
100
|
local-codebase-indexer --root "/path/to/project" doctor
|
|
101
|
+
local-codebase-indexer --root "/path/to/project" report dbo.YourTable --output table-impact.html
|
|
75
102
|
```
|
|
76
103
|
|
|
77
104
|
可查询调用者、Git 版本间影响,以及结合标识符、文本和本地 embedding 的搜索。C#、Python、JavaScript、TypeScript 支持符号解析;T-SQL 和 C# 另有数据访问分析。加上 `--json` 获取结构化结果。
|
|
@@ -10,6 +10,31 @@
|
|
|
10
10
|
|
|
11
11
|
[可重現案例與完整輸出](docs/case-study.md) · [進階手冊](docs/reference.zh-TW.md) · [PyPI](https://pypi.org/project/local-codebase-indexer/) · [MIT 授權](LICENSE)
|
|
12
12
|
|
|
13
|
+
## 與 Claude 的 Grep 及類似工具比較
|
|
14
|
+
|
|
15
|
+
**在本專案的 MES 測試集,相關檔案召回率比 `rg + BM25` 高 9.5~13.1 個百分點。** 內建 SQL → C# → 頁面調查情境中,關係報告涵蓋 **5/5 個必要證據檔案**,單次表名字面搜尋為 **3/5**,涵蓋率 **60% → 100%(+40 個百分點)**。
|
|
16
|
+
|
|
17
|
+
| 固定搜尋測試集 | `rg + BM25` 檔案 Recall@5 | 本專案 | 差異 |
|
|
18
|
+
|---|---:|---:|---:|
|
|
19
|
+
| MES 風格合成資料:42 題、24 個檔案 | 81.0% | **94.0%** | **+13.1 個百分點** |
|
|
20
|
+
| 相同 42 題加入干擾來源:109 個檔案 | 81.0% | **90.5%** | **+9.5 個百分點** |
|
|
21
|
+
| Python 標準函式庫:12 題、85 個真實原始碼檔案 | **100.0%** | 79.2% | −20.8 個百分點 |
|
|
22
|
+
|
|
23
|
+
召回率取 54 題專案自編題目的平均(含雜訊集重跑共 96 次)。本工具取 5 個程式區塊,`rg + BM25` 取 5 個檔案,雙方以檔案計分。這是固定案例比較,並非完整 Claude agent 流程的評測。
|
|
24
|
+
|
|
25
|
+
關係報告比單次字面搜尋慢:範例中為 **228.5 ms 對 18.8 ms**(各 3 次中位數)。Controller 路徑標為 `probable`,不代表執行期證明。[方法](docs/v1-readiness.md#candidate-versus-the-literal-search-baseline) · [原始數據](benchmarks/v1-tool-comparison.json) · [逐題紀錄](benchmarks/v1-tool-comparison-queries.jsonl)。
|
|
26
|
+
|
|
27
|
+
**這個專案多提供的是 SQL → C# → 頁面的索引關係報告。** 在支援的程式模式中,一次 `data-access` 查詢就能列出直接/透過預存程序的存取、Controller Action、頁面與信心標籤。Claude 也能透過多輪 Grep 與讀檔追出關係;此工具把這段調查整理成可重複執行的 CLI/MCP 結果。
|
|
28
|
+
|
|
29
|
+
| 工具/流程 | 適合用途 | 取捨與本專案的用途 |
|
|
30
|
+
|---|---|---|
|
|
31
|
+
| Claude+Grep/ripgrep | 精確識別字、字串與正規表示式,不需建索引 | 直接核對文字仍優先使用。此專案另提供字面資料表名稱以外的 SQL/呼叫/頁面關係。 |
|
|
32
|
+
| [Serena](https://github.com/oraios/serena)+LSP/JetBrains | 後端提供的符號、引用與編輯/重構 | 精確 rename、多載解析優先使用編譯器/IDE 語意。本專案聚焦 SQL 維護報告,不需設定語言伺服器。 |
|
|
33
|
+
| [Claude Context](https://github.com/zilliztech/claude-context) | 自然語言的 BM25+dense vector 混合搜尋 | 官方設定含 embedding provider 與 Milvus/Zilliz,也支援本機 provider。本專案預設不需 embedding API 或向量伺服器,但 hashing 仍可能漏掉自然語言改寫。 |
|
|
34
|
+
| Local Codebase Indexer | SQL Server 表/預存程序 → C# 存取者 → Action/頁面,以及 schema、Git impact | 帶有信心標籤的近似靜態分析,沒有 Roslyn 多載解析或語意 rename。 |
|
|
35
|
+
|
|
36
|
+
範例的 Controller 與 Razor 頁面沒有該表名字串;關係報告透過預存程序與 C# 呼叫追到它們,**4 項內建關係檢查通過**。[原始碼證據與上游功能資料](docs/tool-comparison.md)。
|
|
37
|
+
|
|
13
38
|
## 三步開始
|
|
14
39
|
|
|
15
40
|
需要 **Python 3.10+**,建議在虛擬環境執行。內建 demo 不需要 SQL Server、.NET 執行環境、模型下載或 API key。
|
|
@@ -55,10 +80,11 @@ local-codebase-indexer --root "/path/to/project" data-access YourTable
|
|
|
55
80
|
|
|
56
81
|
## 接上 AI 助手
|
|
57
82
|
|
|
58
|
-
|
|
83
|
+
安裝套件後,依使用的用戶端選一個命令,建立專案內 MCP 設定:
|
|
59
84
|
|
|
60
85
|
```bash
|
|
61
|
-
|
|
86
|
+
local-codebase-indexer --root "/absolute/path/to/project" init --client claude
|
|
87
|
+
local-codebase-indexer --root "/absolute/path/to/project" init --client codex
|
|
62
88
|
```
|
|
63
89
|
|
|
64
90
|
可以問:「哪些程式寫入 `YourTable`?哪些 Controller Action 與頁面會到達它?請列出路徑與信心等級。」必要時重新連線或重啟 MCP 用戶端。
|
|
@@ -72,6 +98,7 @@ local-codebase-indexer --root "/path/to/project" relations OrderRepository.Appro
|
|
|
72
98
|
local-codebase-indexer --root "/path/to/project" impact main...HEAD
|
|
73
99
|
local-codebase-indexer --root "/path/to/project" search "order approval" --explain --limit 5
|
|
74
100
|
local-codebase-indexer --root "/path/to/project" doctor
|
|
101
|
+
local-codebase-indexer --root "/path/to/project" report dbo.YourTable --output table-impact.html
|
|
75
102
|
```
|
|
76
103
|
|
|
77
104
|
可查呼叫者、Git 版本間影響,以及結合識別字、文字與本機 embedding 的搜尋。C#、Python、JavaScript、TypeScript 支援符號解析;T-SQL 與 C# 另有資料存取分析。加上 `--json` 可取得結構化結果。
|
|
@@ -4,9 +4,12 @@ Priorities come from the benchmark (`benchmarks/run_benchmark.py`, baseline in `
|
|
|
4
4
|
|
|
5
5
|
## Next
|
|
6
6
|
|
|
7
|
+
- Validate independent maintainer-authored SQL impact tasks and actual investigation time before making production-accuracy or time-savings claims. The new 100-question public-code development evaluation is source-reviewed but project-authored; its generic retrieval Recall@5 remains 48%.
|
|
8
|
+
- Continue improving broad paraphrase retrieval. See [v1 implementation and evidence](docs/v1-readiness.md); SDK/Claude automatic checks and recorded native Codex transport evidence do not measure model reasoning.
|
|
9
|
+
|
|
7
10
|
0. **MCP Registry discovery**: the 0.8.0 release workflow publishes `server.json` after PyPI succeeds, using GitHub OIDC. Verify the live entry after each release; a local manifest alone does not establish publication. See [discovery instructions](docs/discovery.md).
|
|
8
11
|
1. **Remaining data-flow gaps**: non-sink SQL proc-name literals (`Run("usp_X")`), EF `this.ToTable(..)` inside `EntityTypeConfiguration<T>` (entity not taken from the base class yet), and EF updates through tracked entities when the entity was loaded in another method than the one calling `SaveChanges` (only same-method read + `SaveChanges` is listed, as uncertain).
|
|
9
|
-
2. **C# call graph gaps**: overload resolution by argument type, delegates / lambdas / extension methods,
|
|
12
|
+
2. **C# call graph gaps**: overload resolution by argument type, delegates / lambdas / extension methods, return-type inference across chained receiver expressions. Without Roslyn these stay approximate; edges carry `confirmed` / `probable` / `candidate`.
|
|
10
13
|
|
|
11
14
|
## Deferred (not worth doing yet)
|
|
12
15
|
|
|
@@ -15,13 +18,14 @@ Priorities come from the benchmark (`benchmarks/run_benchmark.py`, baseline in `
|
|
|
15
18
|
| Real embedding model as default | Measured 0.4.0 on a real 30k-chunk C# codebase with Chinese comments, 12 paraphrased queries (6 zh, 6 en): hashing MRR 0.48 / hit@5 6, `all-MiniLM-L6-v2` 0.29 / 6, `paraphrase-multilingual-MiniLM-L12-v2` (int8) 0.41 / 6; full index 128 s vs 35 / 43 min. Benchmark: MiniLM +0.08-0.13 MRR, multilingual -0.01..+0.03. Domain jargon ("split a lot into two") was missed by all three | A model trained on code + Chinese, or embedding becomes incremental enough that branch switches stay under a minute |
|
|
16
19
|
| Content-hash cache of parse results across branch switches | Measured: a switch that rewrites 400 files re-indexes in about 10 s; parsing is about 40% of that, so a cache would save a few seconds at the cost of a large table | Branch switches routinely rewrite thousands of files |
|
|
17
20
|
| ANN index | Exact search is not the bottleneck. Measured (Python stdlib copies, linear growth): 17k chunks cold CLI search 0.35 s / warm 0.13 s / index 10 s; 52k chunks 0.75 s / 0.36 s / 28 s; 104k chunks 1.09 s / 0.73 s / 54 s, 372 MB RSS, 729 MB database. At 104k chunks the cosine product plus top-k takes about 12 ms; loading the vectors out of SQLite (fetch 0.31 s, join 0.12 s) is about half of a warm query | Exact cosine itself becomes slow, which is far beyond 1M chunks |
|
|
18
|
-
| Vector matrix cache | Cheap and measurable: it removes about half of a warm query at 104k chunks (about 0.8 s -> 0.3 s). Not needed below ~50k chunks | A real project passes ~50k chunks. Keep the matrix in the MCP server process, and/or store it as a memory-mapped `.npy` next to the database so the CLI benefits too (invalidate on any index change) |
|
|
19
21
|
| `codebase_trace_execution` | Needs reliable call / data-flow relations; today's usage edges are name matches | Call graph gaps (item 3) are narrowed; today edges carry a confidence level |
|
|
20
22
|
| `codebase_architecture_overview` | Low value for the intended use cases | A concrete need appears |
|
|
21
23
|
| `codebase_find_references` (upgrade) | `relations` already returns name-matched references | Done in part: `relations` already separates confirmed / probable / candidate callers |
|
|
22
24
|
|
|
23
25
|
## Done
|
|
24
26
|
|
|
27
|
+
- 1.0.0: scoped four-part SQL identities and ambiguity handling; AST-byte C# owners and distinct compact overloads; representative evidence paths/depth warnings; versioned MCP/CLI schemas and protocol negotiation; project initialization, progress, offline reports; lexical mode, revision-bound vector cache; frozen real-project/scaling/client evidence and CI artifacts.
|
|
28
|
+
|
|
25
29
|
- 0.9.0: SQL alias/hint/TOP and quoted-name fixes; cursor/TRIM false-positive removal; nested comments and uncertain OPENQUERY analysis; comma sources after JOIN; BOM-aware Unicode source/context handling; constant SQL method attribution; VB6 SQL analysis; separate DDL/schema impact; explicit ignore overrides; modular navigation/context/rendering; lint/mypy CI and Windows Python 3.10/3.12/3.13.
|
|
26
30
|
|
|
27
31
|
- 0.7.0: revision-bound search cursors; historical target snapshots; model content identities; process coordination and crash recovery; focus-preserving context; synonym hot reload; retrieval explanations; project evaluation runner; automatic validated Release assets. Representative user-authored evaluation questions and broader semantic retrieval remain ongoing work.
|