wikifier 4.5.9__tar.gz → 4.6.1__tar.gz

{wikifier-4.5.9/wikifier.egg-info → wikifier-4.6.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: wikifier
-Version: 4.5.9
+Version: 4.6.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

{wikifier-4.5.9 → wikifier-4.6.1}/skills/run.md

@@ -42,13 +42,16 @@ Do **not** open megamodules (`javascript.py`, `import_cache.py`, `bree.py`) to d
 | Need | Use |
 |------|-----|
 | First-run map | `init` → `update-maps` → `health --summary` → `suggest-next` |
-| Steady-state | `check-changes` → edit 🔴/actionable 🟡 only → `record-change` → wiki → `mark-green` |
-| Lookup | MCP Core 6: status, check_changes, needing_attention, get_file_wiki, suggest, record/mark |
-| Deps / cycles | `get_dependencies`, `get_dependents`, `get_cycles` (json) |
+| **Session start (4.6+)** | `session_bootstrap` (or CLI `session-bootstrap`) — one shot: root, health, attention, `actions[]` |
+| Steady-state | `check-changes` (content-honest) → edit 🔴/actionable 🟡 only → `record-change` → wiki → `mark-green` |
+| **Preflight edit** | `prepare_edit` / CLI `prepare-edit <file>` — wiki + status + deps + dependents |
+| **Why / journal** | `why_file` / `search_journal` — semantic trail, not mtime theater |
+| Lookup Core | `session_bootstrap`, `check_changes`, `prepare_edit`, `suggest_next_actions` (json `actions[]`), `record_change`, `mark_green` |
+| Advanced intel | `get_dependencies`, `get_dependents`, `get_cycles`, barrel/diagnostics — not daily Core |
 | Deletion | `record-deletion` |
 | Long-horizon prep | `autonomous-status` / `readiness`; then `daemon start` with lean monitor |
 | Hygiene | `seed-health`, `prune-pending`, `prune-health`, `validate` |
-| Code entry | `cli.py` dispatch + `health.py` + parsers — self-tests in `tests/` + `tests/selftest/` |
+| Code entry | `cli.py` + `agent_loop.py` + `health.py` + parsers — tests in `tests/` |
 
 **Do not open megamodules** (`javascript.py` ~2.6k, `import_cache.py` ~2.3k, `bree.py` ~2k) for workflow decisions — use tools + this table.
 
@@ -61,30 +64,31 @@ Do **not** open megamodules (`javascript.py`, `import_cache.py`, `bree.py`) to d
 **Copy this exact block into the system prompt or the very first instruction of every new LLM session that uses Wikifier:**
 
 ```
-You are now operating inside a Wikifier-managed codebase (Agent Protocol v0.6 — package 4.5.x).
+You are now operating inside a Wikifier-managed codebase (Agent Protocol v0.6 — package 4.6.x).
 
 This is strictly an agent-to-agent wiki for token saving: map lookup (health + file wikis + deps) instead of full sources; selective wiki updates; not a human docs product or Jira.
 
-SELECTIVE WORK (mandatory): Only update/remove/re-wiki 🔴 Red and 🟡 Yellow files. Do not re-summarize 🟢 Green files or the whole tree. First-run builds the structural map; wiki depth is filled as you touch files.
+SELECTIVE WORK (mandatory): Only update/remove/re-wiki 🔴 Red and 🟡 Yellow files. Do not re-summarize 🟢 Green files or the whole tree. First-run builds the structural map; wiki depth is filled as you touch files. check-changes is content-honest (mtime-only thrash does not re-Yellow when source hash matches mark-green baseline).
 
 FIRST ACTIONS:
-1. Prefer MCP tools when connected (get_project_status, get_file_wiki, check_changes, suggest_next_actions, get_dependencies, …). Always pass project_root= for external projects.
+1. Prefer MCP Core: session_bootstrap, check_changes, prepare_edit, suggest_next_actions (use actions[]), record_change, mark_green. Always pass project_root= for external projects.
 2. CLI/library fallback:
-     WIKIFIER_PROJECT_ROOT=/path/to/target python -m wikifier check-changes
-     python -m wikifier health --summary
-     python -m wikifier suggest-next   # or suggest_next_actions(format="json")
-     ... edit only red/yellow sources ...
+     WIKIFIER_PROJECT_ROOT=/path/to/target python -m wikifier session-bootstrap
+     python -m wikifier check-changes
+     python -m wikifier suggest-next --json   # actions[] dispatchable
+     python -m wikifier prepare-edit path/to/file
+     ... edit only red/actionable yellow sources ...
      python -m wikifier record-change "path/to/file" "why (semantic). Include subid if agent work."
      ... update that file's wiki only ...
      python -m wikifier mark-green "path/to/file" "reason"
      if imports changed: python -m wikifier update-maps [--directory=src/]
      if file removed: python -m wikifier record-deletion "path" "why"
      python -m wikifier health --summary
-3. Optional background: `python -m wikifier monitor` or daemon for mtime heartbeat — you still own wiki + mark-green.
-4. Prioritize 🔴 then 🟡 from health/pending. Lookup greens via get_file_wiki; do not rewrite them.
-5. Agent docs edits: record-change + mark-green.
+3. Optional background: `python -m wikifier monitor` or daemon — you still own wiki + mark-green.
+4. Prioritize 🔴 then actionable 🟡. Lookup greens via prepare_edit / get_file_wiki; do not rewrite them.
+5. why_file / search_journal for semantic trail.
 6. Always explicit project_root / WIKIFIER_PROJECT_ROOT for external/multi-project work.
-7. End turn: health + suggest_next_actions.
+7. End turn: health + suggest_next_actions (json).
 
 Never skip record-change — semantic audit trail (journal + health + pending).
 

wikifier-4.6.1/tests/test_agent_loop.py

@@ -0,0 +1,226 @@
+"""Agent-first ideal-loop tests: content-dirty, bootstrap, suggest actions, preflight, journal."""
+
+import importlib
+import os
+import time
+import unittest
+from pathlib import Path
+
+from tests._base import TempProjectTestCase
+
+from wikifier import cli
+from wikifier.health import classify_content_dirty, compute_source_content_hash
+from wikifier.agent_loop import (
+    session_bootstrap,
+    prepare_edit,
+    search_journal,
+    why_file,
+    build_structured_actions,
+)
+
+health_mod = importlib.import_module("wikifier.health")
+
+
+class TestContentHonestDirty(TempProjectTestCase):
+    def test_classify_touch_only_vs_rewrite(self):
+        p = self.write("src/a.py", "x = 1\n")
+        h1 = compute_source_content_hash(p)
+        self.assertIsNotNone(h1)
+        v = classify_content_dirty(p, h1)
+        self.assertFalse(v["content_dirty"])
+        self.assertEqual(v["reason"], "content_unchanged")
+        # mtime thrash without content change
+        os.utime(p, None)
+        v2 = classify_content_dirty(p, h1)
+        self.assertFalse(v2["content_dirty"])
+        self.assertEqual(v2["reason"], "content_unchanged")
+        # rewrite bytes
+        p.write_text("x = 2\n", encoding="utf-8")
+        v3 = classify_content_dirty(p, h1)
+        self.assertTrue(v3["content_dirty"])
+        self.assertEqual(v3["reason"], "content_changed")
+
+    def test_check_changes_skips_mtime_only_after_mark_green(self):
+        p = self.write("mod.py", "print(1)\n")
+        # Seed health green with source baseline via mark_green
+        res_mg = cli.mark_green("mod.py", "baseline", project_root=self.root)
+        self.assertTrue(res_mg.get("success"), res_mg)
+        data = health_mod.load_health(self.root)
+        ent = data["entries"]["mod.py"]
+        self.assertIn("source_content_hash", ent)
+        baseline = ent["source_content_hash"]
+        # Ensure import_cache may list file as dirty via mtime: touch only
+        from wikifier import import_cache as ic
+        cache = {}
+        ic.update_file_data(cache, "mod.py", mtime=1, imports=[], resolved_pairs=[])
+        ic.save_cache(self.root, cache)
+        time.sleep(0.05)
+        os.utime(p, None)
+        # Force compute dirty by setting cache mtime older than file
+        cache = ic.load_cache(self.root)
+        cache["mod.py"]["mtime"] = 1
+        ic.save_cache(self.root, cache)
+        r = cli.check_changes(project_root=self.root)
+        self.assertTrue(r.get("success"), r)
+        # Content unchanged → should not Yellow for content
+        data2 = health_mod.load_health(self.root)
+        st = data2["entries"]["mod.py"]["status"]
+        self.assertIn("Green", st)
+        self.assertEqual(data2["entries"]["mod.py"].get("source_content_hash"), baseline)
+        # Real content edit → Yellow
+        p.write_text("print(2)\n", encoding="utf-8")
+        cache = ic.load_cache(self.root)
+        cache["mod.py"]["mtime"] = 1
+        ic.save_cache(self.root, cache)
+        r2 = cli.check_changes(project_root=self.root)
+        self.assertTrue(r2.get("success"), r2)
+        data3 = health_mod.load_health(self.root)
+        self.assertIn("Yellow", data3["entries"]["mod.py"]["status"])
+        self.assertIn("content", data3["entries"]["mod.py"]["reason"].lower())
+
+    def test_legacy_green_without_hash_rewrite_yellows(self):
+        """Criterion 2: Green with no source_content_hash + real rewrite must Yellow.
+
+        Must not seed post-edit hash and stay Green (post-upgrade / legacy path).
+        """
+        p = self.write("legacy.py", "print('v1')\n")
+        # Legacy Green: upsert only — no source_content_hash baseline
+        health_mod.upsert_entry(self.root, "legacy.py", "🟢 Green", "legacy green no hash")
+        data = health_mod.load_health(self.root)
+        self.assertNotIn("source_content_hash", data["entries"]["legacy.py"] or {})
+        from wikifier import import_cache as ic
+        cache = {}
+        ic.update_file_data(cache, "legacy.py", mtime=1, imports=[], resolved_pairs=[])
+        ic.save_cache(self.root, cache)
+        # Real content rewrite
+        p.write_text("print('v2-rewritten')\n", encoding="utf-8")
+        cache = ic.load_cache(self.root)
+        cache["legacy.py"]["mtime"] = 1  # force dirty vs disk
+        ic.save_cache(self.root, cache)
+        r = cli.check_changes(project_root=self.root)
+        self.assertTrue(r.get("success"), r)
+        self.assertGreaterEqual(int(r.get("changes_detected") or 0), 1)
+        data2 = health_mod.load_health(self.root)
+        ent = data2["entries"]["legacy.py"]
+        self.assertIn("Yellow", ent["status"])
+        # Must not have silently stored the post-edit hash as trusted baseline
+        self.assertNotEqual(
+            ent.get("source_content_hash"),
+            compute_source_content_hash(p),
+            "must not seed post-edit content hash without mark_green",
+        )
+        # After mark_green, baseline is set and further touch-only stays green
+        cli.mark_green("legacy.py", "re-baselined", project_root=self.root)
+        data3 = health_mod.load_health(self.root)
+        self.assertIn("source_content_hash", data3["entries"]["legacy.py"])
+        baseline = data3["entries"]["legacy.py"]["source_content_hash"]
+        cache = ic.load_cache(self.root)
+        cache["legacy.py"]["mtime"] = 1
+        ic.save_cache(self.root, cache)
+        os.utime(p, None)
+        r2 = cli.check_changes(project_root=self.root)
+        self.assertTrue(r2.get("success"), r2)
+        data4 = health_mod.load_health(self.root)
+        self.assertIn("Green", data4["entries"]["legacy.py"]["status"])
+        self.assertEqual(data4["entries"]["legacy.py"]["source_content_hash"], baseline)
+
+
+class TestSessionBootstrapAndSuggest(TempProjectTestCase):
+    def test_session_bootstrap_shape(self):
+        self.write("a.py", "import os\n")
+        health_mod.upsert_entry(self.root, "a.py", "🟡 Yellow", "record-change: edit")
+        boot = session_bootstrap(project_root=self.root)
+        self.assertTrue(boot.get("success"))
+        self.assertEqual(Path(boot["project_root"]).resolve(), self.root)
+        self.assertIn("health_summary", boot)
+        self.assertIn("actions", boot)
+        self.assertIsInstance(boot["actions"], list)
+        self.assertTrue(any("action" in a for a in boot["actions"]))
+        self.assertIn("session_bootstrap", boot.get("core_surface") or [])
+
+    def test_suggest_json_has_structured_actions(self):
+        health_mod.upsert_entry(self.root, "b.py", "🔴 Red", "DELETED — gone")
+        health_mod.upsert_entry(self.root, "c.py", "🟡 Yellow", "content changed")
+        res = cli.suggest_next_actions(project_root=self.root, format="json")
+        self.assertTrue(res.get("success"))
+        actions = res.get("actions") or []
+        self.assertTrue(actions, "expected dispatchable actions")
+        for a in actions:
+            self.assertIn("action", a)
+            self.assertIn("priority", a)
+            self.assertIn("reason", a)
+        kinds = {a["action"] for a in actions}
+        self.assertTrue(kinds & {"investigate_red", "wiki_refresh", "review_acs", "update_maps_if_structure", "lookup_only", "map_first_ok", "fix_scope"})
+
+
+class TestPrepareEditAndJournal(TempProjectTestCase):
+    def test_prepare_edit_returns_status_and_lists(self):
+        self.write("pkg/x.py", "from . import y\n")
+        health_mod.upsert_entry(self.root, "pkg/x.py", "🟢 Green", "ok")
+        # minimal cache edge
+        from wikifier import import_cache as ic
+        cache = {}
+        ic.update_file_data(
+            cache,
+            "pkg/x.py",
+            mtime=1,
+            imports=["./y"],
+            resolved_pairs=[{
+                "raw": "./y",
+                "resolved": "pkg/y.py",
+                "resolved_path": "pkg/y.py",
+                "confidence_score": 0.9,
+            }],
+        )
+        cache["_reverse_dependencies"] = {"pkg/x.py": ["pkg/z.py"]}
+        ic.save_cache(self.root, cache)
+        pe = prepare_edit("pkg/x.py", project_root=self.root)
+        self.assertTrue(pe.get("success"))
+        self.assertEqual(pe.get("file"), "pkg/x.py")
+        self.assertIn("Green", str(pe.get("status") or ""))
+        self.assertTrue(isinstance(pe.get("dependencies"), list))
+        self.assertIn("pkg/z.py", pe.get("dependents") or [])
+
+    def test_journal_search_and_why_file(self):
+        self.write("tracked.py", "v=1\n")
+        r = cli.record_change("tracked.py", "semantic reason alpha-subid", project_root=self.root)
+        self.assertTrue(r.get("success"), r)
+        sj = search_journal(project_root=self.root, query="alpha-subid")
+        self.assertTrue(sj.get("success"))
+        self.assertGreaterEqual(len(sj.get("matches") or []), 1)
+        self.assertTrue(any("alpha-subid" in (m.get("reason") or "") for m in sj["matches"]))
+        sj2 = search_journal(project_root=self.root, file="tracked.py")
+        self.assertGreaterEqual(len(sj2.get("matches") or []), 1)
+        why = why_file("tracked.py", project_root=self.root)
+        self.assertTrue(why.get("success"))
+        self.assertTrue(why.get("health_reason") or why.get("journal_matches"))
+
+
+class TestBuildActionsUnit(unittest.TestCase):
+    def test_build_structured_actions_priorities(self):
+        acts = build_structured_actions(
+            red_files=["a.py"],
+            actionable_yellow_files=["b.py"],
+            red=1,
+            actionable_yellow=1,
+            acs_actionable=3,
+            clean=False,
+        )
+        self.assertTrue(any(a["action"] == "investigate_red" and a["file"] == "a.py" for a in acts))
+        self.assertTrue(any(a["action"] == "wiki_refresh" and a["file"] == "b.py" for a in acts))
+        self.assertTrue(any(a["action"] == "review_acs" for a in acts))
+        # sorted by priority
+        pris = [a["priority"] for a in acts]
+        self.assertEqual(pris, sorted(pris))
+
+
+class TestCliBootstrapEntry(TempProjectTestCase):
+    def test_cli_session_bootstrap_function(self):
+        self.write("z.py", "pass\n")
+        res = cli.session_bootstrap(project_root=self.root)
+        self.assertTrue(res.get("success"))
+        self.assertIn("actions", res)
+
+
+if __name__ == "__main__":
+    unittest.main()

{wikifier-4.5.9 → wikifier-4.6.1}/wikifier/__init__.py

@@ -42,7 +42,12 @@ from .cli import (
     suggest_next_actions,
     update_maps,
     health,  # flat convenience func (delegates to the health module + adds scoping)
+    session_bootstrap,
+    prepare_edit,
+    search_journal,
+    why_file,
 )
+from . import agent_loop
 
 # Re-export module under a non-shadowed name (G5). sys.modules['wikifier.health']
 # remains the real module; package attribute `health` is intentionally the function.
@@ -71,4 +76,4 @@ from .contracts import (
     compute_acs_confidence,
 )
 
-__version__ = "4.5.9"
+__version__ = "4.6.1"