Skip to content

Dianel555/DSkills / skills/agent-wiki

agent-wiki

Unverified

Incremental LLM-friendly wiki generator for Obsidian note vaults. Use when: (1) Building wiki from notes, (2) Ingesting notes to wiki, (3) Obsidian LLM wiki, (4) Incremental knowledge base management. Triggers: 'build wiki from notes', 'ingest notes to wiki', 'Obsidian LLM wiki', 'incremental knowledge base'.

FileKindSize
.env.exampleother408 B
README.mdmarkdown15.3 KB
SKILL.mdskill md23.3 KB
pyproject.tomlmanifest2.1 KB
references/cli-matrix.mdmarkdown5.9 KB
references/homepage.mdmarkdown6.1 KB
references/index-schema.mdmarkdown6.9 KB
references/site-export.mdmarkdown3.1 KB
references/topic-authoring.mdmarkdown5.1 KB
scripts/agent_wiki/__init__.pyscript103 B
scripts/agent_wiki/authors.pyscript3.9 KB
scripts/agent_wiki/bases.pyscript4.0 KB
scripts/agent_wiki/batch.pyscript3.7 KB
scripts/agent_wiki/boundary.pyscript55.8 KB
scripts/agent_wiki/cache.pyscript5.5 KB
scripts/agent_wiki/canvas.pyscript8.0 KB
scripts/agent_wiki/cleanup.pyscript2.4 KB
scripts/agent_wiki/cli.pyscript97 B
scripts/agent_wiki/commands.pyscript28.3 KB
scripts/agent_wiki/config.pyscript4.2 KB
scripts/agent_wiki/coverage.pyscript2.1 KB
scripts/agent_wiki/frontmatter.pyscript1.6 KB
scripts/agent_wiki/home.pyscript7.9 KB
scripts/agent_wiki/keywords.pyscript2.0 KB
scripts/agent_wiki/links.pyscript14.7 KB
scripts/agent_wiki/plugins.pyscript2.1 KB
scripts/agent_wiki/quality.pyscript7.6 KB
scripts/agent_wiki/scanner.pyscript6.7 KB
scripts/agent_wiki/site.pyscript39.2 KB
scripts/agent_wiki/source_type.pyscript3.2 KB
scripts/agent_wiki/wiki_index.pyscript17.4 KB
scripts/agent_wiki/worklist.pyscript5.7 KB
scripts/agent_wiki_cli.pyscript5.5 KB
templates/home/academic.mdmarkdown2.9 KB
templates/home/dashboard.mdmarkdown2.7 KB
templates/home/magazine.mdmarkdown2.5 KB
templates/query/research.mdmarkdown787 B
tests/conftest.pyscript177 B
tests/fixtures/sample_vault/attachments/image.pngbinary26 B
tests/fixtures/sample_vault/课程/双缝实验.mdmarkdown47 B
tests/fixtures/sample_vault/课程/量子力学.mdmarkdown75 B
tests/test_alias_resolution.pyscript7.5 KB
tests/test_authors.pyscript2.2 KB
tests/test_backlinks.pyscript7.0 KB
tests/test_bases.pyscript4.7 KB
tests/test_batch.pyscript3.0 KB
tests/test_benchmark_index.pyscript2.1 KB
tests/test_boundary_platform.pyscript695 B
tests/test_cache.pyscript2.1 KB
tests/test_cache_strict.pyscript2.1 KB
tests/test_canvas.pyscript8.3 KB
tests/test_capture.pyscript5.5 KB
tests/test_cleanup.pyscript1.2 KB
tests/test_cleanup_init_strict.pyscript2.1 KB
tests/test_cli.pyscript6.2 KB
tests/test_config.pyscript2.0 KB
tests/test_coverage.pyscript7.2 KB
tests/test_e2e.pyscript2.5 KB
tests/test_evaluate_enhancements.pyscript14.7 KB
tests/test_featured_base.pyscript4.3 KB
tests/test_final_security_review.pyscript6.6 KB
tests/test_frontmatter.pyscript1.1 KB
tests/test_gen_home.pyscript4.9 KB
tests/test_gen_site_cli.pyscript3.9 KB
tests/test_home.pyscript7.7 KB
tests/test_immutability.pyscript1.4 KB
tests/test_immutability_capture.pyscript2.4 KB
tests/test_index_capture.pyscript4.5 KB
tests/test_index_cli.pyscript5.4 KB
tests/test_index_extension.pyscript17.0 KB
tests/test_index_source_count.pyscript3.0 KB
tests/test_package_structure.pyscript3.4 KB
tests/test_plugins.pyscript3.1 KB
tests/test_quality.pyscript21.3 KB
tests/test_quality_cli.pyscript5.5 KB
tests/test_quality_prose_weight.pyscript3.8 KB
tests/test_quality_script_fairness.pyscript4.7 KB
tests/test_quality_tier_refactor.pyscript4.0 KB
tests/test_scanner.pyscript2.6 KB
tests/test_scanner_fast_path.pyscript3.5 KB
tests/test_scanner_strict.pyscript2.1 KB
tests/test_secure_temporary_writes.pyscript978 B
tests/test_site.pyscript20.2 KB
tests/test_site_import_isolation.pyscript3.9 KB
tests/test_site_slug_refactor.pyscript3.6 KB
tests/test_source_type.pyscript3.5 KB
tests/test_status_metrics.pyscript4.1 KB
tests/test_status_quality.pyscript5.3 KB
tests/test_status_worklist.pyscript3.0 KB
tests/test_structure.pyscript501 B
tests/test_topic_category.pyscript4.2 KB
tests/test_topic_path_boundary.pyscript2.2 KB
tests/test_vault_boundary.pyscript24.3 KB
tests/test_wiki_index.pyscript13.3 KB
tests/test_worklist.pyscript12.3 KB
tests/test_worklist_cli.pyscript1.9 KB

tests/test_wiki_index.py

View on GitHub
import json
import os
import unicodedata
from pathlib import Path

import pytest
from agent_wiki import boundary, config, frontmatter, wiki_index


def _topic(vault: Path, name: str, meta: dict, body: str = "x") -> Path:
    topics = config.topics_dir(vault)
    topics.mkdir(parents=True, exist_ok=True)
    path = topics / name
    path.write_text(frontmatter.dump(meta, body), encoding="utf-8")
    return path


def _init(vault: Path) -> None:
    config.topics_dir(vault).mkdir(parents=True, exist_ok=True)


# --- 1.1 empty schema -------------------------------------------------------

def test_empty_schema_shape():
    assert wiki_index.empty_schema() == {
        "version": wiki_index.INDEX_VERSION,
        "generated_at": "1970-01-01T00:00:00Z",
        "topics": {},
        "queries": {},
        "alias_index": {},
    }


def test_index_path_under_wiki(tmp_path):
    assert config.index_path(tmp_path) == config.wiki_root(tmp_path) / ".wiki-index.json"


# --- 1.2 normalization ------------------------------------------------------

def test_backward_compatible_minimal_frontmatter(tmp_path):
    _init(tmp_path)
    _topic(tmp_path, "T.md", {"title": "T", "sources": ["a.md"], "last_updated": "2026-01-01"})
    data, errors = wiki_index.rebuild(tmp_path)
    entry = data["topics"]["T.md"]
    assert errors == []
    assert entry["title"] == "T"
    assert entry["sources"] == ["a.md"]
    assert entry["year_start"] is None
    assert entry["year_end"] is None
    assert entry["authors"] == []
    assert entry["source_type"] == "markdown"
    assert entry["summary"] == ""


def test_scalar_list_null_coercion(tmp_path):
    _init(tmp_path)
    _topic(tmp_path, "S.md", {
        "authors": "Solo",
        "institutions": ["MIT", "CERN"],
        "year_start": "published 2019 ed",
        "summary": ["one", "two"],
    })
    entry = wiki_index.rebuild(tmp_path)[0]["topics"]["S.md"]
    assert entry["authors"] == ["Solo"]
    assert entry["institutions"] == ["MIT", "CERN"]
    assert entry["source_type"] == ""
    assert entry["year_start"] == 2019
    assert entry["summary"] == "one; two"


def test_int_year_passthrough_and_unparseable_null(tmp_path):
    _init(tmp_path)
    _topic(tmp_path, "Y.md", {"year_start": 2021})
    _topic(tmp_path, "N.md", {"year_start": "no digits"})
    topics = wiki_index.rebuild(tmp_path)[0]["topics"]
    assert topics["Y.md"]["year_start"] == 2021
    assert topics["N.md"]["year_start"] is None


def test_year_wrong_type_is_null_not_repr_scanned(tmp_path):
    _init(tmp_path)
    _topic(tmp_path, "D.md", {"year_start": {"note": 2019}})
    _topic(tmp_path, "F.md", {"year_start": 2019.5})
    topics = wiki_index.rebuild(tmp_path)[0]["topics"]
    assert topics["D.md"]["year_start"] is None
    assert topics["F.md"]["year_start"] is None


def test_year_start_end_coerced_to_int_or_null(tmp_path):
    _init(tmp_path)
    _topic(tmp_path, "R.md", {"year_start": 2021, "year_end": "2026"})
    _topic(tmp_path, "B.md", {"title": "B"})
    topics = wiki_index.rebuild(tmp_path)[0]["topics"]
    assert topics["R.md"]["year_start"] == 2021
    assert topics["R.md"]["year_end"] == 2026
    assert topics["B.md"]["year_start"] is None
    assert topics["B.md"]["year_end"] is None


def test_list_order_preserved_and_nfc(tmp_path):
    _init(tmp_path)
    nfd = unicodedata.normalize("NFD", "café")
    _topic(tmp_path, "L.md", {"keywords": [nfd, "b", "a", "b"]})
    keywords = wiki_index.rebuild(tmp_path)[0]["topics"]["L.md"]["keywords"]
    assert keywords == ["café", "b", "a", "b"]
    assert all(unicodedata.normalize("NFC", k) == k for k in keywords)


def test_title_falls_back_to_stem_when_missing(tmp_path):
    _init(tmp_path)
    _topic(tmp_path, "量子.md", {"sources": []})
    assert wiki_index.rebuild(tmp_path)[0]["topics"]["量子.md"]["title"] == "量子"


def test_summary_truncated_to_1000(tmp_path):
    _init(tmp_path)
    _topic(tmp_path, "Big.md", {"summary": "あ" * 5000})
    summary = wiki_index.rebuild(tmp_path)[0]["topics"]["Big.md"]["summary"]
    assert len(summary) == 1000


# --- 1.3 determinism --------------------------------------------------------

def test_generated_at_is_max_topic_mtime(tmp_path):
    _init(tmp_path)
    p1 = _topic(tmp_path, "A.md", {"title": "A"})
    p2 = _topic(tmp_path, "B.md", {"title": "B"})
    os.utime(p1, ns=(1_000_000_000, 1_000_000_000))
    os.utime(p2, ns=(2_000_000_000, 2_000_000_000))
    data = wiki_index.rebuild(tmp_path)[0]
    assert data["generated_at"] == "1970-01-01T00:00:02Z"


def test_empty_topics_uses_epoch(tmp_path):
    _init(tmp_path)
    data = wiki_index.rebuild(tmp_path)[0]
    assert data["generated_at"] == "1970-01-01T00:00:00Z"
    assert data["topics"] == {}


def test_rebuild_is_byte_identical(tmp_path):
    _init(tmp_path)
    _topic(tmp_path, "中.md", {"title": "中", "authors": ["x", "y"], "summary": "s"})
    first = wiki_index.serialize(wiki_index.rebuild(tmp_path)[0])
    second = wiki_index.serialize(wiki_index.rebuild(tmp_path)[0])
    assert first == second
    assert first.endswith("\n")
    assert json.loads(first)["version"] == wiki_index.INDEX_VERSION


# --- 1.4 atomic write -------------------------------------------------------

def test_save_index_atomic(tmp_path):
    _init(tmp_path)
    wiki_index.save_index(tmp_path, wiki_index.empty_schema())
    path = config.index_path(tmp_path)
    assert json.loads(path.read_text(encoding="utf-8"))["topics"] == {}
    assert not path.with_name(path.name + ".tmp").exists()


def test_save_index_preserves_old_bytes_on_replace_failure(tmp_path, monkeypatch):
    _init(tmp_path)
    path = config.index_path(tmp_path)
    path.parent.mkdir(parents=True, exist_ok=True)
    original = wiki_index.serialize(wiki_index.empty_schema())
    path.write_text(original, encoding="utf-8")

    def boom(dir_fd, tmp_name, destination, fd):
        raise PermissionError("locked")

    monkeypatch.setattr(boundary, "_publish_tmp", boom)
    with pytest.raises(wiki_index.IndexWriteError):
        wiki_index.save_index(tmp_path, {"version": 1, "generated_at": "x", "topics": {"new": {}}})
    assert path.read_text(encoding="utf-8") == original


# --- 1.5 resilient partial rebuild -----------------------------------------

def test_frontmatter_parse_error_is_reported_not_fatal(tmp_path):
    _init(tmp_path)
    _topic(tmp_path, "ok.md", {"title": "ok"})
    (config.topics_dir(tmp_path) / "bad.md").write_text("---\nkey: [\n---\nbody", encoding="utf-8")
    data, errors = wiki_index.rebuild(tmp_path)
    assert "ok.md" in data["topics"]
    assert "bad.md" not in data["topics"]
    assert {"path": "bad.md", "error": "frontmatter_parse_failed"} in errors


def test_decode_error_is_reported(tmp_path):
    _init(tmp_path)
    (config.topics_dir(tmp_path) / "raw.md").write_bytes(b"\xff\xfe\x00bad")
    data, errors = wiki_index.rebuild(tmp_path)
    assert {"path": "raw.md", "error": "topic_decode_failed"} in errors
    assert data["topics"] == {}


def test_normalized_path_collision_is_fatal(tmp_path):
    _init(tmp_path)
    topics = config.topics_dir(tmp_path)
    (topics / unicodedata.normalize("NFC", "café.md")).write_bytes(
        frontmatter.dump({"title": "c"}, "b").encode("utf-8"))
    nfd_name = unicodedata.normalize("NFD", "café.md")
    nfd_path = topics / nfd_name
    if nfd_path.name == unicodedata.normalize("NFC", "café.md"):
        pytest.skip("filesystem normalizes unicode filenames")
    nfd_path.write_bytes(frontmatter.dump({"title": "c2"}, "b").encode("utf-8"))
    with pytest.raises(wiki_index.NormalizedPathCollisionError) as exc:
        wiki_index.rebuild(tmp_path)
    assert exc.value.path == "café.md"


def test_incremental_rebuild(tmp_path):
    """Incremental rebuild reuses existing index and doesn't crash."""
    _init(tmp_path)

    # Create initial topics
    _topic(tmp_path, "topic1.md", {"title": "Topic 1"}, "Initial content")
    _topic(tmp_path, "topic2.md", {"title": "Topic 2"}, "More content")

    # Full rebuild
    data1, errors1 = wiki_index.rebuild(tmp_path, incremental=False)
    assert len(data1["topics"]) == 2
    assert len(errors1) == 0

    # Save index
    wiki_index.save_index(tmp_path, data1)

    # Incremental rebuild with no changes should succeed
    data2, errors2 = wiki_index.rebuild(tmp_path, incremental=True)
    assert len(data2["topics"]) == 2
    assert len(errors2) == 0

    # Add new topic
    _topic(tmp_path, "topic3.md", {"title": "Topic 3"}, "New topic")

    # Incremental rebuild should pick up new topic
    data3, errors3 = wiki_index.rebuild(tmp_path, incremental=True)
    assert len(data3["topics"]) == 3
    assert len(errors3) == 0
    assert "topic3.md" in data3["topics"]


def test_incremental_rebuild_without_existing_index(tmp_path):
    """Incremental rebuild falls back to full rebuild if index missing."""
    _init(tmp_path)
    _topic(tmp_path, "topic1.md", {"title": "Topic 1"}, "Content")

    # Incremental rebuild without saved index should not crash
    data, errors = wiki_index.rebuild(tmp_path, incremental=True)
    assert len(data["topics"]) == 1
    assert len(errors) == 0


def test_incremental_rebuild_with_corrupted_index(tmp_path):
    """Incremental rebuild falls back to full rebuild if index corrupted."""
    _init(tmp_path)
    _topic(tmp_path, "topic1.md", {"title": "Topic 1"}, "Content")

    # Create corrupted index file
    index_path = config.index_path(tmp_path)
    index_path.parent.mkdir(parents=True, exist_ok=True)
    index_path.write_text("not valid json", encoding="utf-8")

    # Incremental rebuild should fall back to full rebuild
    data, errors = wiki_index.rebuild(tmp_path, incremental=True)
    assert len(data["topics"]) == 1
    assert len(errors) == 0


# --- 1.6 mtime-based incremental reuse ---------------------------------------

def test_incremental_skips_parse_for_unchanged_files(tmp_path, monkeypatch):
    """Unchanged files are reused from the existing index without re-parsing."""
    _init(tmp_path)
    _topic(tmp_path, "a.md", {"title": "A"})
    _topic(tmp_path, "b.md", {"title": "B"})
    data1, _ = wiki_index.rebuild(tmp_path)
    wiki_index.save_index(tmp_path, data1)

    def boom(text):
        raise AssertionError("unchanged file was re-parsed")

    monkeypatch.setattr(wiki_index.frontmatter, "parse", boom)
    data2, errors = wiki_index.rebuild(tmp_path, incremental=True)
    assert errors == []
    assert data2["topics"] == data1["topics"]




def test_incremental_reparses_changed_file_only(tmp_path, monkeypatch):
    """Only the changed file is re-parsed; unchanged entries are reused."""
    _init(tmp_path)
    _topic(tmp_path, "a.md", {"title": "A"})
    b = _topic(tmp_path, "b.md", {"title": "B"})
    data1, _ = wiki_index.rebuild(tmp_path)
    wiki_index.save_index(tmp_path, data1)

    parsed: list[str] = []
    real_parse = wiki_index.frontmatter.parse

    def spy(text):
        parsed.append(text)
        return real_parse(text)

    monkeypatch.setattr(wiki_index.frontmatter, "parse", spy)
    b.write_text(frontmatter.dump({"title": "B2"}, "changed"), encoding="utf-8")
    data2, errors = wiki_index.rebuild(tmp_path, incremental=True)
    assert errors == []
    assert data2["topics"]["b.md"]["title"] == "B2"
    assert data2["topics"]["a.md"] == data1["topics"]["a.md"]
    assert len(parsed) == 1
    assert "changed" in parsed[0]


def test_legacy_entry_without_mtime_is_reparsed(tmp_path):
    """Index entries saved before mtime tracking are re-parsed once."""
    _init(tmp_path)
    _topic(tmp_path, "a.md", {"title": "A"})
    data1, _ = wiki_index.rebuild(tmp_path)
    wiki_index.save_index(tmp_path, data1)

    legacy = json.loads(config.index_path(tmp_path).read_text(encoding="utf-8"))
    legacy_entry = legacy["topics"]["a.md"]
    del legacy_entry["mtime_ns"]
    config.index_path(tmp_path).write_text(json.dumps(legacy), encoding="utf-8")

    data2, errors = wiki_index.rebuild(tmp_path, incremental=True)
    assert errors == []
    assert "mtime_ns" in data2["topics"]["a.md"]
    assert data2["topics"]["a.md"]["mtime_ns"] > 0


def test_incremental_with_null_index_falls_back(tmp_path):
    """A JSON-null index file must not crash incremental rebuild; it falls back to full."""
    _init(tmp_path)
    _topic(tmp_path, "A.md", {"title": "A"})
    index_path = config.index_path(tmp_path)
    index_path.parent.mkdir(parents=True, exist_ok=True)
    index_path.write_text("null", encoding="utf-8")
    data, errors = wiki_index.rebuild(tmp_path, incremental=True)
    assert len(data["topics"]) == 1
    assert errors == []


def test_incremental_with_array_index_falls_back(tmp_path):
    """A JSON-array index file must not crash incremental rebuild."""
    _init(tmp_path)
    _topic(tmp_path, "A.md", {"title": "A"})
    index_path = config.index_path(tmp_path)
    index_path.parent.mkdir(parents=True, exist_ok=True)
    index_path.write_text("[1, 2, 3]", encoding="utf-8")
    data, errors = wiki_index.rebuild(tmp_path, incremental=True)
    assert len(data["topics"]) == 1
    assert errors == []


def test_incremental_non_dict_entry_is_reparsed(tmp_path):
    """A corrupt (non-dict) cached entry is re-parsed instead of crashing or being reused."""
    _init(tmp_path)
    _topic(tmp_path, "A.md", {"title": "A"})
    data1, _ = wiki_index.rebuild(tmp_path)
    data1["topics"]["A.md"] = "not a dict"
    wiki_index.save_index(tmp_path, data1)
    data2, errors = wiki_index.rebuild(tmp_path, incremental=True)
    assert errors == []
    assert isinstance(data2["topics"]["A.md"], dict)
    assert data2["topics"]["A.md"]["title"] == "A"
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 322kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 322kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 322kUpdated Claude CodeCodexVerifiedInstall