codemap-core 0.2.2__tar.gz → 0.3.0__tar.gz

{codemap_core-0.2.2 → codemap_core-0.3.0}/CHANGELOG.md

@@ -8,6 +8,106 @@ During `0.x`, MINOR may introduce breaking changes — they will be marked `BREA
 
 ## [Unreleased]
 
+## [0.3.0] — 2026-06-25
+
+The four-layer-memory-model L1 release. The plugin family grows from
+**18 to 20** distributions; every package bumps in lockstep to `0.3.0`,
+and every plugin's `codemap-core` dependency widens to `>=0.3.0,<0.4`.
+
+### New plugins (opt-in)
+
+* **`codemap-mybatis`** — MyBatis Mapper XML indexer. Per-file XML
+  parsing yields `sql_mapping` symbols + `table` symbols + DML
+  `accesses_table` edges (confidence graded by SQL complexity —
+  static / dynamic-tag / `${}` substitution). A new `MyBatisLinkBridge`
+  emits `maps_to` edges from Java Mapper interface methods to their
+  backing XML statements (requires `codemap-java` installed).
+* **`codemap-aimemory`** — emits the four-layer memory model's L1
+  layout (`.ai-memory/entities/*.yml` + `.ai-memory/relations/*.yml`)
+  so AI agents can consume the index directly with stable
+  `entity_id` slugs (fn-* / cls-* / tbl-*). Atomic per-file writes
+  (tmp + rename). Includes an optional LLM enrichment overlay — the
+  core index itself remains LLM-free; enrichment writes to a
+  separate `enrichment/` directory keyed by `symbol_id` and is
+  merged only at emit time.
+
+### New core capability
+
+* **Project-level indexer protocol** (`codemap.indexers.project_base`).
+  Mirrors the per-file `Indexer` but consumes the entire project in
+  one pass, for engines whose output is whole-project (Java semantic
+  resolver, future SCIP-backed importers). Lazy-discovered through
+  the new `codemap.project_indexers` entry-point group.
+* **Emitter protocol** (`codemap.emitters`) — third plugin layer
+  alongside indexers / bridges. Registered through
+  `codemap.emitters` entry-point group with the same Protocol +
+  Registry pattern. The orchestrator runs emitters as the last
+  phase of `codemap index` (after bridges + hotspots).
+* **CLI subcommand registration via entry-points**
+  (`codemap.cli_commands`). Plugins can ship typer subcommands —
+  `codemap-aimemory` uses this to register `codemap enrich`.
+* **Git change-hotspot analyzer** (`codemap.core.git_hotspots`).
+  Language-neutral; surfaces `change_count_90d` on every symbol's
+  `extra`. Graceful skip on non-git / unavailable git.
+* `EdgeKind` adds `overrides`, `accesses_table`; `SymbolKind` adds
+  `table`.
+
+### Java engine rewrite (ADR-0013)
+
+* **`codemap-java`** moves from declaration-only to a full call
+  graph. The per-file indexer now captures `imports`, `supertypes`,
+  `pending_calls` (raw invocation records), method `params` /
+  `return_type`, and field `type` on `Symbol.extra`. A new
+  `JavaCallResolverBridge` (registered as `java_calls`) does
+  project-wide FQN resolution to emit `calls` / `extends` /
+  `implements` edges at `confidence=medium`. ADR-0013 documents
+  the deliberate trade-off (precision ceiling drops from
+  full-semantic `high` to FQN-resolved `medium`, in exchange for
+  zero external toolchain — no scip-java, no JVM build needed).
+* Spring annotation extraction: type / method `@Annotation` nodes
+  land on `Symbol.annotations`; the indexer combines class-level
+  `@RequestMapping` prefix with method verb mappings
+  (`@GetMapping` / `@PostMapping` / …) and writes `http_route`
+  metadata so the existing `http_route` bridge auto-mints route
+  intermediates.
+
+### `codemap-vue` extends
+
+* Captures `axios.<verb>(...)` / `this.$axios.<verb>(...)` /
+  `fetch(...)` invocations inside script blocks, attaching
+  `{method, url, confidence}` records to the enclosing
+  function/method symbol's `extra["http_calls"]`. The existing
+  `http_route` bridge now connects Vue clients to Spring routes
+  automatically.
+
+### `codemap enrich` CLI (new)
+
+```bash
+codemap enrich --backend openai     --model gpt-4o-mini
+codemap enrich --backend anthropic  --model claude-sonnet-4-5
+codemap enrich --backend ollama     --model llama3
+codemap enrich --base-url http://my-proxy/v1 --api-key sk-…
+```
+
+Reads `.codemap/`, calls the configured LLM for each
+function/method symbol, writes overlay YAML files under
+`.ai-memory/enrichment/`. Env-var fallback chain:
+`CODEMAP_LLM_API_KEY` → `ANTHROPIC_API_KEY` → `OPENAI_API_KEY`;
+`CODEMAP_LLM_BASE_URL` → `OPENAI_BASE_URL` → `ANTHROPIC_BASE_URL`.
+The next `codemap index` merges the overlay into
+`entities/functions.yml`. `--dry-run` reports without calling.
+
+### Default prune dirs
+
+`DEFAULT_PRUNE_DIRS` now includes `target` (Maven) and `out`
+(Gradle IDE default) so Java/Kotlin/Scala projects don't double-
+index build output trees.
+
+### New import-linter contract
+
+`emitters may not import cli/mcp/io` keeps the new emitter layer
+honest to the same dependency rules as indexers and bridges.
+
 ## [0.2.2] — 2026-06-05
 
 Lockstep version-only bump across all **18 packages** to keep the

{codemap_core-0.2.2 → codemap_core-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codemap-core
-Version: 0.2.2
+Version: 0.3.0
 Summary: Language-neutral code index for AI agents
 Project-URL: Homepage, https://github.com/qxbyte/codemap
 Project-URL: Repository, https://github.com/qxbyte/codemap

codemap_core-0.3.0/docs/adr/0013-java-engine-tree-sitter-over-scip-java.md

@@ -0,0 +1,115 @@
+# ADR-0013: Java engine — tree-sitter over scip-java
+
+* **Status**: Accepted
+* **Date**: 2026-06-24
+* **Related**: design `2026-06-23-codemap-l1-知识图谱重构-design.md` §A1/§B1 · spike `2026-06-23-scip-java-findings.md` · ADR-0004 (indexer/bridge plugin) · ADR-0007 (diagnostic isolation) · ADR-L001 (language neutrality)
+
+## Context
+
+The original L1 knowledge-graph design (2026-06-23) picked scip-java as Java's
+semantic backend, citing maximum precision (interface→impl, overloads,
+generics, cross-file resolution). Implementing it required:
+
+* ~100 MB scip-java + coursier + JVM toolchain on the user's machine
+* The target project must be `mvn`/`gradle` buildable (private-repo deps, JDK
+  pinning, multi-module)
+* protoc / grpcio-tools to vendor `scip_pb2.py`
+* A spike (Plan 0) to confirm the real SCIP symbol string format before
+  Plan 2's `symbol_map` / `extract_edges` could be written
+* `mvn compile` on every full index — minute-scale, doesn't fit watch mode
+
+The user explicitly rejected this weight tradeoff in favor of a lighter
+default engine that still meets the spec's "high precision call graph"
+ambition for the common path.
+
+## Decision
+
+**Use tree-sitter-java as the sole Java engine.** Permanently drop scip-java.
+
+The architecture stays the same — declarations come from a per-file
+`JavaIndexer`, cross-file edges (calls/extends/implements) come from a
+separate resolver — but the resolver runs in Python on tree-sitter AST plus
+an import + FQN graph it builds itself, not on a `.scip` file.
+
+Implementation shape:
+
+1. **`JavaIndexer` (per-file, existing — extended)**: in addition to today's
+   declarations, capture `import` statements and method invocations into
+   `Symbol.extra["pending_calls"]` (raw records: receiver name, method name,
+   argument arity, location).
+2. **`JavaCallResolverBridge` (new, runs in the bridge phase)**: read all
+   Java symbols + their pending_calls, build a project-wide FQN table from
+   the import statements, same-package declarations, and explicit
+   `extends`/`implements` relations, then emit `calls` / `extends` /
+   `implements` / `overrides` edges with `confidence: medium`.
+3. **Spring annotations + http_route metadata** stay in the indexer (Plan 3
+   Task 1/2) using tree-sitter — no scip-java needed for that anyway.
+4. **MyBatis** (Plan 3 Task 3) rebuilds the Java method `SymbolID` using the
+   codemap-java scheme (consistent with the new indexer), not the scip-java
+   symbol format. This removes the spike-Plan-0 dependency entirely.
+
+### Alternatives considered
+
+* **B — Hybrid (tree-sitter default + scip-java optional)**: tempting but
+  doubles the implementation surface and forces every downstream consumer
+  to handle two backends with different fidelity.
+* **C — Bytecode parsing (javap / asm)**: still requires `mvn compile`, so it
+  inherits scip-java's "your project must build" weight. Python bytecode-
+  parsing ecosystem is thinner than tree-sitter.
+
+## Consequences
+
+What becomes easier:
+
+* Zero external Java toolchain. `pip install codemap-core codemap-java`
+  works out of the box on any machine.
+* No spike unblock required. Plan 2 can start TDD immediately.
+* Watch mode and incremental indexing become realistic (per-file tree-sitter
+  parse is millisecond-scale).
+* Plan 4's Golden test fixture no longer needs scip-java in CI.
+
+What becomes harder / what we accept:
+
+* **Precision ceiling drops from "high" to "medium" for `calls` edges.**
+  Realistic targets on Spring/MyBatis projects:
+  * `calls`: 70–80% precision (overload disambiguation by arity only; dynamic
+    dispatch through interface-typed fields resolved heuristically by
+    DI-known impls — see follow-up below)
+  * `implements`/`extends`: ~95% (explicit `implements X, Y` syntax)
+  * Annotation extraction: 100% (purely syntactic)
+* Reflection, dynamic proxies, and Spring AOP-style indirection produce
+  edges that look correct syntactically but miss runtime targets. These are
+  the same blind spots tree-sitter has anywhere; we mark them with `medium`
+  confidence rather than pretend.
+* The precision gate (Plan 4 Task 5) lowers its `high`-tier threshold,
+  effectively becoming a `medium`-tier `≥ 0.70` gate on `calls` and a
+  `≥ 0.95` gate on `implements`/`extends`. Regression-detection rationale
+  unchanged.
+
+What we keep paying for:
+
+* The FQN resolver is real code we own — when Java's grammar changes (new
+  language features, pattern-matching) tree-sitter-java updates flow
+  through, but our resolver has to keep up too.
+* The `ProjectIndexer` protocol added in Plan 1 Task 2 is retained as a
+  generic extension point for future heavier engines (e.g. someone wants to
+  ship a scip-java backend later) — Java itself no longer uses it, but
+  emptying the slot would break the symmetry with `Indexer`/`Emitter`.
+
+Follow-up ADRs / decisions:
+
+* If/when a project demonstrates that medium precision is insufficient (e.g.
+  precision-gate alarms repeatedly), revisit and consider adding scip-java
+  as an *opt-in* second backend that publishes the same SymbolID shape — at
+  that point Hybrid (alternative B) becomes a focused upgrade rather than
+  default complexity.
+
+## References
+
+* spec `2026-06-23-codemap-l1-知识图谱重构-design.md` (Obsidian vault) §A1/§B1
+* spike `docs/spikes/2026-06-23-scip-java-findings.md` §0 (toolchain blocker
+  that triggered the rethink)
+* `docs/adr/0004-indexer-bridge-plugin.md` (resolver lives as a bridge, not a
+  new plugin layer)
+* `docs/adr/0007-diagnostic-isolation.md` (unresolved calls become
+  diagnostics, never crashes)

codemap_core-0.3.0/docs/spikes/2026-06-23-scip-java-findings.md

@@ -0,0 +1,142 @@
+# scip-java spike findings (Plan 0)
+
+> 创建时间：2026-06-24
+> 状态：**部分完成** —— §0/§3/§4 已落定；§1/§2 阻塞，等本机 scip-java 工具链就绪
+> 关联：spec `2026-06-23-codemap-l1-知识图谱重构-design.md`、`plan-0-验证spike`、交接文档 `2026-06-24-codemap-refactor-execution-readiness.md`
+
+---
+
+## §0. 环境勘察与工具链状态
+
+**本机（xueqiang的 MacBook Pro, Darwin 25.5.0, arm64）：**
+
+| 工具 | 状态 | 备注 |
+|---|---|---|
+| Java 17 | ✅ `17.0.17 LTS` (`/usr/bin/java`) | Maven 工程构建用 |
+| Python 3.13 | ✅ `.venv/bin/python` | 项目自带 venv |
+| `mvn` | ✅ `/opt/homebrew/bin/mvn` (Homebrew) | 已验证可编译 fixture |
+| `scip-java` | ❌ **未安装** | 本轮被代理速度阻塞（见下） |
+| `cs` (coursier) | ❌ 未安装 | 同上 |
+| `protoc` | ❌ 未安装 | Plan 2 生成 `scip_pb2.py` 用，或 `grpcio-tools` 替代 |
+| `grpcio-tools` (PyPI) | ⏳ 待装于 `.venv` | 受 PEP 668 阻挡装到系统 Python，改用 venv |
+
+**安装阻塞证据：**
+
+- `brew install coursier/formulas/coursier` 跑了 5+ 分钟没出任何输出 → kill。
+- 直接 `curl -fLo cs.gz https://github.com/coursier/coursier/releases/latest/download/cs-aarch64-apple-darwin.gz`（21 MB）→ 90 秒只下了 2.3 MB（平均约 30 KB/s）→ 超时退出。
+- HTTPS 通过 SOCKS5 (`127.0.0.1:7890`) 本身可用（`curl https://repo.maven.apache.org/maven2/` → 200 OK，`curl https://github.com` → 200 OK），代理服务有效，**但带宽极低**，scip-java jar 包（数十 MB）实际下载不下来。
+- DNS：系统 nameserver 指向 `198.18.0.2`（Clash/Surge 类代理的 fake-IP 网段）；`nslookup` 直发 UDP 53 失败属于代理软件默认只代理 TCP 的预期行为，对 HTTPS 应用无影响。
+
+**下次推进 §1/§2 的两个可行路径：**
+
+1. 改进代理速度（换节点 / 直连 / 公司代理）后重跑 `cs install scip-java`。
+2. 在带宽好的环境下载 scip-java，scp 到本机后直接 `mv` 到 `~/.local/bin/scip-java`。
+
+---
+
+## §1. 真实 SCIP symbol 字符串格式（HARD GATE for Plan 2/3）
+
+> 状态：**PENDING**（被 §0 工具链阻塞）
+
+待 scip-java 装好后，在 `tests/fixtures/scip-samples/HelloSpring/` 目录执行：
+
+```bash
+cd tests/fixtures/scip-samples/HelloSpring
+scip-java index --output index.scip -- compile
+scip print --json index.scip > index.scip.json
+grep -o '"symbol":[^,]*' index.scip.json | sort -u | head -40
+```
+
+需要在本节回答的问题（来自 plan-0 Task 1 Step 5）：
+
+- [ ] `com.example.hellospring.service.OrderService#calculateOrderPrice(long)` 的**逐字符**真实 SCIP symbol 串
+- [ ] package 描述符到底用什么：Maven `group/artifact version` 还是 `.` 占位
+- [ ] 方法 disambiguator（重载场景；本 fixture 暂无重载，可造一个）
+- [ ] 调用关系怎么表达：`Occurrence.symbol_roles` 位掩码？`SymbolInformation.relationships`？还是按方法 range 内对其它 symbol 的非定义引用推断？
+- [ ] 定义 range 在 `occurrence.range` 还是 `SymbolInformation` 的某字段？是否填 `enclosing_range`？
+
+**直接消费方：**
+- Plan 2 `plugins/codemap-java/src/codemap_java/symbol_map.py` 的 `to_symbolid()` 实测 round-trip 用例
+- Plan 2 `extract_edges` 里 `_enclosing_method()` 的实现策略选择
+- Plan 3 `plugins/codemap-mybatis` 的 `_java_method_id(namespace, method)` 重建，必须**逐字符**等于 scip-java 给同一方法的 symbol，否则 MyBatis 边的 source 悬空
+
+---
+
+## §2. scip-java 增量索引能力
+
+> 状态：**PENDING**（被 §0 工具链阻塞）
+
+待 scip-java 装好后执行：
+
+```bash
+cd tests/fixtures/scip-samples/HelloSpring
+time scip-java index --output index_full.scip -- compile
+# 改一处 OrderService.java 加一行无害日志
+time scip-java index --output index_inc.scip -- compile
+```
+
+需要在本节回答的问题：
+
+- [ ] (a) scip-java 支持增量/部分索引 → Plan 2 可做受影响单元重索引
+- [ ] (b) 仅全量 → spec §5.3② 退化为「每次全量重跑 scip-java + codemap 侧按 sha256 diff」；正确性不变、代价记录在案
+
+**直接消费方：** Plan 2 `JavaScipIndexer.index_project()` 的增量策略；编排器 `_do_incremental` 路径里项目级 indexer 的调用频率（当前 Plan 1 Task 5 实现是每次 incremental 都全量重跑，符合 (b) 假设）。
+
+---
+
+## §3. 目标企业工程可构建性
+
+> 状态：**N/A** —— 本机无目标企业工程
+
+Plan 0 Task 3 的目的是验证「真实业务工程能否稳定 mvn compile + scip-java index」。本机只有 `tests/fixtures/scip-samples/HelloSpring/`（开发期最小 fixture），未持有任何目标企业工程。
+
+**判断与后续动作：**
+
+- 本节的结论只能在能访问真实业务工程的环境里二次评估（开发机 / CI runner）。
+- 一旦目标工程接入，本节需补：JDK 版本、是否多模块（aggregator pom）、私服/离线依赖能否拉取、构建总耗时、scip-java 在该工程上是否成功产 `index.scip`。
+- 不阻塞 Plan 1（已完成）、Plan 2 算法本身（用 HelloSpring fixture 验证）、Plan 3 框架 bridge 算法（同上）。但**精度门禁**（Plan 4 Task 5）的最终意义需在真实工程上跑一次校准。
+
+---
+
+## §4. codemap-vue / codemap-typescript 的 http_calls 现状
+
+> 状态：**已落定**
+
+### 4.1 实测
+
+```bash
+# 仓库根
+grep -rn "http_calls\|http_route\|axios\|fetch" \
+    plugins/codemap-vue plugins/codemap-typescript \
+    src/codemap/core/bridge/http_route.py
+```
+
+实测命中（2026-06-24，分支 `feat/l1-knowledge-graph`）：
+
+- `plugins/codemap-vue/README.md:68` — 文档里仅 1 行示例 symbol（无实现）
+- `src/codemap/core/bridge/http_route.py` — bridge 自身的 5 处（`extra["http_route"]` server 侧、`extra["http_calls"]` client 侧，以及类型注解）
+
+实测 **`plugins/codemap-vue/src/`、`plugins/codemap-typescript/src/` 的实现代码中零命中 `axios` / `fetch` / `http_calls` / `http_route`**。
+
+### 4.2 代码核对
+
+- `plugins/codemap-vue/src/codemap_vue/indexer.py` —— Vue SFC indexer：用 tree-sitter-vue 不可得，所以走「SFC 切片 + 内嵌 JS/TS 走 tree-sitter-javascript / tree-sitter-typescript」。访问者只采集：top-level 函数、类（含方法）、模块级 `const/let/var` 声明。**不识别**调用表达式中的 `axios.<verb>(...)` 或 `fetch(...)` 字面量。
+- `plugins/codemap-typescript/src/codemap_typescript/indexer.py` —— 同模式（直接走 tree-sitter-typescript，无 SFC 切片）。
+
+### 4.3 结论 & Plan 4 起点
+
+- **从零写**（不是「增强已有」）。Plan 4 Task 1 文档里也已写了「实现 http_calls 抽取」，本节是其前置事实确认。
+- 实现位点：在 vue/typescript indexer 的 AST 遍历里加调用表达式访问；识别 `axios.<verb>` / `this.$axios.<verb>` / `fetch` / `useFetch`（按团队约定扩展），把 `{method, url, confidence}` 累加到所在方法/组件符号的 `extra["http_calls"]`。
+- 置信度：纯字面量 url → `medium`；含模板拼接 / 变量 → `low`；动态计算 → 不建边（宁缺毋滥，符合 spec §5.1）。
+- 下游：现成的 `HttpRouteBridge` 已经读 `extra["http_calls"]`，只要 Vue 侧产出格式正确，Plan 3 Task 2 Java 侧产出 `extra["http_route"]` 后 bridge 自动跨语言连边。
+
+---
+
+## 接手 Checklist（下一轮）
+
+- [ ] 把 §0 的代理速度问题解决后跑 `cs install scip-java`（或手工放 scip-java 二进制到 `~/.local/bin/`）。
+- [ ] 跑 `scip-java index` 出 `tests/fixtures/scip-samples/HelloSpring/index.scip`，把 §1 的 5 个问题用实测证据写满。
+- [ ] 跑 §2 的全量+增量两次 `time scip-java index`，二选一。
+- [ ] 把 fixture 工程 + `index.scip` + 本 findings 文档一并 commit（`spike: capture real scip-java output format on HelloSpring sample`）。
+- [ ] 按 §1 的 `REAL` symbol 字符串回填 Plan 2 `symbol_map.py` 测试与 Plan 3 `_java_method_id()` 重建逻辑。
+- [ ] 继续 Plan 2 → 3 → 4。

codemap_core-0.3.0/docs/spikes/2026-06-24-codemap-refactor-execution-readiness.md

@@ -0,0 +1,168 @@
+# CodeMap 知识图谱重构 —— 执行就绪评估与环境交接
+
+> 创建时间：2026-06-24
+> 作者：Claude（按用户「读重构文档→按顺序实现」请求，在动手前做的批判性审查 + 环境勘察）
+> 状态：**未动手实现**。本机缺 scip-java 工具链，用户决定换环境继续。本文是交接清单。
+> 关联计划文档（在 Obsidian vault）：
+> `07-Ideas/CodeMap/重构(适配知识图谱)/` 下的
+> `…-design.md` / `plan-0-验证spike` / `plan-1-地基` / `plan-2-java语义核心` /
+> `plan-3-框架bridge` / `plan-4-贯通与输出`
+> 现有代码库：`/Users/xueqiang/Git/codemap`（git，随仓库可带到新环境）
+
+---
+
+## 0. 一句话结论
+
+5 个 plan 质量很高、可逐步 TDD 执行；**Plan 1（地基）完全不依赖 scip-java，现在/任何环境都能立即开工**。但**文档字面顺序的第一步 Plan 0（验证 spike）被本机工具链阻塞**：`scip-java / maven / gradle / coursier / protoc` 全缺。Plan 2/3/4 中凡是需要**真实 `index.scip`** 的部分都连带阻塞。建议在新环境先装工具链跑 Plan 0，或先在任意环境把 Plan 1 + 不依赖真实 `.scip` 的部分做掉。
+
+---
+
+## 1. 本机环境勘察（2026-06-24，xueqiang的MacBook Pro）
+
+| 工具 | 状态 | 说明 |
+|---|---|---|
+| Java | ✅ `17.0.17 LTS` (`/usr/bin/java`) | 满足目标 JDK 17 |
+| Python | ✅ `3.14.5` | 满足 `requires-python >=3.11` |
+| scip-java | ❌ 未安装 | **Plan 0/2 的硬前置** |
+| maven (`mvn`) | ❌ 未安装 | scip-java 索引需要可构建的 mvn/gradle |
+| gradle | ❌ 未安装 | 同上（二选一） |
+| coursier (`cs`) | ❌ 未安装 | scip-java 官方推荐安装途径 |
+| protoc | ❌ 未安装 | Plan 2 生成 `scip_pb2.py` 需要（或用 `pip install grpcio-tools` 自带 protoc） |
+
+**新环境上手前需补齐**：scip-java、maven（或 gradle）、protoc（或 grpcio-tools）。另需一个**可 `mvn compile` 通过的目标 Java 工程**（Plan 0 Task 3 / Plan 4 golden fixture 的真相源）。
+
+新环境建议安装命令（macOS / Homebrew，供参考，未在本机执行）：
+
+```bash
+brew install coursier/formulas/coursier && cs setup     # 装 JVM 工具基座
+cs install scip-java                                     # 装 scip-java
+brew install maven                                       # 或 gradle
+pip install grpcio-tools                                 # 自带 protoc，给 Plan 2 生成 scip_pb2.py
+scip-java --help                                         # 验证可用
+```
+
+---
+
+## 2. 计划审查：硬编码 API vs 真实代码（已逐项核对）
+
+对 Plan 1（直接硬编码了大量 codemap 内部 API）做了逐项核对，结论：**Plan 1 可按文档原样执行**。核对覆盖到 Plan 2–4 用到的跨层 API。
+
+### 2.1 与计划假设一致（可放心按文档写）
+
+- `src/codemap/core/models.py`
+  - `SymbolKind` Literal 现含 `… "asset", "unknown"`；`EdgeKind` Literal 现含 `… "maps_to", "imports"`。Plan 1 Task 1 要加 `"table"`（SymbolKind）、`"overrides"`/`"accesses_table"`（EdgeKind）——位置假设成立。
+  - `Confidence = Literal["high","medium","low"]`（注意：核心 Confidence **不含** `"llm"`；`"llm"` 只出现在 enrichment YAML，物理隔离，符合设计）。
+  - `Symbol`/`Edge`/`Range`/`Annotation`/`Diagnostic`/`IndexResult` 字段与计划用法一致；`Symbol.extra: dict[str, Any]`、`Symbol.annotations: list[Annotation]` 存在。
+- `src/codemap/core/symbol.py`
+  - `SymbolID.parse(s) -> SymbolID`（classmethod）✅；`to_string()` + `__str__` ✅；构造参数 `scheme`（必填）、`manager="."`、`package_name="."`、`package_version="."`、`descriptors: tuple[Descriptor,...]=()`（`@dataclass(frozen, slots)`）。
+  - `SymbolParseError(ValueError)` ✅。
+  - `Descriptor(name, kind, disambiguator="")` ✅；`DescriptorKind`(StrEnum) 成员 `NAMESPACE/TYPE/TERM/METHOD/TYPE_PARAMETER/PARAMETER/META` ✅（Plan 用到的 TYPE/METHOD/TERM/NAMESPACE 全在）。
+  - `SymbolID.descriptors` 元素有 `.name`/`.kind` ✅。
+- `src/codemap/core/store.py`
+  - `ReadOnlyStore` 是 `@runtime_checkable Protocol`，方法 `get / iter_symbols / iter_edges / callers / callees / search / manifest`。emitter（Plan 1 Task 3 / Plan 4）只用 `iter_symbols`/`iter_edges`，满足。
+  - 另有 `SymbolStore(ReadOnlyStore, Protocol)` 读写协议。
+- `src/codemap/io/json_store.py`
+  - `JsonStore.open(root, *, mode="rw")`（classmethod，返回支持 `with` 的实例）✅；`iter_symbols/iter_edges/upsert_symbols/upsert_edges/upsert_routes/upsert_diagnostics/commit/get` 全部存在，签名与 Plan 用法一致；额外有 `upsert_aliases/iter_routes/iter_aliases/iter_diagnostics/delete_by_file/clear_bridge_outputs`。结构上满足 `ReadOnlyStore`/`SymbolStore`。
+- `src/codemap/indexers/base.py` + `registry.py`
+  - `Indexer` Protocol：`index_file(path, source: bytes, ctx) -> IndexResult`；`supports(path)`；ClassVar `name/version/file_patterns/languages`。
+  - `IndexContext(project_root: Path, relative_path: PurePosixPath, language: str, config={})`（**`relative_path` 是 `PurePosixPath` 不是 str**）。
+  - entry-point group `codemap.indexers`，发现机制 `entry_points(group=…)→ep.load()()→isinstance 校验→按 name 入表`。Plan 1 的 project_indexers / emitters 注册表照抄此模式即可。
+- `src/codemap/cli/commands/index.py`
+  - `_run_bridges(store, stats, config)` ✅、`_index_one(file_path, project_root, store, registry, stats, bar, config)` ✅、`_do_incremental(...)` ✅、`_index_one_prefetched(...)` ✅。
+  - **full-build `else:` 分支真实代码（`index.py:140-144`）与 Plan 1 Task 5 假设一致**：
+    ```python
+    else:
+        with progress_bar("Indexing", total=len(files), enabled=not no_progress) as bar:
+            for file_path in files:
+                _index_one(file_path, path, store, registry, stats, bar, config)
+        _run_bridges(store, stats, config)
+    ```
+  - `_short_exception_message(producer: str, exc: BaseException)` ✅（两参，Plan 调 `_short_exception_message(ix.name, exc)` 匹配）。
+  - 顶部 import 齐全：`Diagnostic`、`Config`、`PurePosixPath`、`logger`、`progress_bar` 全部存在。
+- `src/codemap/core/bridge/http_route.py`
+  - `HttpRouteBridge.resolve(store) -> BridgeResult`；ClassVar `name="http_route"`。
+  - server 侧读 `Symbol.extra["http_route"]`、client 侧读 `Symbol.extra["http_calls"]`，产 `routes_to`（handler→route）与 `calls`（caller→route）边 + `Route`/`Alias`/`Diagnostic`。
+- `plugins/codemap-sql/`：**仅 DDL**（CREATE TABLE/VIEW/INDEX），明确忽略 SELECT/INSERT/UPDATE/DELETE。→ 印证 Plan 3 的修正：MyBatis 必须自带 DML 表名抽取。
+- `plugins/codemap-java/`：当前 `JavaIndexer` 确为**声明级**——`_Visitor.edges` 恒为 `[]`，全文无 `edges.append`。→ 印证设计 §0「现状缺口①」，Plan 2 用 `JavaScipIndexer` 取代它。
+
+### 2.2 与计划措辞/假设**不一致**项（执行时按此修正，不改变算法与断言）
+
+1. **根 `pyproject.toml` 没有任何「语言插件」的 entry-point 注册行**。根 pyproject 只注册 `_example_lang`+`python`（indexers）与 `http_route`+`python_cross_module`（bridges）。Java/Vue/TS/SQL 等都在各自 `plugins/codemap-*/pyproject.toml` 注册。
+   - 影响 **Plan 1 Task 5 Step 5**：在根 pyproject 加 `codemap.project_indexers`/`codemap.emitters` **空占位组**没问题；但 Plan 2 Task 6「从旧 `codemap.indexers` 组移除旧 java 注册」要去改 `plugins/codemap-java/pyproject.toml`，**不是**根 pyproject。
+2. `ReadOnlyStore` Protocol **不含** `iter_routes/iter_diagnostics/iter_aliases`（这些只在 `JsonStore` 具体类）。emitter 若只读 symbols/edges 不受影响；若将来 emitter 想读 routes，需收 `JsonStore` 或扩展 Protocol。
+3. `index()` 是 `register(app)` 内的**嵌套命令函数**，不能直接 `import index`。但 Plan 1 Task 5 的测试只 import **模块级**辅助函数 `_run_project_indexers`/`_apply_hotspots`（新加的就是模块级），不受影响。
+4. `_IndexStats` 是**普通 class 不是 dataclass**，但 `.diagnostics` 字段存在（int 计数），Plan 的 `stats.diagnostics += len(...)` 成立。
+5. `JsonStore.open` 是**返回 context-manager 实例的 classmethod**，不是 `@contextmanager` 生成器（仅措辞）。
+6. `HttpRouteBridge` 同时用 `http_route`(server)+`http_calls`(client) 两个 key，不是单一 key（Plan 3/4 已分别在 Java 侧写 `http_route`、Vue 侧写 `http_calls`，方向正确）。
+7. `importlinter` 现有 3 条 `forbidden` 合约（core / io / indexers 各一条），**无 bridge 专属合约**。Plan 1 Task 5 新增 emitters 合约符合现有模式。
+8. **Vue / TypeScript 插件目前完全没有 `http_calls`/axios/fetch 提取逻辑**（grep 零命中）。→ Plan 4 Task 1 是**从零新写**（不是「增强已有」），Plan 0 §4 的审计结论可直接定为「从零写」。
+
+---
+
+## 3. 阻塞分析：哪些被 scip-java 卡住、哪些没有
+
+### 3.1 **不依赖 scip-java，任意环境可立即做**
+
+- **Plan 1 全部**（Task 1–5）：模型枚举、项目级 indexer 协议+注册表、emitter 协议+注册表、git 热点、编排器接入 + import-linter 合约。纯 Python TDD，自给自足。**这是后面一切的地基，强烈建议最先做。**
+- **Plan 3 Task 1**（Java 注解抽取，tree-sitter-java，已是依赖）、**Task 3**（MyBatis Mapper XML indexer 的单元测试——`table_refs` + `MyBatisIndexer.index_file` 用手工 XML，自给自足）。
+  - ⚠️ 但 Plan 3 的 `_java_method_id` 重建必须**逐字符**等于 scip-java 对同一方法给的 symbol，这点要等 Plan 0 §1 真实符号串才能最终锁定；可先写实现 + 单元测试，留待 Plan 4 golden 联调校验。
+- **Plan 4 Task 1**（Vue `http_calls` 从零写）、**Task 2**（`ids` entity_id 派生）、**Task 3**（`AiMemoryEmitter`，测试用手工 seed 符号）、**Task 4**（`enrich` LLM 增强，LLM 用 mock）。这些测试都不需要真实 `.scip`。
+
+### 3.2 **被 scip-java / 真实 `index.scip` 阻塞**
+
+- **Plan 0 全部**（spike：装 scip-java、造样例工程、跑出真实 `index.scip`、记录 §1 符号串格式 / §2 增量能力 / §3 目标工程可构建性 / §4 Vue 现状）。
+- **Plan 2 Task 2/4/5/6**：`scip_reader`/`extract_symbols`/`extract_edges`/`JavaScipIndexer` e2e 的测试都以 `tests/fixtures/scip-samples/HelloSpring/index.scip` 为真相源——该 fixture 由 Plan 0 用 scip-java 真实产出。
+  - （Plan 2 Task 1 runner、Task 3 symbol_map **可先做**：runner 测试 mock subprocess，symbol_map 是纯字符串→SymbolID；但 Task 3 的 `REAL` 字符串需 Plan 0 §1 实测值替换。）
+- **Plan 3 Task 2 Step 5**（Spring 路由经 http_route bridge 成图的集成测试，依赖 fixture `index.scip`）。
+- **Plan 4 Task 5**（golden 全栈 fixture + 精度门禁，依赖预生成 `index.scip`）——这是把 Plan 2/3 所有 ⚠️Plan-0 假设做总验收的地方。
+
+---
+
+## 4. 推荐执行顺序（roadmap）
+
+**阶段 A（任意环境，立即可做，零返工风险）**
+1. **Plan 1 全部**（地基）。完成后 codemap core 具备：项目级 indexer 钩子、emitter 插件协议、git 热点、新枚举、编排器接入、emitters import-linter 合约。
+
+**阶段 B（需 scip-java 工具链 + 可构建 Java 工程）**
+2. **Plan 0** spike：装工具链 → 造 `tests/fixtures/scip-samples/HelloSpring/` 最小 Maven 工程 → 跑出真实 `index.scip` → 写 `docs/spikes/2026-06-23-scip-java-findings.md` 的 §1–§4。
+   - **§1 是硬出口**：`OrderService#calculateOrderPrice()` 的逐字符真实 symbol 串、package 描述符形态（Maven 坐标 vs `.` 占位）、重载 disambiguator、**调用关系如何表达**（occurrence symbol_roles 位掩码 / SymbolInformation.relationships / enclosing_range）。直接决定 Plan 2 的 `to_symbolid` 与 `extract_edges`、Plan 3 的 `_java_method_id` 重建。
+3. **Plan 2**：用 Plan 0 真实 fixture 与 §1 结论，落地 runner → scip_pb2/reader → symbol_map → extract_symbols/edges → JavaScipIndexer，并替换旧声明级 java 插件。
+4. **Plan 3**：注解 → Spring `http_route` 元数据（写进索引期，复用 http_route bridge）→ MyBatis 插件。用真实 fixture 校准 `_java_method_id`。
+5. **Plan 4**：Vue `http_calls`（从零）→ ids → AiMemoryEmitter → enrich → golden 全栈 fixture + 精度门禁（high 档 precision ≥ 0.98，接 CI）。
+
+> 也可在阶段 A 顺手把 §3.1 列的「不依赖 scip 的 Plan 3/4 子任务」做掉，但要注意 Plan 3 `_java_method_id`、Plan 2 `symbol_map` 的 `REAL` 串等**含 ⚠️Plan-0 常量**的点，必须等 Plan 0 §1 实测后回填，否则会出现「MyBatis 边 source 悬空 / round-trip 断言失败」。稳妥起见：含 ⚠️ 的常量留到阶段 B。
+
+---
+
+## 5. 执行规范提醒（给接手的会话/Agent）
+
+- 每个 plan 顶部都标了 **REQUIRED SUB-SKILL：superpowers:subagent-driven-development（推荐）或 superpowers:executing-plans**，按其逐 task / 逐 step 执行，步骤用 `- [ ]` 跟踪。
+- 全程 **TDD**：先写失败测试 → 跑确认 FAIL → 写实现 → 跑确认 PASS → commit。Plan 里每步都给了具体命令与 Expected。
+- **门禁不降标**：`ruff check`、`mypy --strict`、`pytest --cov-fail-under=80`、`lint-imports`（import-linter）、bench。新代码一并纳入。
+- **不在 main 直接实现**：先开 worktree 或 feature 分支（superpowers:using-git-worktrees）。本次用户选择「跳过」是因为本轮只写结论、不实现。
+- **commit 署名**：按全局规则追加两条 `Co-Authored-By`（Claude 在前、用户实时取 `git config user.name/email` 在后）。
+- **降级铁律**：critical（scip-java 构建失败）之外，任何单层失败都不能让整体 L1 产出失败——保留上一份好索引、记 diagnostic 继续。
+
+---
+
+## 6. 接手 checklist（换环境后从这里开始）
+
+- [ ] 拉取/同步 codemap 仓库到新环境，确认本文件在 `docs/spikes/`。
+- [ ] 装 scip-java + maven（或 gradle）+ protoc/grpcio-tools（见 §1 命令）。
+- [ ] 准备一个可 `mvn -DskipTests compile` 通过的目标 Java 工程（或用 Plan 0 Task 2 的 HelloSpring 最小样例）。
+- [ ] 开 worktree / feature 分支（不在 main 上写）。
+- [ ] 若想零等待：先做 **Plan 1 全部**（阶段 A，不需以上工具）。
+- [ ] 工具链就绪后做 **Plan 0**，把 `2026-06-23-scip-java-findings.md` §1–§4 用实测证据写满。
+- [ ] 按 §1 findings 回填 Plan 2/3 的 ⚠️ 常量，再依次推进 Plan 2 → 3 → 4。
+- [ ] 全链跑通后用 Plan 4 golden 精度门禁验收，接入 CI。
+
+---
+
+## 附：本轮已确认的关键事实索引（避免接手者重复勘察）
+
+- 旧 `JavaIndexer` 声明级、零 Edge：`plugins/codemap-java/src/codemap_java/indexer.py`（`_Visitor.edges=[]`，无 append）。
+- full-build 编排接入点：`src/codemap/cli/commands/index.py:140-144`（`else:` 块，`_run_bridges` 之后是 Plan 1 追加 hotspots/emitters 的位置）。
+- http_route bridge 读 `extra["http_route"]`(server) / `extra["http_calls"]`(client)：`src/codemap/core/bridge/http_route.py`。
+- DDL-only SQL 插件：`plugins/codemap-sql/src/codemap_sql/indexer.py`（docstring 明示忽略 DML）。
+- Vue/TS 无 http_calls：`plugins/codemap-vue`、`plugins/codemap-typescript` grep 零命中。
+- import-linter 合约：`pyproject.toml`（core/io/indexers 三条 forbidden，无 bridge 合约）。