@ngocsangairvds/vsaf 4.0.6 → 4.0.7

package/skills/vds-skill/vds-scripts/vds_cli/tests/unit/test_consumption_funnel.py

@@ -0,0 +1,106 @@
+"""Tests for vds_cli.docs.consumption.funnel."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+from vds_cli.docs.consumption.funnel import (
+    FunnelRow,
+    FunnelStageSummary,
+    aggregate_reads,
+    dead_weight,
+    funnel_summary,
+)
+from vds_cli.docs.consumption.scanner import DocRead
+
+
+def _dt(days_ago: int) -> datetime:
+    return datetime.now(UTC) - timedelta(days=days_ago)
+
+
+class TestDiataxisBucketing:
+    def test_diataxis_bucketing(self) -> None:
+        rows = [
+            FunnelRow(
+                path=Path("a.md"),
+                reads=1,
+                unique_sessions=1,
+                last_read=_dt(1),
+                diataxis="tutorial",
+            ),
+            FunnelRow(
+                path=Path("b.md"),
+                reads=2,
+                unique_sessions=1,
+                last_read=_dt(1),
+                diataxis="how-to",
+            ),
+        ]
+        summary = funnel_summary(rows)
+        assert summary == [
+            FunnelStageSummary(stage="tutorial", read_count=1, unique_docs=1),
+            FunnelStageSummary(stage="how-to", read_count=2, unique_docs=1),
+            FunnelStageSummary(stage="reference", read_count=0, unique_docs=0),
+            FunnelStageSummary(stage="explanation", read_count=0, unique_docs=0),
+        ]
+
+
+class TestDeadWeightBoundary:
+    def test_dead_weight_boundary(self) -> None:
+        path_a = Path("stale.md")
+        path_b = Path("fresh.md")
+        docs = [
+            DocRead(path=path_a, session_id="s1", read_at=_dt(70), diataxis="reference"),
+            DocRead(path=path_b, session_id="s1", read_at=_dt(30), diataxis="how-to"),
+        ]
+        result = dead_weight(docs, window_days=60)
+        assert len(result) == 1
+        assert result[0].path == path_a
+        assert result[0].reads == 0
+        assert result[0].unique_sessions == 0
+        assert result[0].last_read is None
+        assert result[0].diataxis == "reference"
+
+    def test_dead_weight_window_zero(self) -> None:
+        path_a = Path("a.md")
+        docs = [DocRead(path=path_a, session_id="s1", read_at=_dt(1), diataxis=None)]
+        result = dead_weight(docs, window_days=0)
+        assert len(result) == 1
+        assert result[0].reads == 0
+
+
+class TestAggregateReads:
+    def test_same_doc_three_times_one_session(self) -> None:
+        path = Path("x.md")
+        docs = [
+            DocRead(path=path, session_id="s1", read_at=_dt(1), diataxis="tutorial"),
+            DocRead(path=path, session_id="s1", read_at=_dt(2), diataxis="tutorial"),
+            DocRead(path=path, session_id="s1", read_at=_dt(3), diataxis="tutorial"),
+        ]
+        rows = aggregate_reads(docs)
+        assert len(rows) == 1
+        assert rows[0].reads == 3
+        assert rows[0].unique_sessions == 1
+
+    def test_same_doc_three_times_two_sessions(self) -> None:
+        path = Path("y.md")
+        docs = [
+            DocRead(path=path, session_id="s1", read_at=_dt(1), diataxis="how-to"),
+            DocRead(path=path, session_id="s2", read_at=_dt(2), diataxis="how-to"),
+            DocRead(path=path, session_id="s2", read_at=_dt(3), diataxis="how-to"),
+        ]
+        rows = aggregate_reads(docs)
+        assert len(rows) == 1
+        assert rows[0].reads == 3
+        assert rows[0].unique_sessions == 2
+
+
+class TestFunnelSummaryEmpty:
+    def test_funnel_summary_empty(self) -> None:
+        assert funnel_summary([]) == [
+            FunnelStageSummary(stage="tutorial", read_count=0, unique_docs=0),
+            FunnelStageSummary(stage="how-to", read_count=0, unique_docs=0),
+            FunnelStageSummary(stage="reference", read_count=0, unique_docs=0),
+            FunnelStageSummary(stage="explanation", read_count=0, unique_docs=0),
+        ]

package/skills/vds-skill/vds-scripts/vds_cli/tests/unit/test_consumption_scanner.py

@@ -0,0 +1,144 @@
+"""Tests for docs.consumption.scanner."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from vds_cli.docs.consumption.scanner import (
+    scan_consumption,
+)
+
+if TYPE_CHECKING:
+    import pytest
+
+
+def _make_event(file_path: str | list[str], tool_name: str = "Read", timestamp: str | None = None) -> dict:
+    """Build a minimal assistant tool_use event."""
+    content: list[dict] = [
+        {
+            "type": "tool_use",
+            "name": tool_name,
+            "input": {"file_path": file_path},
+        }
+    ]
+    return {
+        "type": "assistant",
+        "timestamp": timestamp or "2026-01-15T12:00:00Z",
+        "message": {"content": content},
+    }
+
+
+def test_reads_single_session(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Three valid tool_use events → three DocReads with correct paths."""
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    docs_dir = repo / "docs" / "agents"
+    docs_dir.mkdir(parents=True)
+    (docs_dir / "agent_a.md").write_text("<!-- diátaxis: tutorial -->\n# A\n", encoding="utf-8")
+    (docs_dir / "agent_b.md").write_text("# B\n", encoding="utf-8")
+    (docs_dir / "agent_c.md").write_text("<!-- diátaxis: how-to -->\n# C\n", encoding="utf-8")
+
+    # Build a session directory with one JSONL file
+    session_dir = tmp_path / "sessions"
+    session_dir.mkdir()
+    jsonl = session_dir / "session-abc.jsonl"
+    events = [
+        _make_event("docs/agents/agent_a.md"),
+        _make_event("docs/agents/agent_b.md"),
+        _make_event("docs/agents/agent_c.md", timestamp="2026-01-15T12:05:00Z"),
+    ]
+    jsonl.write_text("\n".join(json.dumps(e) for e in events) + "\n", encoding="utf-8")
+
+    reads = scan_consumption(repo, session_dir=session_dir)
+    assert len(reads) == 3
+
+    # All should belong to the same session
+    assert {r.session_id for r in reads} == {"session-abc"}
+
+    paths = sorted(str(r.path) for r in reads)
+    assert paths == sorted(
+        [
+            str(repo / "docs" / "agents" / "agent_a.md"),
+            str(repo / "docs" / "agents" / "agent_b.md"),
+            str(repo / "docs" / "agents" / "agent_c.md"),
+        ]
+    )
+
+    diataxis_map = {str(r.path): r.diataxis for r in reads}
+    assert diataxis_map[str(repo / "docs" / "agents" / "agent_a.md")] == "tutorial"
+    assert diataxis_map[str(repo / "docs" / "agents" / "agent_b.md")] is None
+    assert diataxis_map[str(repo / "docs" / "agents" / "agent_c.md")] == "how-to"
+
+
+def test_home_redaction(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Paths under $HOME are emitted with ~ prefix."""
+    # Mock home to tmp_path
+    monkeypatch.setattr(Path, "home", lambda: tmp_path)
+
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    home_doc = tmp_path / "docs" / "agents" / "agent_x.md"
+    home_doc.parent.mkdir(parents=True)
+    home_doc.write_text("# X\n", encoding="utf-8")
+
+    # Use absolute path that lives under mocked home
+    session_dir = tmp_path / "sessions"
+    session_dir.mkdir()
+    jsonl = session_dir / "session-redact.jsonl"
+    jsonl.write_text(
+        json.dumps(_make_event(str(home_doc))) + "\n",
+        encoding="utf-8",
+    )
+
+    reads = scan_consumption(repo, session_dir=session_dir)
+    assert len(reads) == 1
+    assert reads[0].path == Path("~") / "docs" / "agents" / "agent_x.md"
+
+
+def test_missing_file_graceful(tmp_path: Path) -> None:
+    """Missing or empty JSONL directory returns empty list."""
+    repo = tmp_path / "repo"
+    repo.mkdir()
+
+    missing_dir = tmp_path / "nonexistent"
+    assert scan_consumption(repo, session_dir=missing_dir) == []
+
+    empty_dir = tmp_path / "empty"
+    empty_dir.mkdir()
+    assert scan_consumption(repo, session_dir=empty_dir) == []
+
+
+def test_session_deduplication(tmp_path: Path) -> None:
+    """Same doc in same session counted once; different sessions counted separately."""
+    repo = tmp_path / "repo"
+    repo.mkdir()
+    doc = repo / "docs" / "agents" / "agent_y.md"
+    doc.parent.mkdir(parents=True)
+    doc.write_text("# Y\n", encoding="utf-8")
+
+    session_dir = tmp_path / "sessions"
+    session_dir.mkdir()
+
+    s1 = session_dir / "session-s1.jsonl"
+    s1.write_text(
+        json.dumps(_make_event("docs/agents/agent_y.md"))
+        + "\n"
+        + json.dumps(_make_event("docs/agents/agent_y.md"))
+        + "\n",
+        encoding="utf-8",
+    )
+
+    s2 = session_dir / "session-s2.jsonl"
+    s2.write_text(
+        json.dumps(_make_event("docs/agents/agent_y.md")) + "\n",
+        encoding="utf-8",
+    )
+
+    reads = scan_consumption(repo, session_dir=session_dir)
+    assert len(reads) == 2
+
+    sessions = [r.session_id for r in reads]
+    assert sessions.count("session-s1") == 1
+    assert sessions.count("session-s2") == 1

package/skills/vds-skill/vds-scripts/vds_cli/tests/unit/test_docs_cmd.py

@@ -0,0 +1,89 @@
+"""Unit tests for docs command helpers."""
+
+from __future__ import annotations
+
+import os
+import time
+from pathlib import Path
+
+from vds_cli.docs_cmd import check_freshness, load_freshness_pairs, validate_docs
+
+
+def test_validate_docs_reports_and_fixes_claude_symlink(tmp_path: Path) -> None:
+    repo = tmp_path / "vds-scripts"
+    (repo / "docs" / "phases").mkdir(parents=True)
+    (repo / "AGENTS.md").write_text("# AGENTS\n\n- docs/phases/CHANGELOG.md\n", encoding="utf-8")
+    (repo / "llms.txt").write_text("# Index\n\n- [agents](./AGENTS.md)\n", encoding="utf-8")
+    (repo / "CLAUDE.md").write_text("legacy copy", encoding="utf-8")
+    (repo / "docs" / "phases" / "CHANGELOG.md").write_text("# Changelog\n", encoding="utf-8")
+
+    before = validate_docs(repo, repo=None, fix=False)
+    assert any(issue.check == "claude_symlink" for issue in before)
+
+    after = validate_docs(repo, repo=None, fix=True)
+    assert any(issue.check == "claude_symlink" and issue.fixed for issue in after)
+    assert (repo / "CLAUDE.md").is_symlink()
+    assert (repo / "CLAUDE.md").readlink() == Path("AGENTS.md")
+
+
+def test_load_freshness_pairs_parses_yaml_shape(tmp_path: Path) -> None:
+    config = tmp_path / ".freshness.yaml"
+    config.write_text(
+        "pairs:\n  - doc: docs/a.md\n    source: src/a.py\n    max_lag_days: 3\n",
+        encoding="utf-8",
+    )
+
+    pairs = load_freshness_pairs(config)
+    assert len(pairs) == 1
+    assert pairs[0].doc == "docs/a.md"
+    assert pairs[0].source == "src/a.py"
+    assert pairs[0].max_lag_days == 3
+
+
+def test_check_freshness_uses_mtime_and_flags_lag(tmp_path: Path) -> None:
+    repo = tmp_path / "vds-scripts"
+    (repo / "docs").mkdir(parents=True)
+    (repo / "src").mkdir(parents=True)
+
+    doc = repo / "docs" / "a.md"
+    src = repo / "src" / "a.py"
+    doc.write_text("doc", encoding="utf-8")
+    src.write_text("source", encoding="utf-8")
+
+    now = time.time()
+    os.utime(doc, (now - 86400 * 3, now - 86400 * 3))
+    os.utime(src, (now, now))
+
+    config = repo / "docs" / ".freshness.yaml"
+    config.write_text(
+        "pairs:\n  - doc: docs/a.md\n    source: src/a.py\n    max_lag_days: 1\n",
+        encoding="utf-8",
+    )
+
+    issues = check_freshness(repo, config)
+    assert len(issues) == 1
+    assert issues[0].doc == "docs/a.md"
+    assert issues[0].source == "src/a.py"
+
+
+def test_validate_docs_check_ecosystem_pass(tmp_path: Path) -> None:
+    repo = tmp_path / "vds-scripts"
+    repo.mkdir()
+    (repo / "AGENTS.md").write_text("# AGENTS", encoding="utf-8")
+    (repo / "llms.txt").write_text("# Index", encoding="utf-8")
+    (repo / "ECOSYSTEM-CHANGELOG.md").write_text("# Changelog\n", encoding="utf-8")
+    (repo / "ECOSYSTEM-DOCS.md").write_text("# Index\n", encoding="utf-8")
+    issues = validate_docs(repo, check_ecosystem=True)
+    assert not any(issue.check.startswith("ecosystem") for issue in issues)
+
+
+def test_validate_docs_check_ecosystem_missing(tmp_path: Path) -> None:
+    repo = tmp_path / "vds-scripts"
+    repo.mkdir()
+    (repo / "AGENTS.md").write_text("# AGENTS", encoding="utf-8")
+    (repo / "llms.txt").write_text("# Index", encoding="utf-8")
+    issues = validate_docs(repo, check_ecosystem=True)
+    ecosystem_issues = [i for i in issues if i.check.startswith("ecosystem")]
+    assert len(ecosystem_issues) == 2
+    assert any("ECOSYSTEM-DOCS.md" in i.message for i in ecosystem_issues)
+    assert any("ECOSYSTEM-CHANGELOG.md" in i.message for i in ecosystem_issues)

package/skills/vds-skill/vds-scripts/vds_cli/tests/unit/test_docs_cmd_wave8.py

@@ -0,0 +1,161 @@
+"""Unit tests for Wave 8 docs validation features (DOC-V2-023 through DOC-V2-026)."""
+
+from pathlib import Path
+
+from vds_cli.docs_cmd import (
+    _check_cross_repo_links,
+    _check_diataxis_headers,
+    _check_orchestrator_docs,
+    _check_skill_docs,
+    _check_vi_docs,
+)
+
+
+class TestCheckViDocs:
+    def test_missing_agents_vi(self, tmp_path: Path) -> None:
+        (tmp_path / "AGENTS.md").write_text("# AGENTS\n")
+        issues = _check_vi_docs("test-repo", tmp_path)
+        assert any(i.check == "vi_translation_missing" for i in issues)
+
+    def test_agents_vi_present(self, tmp_path: Path) -> None:
+        (tmp_path / "AGENTS.md").write_text("# AGENTS\n")
+        (tmp_path / "AGENTS.vi.md").write_text("# AGENTS VI\n")
+        issues = _check_vi_docs("test-repo", tmp_path)
+        assert not any(i.check == "vi_translation_missing" for i in issues)
+
+    def test_missing_vi_docs_dir(self, tmp_path: Path) -> None:
+        (tmp_path / "docs" / "agents").mkdir(parents=True)
+        issues = _check_vi_docs("test-repo", tmp_path)
+        assert any(i.check == "vi_docs_missing" for i in issues)
+
+    def test_vi_docs_dir_present(self, tmp_path: Path) -> None:
+        (tmp_path / "docs" / "agents").mkdir(parents=True)
+        (tmp_path / "docs" / "vi" / "agents").mkdir(parents=True)
+        issues = _check_vi_docs("test-repo", tmp_path)
+        assert not any(i.check == "vi_docs_missing" for i in issues)
+
+    def test_llms_missing_vi_link(self, tmp_path: Path) -> None:
+        (tmp_path / "llms.txt").write_text("# Index\n")
+        issues = _check_vi_docs("test-repo", tmp_path)
+        assert any(i.check == "vi_llms_missing" for i in issues)
+
+    def test_llms_has_vi_link(self, tmp_path: Path) -> None:
+        (tmp_path / "llms.txt").write_text("# Index\n\n- [vi](docs/vi/)\n")
+        issues = _check_vi_docs("test-repo", tmp_path)
+        assert not any(i.check == "vi_llms_missing" for i in issues)
+
+
+class TestCheckDiataxisHeaders:
+    def test_valid_header(self, tmp_path: Path) -> None:
+        docs = tmp_path / "docs" / "agents"
+        docs.mkdir(parents=True)
+        (docs / "test.md").write_text("<!-- diátaxis: how-to -->\n# Test\n")
+        issues = _check_diataxis_headers("test-repo", tmp_path)
+        assert len(issues) == 0
+
+    def test_missing_header(self, tmp_path: Path) -> None:
+        docs = tmp_path / "docs" / "agents"
+        docs.mkdir(parents=True)
+        (docs / "test.md").write_text("# Test\n")
+        issues = _check_diataxis_headers("test-repo", tmp_path)
+        assert any(i.check == "diataxis_header_missing" for i in issues)
+
+    def test_invalid_quadrant(self, tmp_path: Path) -> None:
+        docs = tmp_path / "docs" / "agents"
+        docs.mkdir(parents=True)
+        (docs / "test.md").write_text("<!-- diátaxis: invalid -->\n# Test\n")
+        issues = _check_diataxis_headers("test-repo", tmp_path)
+        assert any(i.check == "diataxis_header_invalid" for i in issues)
+
+
+class TestCheckCrossRepoLinks:
+    def test_valid_cross_repo_link(self, tmp_path: Path) -> None:
+        repo1 = tmp_path / "vds-scripts"
+        repo2 = tmp_path / "vds-skills"
+        repo1.mkdir()
+        repo2.mkdir()
+        docs = repo1 / "docs" / "agents"
+        docs.mkdir(parents=True)
+        (docs / "test.md").write_text("[skill](../vds-skills/skills/test/SKILL.md)\n")
+        (repo2 / "skills" / "test").mkdir(parents=True)
+        (repo2 / "skills" / "test" / "SKILL.md").write_text("# Skill\n")
+        issues = _check_cross_repo_links("vds-scripts", repo1, tmp_path)
+        assert len(issues) == 0
+
+    def test_broken_cross_repo_link(self, tmp_path: Path) -> None:
+        repo1 = tmp_path / "vds-scripts"
+        repo2 = tmp_path / "vds-skills"
+        repo1.mkdir()
+        repo2.mkdir()
+        docs = repo1 / "docs" / "agents"
+        docs.mkdir(parents=True)
+        (docs / "test.md").write_text("[skill](../vds-skills/skills/test/MISSING.md)\n")
+        issues = _check_cross_repo_links("vds-scripts", repo1, tmp_path)
+        assert any(i.check == "cross_repo_link_broken" for i in issues)
+
+    def test_ignores_non_repo_links(self, tmp_path: Path) -> None:
+        repo1 = tmp_path / "vds-scripts"
+        repo1.mkdir()
+        docs = repo1 / "docs" / "agents"
+        docs.mkdir(parents=True)
+        (docs / "test.md").write_text("[local](../reference/other.md)\n")
+        issues = _check_cross_repo_links("vds-scripts", repo1, tmp_path)
+        assert len(issues) == 0
+
+
+class TestCheckOrchestratorDocs:
+    def test_orchestrator_with_doc(self, tmp_path: Path) -> None:
+        vds_cli = tmp_path / "vds_cli" / "src" / "vds_cli"
+        vds_cli.mkdir(parents=True)
+        (vds_cli / "router.py").write_text('"audit": {\n  "module": "audit"\n}\n')
+        ref = tmp_path / "docs" / "agents" / "reference"
+        ref.mkdir(parents=True)
+        (ref / "audit-orchestrator.md").write_text("# Audit\n")
+        issues = _check_orchestrator_docs("test-repo", tmp_path)
+        assert len(issues) == 0
+
+    def test_orchestrator_without_doc(self, tmp_path: Path) -> None:
+        vds_cli = tmp_path / "vds_cli" / "src" / "vds_cli"
+        vds_cli.mkdir(parents=True)
+        (vds_cli / "router.py").write_text('"custom_orch": {\n  "module": "custom"\n}\n')
+        ref = tmp_path / "docs" / "agents" / "reference"
+        ref.mkdir(parents=True)
+        issues = _check_orchestrator_docs("test-repo", tmp_path)
+        assert any(i.check == "orchestrator_doc_missing" for i in issues)
+
+
+class TestCheckSkillDocs:
+    def test_skill_with_quality_and_refs(self, tmp_path: Path) -> None:
+        skills = tmp_path / "skills"
+        skills.mkdir()
+        skill = skills / "test-skill"
+        skill.mkdir()
+        (skill / "SKILL.md").write_text("# Skill\n")
+        (skill / "QUALITY.md").write_text("# Quality\n")
+        (skill / "references").mkdir()
+        issues = _check_skill_docs("vds-skills", tmp_path)
+        assert len(issues) == 0
+
+    def test_skill_missing_quality(self, tmp_path: Path) -> None:
+        skills = tmp_path / "skills"
+        skills.mkdir()
+        skill = skills / "test-skill"
+        skill.mkdir()
+        (skill / "SKILL.md").write_text("# Skill\n")
+        (skill / "references").mkdir()
+        issues = _check_skill_docs("vds-skills", tmp_path)
+        assert any(i.check == "skill_quality_doc" for i in issues)
+
+    def test_skill_missing_refs(self, tmp_path: Path) -> None:
+        skills = tmp_path / "skills"
+        skills.mkdir()
+        skill = skills / "test-skill"
+        skill.mkdir()
+        (skill / "SKILL.md").write_text("# Skill\n")
+        (skill / "QUALITY.md").write_text("# Quality\n")
+        issues = _check_skill_docs("vds-skills", tmp_path)
+        assert any(i.check == "skill_references" for i in issues)
+
+    def test_skips_non_vds_skills_repo(self, tmp_path: Path) -> None:
+        issues = _check_skill_docs("vds-scripts", tmp_path)
+        assert len(issues) == 0

package/skills/vds-skill/vds-scripts/vds_cli/tests/unit/test_docs_metrics.py

@@ -0,0 +1,16 @@
+"""Tests for docs_metrics module."""
+
+from vds_cli.docs_metrics import generate_freshness_heatmap, generate_onboarding_funnel
+
+
+class TestOnboardingFunnel:
+    def test_generates_result(self, tmp_path):
+        result = generate_onboarding_funnel(tmp_path)
+        assert "steps" in result
+        assert len(result["steps"]) == 4
+
+
+class TestFreshnessHeatmap:
+    def test_empty_repos(self):
+        result = generate_freshness_heatmap([])
+        assert result["repos"] == {}

package/skills/vds-skill/vds-scripts/vds_cli/tests/unit/test_docs_quality_score.py

@@ -0,0 +1,61 @@
+"""Tests for docs quality scoring (FR-4)."""
+
+from pathlib import Path
+
+from vds_cli.docs_cmd import score_all_docs, score_doc
+
+
+class TestScoreDoc:
+    def test_score_high_quality_doc(self, tmp_path: Path) -> None:
+        doc = tmp_path / "test.md"
+        doc.write_text(
+            "<!-- diátaxis: reference -->\n\n# Test\n\n## Scope\n\n- **Does:** things.\n"
+            "## CLI Entry\n\n```bash\nvds-cli test --help\n```\n\n"
+            "## Key Commands\n\n| Command | Purpose |\n|---------|---------|\n"
+            "| `run` | Run thing |\n\n"
+            "## Common Workflows\n\n### Workflow: Test\n\n1. Step one\n2. Step two\n\n"
+            "## Related\n\n- [other](other-orchestrator.md)\n",
+            encoding="utf-8",
+        )
+        result = score_doc(doc)
+        assert result["total"] >= 0.8
+        assert result["commands"] == 1.0
+        assert result["workflows"] == 1.0
+        assert result["cross_links"] == 1.0
+
+    def test_score_low_quality_doc(self, tmp_path: Path) -> None:
+        doc = tmp_path / "test.md"
+        doc.write_text("# Test\n\nShort doc.\n", encoding="utf-8")
+        result = score_doc(doc)
+        assert result["total"] < 0.5
+        assert result["commands"] == 0.0
+        assert result["workflows"] == 0.0
+        assert result["cross_links"] == 0.0
+
+    def test_score_length_only(self, tmp_path: Path) -> None:
+        doc = tmp_path / "test.md"
+        lines = ["# Test\n"] + ["More content.\n"] * 90
+        doc.write_text("".join(lines), encoding="utf-8")
+        result = score_doc(doc)
+        assert result["length"] == 1.0
+        assert result["commands"] == 0.0
+
+
+class TestScoreAllDocs:
+    def test_empty_repo(self, tmp_path: Path) -> None:
+        result = score_all_docs(tmp_path)
+        assert result["count"] == 0
+        assert result["average"] == 0.0
+
+    def test_single_doc(self, tmp_path: Path) -> None:
+        docs = tmp_path / "docs" / "agents"
+        docs.mkdir(parents=True)
+        doc = docs / "test.md"
+        doc.write_text(
+            "<!-- diátaxis: reference -->\n# Test\n\n```bash\ncmd\n```\nWorkflow: test\n\n[link](other.md)\n",
+            encoding="utf-8",
+        )
+        result = score_all_docs(tmp_path)
+        assert result["count"] == 1
+        assert "docs/agents/test.md" in result["docs"]
+        assert result["average"] > 0.0