wikifier 4.6.2__tar.gz → 4.6.4__tar.gz

{wikifier-4.6.2/wikifier.egg-info → wikifier-4.6.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.6.2
+Version: 4.6.4
 Summary: Zero-dependency agent-to-agent codebase wiki for LLMs and AI agents. Autonomously maintained via record-change and mark-green for token-efficient lookup of files, dependencies, health, and summaries — across tiny scripts to 50k+ monorepos. Optional MCP server with rich tools for agents.
 Author-email: Aron Amos <aron@example.com>
 Maintainer: Aron Amos
@@ -84,27 +84,34 @@ Always set an explicit root for external trees: `WIKIFIER_PROJECT_ROOT=/abs/path
 
 ## Steady state (only touch what needs it)
 
-Full protocol: [`skills/run.md`](skills/run.md).
+Full protocol: [`skills/run.md`](skills/run.md) (Agent Protocol v0.6 — package **4.6.x**).
 
 ```bash
-wikifier check-changes          # yellow dirty files; red ghosts (missing paths)
-# prioritize 🔴 then 🟡 — do NOT re-wiki 🟢 Green files
+wikifier session-bootstrap      # one-shot: root, health, attention, actions[]
+wikifier check-changes          # content-honest dirty; red ghosts (missing paths)
+# prioritize 🔴 then *actionable* 🟡 — do NOT re-wiki 🟢 Green files
+wikifier prepare-edit path/file.py   # wiki + status + deps/dependents preflight
 # ... edit only those sources ...
 wikifier record-change "path/file.py" "why this changed"   # required
 # ... refresh that file’s wiki summary only ...
 wikifier mark-green "path/file.py"
-wikifier update-maps            # only if imports/structure changed
+wikifier update-maps            # only if imports/structure changed (warm 0-dirty is cheap)
 # removals:
 wikifier record-deletion "path/gone.py" "why removed"
 ```
 
-MCP **Core 6** (start every session): `get_project_status`, `check_changes`, `get_files_needing_attention`, `get_file_wiki`, `suggest_next_actions`, `record_change` / `mark_green`. Intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`. Always pass `project_root=` for external trees.
+**Core 6** (prefer every session — MCP or library/CLI):  
+`session_bootstrap` → `check_changes` → `prepare_edit` → `suggest_next_actions` (json `actions[]`) → `record_change` → `mark_green`.
+
+Advanced intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`, barrels/diagnostics. Always pass `project_root=` / `WIKIFIER_PROJECT_ROOT` for external trees. **Never** point `project_root` at a multi-repo parent folder (e.g. a directory of clones).
 
 ## What you get
 
-- **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust, Go, C/C++ includes, C# usings; per-edge confidence; name-routed barrel expansion for TS/JS
+- **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust (`use`/`mod` + best-effort `crate::` paths), Go, C/C++ includes, C# usings; per-edge confidence; barrel expansion for TS/JS
 - **Incremental pipeline** — pure-Python `update-maps`: dirty parse → import cache → reverse deps → cycles → `library.md`
-- **Selective agent work** — health + suggest bias to 🔴/🟡 only; ACS *actionable* low-conf excludes stdlib/external noise
+- **Warm agent maps (4.6.3+ / 4.6.4+)** — zero-dirty fast path skips full graph/`library.md` rewrite; **stdlib SQLite** import cache (dual-read legacy JSON) so warm dirty scans use mtime/hash index not multi‑MB pair JSON; content-hash dirty; `--directory=` scopes walks
+- **Partial-map honesty** — `map_coverage` on `update_maps` / bootstrap (`complete`, `files_remaining_dirty`, `acs_version`, `cache_backend`); budgeted runs are not “done”
+- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` alone
 - **Scale** — reverse index + barrel invalidation so one edit doesn’t re-scan the monorepo
 - **MCP tools** — optional server for Claude, Cursor, Cline, and other MCP clients
 - **Zero core dependencies** — stdlib only; forks can add their own stack on top
@@ -112,32 +119,45 @@ MCP **Core 6** (start every session): `get_project_status`, `check_changes`, `ge
 
 ## Performance (measured)
 
-| Project | Scale | Full `update-maps` |
-|---------|-------|--------------------|
-| llama_index | ~3.8k Python files | ~8.5s |
-| Babylon.js | ~3.9k TS files, barrel-heavy | ~4.5 min (scoped re-runs ~80s) |
-| Large trees (e.g. LLVM-scale) | tens of thousands of files | candidate scan in seconds |
+Full / heavy runs (historical order-of-magnitude):
+
+| Project | Scale | Full / heavy `update-maps` |
+|---------|-------|----------------------------|
+| llama_index | ~3.8k Python files | ~8.5s class full |
+| Babylon.js | ~3.9k TS files, barrel-heavy | minutes full; scoped re-runs tens of seconds |
+| Large trees (e.g. LLVM-scale) | tens of thousands of files | use lean monitor + `--directory` / `--max-files` |
+
+Warm **0-dirty** re-runs after 4.6.3 (same machine; scoped where noted) — agent session path:
+
+| Project | Scope | Warm2 `update-maps` |
+|---------|-------|---------------------|
+| Wikifier (self) | incremental full | ~43 ms |
+| redox | `src` | ~17 ms |
+| llama_index | `llama-index-core` | ~0.6 s |
+| rust | `library/std/src` (budgeted) | ~0.7 s (vs multi-second full-tree walk before scoped collect) |
 
-Tests: `python -m unittest discover tests` (stdlib only).
+Tests: `python -m unittest discover tests` (stdlib only; 86+ cases including agent-scale edges).
 
 ## Commands
 
 | Command | Purpose |
 |---------|---------|
 | `wikifier init [--target DIR]` | Bootstrap project + human `index.html` |
-| `wikifier check-changes` | Incremental scan → health / pending |
+| `wikifier session-bootstrap` | Session start: health, attention, dispatchable `actions[]` |
+| `wikifier check-changes` | Content-honest scan → health / pending |
+| `wikifier prepare-edit <file>` | Preflight: status, wiki snippet, deps, dependents |
 | `wikifier record-change <file> "reason"` | Log *why* (required after edits) |
-| `wikifier mark-green <file>` | Mark wiki current |
+| `wikifier mark-green <file>` | Mark wiki current + source content-hash baseline |
 | `wikifier record-deletion <file> "reason"` | Mark removed paths 🔴 + prune barrel refs |
-| `wikifier suggest-next` | Next actions (🔴/🟡 only) |
-| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` |
+| `wikifier suggest-next` | Next actions (🔴/actionable 🟡 only; `--json` for `actions[]`) |
+| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` (warm 0-dirty is fast) |
 | `wikifier health [--summary\|--json]` | Health matrix (machine-friendly flags) |
 | `wikifier validate` | Missing wiki rows + ghost paths |
 | `wikifier cycles` | Circular deps + break hints |
 | `wikifier monitor` / `daemon` | Background maintenance (`WIKIFIER_DAEMON_MAPS=0` for check-only) |
 | `wikifier serve` | Localhost dashboard with Run/Stop |
 
-Library: `from wikifier import check_changes, record_change, mark_green, suggest_next_actions, update_maps, health`.
+Library: `from wikifier import session_bootstrap, prepare_edit, check_changes, record_change, mark_green, suggest_next_actions, update_maps, health, list_core_tools`.
 
 ## MCP
 

{wikifier-4.6.2 → wikifier-4.6.4}/README.md

@@ -52,27 +52,34 @@ Always set an explicit root for external trees: `WIKIFIER_PROJECT_ROOT=/abs/path
 
 ## Steady state (only touch what needs it)
 
-Full protocol: [`skills/run.md`](skills/run.md).
+Full protocol: [`skills/run.md`](skills/run.md) (Agent Protocol v0.6 — package **4.6.x**).
 
 ```bash
-wikifier check-changes          # yellow dirty files; red ghosts (missing paths)
-# prioritize 🔴 then 🟡 — do NOT re-wiki 🟢 Green files
+wikifier session-bootstrap      # one-shot: root, health, attention, actions[]
+wikifier check-changes          # content-honest dirty; red ghosts (missing paths)
+# prioritize 🔴 then *actionable* 🟡 — do NOT re-wiki 🟢 Green files
+wikifier prepare-edit path/file.py   # wiki + status + deps/dependents preflight
 # ... edit only those sources ...
 wikifier record-change "path/file.py" "why this changed"   # required
 # ... refresh that file’s wiki summary only ...
 wikifier mark-green "path/file.py"
-wikifier update-maps            # only if imports/structure changed
+wikifier update-maps            # only if imports/structure changed (warm 0-dirty is cheap)
 # removals:
 wikifier record-deletion "path/gone.py" "why removed"
 ```
 
-MCP **Core 6** (start every session): `get_project_status`, `check_changes`, `get_files_needing_attention`, `get_file_wiki`, `suggest_next_actions`, `record_change` / `mark_green`. Intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`. Always pass `project_root=` for external trees.
+**Core 6** (prefer every session — MCP or library/CLI):  
+`session_bootstrap` → `check_changes` → `prepare_edit` → `suggest_next_actions` (json `actions[]`) → `record_change` → `mark_green`.
+
+Advanced intel as needed: `get_dependencies`, `get_dependents`, `get_cycles`, barrels/diagnostics. Always pass `project_root=` / `WIKIFIER_PROJECT_ROOT` for external trees. **Never** point `project_root` at a multi-repo parent folder (e.g. a directory of clones).
 
 ## What you get
 
-- **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust, Go, C/C++ includes, C# usings; per-edge confidence; name-routed barrel expansion for TS/JS
+- **Import analysis** — Python, JS/TS (ESM/CJS, barrels), Rust (`use`/`mod` + best-effort `crate::` paths), Go, C/C++ includes, C# usings; per-edge confidence; barrel expansion for TS/JS
 - **Incremental pipeline** — pure-Python `update-maps`: dirty parse → import cache → reverse deps → cycles → `library.md`
-- **Selective agent work** — health + suggest bias to 🔴/🟡 only; ACS *actionable* low-conf excludes stdlib/external noise
+- **Warm agent maps (4.6.3+ / 4.6.4+)** — zero-dirty fast path skips full graph/`library.md` rewrite; **stdlib SQLite** import cache (dual-read legacy JSON) so warm dirty scans use mtime/hash index not multi‑MB pair JSON; content-hash dirty; `--directory=` scopes walks
+- **Partial-map honesty** — `map_coverage` on `update_maps` / bootstrap (`complete`, `files_remaining_dirty`, `acs_version`, `cache_backend`); budgeted runs are not “done”
+- **Selective agent work** — health + suggest bias to 🔴/actionable 🟡 only; **ACS v1.3** `reason_code` / `agent_signal`; prefer `actionable_low_conf_edges` + reason codes — **never** raw `low_conf_edges` alone
 - **Scale** — reverse index + barrel invalidation so one edit doesn’t re-scan the monorepo
 - **MCP tools** — optional server for Claude, Cursor, Cline, and other MCP clients
 - **Zero core dependencies** — stdlib only; forks can add their own stack on top
@@ -80,32 +87,45 @@ MCP **Core 6** (start every session): `get_project_status`, `check_changes`, `ge
 
 ## Performance (measured)
 
-| Project | Scale | Full `update-maps` |
-|---------|-------|--------------------|
-| llama_index | ~3.8k Python files | ~8.5s |
-| Babylon.js | ~3.9k TS files, barrel-heavy | ~4.5 min (scoped re-runs ~80s) |
-| Large trees (e.g. LLVM-scale) | tens of thousands of files | candidate scan in seconds |
+Full / heavy runs (historical order-of-magnitude):
+
+| Project | Scale | Full / heavy `update-maps` |
+|---------|-------|----------------------------|
+| llama_index | ~3.8k Python files | ~8.5s class full |
+| Babylon.js | ~3.9k TS files, barrel-heavy | minutes full; scoped re-runs tens of seconds |
+| Large trees (e.g. LLVM-scale) | tens of thousands of files | use lean monitor + `--directory` / `--max-files` |
+
+Warm **0-dirty** re-runs after 4.6.3 (same machine; scoped where noted) — agent session path:
+
+| Project | Scope | Warm2 `update-maps` |
+|---------|-------|---------------------|
+| Wikifier (self) | incremental full | ~43 ms |
+| redox | `src` | ~17 ms |
+| llama_index | `llama-index-core` | ~0.6 s |
+| rust | `library/std/src` (budgeted) | ~0.7 s (vs multi-second full-tree walk before scoped collect) |
 
-Tests: `python -m unittest discover tests` (stdlib only).
+Tests: `python -m unittest discover tests` (stdlib only; 86+ cases including agent-scale edges).
 
 ## Commands
 
 | Command | Purpose |
 |---------|---------|
 | `wikifier init [--target DIR]` | Bootstrap project + human `index.html` |
-| `wikifier check-changes` | Incremental scan → health / pending |
+| `wikifier session-bootstrap` | Session start: health, attention, dispatchable `actions[]` |
+| `wikifier check-changes` | Content-honest scan → health / pending |
+| `wikifier prepare-edit <file>` | Preflight: status, wiki snippet, deps, dependents |
 | `wikifier record-change <file> "reason"` | Log *why* (required after edits) |
-| `wikifier mark-green <file>` | Mark wiki current |
+| `wikifier mark-green <file>` | Mark wiki current + source content-hash baseline |
 | `wikifier record-deletion <file> "reason"` | Mark removed paths 🔴 + prune barrel refs |
-| `wikifier suggest-next` | Next actions (🔴/🟡 only) |
-| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` |
+| `wikifier suggest-next` | Next actions (🔴/actionable 🟡 only; `--json` for `actions[]`) |
+| `wikifier update-maps [--directory=src/] [--max-files=N]` | Rebuild graph + `library.md` (warm 0-dirty is fast) |
 | `wikifier health [--summary\|--json]` | Health matrix (machine-friendly flags) |
 | `wikifier validate` | Missing wiki rows + ghost paths |
 | `wikifier cycles` | Circular deps + break hints |
 | `wikifier monitor` / `daemon` | Background maintenance (`WIKIFIER_DAEMON_MAPS=0` for check-only) |
 | `wikifier serve` | Localhost dashboard with Run/Stop |
 
-Library: `from wikifier import check_changes, record_change, mark_green, suggest_next_actions, update_maps, health`.
+Library: `from wikifier import session_bootstrap, prepare_edit, check_changes, record_change, mark_green, suggest_next_actions, update_maps, health, list_core_tools`.
 
 ## MCP
 

{wikifier-4.6.2 → wikifier-4.6.4}/skills/run.md

@@ -11,7 +11,8 @@
 - File Tree + `wikifier serve`; MCP status/attention use library + emoji (not `[GREEN]` tags).
 - **First-run:** `init` → `update-maps` → `health --summary` → `suggest_next_actions`. Map is automatic; wiki *prose* is agent-filled over time.
 - **Map-first ≠ wiki-done:** `health_score` **Map Ready** + many 🟡 *Initial stubs* means structural coverage only. Do **not** bulk-wiki stubs. Wiki a file when you edit it, then `mark-green`. Prefer `actionable_yellow` / 🔴 over raw yellow counts.
-- **Steady-state selective work:** only 🔴 and *actionable* 🟡 (never re-wiki 🟢; never re-wiki the whole stub set). ACS uses `actionable_low_conf_edges`.
+- **Steady-state selective work:** only 🔴 and *actionable* 🟡 (never re-wiki 🟢; never re-wiki the whole stub set). **ACS v1.3:** use `actionable_low_conf_edges` + `reason_code_counts` / `agent_signal` (`skip`|`investigate`). Do **not** thrash on raw `low_conf_edges` (includes external/bare scores ~0.48). Prefer `map_coverage.complete` / `files_remaining_dirty` after budgeted `update-maps` — `success: true` ≠ map complete.
+- **Warm maps:** import cache prefers stdlib SQLite (`.wikifier_staging/import_cache.sqlite`); zero-dirty path uses mtime index + meta, not full pair payload.
 - **Dual scope:** `monitored_paths` = check-changes/health scope (keep lean). `update-maps --directory=` / `--max-files=` = map walk. Never set `project_root` to a multi-repo parent (e.g. `cloned_sample_projects`).
 - **CLI target:** `wikifier --target /abs/project health --summary` (flags stripped before the command). Or `WIKIFIER_PROJECT_ROOT=…`.
 - **Long-horizon:** `wikifier autonomous-status` (or `readiness`) before unattended runs; daemon writes `.wikifier_staging/daemon_heartbeat.json`. Soak ≥72h is still evidence work, not automatic.

wikifier-4.6.4/tests/test_agent_scale.py

@@ -0,0 +1,244 @@
+"""Agent-scale perf/accuracy path tests (zero-dirty, content-hash dirty, ACS v1.3).
+
+Drives shipped library APIs only — no reimplementation of the unit under test.
+"""
+
+from __future__ import annotations
+
+import os
+import time
+import unittest
+from pathlib import Path
+
+from tests._base import TempProjectTestCase
+
+from wikifier import cli
+from wikifier import import_cache as ic
+from wikifier.import_cache import (
+    classify_edge_agent_signal,
+    compute_acs_summary,
+    compute_file_content_hash,
+)
+
+
+class TestContentHashDirty(TempProjectTestCase):
+    def test_mtime_thrash_does_not_reparse_when_content_hash_matches(self):
+        p = self.write("pkg/a.py", "import os\nx = 1\n")
+        # First map: populates cache + content_hash
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        self.assertGreaterEqual(int(r1.get("files_parsed") or 0), 1)
+        cache = ic.load_cache(self.root)
+        ent = cache.get("pkg/a.py") or cache.get("a.py")
+        # find entry
+        if ent is None:
+            for k, v in cache.items():
+                if str(k).endswith("a.py") and isinstance(v, dict):
+                    ent = v
+                    break
+        self.assertIsInstance(ent, dict, msg=f"cache keys={list(cache)[:20]}")
+        self.assertIn("content_hash", ent)
+        stored = ent["content_hash"]
+        live = compute_file_content_hash(p)
+        self.assertEqual(stored, live)
+
+        # Force stale mtime in cache, then touch file (same bytes)
+        ent["mtime"] = 1
+        ic.save_cache(self.root, cache)
+        time.sleep(0.05)
+        os.utime(p, None)
+
+        updates = []
+        need = ic.compute_files_needing_reparse(
+            self.root, [p], full_rebuild=False, content_stable_mtime_updates=updates
+        )
+        self.assertEqual(need, [], msg=f"should not reparse content-stable; updates={updates}")
+        self.assertGreaterEqual(len(updates), 1)
+
+    def test_content_change_does_reparse(self):
+        p = self.write("b.py", "y = 1\n")
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        cache = ic.load_cache(self.root)
+        ent = cache.get("b.py")
+        self.assertIsInstance(ent, dict)
+        ent["mtime"] = 1
+        # Keep old hash so mtime+hash mismatch forces reparse after rewrite
+        ic.save_cache(self.root, cache)
+        p.write_text("y = 2\n", encoding="utf-8")
+        time.sleep(0.02)
+        need = ic.compute_files_needing_reparse(self.root, [p], full_rebuild=False)
+        self.assertEqual(len(need), 1)
+        self.assertEqual(need[0].resolve(), p.resolve())
+
+
+class TestZeroDirtyFastPath(TempProjectTestCase):
+    def test_second_update_maps_uses_fast_path(self):
+        self.write("m.py", "print(1)\n")
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        # Ensure library exists so fast path can skip rewrite
+        self.assertTrue((self.root / "library.md").is_file() or r1.get("library", {}).get("success"))
+
+        r2 = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r2.get("success"), r2)
+        self.assertEqual(int(r2.get("files_parsed") or 0), 0)
+        self.assertEqual(int(r2.get("files_to_reparse") or 0), 0)
+        self.assertTrue(r2.get("zero_dirty_fast_path"), r2)
+        lib = r2.get("library") or {}
+        self.assertTrue(lib.get("success"), lib)
+        # Prefer skip when library already present
+        if (self.root / "library.md").is_file():
+            self.assertTrue(lib.get("skipped") or lib.get("path"))
+
+    def test_zero_dirty_persists_acs_v13_to_disk(self):
+        """Warm zero-dirty path must write ACS 1.3 + reason_code_counts to import_cache."""
+        self.write("n.py", "import os\nx=1\n")
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        # Simulate pre-1.3 cache left on disk (the bug: warm path upgraded memory only)
+        cache = ic.load_cache(self.root)
+        cache["_acs_summary"] = {
+            "acs_version": "1.2",
+            "total_scored_edges": 1,
+            "avg_confidence": 0.5,
+            "low_conf_edges": 1,
+            "actionable_low_conf_edges": 0,
+        }
+        ic.save_cache(self.root, cache)
+        on_disk = ic.load_cache(self.root)
+        self.assertEqual(str((on_disk.get("_acs_summary") or {}).get("acs_version")), "1.2")
+
+        r2 = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r2.get("success"), r2)
+        self.assertTrue(r2.get("zero_dirty_fast_path"), r2)
+        self.assertEqual((r2.get("acs") or {}).get("acs_version"), "1.3")
+
+        reloaded = ic.load_cache(self.root)
+        acs = reloaded.get("_acs_summary") or {}
+        self.assertEqual(acs.get("acs_version"), "1.3", msg=acs)
+        self.assertIn("reason_code_counts", acs)
+        self.assertIsInstance(acs.get("reason_code_counts"), dict)
+
+    def test_max_files_skip_honesty(self):
+        for i in range(5):
+            self.write(f"f{i}.py", f"v = {i}\n")
+        r = cli.update_maps(project_root=self.root, full=True, max_files=2)
+        self.assertTrue(r.get("success"), r)
+        self.assertEqual(int(r.get("files_parsed") or 0), 2)
+        self.assertEqual(int(r.get("files_skipped") or 0), 3)
+
+
+class TestACSv13(TempProjectTestCase):
+    def test_classify_edge_reason_codes(self):
+        ext = {
+            "raw": "os",
+            "resolved": "",
+            "confidence_score": 0.48,
+            "diagnostic": {"category": "external_or_bare"},
+            "resolution_metadata": {"strategy": "python-bare-or-external"},
+        }
+        sig = classify_edge_agent_signal(ext)
+        self.assertEqual(sig["agent_signal"], "skip")
+        self.assertEqual(sig["reason_code"], "external_or_bare")
+        self.assertFalse(sig["actionable"])
+
+        unres = {"raw": ".missing", "resolved": "", "confidence_score": 0.4}
+        sig2 = classify_edge_agent_signal(unres)
+        self.assertEqual(sig2["agent_signal"], "investigate")
+        self.assertEqual(sig2["reason_code"], "unresolved_project")
+        self.assertTrue(sig2["actionable"])
+
+        ok = {"raw": "./x", "resolved": "x.py", "confidence_score": 0.95}
+        sig3 = classify_edge_agent_signal(ok)
+        self.assertEqual(sig3["reason_code"], "high_confidence_ok")
+        self.assertFalse(sig3["actionable"])
+
+    def test_compute_acs_summary_v13_shape(self):
+        cache = {
+            "a.py": {
+                "mtime": 1,
+                "resolved_pairs": [
+                    {
+                        "raw": "os",
+                        "resolved": "",
+                        "confidence_score": 0.48,
+                        "diagnostic": {"category": "external_or_bare"},
+                        "resolution_metadata": {"strategy": "python-bare-or-external"},
+                    },
+                    {
+                        "raw": ".b",
+                        "resolved": "b.py",
+                        "confidence_score": 0.5,
+                        "confidence_explanation": "low internal",
+                    },
+                    {
+                        "raw": ".missing",
+                        "resolved": "",
+                        "confidence_score": 0.4,
+                        "confidence_explanation": "unresolved project",
+                    },
+                ],
+            }
+        }
+        acs = compute_acs_summary(cache)
+        self.assertEqual(acs["acs_version"], "1.3")
+        self.assertIn("reason_code_counts", acs)
+        self.assertIn("agent_signal_counts", acs)
+        self.assertGreaterEqual(acs["actionable_low_conf_edges"], 2)
+        self.assertGreaterEqual(acs["external_noise_edges"], 1)
+        self.assertIn("investigate", acs["agent_signal_counts"])
+
+
+class TestCoreLoopEdges(TempProjectTestCase):
+    def test_session_bootstrap_and_prepare_edit(self):
+        self.write("hub.py", "import os\n")
+        cli.update_maps(project_root=self.root, full=True)
+        boot = cli.session_bootstrap(project_root=self.root)
+        self.assertTrue(boot.get("success"), boot)
+        self.assertIn("actions", boot)
+        pe = cli.prepare_edit("hub.py", project_root=self.root)
+        self.assertTrue(pe.get("success"), pe)
+        self.assertIn("status", pe)
+
+    def test_invalid_project_root_structured(self):
+        # missing path should not crash core helpers
+        missing = self.root / "no_such_project_dir"
+        r = cli.check_changes(project_root=missing)
+        self.assertIsInstance(r, dict)
+        # either success with empty or structured failure — never exception
+        self.assertIn("success", r)
+
+    def test_prepare_edit_missing_file_fails(self):
+        r = cli.prepare_edit("does_not_exist_xyz.py", project_root=self.root)
+        self.assertIsInstance(r, dict)
+        self.assertFalse(r.get("success"), r)
+        self.assertIn("error", r)
+
+    def test_multi_repo_parent_scope_warning_or_ok_flag(self):
+        # Bootstrap on a real root must set scope.ok; parent-of-many is agent anti-pattern
+        boot = cli.session_bootstrap(project_root=self.root)
+        self.assertTrue(boot.get("success"), boot)
+        scope = boot.get("scope") or {}
+        self.assertIn("ok", scope)
+
+
+class TestRustCrateResolve(TempProjectTestCase):
+    def test_crate_use_resolves_sibling_module(self):
+        from wikifier.parsers import rust as rust_parser
+
+        lib = self.write("src/lib.rs", "mod foo;\npub use crate::foo::bar;\n")
+        self.write("src/foo.rs", "pub fn bar() {}\n")
+        edges = rust_parser.parse_rust_imports(str(lib))
+        uses = [e for e in edges if e.get("statement_type") == "use"]
+        self.assertTrue(uses)
+        # at least one use should resolve to foo.rs when crate path works
+        resolved_any = [e for e in uses if e.get("resolved_path")]
+        self.assertTrue(
+            resolved_any,
+            msg=f"expected crate:: resolve; edges={uses}",
+        )
+
+
+if __name__ == "__main__":
+    unittest.main()

wikifier-4.6.4/tests/test_cache_store.py

@@ -0,0 +1,193 @@
+"""SQLite cache store + map_coverage + warm path (shipped APIs, zero-dep)."""
+
+from __future__ import annotations
+
+import os
+import time
+import unittest
+from pathlib import Path
+
+from tests._base import TempProjectTestCase
+
+from wikifier import cli
+from wikifier import import_cache as ic
+from wikifier import cache_store as cs
+
+
+class TestSqliteCacheRoundTrip(TempProjectTestCase):
+    def test_save_load_sqlite_primary(self):
+        self.write("a.py", "import os\n")
+        r = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r.get("success"), r)
+        self.assertTrue(cs.has_sqlite(self.root), "sqlite should exist after save")
+        cache = ic.load_cache(self.root)
+        self.assertIn("a.py", cache)
+        self.assertIsInstance(cache["a.py"].get("mtime"), int)
+        # light index works without requiring pairs field presence
+        idx = ic.load_mtime_index(self.root)
+        self.assertIn("a.py", idx)
+        self.assertEqual(idx["a.py"]["mtime"], cache["a.py"]["mtime"])
+
+    def test_legacy_json_dual_read_then_migrate(self):
+        # Plant legacy JSON only (no sqlite)
+        staging = self.root / ".wikifier_staging"
+        staging.mkdir(parents=True, exist_ok=True)
+        import json
+        legacy = {
+            "x.py": {
+                "mtime": 1,
+                "content_hash": "sha256:abc",
+                "imports": ["os"],
+                "resolved": [],
+                "resolved_pairs": [{"raw": "os", "resolved": "", "confidence_score": 0.48}],
+            },
+            "_acs_summary": {
+                "acs_version": "1.2",
+                "total_scored_edges": 1,
+                "actionable_low_conf_edges": 0,
+                "low_conf_edges": 1,
+            },
+        }
+        (staging / "import_cache.json").write_text(
+            json.dumps(legacy), encoding="utf-8"
+        )
+        loaded = ic.load_cache(self.root)
+        self.assertIn("x.py", loaded)
+        # update_maps migrates
+        self.write("x.py", "import os\n")
+        r = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r.get("success"), r)
+        self.assertTrue(cs.has_sqlite(self.root))
+
+
+class TestWarmPathNoFullJsonTax(TempProjectTestCase):
+    def test_zero_dirty_reports_sqlite_backend_and_coverage(self):
+        self.write("m.py", "print(1)\n")
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        r2 = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r2.get("success"), r2)
+        self.assertTrue(r2.get("zero_dirty_fast_path"), r2)
+        self.assertIn(r2.get("cache_backend"), ("sqlite", "sqlite+json", "json"))
+        cov = r2.get("map_coverage") or {}
+        self.assertTrue(cov.get("complete"), cov)
+        self.assertIn("files_remaining_dirty", cov)
+        self.assertEqual(int(cov["files_remaining_dirty"]), 0)
+
+    def test_zero_dirty_skips_full_payload_load_cache_dict(self):
+        """Shipped warm path must not deserialize full file payloads on 0-dirty.
+
+        Criterion: after SQLite is warm, zero-dirty update_maps must not call
+        cache_store.load_cache_dict (full pairs) or ic.load_cache (legacy full).
+        Light index + meta only.
+        """
+        self.write("warm.py", "print(0)\n")
+        r1 = cli.update_maps(project_root=self.root, full=True)
+        self.assertTrue(r1.get("success"), r1)
+        self.assertTrue(cs.has_sqlite(self.root))
+        # Second run seeds zero-dirty + sqlite
+        r_seed = cli.update_maps(project_root=self.root, full=False)
+        self.assertTrue(r_seed.get("zero_dirty_fast_path"), r_seed)
+
+        full_loads = {"load_cache_dict": 0, "load_cache": 0}
+        real_lcd = cs.load_cache_dict
+        real_lc = ic.load_cache
+
+        def counting_lcd(root):
+            full_loads["load_cache_dict"] += 1
+            return real_lcd(root)
+
+        def counting_lc(root):
+            full_loads["load_cache"] += 1
+            return real_lc(root)
+
+        # Patch at the modules the shipped path imports from
+        import wikifier.cache_store as cs_mod
+        import wikifier.import_cache as ic_mod
+        orig_cs = cs_mod.load_cache_dict
+        orig_ic = ic_mod.load_cache
+        cs_mod.load_cache_dict = counting_lcd  # type: ignore
+        ic_mod.load_cache = counting_lc  # type: ignore
+        try:
+            r2 = cli.update_maps(project_root=self.root, full=False)
+        finally:
+            cs_mod.load_cache_dict = orig_cs  # type: ignore
+            ic_mod.load_cache = orig_ic  # type: ignore
+
+        self.assertTrue(r2.get("success"), r2)
+        self.assertTrue(r2.get("zero_dirty_fast_path"), r2)
+        self.assertEqual(
+            full_loads["load_cache_dict"],
+            0,
+            f"warm 0-dirty must not call load_cache_dict; counts={full_loads}",
+        )
+        self.assertEqual(
+            full_loads["load_cache"],
+            0,
+            f"warm 0-dirty must not call load_cache; counts={full_loads}",
+        )
+
+    def test_max_files_coverage_incomplete(self):
+        for i in range(6):
+            self.write(f"f{i}.py", f"v={i}\n")
+        r = cli.update_maps(project_root=self.root, full=True, max_files=2)
+        self.assertTrue(r.get("success"), r)
+        cov = r.get("map_coverage") or {}
+        self.assertFalse(cov.get("complete"), cov)
+        self.assertEqual(int(cov.get("files_skipped") or 0), 4)
+        self.assertGreaterEqual(int(cov.get("files_remaining_dirty") or 0), 4)
+        self.assertIn("agent_note", cov)
+
+    def test_mtime_index_skips_content_stable(self):
+        p = self.write("s.py", "x=1\n")
+        cli.update_maps(project_root=self.root, full=True)
+        cache = ic.load_cache(self.root)
+        ent = cache["s.py"]
+        ent["mtime"] = 1
+        ic.save_cache(self.root, cache)
+        time.sleep(0.05)
+        os.utime(p, None)
+        updates = []
+        need = ic.compute_files_needing_reparse(
+            self.root, [p], content_stable_mtime_updates=updates
+        )
+        # content_hash should make this stable once hash stored
+        if ent.get("content_hash"):
+            self.assertEqual(need, [])
+            self.assertGreaterEqual(len(updates), 1)
+
+
+class TestBootstrapCoverageAndAcsGuidance(TempProjectTestCase):
+    def test_bootstrap_surfaces_acs_guidance(self):
+        self.write("h.py", "import os\n")
+        cli.update_maps(project_root=self.root, full=True)
+        boot = cli.session_bootstrap(project_root=self.root)
+        self.assertTrue(boot.get("success"), boot)
+        self.assertIn("acs_guidance", boot)
+        self.assertIn("actionable_low_conf_edges", boot["acs_guidance"])
+        acs = boot.get("acs") or {}
+        self.assertIn("acs_version", acs)
+
+
+class TestGoModResolve(TempProjectTestCase):
+    def test_same_module_import_resolves(self):
+        from wikifier.parsers import go_lang as go
+
+        self.write(
+            "go.mod",
+            "module example.com/demo\n\ngo 1.21\n",
+        )
+        self.write("pkg/util/util.go", "package util\nfunc X() {}\n")
+        main = self.write(
+            "cmd/main.go",
+            'package main\nimport "example.com/demo/pkg/util"\n',
+        )
+        edges = go.parse_go_imports(str(main))
+        self.assertTrue(edges)
+        resolved = [e for e in edges if e.get("resolved_path")]
+        self.assertTrue(resolved, msg=f"edges={edges}")
+        self.assertIn("util", resolved[0]["resolved_path"])
+
+
+if __name__ == "__main__":
+    unittest.main()