Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
"""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")