Skip to content

Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.

9.3 KB
Raw Blame
"""Extraction rules for the documentation drift detector.

One test per rule Phase 1 learned the hard way. Each docstring names the
measurement that justifies the rule, so a future reader retuning one can see
what it costs.
"""

from __future__ import annotations

import pytest

from repowise.core.analysis.doc_drift.extractor import (
    extract,
    is_checkable_document,
    is_guide_document,
    prose_lines,
)
from repowise.core.analysis.doc_drift.models import DriftKind


def _kinds(text: str, doc: str = "docs/x.md") -> set[DriftKind]:
    return {r.kind for r in extract(text, doc)}


def _targets(text: str, kind: DriftKind, doc: str = "docs/x.md") -> list[str]:
    return [r.target for r in extract(text, doc) if r.kind is kind]


# ---------------------------------------------------------------------------
# Fenced and generated spans
# ---------------------------------------------------------------------------


def test_fenced_code_contributes_nothing():
    """Paths inside a fence are illustrative by construction."""
    text = "Real: `src/a.py`\n```\nsee `src/invented.py`\n```\nAfter: `src/b.py`\n"
    targets = _targets(text, DriftKind.PATH)
    assert "src/invented.py" not in targets
    assert targets == ["src/a.py", "src/b.py"]


def test_tilde_fences_are_fences_too():
    text = "~~~\n`src/invented.py`\n~~~\n"
    assert _targets(text, DriftKind.PATH) == []


def test_generated_span_is_skipped():
    """Repowise's own output is not a drift target.

    The START marker carries a trailing sentence and an em dash
    (``editor_files/base.py:28``), so the skip must match on the prefix rather
    than the full literal.
    """
    text = (
        "Mine: `src/a.py`\n"
        "<!-- REPOWISE:START — Do not edit below this line. "
        "Auto-generated by Repowise. -->\n"
        "Generated: `src/generated.py`\n"
        "<!-- REPOWISE:END -->\n"
        "Mine again: `src/b.py`\n"
    )
    targets = _targets(text, DriftKind.PATH)
    assert targets == ["src/a.py", "src/b.py"]


@pytest.mark.parametrize("tag", ["REPOWISE", "REPOWISE_AGENTS", "REPOWISE_DISTILL"])
def test_every_live_marker_tag_is_skipped(tag: str):
    """All three tags in use today, so a new generator does not leak findings."""
    text = f"<!-- {tag}:START -->\n`src/generated.py`\n<!-- {tag}:END -->\n"
    assert _targets(text, DriftKind.PATH) == []


def test_line_numbers_survive_skipped_spans():
    """A finding's line has to point at the real file."""
    text = "intro\n```\nfenced\n```\n`src/a.py`\n"
    refs = extract(text, "docs/x.md")
    assert [r.line for r in refs] == [5]


# ---------------------------------------------------------------------------
# Rule 3: commands only from inline code spans
# ---------------------------------------------------------------------------


def test_commands_are_read_only_from_inline_code():
    """Scanning bare prose matched English.

    Phase 1's first run produced "make room", "make that", "make the" and
    "make no" as missing build targets: 43 of 55 findings, entirely noise.
    """
    assert _targets("We make room for this and make the call.", DriftKind.COMMAND) == []
    assert _targets("Run `make build` first.", DriftKind.COMMAND) == ["make:build"]


def test_npm_run_commands_are_extracted():
    assert _targets("Run `npm run test`.", DriftKind.COMMAND) == ["npm:test"]
    assert _targets("Run `pnpm run type-check`.", DriftKind.COMMAND) == ["npm:type-check"]


# ---------------------------------------------------------------------------
# The symbol class does not exist
# ---------------------------------------------------------------------------


def test_only_code_shaped_identifiers_become_symbol_candidates():
    """Backticks mean "literal": a word or a constant is never a candidate.

    Candidacy is shape only; git history decides whether one was a symbol.
    """
    text = "Set `OPENAI_API_KEY`, pass a `string`, and call `resolve_target`."
    refs = extract(text, "docs/x.md")
    assert [(r.kind, r.target) for r in refs] == [(DriftKind.SYMBOL, "resolve_target")]


# ---------------------------------------------------------------------------
# Path shaping
# ---------------------------------------------------------------------------


def test_bare_filename_is_still_extracted_but_prose_is_not():
    """Extraction is permissive; the resolver decides checkability."""
    assert _targets("See `config.yaml` for this.", DriftKind.PATH) == ["config.yaml"]
    assert _targets("That is, `e.g` and `i.e` here.", DriftKind.PATH) == []


@pytest.mark.parametrize(
    "token",
    ["path/to/thing.py", "your/app/main.py", "examples/foo.py", "src/{name}.py"],
)
def test_placeholders_and_templates_are_not_paths(token: str):
    assert _targets(f"Create `{token}` now.", DriftKind.PATH) == []


def test_urls_are_never_paths_or_links():
    text = "See [docs](https://example.com/a.py) and `https://x.dev/b.py`."
    assert extract(text, "docs/x.md") == []


# ---------------------------------------------------------------------------
# Links and anchors
# ---------------------------------------------------------------------------


def test_link_with_fragment_yields_both_a_link_and_an_anchor():
    """One line, two assertions: the file exists, and it declares the heading."""
    refs = extract("See [it](../README.md#setup).", "docs/x.md")
    assert {r.kind for r in refs} == {DriftKind.LINK, DriftKind.ANCHOR}


def test_same_document_anchor_targets_its_own_file():
    refs = extract("See [below](#some-heading).", "docs/x.md")
    assert [(r.kind, r.target) for r in refs] == [
        (DriftKind.ANCHOR, "docs/x.md#some-heading")
    ]


def test_heading_lines_still_assert_paths():
    """A section title asserts a path exactly as body prose does.

    Skipping heading lines silently dropped a real defect in this repository:
    ``ARCHITECTURE.md`` names ``git_indexer.py`` in a ``### 7.1`` heading.
    """
    text = "### 7.1 GitIndexer (`packages/core/ingestion/git_indexer.py`)\n"
    assert _targets(text, DriftKind.PATH) == ["packages/core/ingestion/git_indexer.py"]


def test_section_trail_is_recorded_as_evidence():
    text = "## Adding a language\n\n### Step 1\n\nCreate `src/specs/x.py`.\n"
    refs = extract(text, "docs/x.md")
    assert refs[0].section == "Adding a language > Step 1"


def test_sibling_heading_pops_the_trail():
    text = "## A\n\n### A1\n\n## B\n\nSee `src/x.py`.\n"
    refs = extract(text, "docs/x.md")
    assert refs[0].section == "B"


# ---------------------------------------------------------------------------
# Rule 2: historical documents excluded by stem PATTERN
# ---------------------------------------------------------------------------


@pytest.mark.parametrize(
    "path",
    [
        "CHANGELOG.md",
        "docs/changelog.md",
        "docs/release-notes.md",
        "docs/release_notes.md",
        "RELEASES.md",
        "docs/whatsnew.md",
        "docs/migration-guide.md",
        "UPGRADING.md",
        "docs/HISTORY.md",
        "docs/news.md",
    ],
)
def test_historical_documents_are_excluded(path: str):
    """A changelog describes the tree as it was at each release.

    Matched on the stem as a pattern, never an exact filename list: Phase 1's
    first fixture was ``CHANGELOG.md``, which silently failed on fastapi's
    ``release-notes.md`` --- and all 17 of that repo's path findings came from
    that one file.
    """
    assert not is_checkable_document(path)


def test_ordinary_documents_are_checkable():
    assert is_checkable_document("docs/architecture/ARCHITECTURE.md")
    assert is_checkable_document("README.md")


@pytest.mark.parametrize(
    "path",
    [
        "node_modules/pkg/README.md",
        "vendor/lib/README.md",
        "tests/fixtures/sample/README.md",
        "tests/unit/doc_drift/data/sample.md",
        # fastapi keeps deliberately-broken markdown here to feed its own
        # link fixer. Checking it reports a project's test inputs as its
        # documentation; this shape produced four false findings before the
        # shared classifier replaced a hand-written directory list.
        "scripts/tests/test_translation_fixer/test_markdown_links/data/en_doc.md",
    ],
)
def test_vendored_and_fixture_documents_are_excluded(path: str):
    assert not is_checkable_document(path)


@pytest.mark.parametrize(
    "path",
    [
        "docs/layers/TEST_INTELLIGENCE.md",
        "docs/TESTING.md",
        "docs/test-strategy.md",
    ],
)
def test_documents_about_testing_are_not_test_files(path: str):
    """A document describing the test layer is prose, not a fixture.

    The shared classifier also recognises the ``test_*`` filename convention,
    which is a convention of code. Applied to the whole path it classes
    ``docs/layers/TEST_INTELLIGENCE.md`` as a test file and silently drops one
    of this repository's fourteen real defects, so the check is scoped to the
    containing directory.
    """
    assert is_checkable_document(path)


def test_non_markdown_is_not_a_document():
    """`.rst` and `.adoc` are outside this detector's reach entirely."""
    assert not is_checkable_document("docs/index.rst")
    assert not is_checkable_document("docs/index.adoc")


def test_guide_documents_are_recognised():
    assert is_guide_document(".github/CONTRIBUTING.md")
    assert is_guide_document("docs/tutorial.md")
    assert not is_guide_document("docs/architecture/ARCHITECTURE.md")


def test_prose_lines_are_one_indexed():
    assert next(iter(prose_lines("first\nsecond\n"))) == (1, "first")