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

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

@@ -8,6 +8,150 @@ During `0.x`, MINOR may introduce breaking changes — they will be marked `BREA
 
 ## [Unreleased]
 
+## [0.3.1] — 2026-06-25
+
+Quick follow-up to 0.3.0. Lockstep version-only bump across all **20
+packages** to keep the family in sync; the only source change is in
+`codemap-aimemory`.
+
+### `codemap-aimemory` — LLM CLI configuration
+
+* New subcommand group **`codemap llm config`** (registered through the
+  `codemap.cli_commands` entry-point group introduced in 0.3.0):
+  * `codemap llm config set api-key <key>` — persist to
+    `~/.config/codemap/llm.yaml` (or `$XDG_CONFIG_HOME/codemap/llm.yaml`),
+    written `chmod 600` because it carries a credential.
+  * `codemap llm config set base-url <url>` / `model` / `backend`.
+  * `codemap llm config unset <key>` — clear one field; the on-disk
+    file only contains non-`None` values.
+  * `codemap llm config show` — print the effective config with one of
+    `[env]` / `[file]` / `[default]` annotated per field; API keys are
+    masked.
+  * `codemap llm config path` — print the config file location.
+* `codemap enrich` resolution order is now (first non-empty wins):
+  CLI flag → env var → file config (new in 0.3.1) → built-in defaults.
+* Behavioural reminder: **API key is the LLM on/off switch.**
+  `codemap index` never calls any LLM; `codemap enrich` without a key
+  errors out cleanly, never silently. No background LLM traffic.
+
+### Documentation
+
+* README + README.zh-CN: new "Output formats" section documenting every
+  file under `.codemap/` and `.ai-memory/` (kind, shape, who consumes it).
+* README + README.zh-CN: new "LLM configuration" section with the
+  three-source resolution order and a Chinese / open-source LLM endpoint
+  cheatsheet (DeepSeek, GLM, MiniMax, Kimi, Qwen, MiMo, Ollama, native
+  Anthropic) — all use `--backend openai` with their own `base-url`.
+* INSTALL: bump heading and mention the new CLI.
+
+### Plugin tests
+
+19 new unit tests in `codemap-aimemory` covering: XDG path resolution,
+load / save / unset round-trip, `chmod 600` on save, corrupt-YAML
+graceful fallback, dash-vs-underscore key aliasing, CLI set / show /
+unset / path, source-annotation correctness in `show`. Plugin test
+total: 38 → 57. Other plugins unchanged.
+
+## [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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: codemap-core
-Version: 0.2.2
+Version: 0.3.1
 Summary: Language-neutral code index for AI agents
 Project-URL: Homepage, https://github.com/qxbyte/codemap
 Project-URL: Repository, https://github.com/qxbyte/codemap
@@ -78,8 +78,10 @@ mappings, and cross-file relationships without grepping the entire
 project. Indexing is static, fast, and reproducible — no LLM in the
 index path.
 
-**Status**: 0.2.0 stable. Installable from PyPI as `codemap-core`
-plus 17 `codemap-<lang>` plugins.
+**Status**: 0.3.1 stable. Installable from PyPI as `codemap-core`
+plus 17 `codemap-<lang>` plugins + 2 framework / output plugins
+(`codemap-mybatis`, `codemap-aimemory`, added in 0.3.0; 0.3.1
+adds the `codemap llm config` CLI).
 
 > 👉 **In a hurry?** The [`INSTALL.md`](./INSTALL.md) guide is the
 > definitive walkthrough — it covers `pipx` / `uv tool` / `pip`,
@@ -315,6 +317,14 @@ codemap routes                          # HTTP routes from the http_route bridge
 
 # Machine-readable output: all commands take --json
 codemap --json callers '<symbol-id>'
+
+# Optional LLM enrichment (codemap-aimemory plugin, 0.3.0+)
+codemap llm config set api-key sk-xxx       # persist to ~/.config/codemap/llm.yaml
+codemap llm config set base-url https://api.deepseek.com/v1
+codemap llm config set model deepseek-chat
+codemap llm config show                     # masked-key view + value source
+codemap enrich .                            # fills .ai-memory/enrichment/*.yml
+codemap enrich . --dry-run                  # count fn/method symbols, no API call
 ```
 
 Exit codes follow `sysexits.h` (ADR-005); see
@@ -322,6 +332,103 @@ Exit codes follow `sysexits.h` (ADR-005); see
 
 ---
 
+## Output formats
+
+`codemap index` produces two parallel directories at the project root:
+
+```
+<project>/
+├── .codemap/        ← deterministic, machine-friendly index (queried by `codemap …`)
+└── .ai-memory/      ← four-layer-memory-model L1 layout (consumed by AI agents)
+```
+
+### `.codemap/` — deterministic index (JSON, 7 files)
+
+| File | Contents |
+|---|---|
+| `symbols.json` | All symbols keyed by `SymbolID`. Each entry: `kind`, `language`, `file`, `range`, `signature`, `annotations`, `confidence`, `extra` (per-language metadata: `pending_calls`, `http_route`, `supertypes`, `imports`, `params`, `return_type`, `change_count_90d`, …). |
+| `edges.json` | Directed relations: `calls` / `extends` / `implements` / `overrides` / `references` / `routes_to` / `maps_to` / `imports` / `accesses_table`. Each carries `confidence` ∈ {`high`, `medium`, `low`}. |
+| `routes.json` | HTTP routes minted by the `http_route` bridge from `extra["http_route"]`. |
+| `aliases.json` | Synthetic intermediate ↔ real symbol links (e.g. route → handler). |
+| `manifest.json` | Project root, `codemap_version`, registered indexers + bridges + their versions, per-file sha256 / mtime / language. |
+| `diagnostics.json` | Indexer / bridge warnings collected during the run (severity + code + message + producer). |
+| `.lock` | Cross-process write lock; do not edit. |
+
+### `.ai-memory/` — four-layer memory L1 (YAML, 6 files)
+
+Generated by `codemap-aimemory` when installed. AI agents read this
+tree directly. Stable `entity_id` slugs are derived from the SCIP
+`SymbolID` (e.g. `fn-calcPrice` / `cls-OrderService` / `tbl-sf_coupon`).
+
+```
+.ai-memory/
+├── entities/
+│   ├── functions.yml      fn-* / cls-* with calls / called_by /
+│   │                      related_tables / signature / line_range /
+│   │                      confidence / change_count_90d / business_meaning
+│   ├── tables.yml         tbl-* table entities
+│   └── files.yml          file-* file entries
+├── relations/
+│   ├── call-graph.yml      `{from, to, type=calls, confidence}`
+│   ├── table-relations.yml `{from, to, type=accesses_table, confidence}`
+│   └── rule-constraints.yml empty placeholder (L2 owns)
+└── enrichment/             OPTIONAL: LLM-generated explanations
+    └── <sha1[:12]>.yml     `{symbol_id, business_meaning,
+                              related_rules, confidence:"llm",
+                              source_model, generated_at}`
+```
+
+Two-hop fan-out: when a Java method `maps_to` a `sql_mapping` that
+`accesses_table` T, T automatically lands on the method's
+`related_tables`. So `fn-selectByUser.related_tables = [tbl-sf_coupon]`
+without the agent needing to follow the chain itself.
+
+---
+
+## LLM configuration (optional)
+
+The core index is **always LLM-free** — `codemap index` never calls any
+LLM. Only the optional `codemap enrich` command in `codemap-aimemory`
+writes the `enrichment/` overlay, and only when **you** invoke it. The
+existence of an API key is the on/off switch: without one, `codemap
+enrich` exits with a clear error and no network call is made.
+
+Three configuration sources, **first non-empty wins**:
+
+1. **CLI flag** — `--api-key`, `--base-url`, `--model`, `--backend`
+2. **Environment variable** — `CODEMAP_LLM_API_KEY` (also
+   `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`); `CODEMAP_LLM_BASE_URL`
+   (also `OPENAI_BASE_URL`, `ANTHROPIC_BASE_URL`);
+   `CODEMAP_LLM_MODEL`; `CODEMAP_LLM_BACKEND`
+3. **Persistent file config** — `~/.config/codemap/llm.yaml` (managed
+   by `codemap llm config set/unset/show`; written `chmod 600`)
+4. Built-in defaults — backend `openai`, model `gpt-4o-mini`
+
+### Common provider endpoints (OpenAI-compatible — `--backend openai`)
+
+| Provider | Model example | Base URL |
+|---|---|---|
+| OpenAI | `gpt-4o-mini` | `https://api.openai.com/v1` *(default)* |
+| DeepSeek | `deepseek-chat` | `https://api.deepseek.com/v1` |
+| 智谱 GLM | `glm-4-flash` | `https://open.bigmodel.cn/api/paas/v4/` |
+| MiniMax | `abab6.5s-chat` | `https://api.minimax.chat/v1` |
+| 月之暗面 Kimi | `moonshot-v1-8k` | `https://api.moonshot.cn/v1` |
+| 阿里通义 | `qwen-plus` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| 小米 MiMo | `mimo-large` | *(per vendor docs; OpenAI-compatible)* |
+| Ollama (local) | `llama3` | `http://localhost:11434/v1` — use `--backend ollama` (key not needed) |
+| Anthropic native | `claude-sonnet-4-5` | *(use `--backend anthropic`; requires `anthropic` SDK via `pip install codemap-aimemory[llm]`)* |
+
+Example with DeepSeek:
+
+```bash
+codemap llm config set base-url https://api.deepseek.com/v1
+codemap llm config set api-key sk-xxx
+codemap llm config set model deepseek-chat
+codemap enrich .
+```
+
+---
+
 ## Configuration
 
 Project-level configuration lives at `.codemap/config.yaml` (committed

{codemap_core-0.2.2 → codemap_core-0.3.1}/README.md

@@ -11,8 +11,10 @@ mappings, and cross-file relationships without grepping the entire
 project. Indexing is static, fast, and reproducible — no LLM in the
 index path.
 
-**Status**: 0.2.0 stable. Installable from PyPI as `codemap-core`
-plus 17 `codemap-<lang>` plugins.
+**Status**: 0.3.1 stable. Installable from PyPI as `codemap-core`
+plus 17 `codemap-<lang>` plugins + 2 framework / output plugins
+(`codemap-mybatis`, `codemap-aimemory`, added in 0.3.0; 0.3.1
+adds the `codemap llm config` CLI).
 
 > 👉 **In a hurry?** The [`INSTALL.md`](./INSTALL.md) guide is the
 > definitive walkthrough — it covers `pipx` / `uv tool` / `pip`,
@@ -248,6 +250,14 @@ codemap routes                          # HTTP routes from the http_route bridge
 
 # Machine-readable output: all commands take --json
 codemap --json callers '<symbol-id>'
+
+# Optional LLM enrichment (codemap-aimemory plugin, 0.3.0+)
+codemap llm config set api-key sk-xxx       # persist to ~/.config/codemap/llm.yaml
+codemap llm config set base-url https://api.deepseek.com/v1
+codemap llm config set model deepseek-chat
+codemap llm config show                     # masked-key view + value source
+codemap enrich .                            # fills .ai-memory/enrichment/*.yml
+codemap enrich . --dry-run                  # count fn/method symbols, no API call
 ```
 
 Exit codes follow `sysexits.h` (ADR-005); see
@@ -255,6 +265,103 @@ Exit codes follow `sysexits.h` (ADR-005); see
 
 ---
 
+## Output formats
+
+`codemap index` produces two parallel directories at the project root:
+
+```
+<project>/
+├── .codemap/        ← deterministic, machine-friendly index (queried by `codemap …`)
+└── .ai-memory/      ← four-layer-memory-model L1 layout (consumed by AI agents)
+```
+
+### `.codemap/` — deterministic index (JSON, 7 files)
+
+| File | Contents |
+|---|---|
+| `symbols.json` | All symbols keyed by `SymbolID`. Each entry: `kind`, `language`, `file`, `range`, `signature`, `annotations`, `confidence`, `extra` (per-language metadata: `pending_calls`, `http_route`, `supertypes`, `imports`, `params`, `return_type`, `change_count_90d`, …). |
+| `edges.json` | Directed relations: `calls` / `extends` / `implements` / `overrides` / `references` / `routes_to` / `maps_to` / `imports` / `accesses_table`. Each carries `confidence` ∈ {`high`, `medium`, `low`}. |
+| `routes.json` | HTTP routes minted by the `http_route` bridge from `extra["http_route"]`. |
+| `aliases.json` | Synthetic intermediate ↔ real symbol links (e.g. route → handler). |
+| `manifest.json` | Project root, `codemap_version`, registered indexers + bridges + their versions, per-file sha256 / mtime / language. |
+| `diagnostics.json` | Indexer / bridge warnings collected during the run (severity + code + message + producer). |
+| `.lock` | Cross-process write lock; do not edit. |
+
+### `.ai-memory/` — four-layer memory L1 (YAML, 6 files)
+
+Generated by `codemap-aimemory` when installed. AI agents read this
+tree directly. Stable `entity_id` slugs are derived from the SCIP
+`SymbolID` (e.g. `fn-calcPrice` / `cls-OrderService` / `tbl-sf_coupon`).
+
+```
+.ai-memory/
+├── entities/
+│   ├── functions.yml      fn-* / cls-* with calls / called_by /
+│   │                      related_tables / signature / line_range /
+│   │                      confidence / change_count_90d / business_meaning
+│   ├── tables.yml         tbl-* table entities
+│   └── files.yml          file-* file entries
+├── relations/
+│   ├── call-graph.yml      `{from, to, type=calls, confidence}`
+│   ├── table-relations.yml `{from, to, type=accesses_table, confidence}`
+│   └── rule-constraints.yml empty placeholder (L2 owns)
+└── enrichment/             OPTIONAL: LLM-generated explanations
+    └── <sha1[:12]>.yml     `{symbol_id, business_meaning,
+                              related_rules, confidence:"llm",
+                              source_model, generated_at}`
+```
+
+Two-hop fan-out: when a Java method `maps_to` a `sql_mapping` that
+`accesses_table` T, T automatically lands on the method's
+`related_tables`. So `fn-selectByUser.related_tables = [tbl-sf_coupon]`
+without the agent needing to follow the chain itself.
+
+---
+
+## LLM configuration (optional)
+
+The core index is **always LLM-free** — `codemap index` never calls any
+LLM. Only the optional `codemap enrich` command in `codemap-aimemory`
+writes the `enrichment/` overlay, and only when **you** invoke it. The
+existence of an API key is the on/off switch: without one, `codemap
+enrich` exits with a clear error and no network call is made.
+
+Three configuration sources, **first non-empty wins**:
+
+1. **CLI flag** — `--api-key`, `--base-url`, `--model`, `--backend`
+2. **Environment variable** — `CODEMAP_LLM_API_KEY` (also
+   `ANTHROPIC_API_KEY`, `OPENAI_API_KEY`); `CODEMAP_LLM_BASE_URL`
+   (also `OPENAI_BASE_URL`, `ANTHROPIC_BASE_URL`);
+   `CODEMAP_LLM_MODEL`; `CODEMAP_LLM_BACKEND`
+3. **Persistent file config** — `~/.config/codemap/llm.yaml` (managed
+   by `codemap llm config set/unset/show`; written `chmod 600`)
+4. Built-in defaults — backend `openai`, model `gpt-4o-mini`
+
+### Common provider endpoints (OpenAI-compatible — `--backend openai`)
+
+| Provider | Model example | Base URL |
+|---|---|---|
+| OpenAI | `gpt-4o-mini` | `https://api.openai.com/v1` *(default)* |
+| DeepSeek | `deepseek-chat` | `https://api.deepseek.com/v1` |
+| 智谱 GLM | `glm-4-flash` | `https://open.bigmodel.cn/api/paas/v4/` |
+| MiniMax | `abab6.5s-chat` | `https://api.minimax.chat/v1` |
+| 月之暗面 Kimi | `moonshot-v1-8k` | `https://api.moonshot.cn/v1` |
+| 阿里通义 | `qwen-plus` | `https://dashscope.aliyuncs.com/compatible-mode/v1` |
+| 小米 MiMo | `mimo-large` | *(per vendor docs; OpenAI-compatible)* |
+| Ollama (local) | `llama3` | `http://localhost:11434/v1` — use `--backend ollama` (key not needed) |
+| Anthropic native | `claude-sonnet-4-5` | *(use `--backend anthropic`; requires `anthropic` SDK via `pip install codemap-aimemory[llm]`)* |
+
+Example with DeepSeek:
+
+```bash
+codemap llm config set base-url https://api.deepseek.com/v1
+codemap llm config set api-key sk-xxx
+codemap llm config set model deepseek-chat
+codemap enrich .
+```
+
+---
+
 ## Configuration
 
 Project-level configuration lives at `.codemap/config.yaml` (committed

codemap_core-0.3.1/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)