wikifier 4.2.0__tar.gz → 4.3.1__tar.gz

{wikifier-4.2.0/wikifier.egg-info → wikifier-4.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.2.0
+Version: 4.3.1
 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
@@ -92,7 +92,7 @@ For external projects or monorepos, always pass an explicit root: `WIKIFIER_PROJ
 
 ## What You Get
 
-- **Fast, real dependency analysis** — Python and JavaScript/TypeScript import parsing (ES modules, CommonJS, dynamic imports, TypeScript path aliases, package.json exports, workspaces), barrel/re-export chain expansion, and per-edge confidence scoring with actionable explanations
+- **Fast, real dependency analysis** — Python and JavaScript/TypeScript import parsing (ES modules, CommonJS, dynamic imports, TypeScript path aliases, package.json exports, workspaces), per-edge confidence scoring with actionable explanations, and **name-routed barrel expansion**: an import through an `export *` barrel resolves to the leaves that actually define the imported symbols, not hundreds of false edges
 - **A pure-Python update pipeline** — `update-maps` parses every changed file in-process, persists a canonical import cache, computes reverse dependencies, Tarjan-based circular dependency detection, and regenerates `library.md` atomically
 - **Incremental everything** — mtime-based dirty detection plus a barrel-aware reverse index means editing one file re-analyzes only its true consumers, even in barrel-heavy monorepos
 - **Autonomous maintenance** — agents log intent with `record-change`, refresh summaries, and `mark-green`; a background `monitor`/daemon keeps the matrix fresh
@@ -107,7 +107,7 @@ Validated by dogfooding on Wikifier itself plus large open-source codebases —
 | Codebase | Scale | Full `update-maps` |
 |----------|-------|--------------------|
 | llama_index | 3,837 Python files | **~8.5s** (17k import edges, full map) |
-| Babylon.js | 3,905 TypeScript files, barrel-heavy | completes with full 5,389-node map |
+| Babylon.js | 3,905 TypeScript files, barrel-heavy | **~4.5min** full build (44k precise edges, 5,389-node map); scoped re-runs ~80s |
 | Linux kernel / LLVM / Rust | 37k–54k file trees | candidate scan in 3–8s |
 
 JS/TS parsing runs at ~22ms per file; Python at ~1ms. Incremental runs after the first build take seconds. Verified by a stdlib-only test suite (`python -m unittest discover tests`).
@@ -120,7 +120,7 @@ JS/TS parsing runs at ~22ms per file; Python at ~1ms. Incremental runs after the
 | `wikifier check-changes` | Incremental change scan + health/pending update |
 | `wikifier record-change <file> "reason"` | Log the *why* (required after edits) |
 | `wikifier mark-green <file>` | Mark the wiki entry current |
-| `wikifier update-maps [--full] [--directory=src/]` | Rebuild dependency graph + library.md (pure-Python pipeline; `--sh` for the legacy shell path) |
+| `wikifier update-maps [--full] [--directory=src/]` | Rebuild dependency graph + library.md (single pure-Python pipeline; the shell launcher delegates here) |
 | `wikifier health [--summary\|--json]` | Health matrix — compact formats for agents |
 | `wikifier cycles` | Circular dependency report with break recommendations |
 | `wikifier monitor &` / `wikifier daemon start` | Background heartbeat / managed maintenance |
@@ -137,22 +137,22 @@ Works with Claude Desktop, Claude Code, Cursor, Cline, and any Model Context Pro
 
 ## The Human Layer (Secondary, by Design)
 
-`wikifier init` copies a single static `index.html` into your project: a read-only dashboard showing the Mermaid code-structure chart, files with short descriptions, and a folder browser — useful for humans investigating what the agents know. Command buttons copy the exact CLI command and live-poll for results (a static page can't execute shell commands — that's the browser sandbox working as intended). The agent-facing markdown files and tools remain the single source of truth.
+`wikifier init` copies a single static `index.html` into your project: a read-only dashboard showing the Mermaid code-structure chart, files with short descriptions, and a folder browser — useful for humans investigating what the agents know. View it with **`wikifier serve`** (then open http://localhost:8787/index.html) — browsers block `file://` fetches, so a double-clicked index.html can't read the wiki files; the page detects that case and shows you the fix. Command buttons copy the exact CLI command and live-poll for results (a static page can't execute shell commands — that's the browser sandbox working as intended). The agent-facing markdown files and tools remain the single source of truth.
 
 ## Intended Use: Strictly Agent-to-Agent
 
 Wikifier is a token-saving wiki layer *for agents*, and deliberately nothing more: not a general documentation generator, not an IDE plugin, not a code search engine for humans. Agents consult the map instead of re-reading sources, keep it current as they work, and create new wiki entries on the fly. The human dashboard is a window into that, not the product.
 
-## What's New in v4.2.0
+## What's New in v4.3.0
 
-A full real-world dogfood sweep (this repo + RecipeLab + 8 large OSS projects) followed by a fix pass for everything it surfaced:
+Precision and performance, validated on real monorepos:
 
-- `update-maps` now defaults to the **pure-Python pipeline**: every changed file actually parsed, canonical cache schema, cycles/ACS/reverse-deps computed, `library.md` regenerated atomically
-- **43× faster JS/TS parsing** (barrel-cache persistence batched per run instead of per chain)
-- Fixed a POSIX lock self-deadlock in the library workflow calls (the likely cause of historical MCP timeouts), barrel-churn invalidation, static-import flag pollution, exclude-pattern globs, `health --summary/--json`, and several shell-path crashes — one of which could destroy an existing `library.md`
-- **New stdlib-only test suite** (28 tests) — the project's first formal regression net
+- **Name-routed barrel expansion** — an import through an `export *` barrel resolves to the leaves that define the imported symbols (on Babylon.js, one 778-edge import became 3 precise edges; repo-wide edge count dropped 89%). Imports with no routable names are capped with the truncation *reported* on the edge — never silent
+- **Thin shell** — the launcher now delegates `update-maps` to the Python pipeline (2,910 → 785 lines; 3m39s → 2s on a small project; a hang-prone legacy code path is gone entirely)
+- **Bounded barrel-cache persistence + memoized root discovery** — Babylon.js's import cache shrank 274MB → 101MB, and a pathological scoped re-run went from 75 minutes to ~80 seconds
+- `imported_names` is now populated on JS/TS edges, and files outside the configured project root resolve correctly (containment rule)
 
-Full details: [`CHANGELOG.md`](CHANGELOG.md) and `Findings/2026-06-10-Dogfood-Refactor-Validation.md`.
+v4.2.0 (same day) made `update-maps` a real full pipeline, fixed the lock deadlock behind historical MCP timeouts, and added the test suite. Full history: [`CHANGELOG.md`](CHANGELOG.md) and `Findings/`.
 
 ## Links
 

{wikifier-4.2.0 → wikifier-4.3.1}/README.md

@@ -60,7 +60,7 @@ For external projects or monorepos, always pass an explicit root: `WIKIFIER_PROJ
 
 ## What You Get
 
-- **Fast, real dependency analysis** — Python and JavaScript/TypeScript import parsing (ES modules, CommonJS, dynamic imports, TypeScript path aliases, package.json exports, workspaces), barrel/re-export chain expansion, and per-edge confidence scoring with actionable explanations
+- **Fast, real dependency analysis** — Python and JavaScript/TypeScript import parsing (ES modules, CommonJS, dynamic imports, TypeScript path aliases, package.json exports, workspaces), per-edge confidence scoring with actionable explanations, and **name-routed barrel expansion**: an import through an `export *` barrel resolves to the leaves that actually define the imported symbols, not hundreds of false edges
 - **A pure-Python update pipeline** — `update-maps` parses every changed file in-process, persists a canonical import cache, computes reverse dependencies, Tarjan-based circular dependency detection, and regenerates `library.md` atomically
 - **Incremental everything** — mtime-based dirty detection plus a barrel-aware reverse index means editing one file re-analyzes only its true consumers, even in barrel-heavy monorepos
 - **Autonomous maintenance** — agents log intent with `record-change`, refresh summaries, and `mark-green`; a background `monitor`/daemon keeps the matrix fresh
@@ -75,7 +75,7 @@ Validated by dogfooding on Wikifier itself plus large open-source codebases —
 | Codebase | Scale | Full `update-maps` |
 |----------|-------|--------------------|
 | llama_index | 3,837 Python files | **~8.5s** (17k import edges, full map) |
-| Babylon.js | 3,905 TypeScript files, barrel-heavy | completes with full 5,389-node map |
+| Babylon.js | 3,905 TypeScript files, barrel-heavy | **~4.5min** full build (44k precise edges, 5,389-node map); scoped re-runs ~80s |
 | Linux kernel / LLVM / Rust | 37k–54k file trees | candidate scan in 3–8s |
 
 JS/TS parsing runs at ~22ms per file; Python at ~1ms. Incremental runs after the first build take seconds. Verified by a stdlib-only test suite (`python -m unittest discover tests`).
@@ -88,7 +88,7 @@ JS/TS parsing runs at ~22ms per file; Python at ~1ms. Incremental runs after the
 | `wikifier check-changes` | Incremental change scan + health/pending update |
 | `wikifier record-change <file> "reason"` | Log the *why* (required after edits) |
 | `wikifier mark-green <file>` | Mark the wiki entry current |
-| `wikifier update-maps [--full] [--directory=src/]` | Rebuild dependency graph + library.md (pure-Python pipeline; `--sh` for the legacy shell path) |
+| `wikifier update-maps [--full] [--directory=src/]` | Rebuild dependency graph + library.md (single pure-Python pipeline; the shell launcher delegates here) |
 | `wikifier health [--summary\|--json]` | Health matrix — compact formats for agents |
 | `wikifier cycles` | Circular dependency report with break recommendations |
 | `wikifier monitor &` / `wikifier daemon start` | Background heartbeat / managed maintenance |
@@ -105,22 +105,22 @@ Works with Claude Desktop, Claude Code, Cursor, Cline, and any Model Context Pro
 
 ## The Human Layer (Secondary, by Design)
 
-`wikifier init` copies a single static `index.html` into your project: a read-only dashboard showing the Mermaid code-structure chart, files with short descriptions, and a folder browser — useful for humans investigating what the agents know. Command buttons copy the exact CLI command and live-poll for results (a static page can't execute shell commands — that's the browser sandbox working as intended). The agent-facing markdown files and tools remain the single source of truth.
+`wikifier init` copies a single static `index.html` into your project: a read-only dashboard showing the Mermaid code-structure chart, files with short descriptions, and a folder browser — useful for humans investigating what the agents know. View it with **`wikifier serve`** (then open http://localhost:8787/index.html) — browsers block `file://` fetches, so a double-clicked index.html can't read the wiki files; the page detects that case and shows you the fix. Command buttons copy the exact CLI command and live-poll for results (a static page can't execute shell commands — that's the browser sandbox working as intended). The agent-facing markdown files and tools remain the single source of truth.
 
 ## Intended Use: Strictly Agent-to-Agent
 
 Wikifier is a token-saving wiki layer *for agents*, and deliberately nothing more: not a general documentation generator, not an IDE plugin, not a code search engine for humans. Agents consult the map instead of re-reading sources, keep it current as they work, and create new wiki entries on the fly. The human dashboard is a window into that, not the product.
 
-## What's New in v4.2.0
+## What's New in v4.3.0
 
-A full real-world dogfood sweep (this repo + RecipeLab + 8 large OSS projects) followed by a fix pass for everything it surfaced:
+Precision and performance, validated on real monorepos:
 
-- `update-maps` now defaults to the **pure-Python pipeline**: every changed file actually parsed, canonical cache schema, cycles/ACS/reverse-deps computed, `library.md` regenerated atomically
-- **43× faster JS/TS parsing** (barrel-cache persistence batched per run instead of per chain)
-- Fixed a POSIX lock self-deadlock in the library workflow calls (the likely cause of historical MCP timeouts), barrel-churn invalidation, static-import flag pollution, exclude-pattern globs, `health --summary/--json`, and several shell-path crashes — one of which could destroy an existing `library.md`
-- **New stdlib-only test suite** (28 tests) — the project's first formal regression net
+- **Name-routed barrel expansion** — an import through an `export *` barrel resolves to the leaves that define the imported symbols (on Babylon.js, one 778-edge import became 3 precise edges; repo-wide edge count dropped 89%). Imports with no routable names are capped with the truncation *reported* on the edge — never silent
+- **Thin shell** — the launcher now delegates `update-maps` to the Python pipeline (2,910 → 785 lines; 3m39s → 2s on a small project; a hang-prone legacy code path is gone entirely)
+- **Bounded barrel-cache persistence + memoized root discovery** — Babylon.js's import cache shrank 274MB → 101MB, and a pathological scoped re-run went from 75 minutes to ~80 seconds
+- `imported_names` is now populated on JS/TS edges, and files outside the configured project root resolve correctly (containment rule)
 
-Full details: [`CHANGELOG.md`](CHANGELOG.md) and `Findings/2026-06-10-Dogfood-Refactor-Validation.md`.
+v4.2.0 (same day) made `update-maps` a real full pipeline, fixed the lock deadlock behind historical MCP timeouts, and added the test suite. Full history: [`CHANGELOG.md`](CHANGELOG.md) and `Findings/`.
 
 ## Links
 

{wikifier-4.2.0 → wikifier-4.3.1}/index.html

@@ -770,9 +770,44 @@ Open index.html in the project for the live visual version.
         }
 
         // Boot: only what the human view needs (chart + files+descs + tree + monitor). Poll for live feel.
+        // Browsers refuse fetch() from file:// pages (unique-origin sandbox),
+        // so a double-clicked index.html can never read the wiki artifacts —
+        // the map stays empty while the console fills with CORS errors. Show
+        // the one-command fix prominently instead of failing silently.
+        function showFileProtocolNotice() {
+            const div = document.createElement('div');
+            div.id = 'file-protocol-notice';
+            div.style.cssText = 'position:sticky;top:0;z-index:60;background:#7c2d12;color:#ffedd5;padding:14px 18px;font-size:14px;line-height:1.6;box-shadow:0 2px 8px rgba(0,0,0,.4)';
+            div.innerHTML = '<strong>The dashboard cannot read the wiki files when opened directly from disk.</strong><br>' +
+                'Browsers block <code>fetch()</code> on <code>file://</code> pages (security sandbox), so the map and file list would stay empty. ' +
+                'Serve this folder over localhost instead — run one of these in the project folder, then open the link:' +
+                '<div style="margin-top:8px;display:flex;gap:8px;flex-wrap:wrap;align-items:center">' +
+                '<button id="fpCopyServe" style="background:#10b981;color:#06281e;border:none;border-radius:6px;padding:6px 12px;font-weight:600;cursor:pointer">Copy: wikifier serve</button>' +
+                '<button id="fpCopyPy" style="background:#374151;color:#e5e7eb;border:none;border-radius:6px;padding:6px 12px;cursor:pointer">Copy: python3 -m http.server 8787</button>' +
+                '<a href="http://localhost:8787/index.html" style="color:#5eead4;text-decoration:underline">open http://localhost:8787/index.html</a>' +
+                '</div>';
+            document.body.prepend(div);
+            const wire = (id, text) => {
+                const b = document.getElementById(id);
+                if (!b) return;
+                b.onclick = () => navigator.clipboard.writeText(text).then(() => {
+                    const old = b.textContent;
+                    b.textContent = 'Copied ✓';
+                    setTimeout(() => { b.textContent = old; }, 1600);
+                });
+            };
+            wire('fpCopyServe', 'wikifier serve');
+            wire('fpCopyPy', 'python3 -m http.server 8787');
+        }
+
         function boot() {
             initTailwind();
 
+            if (location.protocol === 'file:') {
+                showFileProtocolNotice();
+                return; // skip data loads + polling: every fetch would fail
+            }
+
             loadHealthMatrix();
             loadMermaid();
             loadMonitorStatus();

{wikifier-4.2.0 → wikifier-4.3.1}/skills/run.md

@@ -7,8 +7,8 @@
 **Status**: Active. Supersedes v0.5.  
 **See also**: `README.md` (Intended Use section: strictly agent-to-agent wiki for token saving), M5-Dogfood-Assessment-Report.md, Findings/2026-06-10-Dogfood-Refactor-Validation.md, and the library in wikifier/.
 
-**v0.6 migration notes (package v4.2.0)** — changes are additive or strictly-better defaults; v0.5 agent behavior keeps working:
-- `update-maps` (CLI) now runs the **pure-Python full pipeline by default**: every dirty file is parsed in-process, the canonical per-file cache is persisted, reverse deps + cycles + ACS are computed, and `library.md` is regenerated atomically. `--python-primary` is accepted but redundant; `--sh`/`--legacy-sh` selects the legacy shell path (slow fallback). Scoping is explicit via `--directory=`/`--max-files=` and reported in the result (`files_skipped`) — there are no silent caps.
+**v0.6 migration notes (packages v4.2.0–v4.3.0)** — changes are additive or strictly-better defaults; v0.5 agent behavior keeps working:
+- `update-maps` (CLI) now runs the **pure-Python full pipeline**: every dirty file is parsed in-process, the canonical per-file cache is persisted, reverse deps + cycles + ACS are computed, and `library.md` is regenerated atomically. `--python-primary` is accepted but redundant; the in-shell first-pass was retired entirely (wikifier.sh's update-maps delegates to this pipeline; `--sh`/`--legacy-sh` are deprecated no-ops). Scoping is explicit via `--directory=`/`--max-files=` and reported in the result (`files_skipped`) — there are no silent caps.
 - `run_full_update`/`update_maps` returns gained additive fields: `files_parsed` (actual), `parseable_files`, `edges_persisted`, `files_skipped`, `cycles`, `library`. Tolerate additive fields as always.
 - `wikifier health --summary|--json|--format=...` now work from the CLI (previously library-only).
 - A POSIX lock self-deadlock in library `record_change`/`mark_green`/`check_changes` was fixed (locking is now re-entrant per process). MCP timeouts on those tools should no longer occur; the CLI fallback guidance below remains valid as defense in depth.
@@ -158,7 +158,7 @@ See the full design, mandatory workflow example, and M2 exit criteria in the pla
 | `wikifier prepare-edit` | `<file>` | Stage current mtime before you start editing (for future diffing). |
 | `wikifier mark-green` | `<file> [reason]` | Flip file status to Green after you have written/updated its wiki summary. |
 | `wikifier monitor` | — | Start background 30s heartbeat (run with `&` or in separate terminal). |
-| `wikifier update-maps` | `[--full] [--directory=...] [--max-files=N] [--sh]` | Rebuild `library.md` + import cache (pure-Python full pipeline by default; `--sh` = legacy shell fallback). |
+| `wikifier update-maps` | `[--full] [--directory=...] [--max-files=N]` | Rebuild `library.md` + import cache (single pure-Python pipeline; the shell launcher delegates here). |
 | `wikifier validate` | — | Ensure every file in monitored_paths has at least a health row. |
 | `wikifier journal` | `[YYYY-MM-DD]` | Read the journal for a day (default = today). |
 | `wikifier issues` | `[simple|moderate|high|critical]` | List logged issues by severity. |
@@ -250,4 +250,4 @@ All support `project_root=...` and return structured data (plus side-effecting s
 
 See README.md "Intended Use" for the strict agent-to-agent wiki scope (token saving for lookup + autonomous update/create of wiki entries only). M5 dogfood validated this on real external projects with the exact patterns above. Recent 4.0.1 hygiene (health coerce + superseded prune) further improves reliability of the matrix for agents doing direct lookups/updates.
 
-**Human investigation layer (secondary, opt-in)**: `wikifier init` copies only `index.html` (the clean human wiki viewer) into the target project (the folder where MCP/CLI run). `diagnostics.html` (Wikifier maintainer hub) is no longer copied — it would show the wrong tree (Wikifier's internals) and be stale for the host project. Humans open the local `index.html` (via `python -m http.server` recommended) to see a clean visual of *that project's* agent-maintained wiki: prominent code structure / dependency chart (Mermaid) as the hero, followed by a simple "Files & descriptions" list (paths + short "what this file is about" summaries pulled from the wiki notes), and a lightweight "Browse by folder" tree derived from the health data. A "Quick actions" toolbar provides one-click copy buttons for the main commands (check-changes, update-maps, monitor &); empty states ("No structure map yet", "No files in the wiki yet") have prominent primary buttons for first-time commands (update-maps prioritized, combined check-changes+update-maps for files). On first open with no map, the `wikifier update-maps` command is auto-copied (sessionStorage-guarded one-time per browser session) and live-wait mode is immediately activated. Buttons use copy + live-wait: they copy the exact command and inject a fixed top "Waiting for `wikifier ...` to produce data... (auto-polling)" banner with aggressive 3s polling that auto-detects when library.md / file_health.* update (from the terminal run) and refreshes the chart/files automatically; includes an "I ran it — refresh now" link in the banner and a success toast on detection. A short explanatory note in the UI clarifies the model: this is a pure static zero-dep viewer (browser JS cannot execute host shell commands due to security sandbox); the auto we provide is copy + immediate live-wait + fast poll so results (trees, files, descriptions) appear automatically after the user pastes/runs in their terminal. "Good enough" acceptance recorded for this copy+live-wait UX. Prominent copy buttons also export "structure as text" (Mermaid source) and a clean full snapshot (tree + file list + descriptions) — exactly the compact, token-saving view agents use. The default human page is intentionally free of dense agent internals (those live in `diagnostics.html` in the Wikifier source for technical users). If an old diagnostics.html is present, it can be safely deleted. The .md files + MCP/CLI/tools remain the primary SSOT and update mechanism for agents. This layer lets humans (or teams) visually investigate and copy-paste wiki summaries for their own work / LLM chats without touching agent behavior or adding deps.
+**Human investigation layer (secondary, opt-in)**: `wikifier init` copies only `index.html` (the clean human wiki viewer) into the target project (the folder where MCP/CLI run). `diagnostics.html` (Wikifier maintainer hub) is no longer copied — it would show the wrong tree (Wikifier's internals) and be stale for the host project. Humans run `wikifier serve` and open http://localhost:8787/index.html (browsers block file:// fetches, so a double-clicked index.html shows an empty map — the page itself now detects this and shows the fix) to see a clean visual of *that project's* agent-maintained wiki: prominent code structure / dependency chart (Mermaid) as the hero, followed by a simple "Files & descriptions" list (paths + short "what this file is about" summaries pulled from the wiki notes), and a lightweight "Browse by folder" tree derived from the health data. A "Quick actions" toolbar provides one-click copy buttons for the main commands (check-changes, update-maps, monitor &); empty states ("No structure map yet", "No files in the wiki yet") have prominent primary buttons for first-time commands (update-maps prioritized, combined check-changes+update-maps for files). On first open with no map, the `wikifier update-maps` command is auto-copied (sessionStorage-guarded one-time per browser session) and live-wait mode is immediately activated. Buttons use copy + live-wait: they copy the exact command and inject a fixed top "Waiting for `wikifier ...` to produce data... (auto-polling)" banner with aggressive 3s polling that auto-detects when library.md / file_health.* update (from the terminal run) and refreshes the chart/files automatically; includes an "I ran it — refresh now" link in the banner and a success toast on detection. A short explanatory note in the UI clarifies the model: this is a pure static zero-dep viewer (browser JS cannot execute host shell commands due to security sandbox); the auto we provide is copy + immediate live-wait + fast poll so results (trees, files, descriptions) appear automatically after the user pastes/runs in their terminal. "Good enough" acceptance recorded for this copy+live-wait UX. Prominent copy buttons also export "structure as text" (Mermaid source) and a clean full snapshot (tree + file list + descriptions) — exactly the compact, token-saving view agents use. The default human page is intentionally free of dense agent internals (those live in `diagnostics.html` in the Wikifier source for technical users). If an old diagnostics.html is present, it can be safely deleted. The .md files + MCP/CLI/tools remain the primary SSOT and update mechanism for agents. This layer lets humans (or teams) visually investigate and copy-paste wiki summaries for their own work / LLM chats without touching agent behavior or adding deps.

{wikifier-4.2.0 → wikifier-4.3.1}/tests/test_parsers.py

@@ -153,5 +153,63 @@ class TestJavaScriptParser(TempProjectTestCase):
         self.assertEqual(edge.get("resolution_confidence"), "high")
 
 
+class TestBarrelLeafExplosionPolicy(TempProjectTestCase):
+    """Leaf-explosion policy: name routing + reported cap.
+
+    A named import through an `export *` barrel must emit the entry edge plus
+    only the leaves that export the requested names (precision); imports with
+    no usable names (side-effect/namespace/dynamic) fall back to a cap whose
+    truncation is reported via barrel_leaf_selection — never silent.
+    """
+
+    LEAVES = 30
+
+    def setUp(self):
+        super().setUp()
+        lines = []
+        for i in range(self.LEAVES):
+            self.write(f"big/leaf{i}.js", f"export const thing{i} = {i};\n")
+            lines.append(f"export * from './leaf{i}.js';")
+        self.write("big/index.js", "\n".join(lines) + "\n")
+        self.write("named.js", "import { thing7 } from './big';\n")
+        self.write("nameless.js", "import * as big from './big';\n")
+
+    def _parse(self, rel):
+        self.reset_js_parser_state()
+        from wikifier.parsers.javascript import parse_javascript_imports
+        return parse_javascript_imports(str(self.root / rel))
+
+    def test_named_import_routes_to_defining_leaf(self):
+        edges = self._parse("named.js")
+        paths = [e.get("resolved_path") for e in edges]
+        self.assertIn("big/index.js", paths, "entry-barrel edge must be kept")
+        self.assertIn("big/leaf7.js", paths, "the leaf defining thing7 must be kept")
+        self.assertLessEqual(
+            len(edges), 4,
+            f"name routing should drop non-matching leaves, got {len(edges)}: {paths}",
+        )
+        edge = find_edge(edges, raw_module="./big")
+        self.assertIn("thing7", edge.get("imported_names") or [])
+
+    def test_nameless_import_is_capped_with_reported_selection(self):
+        import os
+        old = os.environ.get("WIKIFIER_BARREL_LEAF_CAP")
+        os.environ["WIKIFIER_BARREL_LEAF_CAP"] = "5"
+        try:
+            edges = self._parse("nameless.js")
+        finally:
+            if old is None:
+                os.environ.pop("WIKIFIER_BARREL_LEAF_CAP", None)
+            else:
+                os.environ["WIKIFIER_BARREL_LEAF_CAP"] = old
+        barrel_edges = [e for e in edges if e.get("via_barrel")]
+        self.assertLessEqual(len(barrel_edges), 6, "cap must bound emission (entry + 5 leaves)")
+        sels = [e.get("barrel_leaf_selection") for e in edges if e.get("barrel_leaf_selection")]
+        self.assertTrue(sels, "truncation must be reported via barrel_leaf_selection")
+        self.assertTrue(sels[0].get("truncated"))
+        self.assertEqual(sels[0].get("leaves_emitted"), 5)
+        self.assertEqual(sels[0].get("leaves_total"), self.LEAVES)
+
+
 if __name__ == "__main__":
     unittest.main(verbosity=2)

{wikifier-4.2.0 → wikifier-4.3.1}/wikifier/__init__.py

@@ -61,4 +61,4 @@ from .contracts import (
     compute_acs_confidence,
 )
 
-__version__ = "4.2.0"
+__version__ = "4.3.1"

{wikifier-4.2.0 → wikifier-4.3.1}/wikifier/cli.py

@@ -381,6 +381,7 @@ def _pair_from_parser_edge(edge: Dict[str, Any], root: Path) -> Optional[Dict[st
         "confidence_score", "confidence_reasons", "confidence_explanation",
         "barrel_v2", "resolution_metadata", "strategy", "cdia_v1",
         "conditional_analysis", "dynamic_analysis", "diagnostic",
+        "imported_names", "barrel_leaf_selection",
     ):
         v = edge.get(k)
         if v not in (None, "", [], {}):
@@ -732,8 +733,12 @@ def main():
             python_primary_requested = True
             continue  # consume, do not forward to sh
         if a in ("--sh", "--legacy-sh", "--no-python-primary"):
-            python_primary_requested = False
-            continue  # consume, do not forward to sh
+            # The in-shell update-maps implementation was retired (2026-06-10
+            # thin-shell rework); wikifier.sh itself now delegates here.
+            print("[wikifier] note: --sh is a deprecated no-op — the legacy shell "
+                  "update-maps path was retired; the Python pipeline always runs.",
+                  file=sys.stderr)
+            continue  # consume; stay on the Python pipeline
         if a in ("update-maps", "update_maps"):
             is_update_maps_cmd = True
         stripped_filtered.append(a)

{wikifier-4.2.0 → wikifier-4.3.1}/wikifier/import_cache.py

@@ -68,7 +68,15 @@ def save_cache(root: Path, cache: Dict[str, Any]) -> None:
 
     Uses file locking (M2-Rem-07) to prevent corruption when multiple
     agents are running update-maps or health operations concurrently.
+
+    Set WIKIFIER_DEBUG_SAVES=1 to print each save's call site to stderr —
+    the diagnostic for "who keeps rewriting the cache mid-run".
     """
+    if os.environ.get("WIKIFIER_DEBUG_SAVES"):
+        import sys as _sys
+        import traceback
+        frames = "".join(traceback.format_stack()[-4:-1])
+        print(f"[save_cache] root={root}\n{frames}", file=_sys.stderr)
     if locking:
         with locking.file_lock(root):
             _do_save_cache(root, cache)
@@ -100,8 +108,11 @@ def _do_save_cache(root: Path, cache: Dict[str, Any]) -> None:
                         cache[k] = prev[k]
     except Exception:
         pass  # never let preservation break the save itself
+    # Compact separators: the cache is machine-consumed only, and indent=2
+    # made barrel-heavy caches ~2-3x larger and proportionally slower to
+    # write (observed: 274MB on Babylon.js).
     with open(cache_path, "w", encoding="utf-8") as f:
-        json.dump(cache, f, indent=2, ensure_ascii=False)
+        json.dump(cache, f, ensure_ascii=False, separators=(",", ":"))
 
 
 def get_file_data(cache: Dict[str, Any], rel_path: str) -> Optional[Dict[str, Any]]:

{wikifier-4.2.0 → wikifier-4.3.1}/wikifier/index.html

@@ -770,9 +770,44 @@ Open index.html in the project for the live visual version.
         }
 
         // Boot: only what the human view needs (chart + files+descs + tree + monitor). Poll for live feel.
+        // Browsers refuse fetch() from file:// pages (unique-origin sandbox),
+        // so a double-clicked index.html can never read the wiki artifacts —
+        // the map stays empty while the console fills with CORS errors. Show
+        // the one-command fix prominently instead of failing silently.
+        function showFileProtocolNotice() {
+            const div = document.createElement('div');
+            div.id = 'file-protocol-notice';
+            div.style.cssText = 'position:sticky;top:0;z-index:60;background:#7c2d12;color:#ffedd5;padding:14px 18px;font-size:14px;line-height:1.6;box-shadow:0 2px 8px rgba(0,0,0,.4)';
+            div.innerHTML = '<strong>The dashboard cannot read the wiki files when opened directly from disk.</strong><br>' +
+                'Browsers block <code>fetch()</code> on <code>file://</code> pages (security sandbox), so the map and file list would stay empty. ' +
+                'Serve this folder over localhost instead — run one of these in the project folder, then open the link:' +
+                '<div style="margin-top:8px;display:flex;gap:8px;flex-wrap:wrap;align-items:center">' +
+                '<button id="fpCopyServe" style="background:#10b981;color:#06281e;border:none;border-radius:6px;padding:6px 12px;font-weight:600;cursor:pointer">Copy: wikifier serve</button>' +
+                '<button id="fpCopyPy" style="background:#374151;color:#e5e7eb;border:none;border-radius:6px;padding:6px 12px;cursor:pointer">Copy: python3 -m http.server 8787</button>' +
+                '<a href="http://localhost:8787/index.html" style="color:#5eead4;text-decoration:underline">open http://localhost:8787/index.html</a>' +
+                '</div>';
+            document.body.prepend(div);
+            const wire = (id, text) => {
+                const b = document.getElementById(id);
+                if (!b) return;
+                b.onclick = () => navigator.clipboard.writeText(text).then(() => {
+                    const old = b.textContent;
+                    b.textContent = 'Copied ✓';
+                    setTimeout(() => { b.textContent = old; }, 1600);
+                });
+            };
+            wire('fpCopyServe', 'wikifier serve');
+            wire('fpCopyPy', 'python3 -m http.server 8787');
+        }
+
         function boot() {
             initTailwind();
 
+            if (location.protocol === 'file:') {
+                showFileProtocolNotice();
+                return; // skip data loads + polling: every fetch would fail
+            }
+
             loadHealthMatrix();
             loadMermaid();
             loadMonitorStatus();

{wikifier-4.2.0 → wikifier-4.3.1}/wikifier/parsers/bree.py

@@ -342,6 +342,10 @@ class BarrelResolutionCache:
     def __post_init__(self) -> None:
         self.resolutions = dict(self.resolutions or {})
         self.file_index = dict(self.file_index or {})
+        # Transient set views over persisted membership lists (never serialized;
+        # see _membership). Without these, store() membership tests were linear
+        # scans that went quadratic across a run on barrels with many importers.
+        self._fast_sets: Dict[str, set] = {}
 
     @classmethod
     def from_cache(cls, cache: Dict[str, Any]) -> "BarrelResolutionCache":
@@ -358,6 +362,16 @@ class BarrelResolutionCache:
         state); an explicit empty dict therefore remains the way to express
         intentional clearing (prune-to-zero, clear()).
         """
+        # Stable output: importer/chain lists are append-ordered in memory for
+        # speed; sort once here so the persisted form is deterministic.
+        for entry in self.resolutions.values():
+            if isinstance(entry.get("importers"), list):
+                entry["importers"] = sorted(set(entry["importers"]))
+        for idxe in self.file_index.values():
+            if isinstance(idxe.get("importers"), list):
+                idxe["importers"] = sorted(set(idxe["importers"]))
+            if isinstance(idxe.get("chain_ids"), list):
+                idxe["chain_ids"] = sorted(set(idxe["chain_ids"]))
         cache["_barrel_resolutions"] = self.resolutions or {}
         cache["_barrel_file_index"] = self.file_index or {}
 
@@ -372,6 +386,58 @@ class BarrelResolutionCache:
     def get(self, chain_id: str) -> Optional[Dict[str, Any]]:
         return self.resolutions.get(chain_id)
 
+    @staticmethod
+    def _lean_results(results: Optional[List[Dict[str, Any]]]) -> List[Dict[str, Any]]:
+        """Compress chain results for persistence.
+
+        Stored results exist so a cache hit can replay the expansion (and so
+        name routing on hits still sees the full leaf set) — they do NOT need
+        the heavy per-leaf payloads (resolution_metadata, barrel_v2 hop blobs,
+        analysis fields), which the emission layer rebuilds or defaults.
+        Those payloads were the dominant weight of barrel-heavy caches
+        (274MB import_cache.json on Babylon.js). Leaves are also deduped by
+        resolved_path (BREE can reach the same leaf via multiple hop paths).
+        """
+        lean: List[Dict[str, Any]] = []
+        seen: set = set()
+        for r in results or []:
+            if not isinstance(r, dict):
+                continue
+            rp = r.get("resolved_path")
+            if rp:
+                if rp in seen:
+                    continue
+                seen.add(rp)
+            slim = {}
+            for k in (
+                "module", "resolved_path", "via_barrel", "barrel_chain",
+                "barrel_depth", "is_conditional", "conditional_context",
+                "barrel_detector",
+            ):
+                v = r.get(k)
+                if v is not None:
+                    slim[k] = v
+            lean.append(slim)
+        return lean
+
+    @staticmethod
+    def _lean_hops(hops: Optional[List[Any]]) -> List[Dict[str, Any]]:
+        """Keep only primitive hop fields (drop per-hop metadata dicts)."""
+        out: List[Dict[str, Any]] = []
+        for h in hops or []:
+            if isinstance(h, dict):
+                out.append({k: v for k, v in h.items() if not isinstance(v, (dict, list))})
+        return out
+
+    def _membership(self, key: str, current: List[str]) -> set:
+        """Transient set view over a persisted list (membership tests during
+        store() were linear scans — quadratic across a run on popular barrels)."""
+        s = self._fast_sets.get(key)
+        if s is None:
+            s = set(current)
+            self._fast_sets[key] = s
+        return s
+
     def store(
         self,
         *,
@@ -433,15 +499,19 @@ class BarrelResolutionCache:
                     snap[ck or str(k)] = 0.0
         cid = chain_id or self._make_chain_id(bc, start_specifier)
         entry = self.resolutions.get(cid, {})
-        # merge importers
-        existing_imps = set(entry.get("importers", []))
-        existing_imps.update(imps)
+        # merge importers (set-backed membership; lists stay the persisted form)
+        imp_list = entry.get("importers", [])
+        imp_set = self._membership(f"res:{cid}", imp_list)
+        for imp in imps:
+            if imp and imp not in imp_set:
+                imp_set.add(imp)
+                imp_list.append(imp)
         entry.update({
             "chain_id": cid,
-            "importers": sorted(existing_imps),
+            "importers": imp_list,
             "barrel_chain": bc or entry.get("barrel_chain", []),
-            "hops": hops or entry.get("hops", []),
-            "results": results or entry.get("results", []),
+            "hops": self._lean_hops(hops) if hops else entry.get("hops", []),
+            "results": self._lean_results(results) if results else entry.get("results", []),
             "start_specifier": start_specifier or entry.get("start_specifier", ""),
             "detector_used": detector_used or entry.get("detector_used", "unknown"),
             "is_partial": is_partial or entry.get("is_partial", False),
@@ -461,10 +531,14 @@ class BarrelResolutionCache:
             if fkey not in self.file_index:
                 self.file_index[fkey] = {"chain_ids": [], "importers": []}
             idxe = self.file_index[fkey]
-            if cid not in idxe["chain_ids"]:
+            cid_set = self._membership(f"idx_c:{fkey}", idxe["chain_ids"])
+            if cid not in cid_set:
+                cid_set.add(cid)
                 idxe["chain_ids"].append(cid)
+            imp_idx_set = self._membership(f"idx_i:{fkey}", idxe["importers"])
             for imp in imps:
-                if imp and imp not in idxe["importers"]:
+                if imp and imp not in imp_idx_set:
+                    imp_idx_set.add(imp)
                     idxe["importers"].append(imp)
 
         return cid