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.

8.6 KB
Raw Blame
"""Folder-specific documentation floors (issue #633).

Raghav's spec: a floor, not a cap. ``((glob, pct), ...)`` rules promise at
least ``pct`` of the code files under each glob get a file_page, whatever
their global importance score, unioned additively into the selection so the
cost table stays truthful about what the user asked for.

Key property pinned here: a folder pinned at 1.0 gets full file-page
coverage even when its files score below the global cutoff (and therefore
below the cap the folder rule must override).
"""

from __future__ import annotations

from dataclasses import dataclass, field

from repowise.core.generation.models import GenerationConfig
from repowise.core.generation.selection import SelectionInputs, select_pages


@dataclass
class _FakeFileInfo:
    path: str
    language: str = "python"
    abs_path: str = ""
    size_bytes: int = 5_000
    is_test: bool = False
    is_config: bool = False
    is_api_contract: bool = False
    is_entry_point: bool = False
    git_hash: str = ""

    def __post_init__(self) -> None:
        if not self.abs_path:
            self.abs_path = f"/repo/{self.path}"


@dataclass
class _FakeSymbol:
    name: str
    qualified_name: str = ""
    kind: str = "function"
    visibility: str = "public"
    signature: str = "()"
    docstring: str | None = None
    decorators: list[str] = field(default_factory=list)
    is_async: bool = False
    complexity_estimate: int = 1
    parent_name: str | None = None

    def __post_init__(self) -> None:
        if not self.qualified_name:
            self.qualified_name = self.name


@dataclass
class _FakeParsedFile:
    file_info: _FakeFileInfo
    symbols: list[_FakeSymbol] = field(default_factory=list)
    imports: list[object] = field(default_factory=list)
    exports: list[str] = field(default_factory=list)
    docstring: str | None = None
    parse_errors: list[str] = field(default_factory=list)


def _build_synthetic_repo(
    n_files: int,
) -> tuple[list[_FakeParsedFile], dict[str, float], dict[str, float], dict[str, int]]:
    """PageRank tapers linearly (top 1.0, bottom ~0.01); every 25 files share
    a ``pkg{i//25}`` prefix. Each file carries three public symbols so it
    clears the score floor (same shape as test_selection_contract's fixture)."""
    parsed: list[_FakeParsedFile] = []
    pagerank: dict[str, float] = {}
    betweenness: dict[str, float] = {}
    community: dict[str, int] = {}
    for i in range(n_files):
        path = f"pkg{i // 25}/module_{i}.py"
        syms = [
            _FakeSymbol(name=f"func_{i}_{k}", qualified_name=f"module_{i}.func_{i}_{k}")
            for k in range(3)
        ]
        parsed.append(_FakeParsedFile(file_info=_FakeFileInfo(path=path), symbols=syms))
        pagerank[path] = 1.0 - (i / max(1, n_files - 1)) * 0.99
        betweenness[path] = 0.0
        community[path] = i // 25
    return parsed, pagerank, betweenness, community


def _inputs(parsed, pagerank, betweenness, community, cfg):
    return SelectionInputs(
        parsed_files=parsed,
        pagerank=pagerank,
        betweenness=betweenness,
        community=community,
        community_info=None,
        sccs=[],
        git_meta_map=None,
        config=cfg,
    )


def test_folder_pinned_at_1_0_covers_every_code_file_under_the_glob() -> None:
    """Files below the global cutoff must still be pinnable (the floor)."""
    parsed, pagerank, betweenness, community = _build_synthetic_repo(50)
    # Force a tight global cap so most files fall outside it.
    cfg = GenerationConfig(max_file_pages=10, folder_coverage=(("pkg0", 1.0),))
    sel = select_pages(_inputs(parsed, pagerank, betweenness, community, cfg))

    assert len(sel.file_page_paths) >= 10  # global pick remains
    # pkg0 holds files 0..24 (i // 25 == 0); all of them must be present.
    pinned = {p for p in sel.file_page_paths if p.startswith("pkg0/")}
    all_pkg0 = {p.file_info.path for p in parsed if p.file_info.path.startswith("pkg0/")}
    assert pinned == all_pkg0, (
        "a 1.0 folder floor must pin every code file under the glob, "
        "including those below the global cutoff"
    )


def test_folder_floor_is_additive_not_displacing() -> None:
    """The union never removes a global pick — the floor only adds pages."""
    parsed, pagerank, betweenness, community = _build_synthetic_repo(50)
    cfg = GenerationConfig(max_file_pages=10, folder_coverage=(("pkg0", 1.0),))
    sel = select_pages(_inputs(parsed, pagerank, betweenness, community, cfg))

    unpinned = select_pages(
        _inputs(parsed, pagerank, betweenness, community, GenerationConfig(max_file_pages=10))
    )
    global_picks = set(unpinned.file_page_paths)
    assert global_picks <= set(sel.file_page_paths), (
        "folder pins must be additive — global picks stay select()ed"
    )


def test_partial_folder_floor_takes_ceil_pct_highest_scored() -> None:
    parsed, pagerank, betweenness, community = _build_synthetic_repo(80)
    cfg = GenerationConfig(max_file_pages=5, folder_coverage=(("pkg1", 0.5),))
    sel = select_pages(_inputs(parsed, pagerank, betweenness, community, cfg))

    # pkg1 holds files 25..49 (i // 25 == 1) → 25 files, half = ceil(12.5) = 13.
    pkg1 = {p.file_info.path for p in parsed if p.file_info.path.startswith("pkg1/")}
    got = {p for p in sel.file_page_paths if p in pkg1}
    assert len(got) == 13

    # The pinned 13 must be the highest-scored of pkg1 (PageRank tapers, so
    # the top 13 by pagerank, tie-broken by path).
    ranked = sorted(pkg1, key=lambda p: (-pagerank[p], p))
    assert got == set(ranked[:13])


def test_empty_rules_and_zero_pct_are_no_ops() -> None:
    parsed, pagerank, betweenness, community = _build_synthetic_repo(30)
    cfg = GenerationConfig(
        max_file_pages=5, folder_coverage=(("pkg0", 0.0), ("no/such/dir", 1.0))
    )
    sel = select_pages(_inputs(parsed, pagerank, betweenness, community, cfg))
    unpinned = select_pages(
        _inputs(parsed, pagerank, betweenness, community, GenerationConfig(max_file_pages=5))
    )
    assert sel.file_page_paths == unpinned.file_page_paths


def test_folder_rule_glob_shape_matches_subtree() -> None:
    """``src/core`` (no glob metachars) matches the dir and everything under it."""
    parsed, pagerank, betweenness, community = _build_synthetic_repo(30)
    # Rename a slice of the synthetic repo into a subtree.
    for p in parsed:
        if p.file_info.path.startswith("pkg1/"):
            p.file_info.path = "src/core/" + p.file_info.path.removeprefix("pkg1/")
    pagerank = {("src/core/" + k.removeprefix("pkg1/")) if k.startswith("pkg1/") else k: v for k, v in pagerank.items()}

    cfg = GenerationConfig(max_file_pages=5, folder_coverage=(("src/core", 1.0),))
    sel = select_pages(_inputs(parsed, pagerank, betweenness, community, cfg))

    under_core = {p.file_info.path for p in parsed if p.file_info.path.startswith("src/core/")}
    got = {p for p in sel.file_page_paths if p.startswith("src/core/")}
    assert got == under_core


def test_config_yaml_parse_accepts_glob_equals_pct_strings() -> None:
    cfg = GenerationConfig.from_repo_config(
        {"folder_coverage": ["src/core=1.0", 'src/other="0.5"']}
    )
    assert cfg.folder_coverage == (("src/core", 1.0), ("src/other", 0.5))


def test_config_yaml_parse_rejects_bad_rules() -> None:
    import pytest

    with pytest.raises(ValueError, match="folder_coverage must be a list"):
        GenerationConfig.from_repo_config({"folder_coverage": "src/core=1.0"})
    with pytest.raises(ValueError, match="not a number"):
        GenerationConfig.from_repo_config({"folder_coverage": ["src/core=high"]})
    with pytest.raises(ValueError, match=r"pct must be in \[0, 1\]"):
        GenerationConfig.from_repo_config({"folder_coverage": ["src/core=1.5"]})


def test_overlapping_rules_pin_each_file_once_and_report_per_folder() -> None:
    parsed, pagerank, betweenness, community = _build_synthetic_repo(50)
    cfg = GenerationConfig(
        max_file_pages=5, folder_coverage=(("pkg0", 1.0), ("pkg0/*", 1.0), ("pkg1", 0.5))
    )
    sel = select_pages(_inputs(parsed, pagerank, betweenness, community, cfg))

    assert len(sel.file_page_paths) == len(set(sel.file_page_paths))
    assert sel.folder_coverage == [("pkg0", 25, 25), ("pkg0/*", 25, 25), ("pkg1", 13, 25)]


def test_parse_accepts_dot_slash_and_pairs_and_rejects_nan() -> None:
    import pytest

    from repowise.core.generation.folder_coverage import parse_folder_coverage

    assert parse_folder_coverage(["./src/core=1"]) == (("src/core", 1.0),)
    assert parse_folder_coverage([("src/core", 0.5)]) == (("src/core", 0.5),)
    with pytest.raises(ValueError, match=r"pct must be in \[0, 1\]"):
        parse_folder_coverage(["src/core=nan"])