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.

15.0 KB
Raw Blame
"""Resolution rules: four verdicts, and the anchoring rule that earns them."""

from __future__ import annotations

import pytest

from repowise.core.analysis.doc_drift.extractor import extract
from repowise.core.analysis.doc_drift.models import DocReference, DriftKind, DriftVerdict
from repowise.core.analysis.doc_drift.resolver import RepoIndex, join_relative, resolve

TREE = frozenset(
    {
        "README.md",
        "Makefile",
        "package.json",
        "docs/guide.md",
        "docs/architecture/ARCHITECTURE.md",
        "src/app.py",
        "src/util/helpers.py",
        "src/util/dup.py",
        "other/dup.py",
    }
)


def _index(**kw) -> RepoIndex:
    return RepoIndex.build(
        tracked_paths=kw.get("tree", TREE),
        doc_text=kw.get("docs", {}),
        manifest_text=kw.get("manifests", {}),
    )


def _ref(target: str, kind=DriftKind.PATH, doc="docs/architecture/ARCHITECTURE.md"):
    return DocReference(kind, target, target, doc, 1, "ctx")


# ---------------------------------------------------------------------------
# Rule 1: a reference is checkable only when anchored
# ---------------------------------------------------------------------------


def test_exact_path_resolves():
    assert resolve(_index(), _ref("src/app.py")).verdict is DriftVerdict.RESOLVED


def test_directory_resolves():
    assert resolve(_index(), _ref("src/util")).verdict is DriftVerdict.RESOLVED


def test_anchored_path_with_no_candidate_is_missing():
    res = resolve(_index(), _ref("src/util/gone.py"))
    assert res.verdict is DriftVerdict.MISSING
    assert res.origin == "path_no_candidate"


@pytest.mark.parametrize(
    "target",
    ["CLAUDE.md", "config.yaml", "state.json", "login.py", "opencode.json"],
)
def test_bare_filenames_are_never_checkable(target: str):
    """Rule 1. Bare filenames are never checkable.

    These are files Repowise writes into the user's tree, or invented
    examples. Phase 1's first run flagged 639 paths at a 49% rate, nearly all
    of this family. Requiring a separator plus a real first segment took the
    class to 1.3%.
    """
    assert resolve(_index(), _ref(target)).verdict is DriftVerdict.UNCHECKABLE


@pytest.mark.parametrize(
    "target", ["routes/web.php", "vendor/thing/ext_localconf.php", "app/models/user.rb"]
)
def test_foreign_first_segment_is_uncheckable(target: str):
    """A framework the docs merely describe is not this repository."""
    res = resolve(_index(), _ref(target))
    assert res.verdict is DriftVerdict.UNCHECKABLE
    assert res.detail == "unanchored"


# ---------------------------------------------------------------------------
# Rule: a path the prose places in the reader's own project is uncheckable,
# before anchoring even runs (#2743)
# ---------------------------------------------------------------------------


def _sentence_ref(context: str, raw: str, target: str | None = None) -> DocReference:
    """A reference whose ``context`` is a full sentence, not a bare marker.

    ``_ref`` above sets ``context="ctx"``, which carries no prose for the
    reader-project check to read, so these tests build the real shape.
    """
    return DocReference(
        DriftKind.PATH, raw, target or raw, "docs/architecture/ARCHITECTURE.md", 1, context
    )


@pytest.mark.parametrize(
    "context,raw",
    [
        (
            "Add this to your project's `src/setupTests.ts`:",
            "src/setupTests.ts",
        ),
        (
            "Then add the plugin to your project's `config/app.config.ts`.",
            "config/app.config.ts",
        ),
    ],
)
def test_a_path_in_the_readers_own_project_is_uncheckable(context: str, raw: str):
    """Even though ``src``/``config`` are real top-level dirs here, these are not."""
    res = resolve(_index(), _sentence_ref(context, raw))
    assert res.verdict is DriftVerdict.UNCHECKABLE
    assert res.detail == "reader-project"


def test_a_missing_path_on_a_neutral_line_still_reports():
    context = "See `src/index.ts` for the entry point, and `src/gone.py` which was removed."
    res = resolve(_index(), _sentence_ref(context, "src/gone.py"))
    assert res.verdict is DriftVerdict.MISSING
    assert res.detail == "no-candidate"


def test_an_earlier_sentences_reader_project_phrase_does_not_leak_forward():
    """The check is scoped to the current sentence, not the whole line."""
    context = "This mirrors your project's layout. See `src/gone.py` for details."
    res = resolve(_index(), _sentence_ref(context, "src/gone.py"))
    assert res.verdict is DriftVerdict.MISSING


def test_a_bare_your_with_no_recognised_phrase_is_still_checked():
    """'you can find it in ...' must not be swallowed by a bare 'your'."""
    context = "You can find it in `src/gone.py`."
    res = resolve(_index(), _sentence_ref(context, "src/gone.py"))
    assert res.verdict is DriftVerdict.MISSING


# ---------------------------------------------------------------------------
# Rule 6: ambiguous is never reported as missing
# ---------------------------------------------------------------------------


def test_single_basename_match_is_ambiguous_not_missing():
    """Phase 1 found five of these. Reporting them as drift would be wrong."""
    res = resolve(_index(), _ref("src/helpers.py"))
    assert res.verdict is DriftVerdict.AMBIGUOUS
    assert res.confidence == 0.0


def test_multiple_basename_matches_are_ambiguous():
    res = resolve(_index(), _ref("src/nested/dup.py"))
    assert res.verdict is DriftVerdict.AMBIGUOUS
    assert "basename-multi" in res.detail


def test_relative_link_resolves_against_its_own_document():
    ref = DocReference(DriftKind.LINK, "../guide.md", "../guide.md",
                       "docs/architecture/ARCHITECTURE.md", 1, "ctx")
    res = resolve(_index(), ref)
    assert res.verdict is DriftVerdict.RESOLVED
    assert res.detail == "relative-to-doc"


# ---------------------------------------------------------------------------
# join_relative: normalize segments, never strip characters (#4014)
# ---------------------------------------------------------------------------


def test_join_relative_keeps_the_leading_dot_of_a_dotfile_directory():
    assert (
        join_relative("docs/index.md", "../.github/workflows/ci.yml") == ".github/workflows/ci.yml"
    )


def test_join_relative_keeps_parent_segments_that_escape_the_root():
    assert join_relative("docs/index.md", "../../other-repo/README.md") == "../other-repo/README.md"


def test_a_link_into_dotgithub_resolves_instead_of_reporting_drift():
    idx = _index(tree=TREE | {".github/workflows/ci.yml"})
    ref = DocReference(
        DriftKind.LINK,
        "../.github/workflows/ci.yml",
        "../.github/workflows/ci.yml",
        "docs/index.md",
        1,
        "ctx",
    )
    res = resolve(idx, ref)
    assert res.verdict is DriftVerdict.RESOLVED
    assert res.detail == "relative-to-doc"
    assert res.resolved_target == ".github/workflows/ci.yml"


def test_a_link_that_escapes_the_repository_root_is_uncheckable():
    ref = DocReference(
        DriftKind.LINK,
        "../../other-repo/README.md",
        "../../other-repo/README.md",
        "docs/index.md",
        1,
        "ctx",
    )
    res = resolve(_index(), ref)
    assert res.verdict is DriftVerdict.UNCHECKABLE
    assert res.detail == "unanchored"


# ---------------------------------------------------------------------------
# Anchors: rules 4 and 5
# ---------------------------------------------------------------------------


def _anchor_index(readme: str, tree=None):
    return RepoIndex.build(
        tracked_paths=tree or TREE,
        doc_text={"README.md": readme},
        manifest_text={},
    )


def _anchor_ref(fragment: str):
    return DocReference(
        DriftKind.ANCHOR, f"README.md#{fragment}", f"README.md#{fragment}",
        "docs/guide.md", 1, "ctx",
    )


def test_heading_anchor_resolves():
    idx = _anchor_index("## Start in minutes\n")
    assert resolve(idx, _anchor_ref("start-in-minutes")).verdict is DriftVerdict.RESOLVED


def test_renamed_heading_is_missing():
    """The class no linter catches: each document is internally valid and the
    target file exists. Only the pair is wrong."""
    idx = _anchor_index("## Start in minutes (no API key)\n")
    res = resolve(idx, _anchor_ref("quickstart-under-5-minutes-no-api-key"))
    assert res.verdict is DriftVerdict.MISSING
    assert res.origin == "anchor_no_heading"


@pytest.mark.parametrize("tag", ['<a id="code-health"></a>', "<a name='code-health'>"])
def test_explicit_html_anchors_are_link_targets(tag: str):
    """Rule 4. A declared target no heading slug reproduces.

    A heading-only checker calls every one of them broken; this was the single
    largest false-positive family in Phase 1's first run.
    """
    idx = _anchor_index(f"{tag}\n\n## Something Else\n")
    assert resolve(idx, _anchor_ref("code-health")).verdict is DriftVerdict.RESOLVED


def test_each_whitespace_character_becomes_its_own_dash():
    """Rule 5. ``SQL + dbt`` slugs to ``sql--dbt``, not ``sql-dbt``.

    Collapsing whitespace runs accounted for 70% of this class's findings in
    Phase 1's first run.
    """
    idx = _anchor_index("## SQL + dbt\n")
    assert resolve(idx, _anchor_ref("sql--dbt")).verdict is DriftVerdict.RESOLVED
    assert resolve(idx, _anchor_ref("sql-dbt")).verdict is DriftVerdict.MISSING


def test_repeated_headings_get_githubs_numbered_anchors():
    """GitHub names the second ``## Usage`` ``#usage-1`` and the third
    ``#usage-2``; only one more suffix than there are repeats exists."""
    idx = _anchor_index("## Usage\n\n## Usage\n\nUsage\n-----\n")
    for fragment in ("usage", "usage-1", "usage-2"):
        assert resolve(idx, _anchor_ref(fragment)).verdict is DriftVerdict.RESOLVED
    res = resolve(idx, _anchor_ref("usage-3"))
    assert res.verdict is DriftVerdict.MISSING
    assert res.origin == "anchor_no_heading"


def test_a_suffix_skips_a_slug_a_literal_heading_already_took():
    """``## Usage 1`` claims ``usage-1``, so the repeated ``## Usage`` after it
    becomes ``usage-2``, and a later repeat of ``## Usage 1`` becomes
    ``usage-1-1``. This is github-slugger's bookkeeping, not a naive count."""
    idx = _anchor_index("## Usage\n\n## Usage 1\n\n## Usage\n\n## Usage 1\n")
    anchors = idx.doc_anchors("README.md")
    assert {"usage", "usage-1", "usage-2", "usage-1-1"} <= anchors
    assert "usage-3" not in anchors


def test_anchor_into_a_missing_document_is_uncheckable_not_missing():
    """The LINK row already reports the missing file; saying it twice would
    double-count one defect."""
    idx = _anchor_index("## Heading\n")
    ref = DocReference(DriftKind.ANCHOR, "docs/gone.md#x", "docs/gone.md#x",
                       "docs/guide.md", 1, "ctx")
    assert resolve(idx, ref).verdict is DriftVerdict.UNCHECKABLE


# ---------------------------------------------------------------------------
# Commands
# ---------------------------------------------------------------------------


def test_make_target_resolves_and_missing_target_is_flagged():
    idx = _index(manifests={"Makefile": "build:\n\techo hi\ntest:\n\techo t\n"})
    ok = DocReference(DriftKind.COMMAND, "make build", "make:build", "docs/guide.md", 1, "c")
    bad = DocReference(DriftKind.COMMAND, "make gone", "make:gone", "docs/guide.md", 1, "c")
    assert resolve(idx, ok).verdict is DriftVerdict.RESOLVED
    assert resolve(idx, bad).verdict is DriftVerdict.MISSING


def test_make_variable_assignment_is_not_a_target():
    """``CC := gcc`` is an assignment, not a target."""
    idx = _index(manifests={"Makefile": "CC := gcc\nbuild:\n\techo hi\n"})
    ref = DocReference(DriftKind.COMMAND, "make CC", "make:CC", "docs/guide.md", 1, "c")
    assert resolve(idx, ref).verdict is DriftVerdict.MISSING


def test_commands_are_uncheckable_without_a_manifest():
    idx = _index(manifests={})
    ref = DocReference(DriftKind.COMMAND, "make build", "make:build", "docs/guide.md", 1, "c")
    assert resolve(idx, ref).verdict is DriftVerdict.UNCHECKABLE


def test_npm_script_resolves():
    idx = _index(manifests={"package.json": '{"scripts": {"build": "tsc"}}'})
    ok = DocReference(DriftKind.COMMAND, "npm run build", "npm:build", "docs/guide.md", 1, "c")
    assert resolve(idx, ok).verdict is DriftVerdict.RESOLVED


def test_malformed_package_json_does_not_crash():
    idx = _index(manifests={"package.json": "{not json"})
    ref = DocReference(DriftKind.COMMAND, "npm run build", "npm:build", "docs/guide.md", 1, "c")
    assert resolve(idx, ref).verdict is DriftVerdict.UNCHECKABLE


# ---------------------------------------------------------------------------
# The guide confidence tier
# ---------------------------------------------------------------------------


def test_guide_documents_drop_one_confidence_tier():
    """A tier, not an exclusion: a guide naming a real file that moved is
    still drift."""
    plain = resolve(_index(), _ref("src/util/gone.py"), is_guide=False)
    guide = resolve(_index(), _ref("src/util/gone.py"), is_guide=True)
    assert plain.verdict is guide.verdict is DriftVerdict.MISSING
    assert guide.confidence < plain.confidence


def test_only_missing_carries_confidence():
    for target in ("src/app.py", "CLAUDE.md", "src/helpers.py"):
        assert resolve(_index(), _ref(target)).confidence == 0.0


def test_end_to_end_on_a_small_document():
    """Extraction and resolution agree on a document mixing all four classes."""
    text = (
        "# Doc\n\n"
        "Real path `src/app.py`, gone path `src/util/gone.py`.\n"
        "Run `make build`. See [readme](README.md#heading).\n"
    )
    idx = RepoIndex.build(
        tracked_paths=TREE,
        doc_text={"README.md": "## Heading\n"},
        manifest_text={"Makefile": "build:\n\techo\n"},
    )
    verdicts = {
        (r.kind, resolve(idx, r).verdict) for r in extract(text, "docs/guide.md")
    }
    assert (DriftKind.PATH, DriftVerdict.RESOLVED) in verdicts
    assert (DriftKind.PATH, DriftVerdict.MISSING) in verdicts
    assert (DriftKind.COMMAND, DriftVerdict.RESOLVED) in verdicts
    assert (DriftKind.ANCHOR, DriftVerdict.RESOLVED) in verdicts


# ---------------------------------------------------------------------------
# The on-disk probe: present in the tree, absent from the index
# ---------------------------------------------------------------------------


def _probed_index(present: set[str], asked: list[str] | None = None) -> RepoIndex:
    def on_disk(rel: str) -> bool:
        if asked is not None:
            asked.append(rel)
        return rel in present

    return RepoIndex.build(TREE, {}, {}, on_disk=on_disk)


def test_unindexed_file_on_disk_is_uncheckable_not_missing():
    res = resolve(_probed_index({"src/util/fixture.py"}), _ref("src/util/fixture.py"))
    assert res.verdict is DriftVerdict.UNCHECKABLE
    assert res.detail == "outside-index"


def test_probe_that_finds_nothing_leaves_the_finding():
    res = resolve(_probed_index(set()), _ref("src/util/gone.py"))
    assert res.verdict is DriftVerdict.MISSING


def test_probe_is_asked_only_about_would_be_misses():
    asked: list[str] = []
    idx = _probed_index(set(), asked)
    resolve(idx, _ref("src/app.py"))
    resolve(idx, _ref("CLAUDE.md"))
    assert asked == []