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.

10.9 KB
Raw Blame
"""The owners summary, the knowledge matrix and the concentration they share.

All three read people, never automation: a bot's commits and owned files
leave every share, on both sides of the fraction.
"""

from __future__ import annotations

from datetime import UTC, datetime, timedelta

from repowise.core.analysis.knowledge_matrix import (
    build_knowledge_matrix,
    file_author_shares,
)
from repowise.core.analysis.owners import aggregate_owners, people_resolver
from repowise.core.analysis.owners_summary import build_owner_summary
from repowise.core.analysis.ownership_concentration import (
    module_silos,
    owned_files,
    person_owner,
    top_owners,
    truck_factor,
)
from repowise.core.stats_highlights import build_people

_HEAD = datetime(2026, 9, 1, tzinfo=UTC)
_BOT = ("dependabot[bot]", "49699333+dependabot[bot]@users.noreply.github.com")
_ADA = ("Ada Lovelace", "[email protected]")
_ADA_ALT = ("Ada Lovelace", "[email protected]")
_BOB = ("Bob Stone", "[email protected]")
_CY = ("Cy Young", "[email protected]")


def _author(who: tuple[str, str], commits: int) -> dict:
    return {"name": who[0], "email": who[1], "commit_count": commits}


def _row(
    path: str,
    owner: tuple[str, str],
    authors: list[dict],
    *,
    bus_factor: int = 1,
    hotspot: bool = False,
    changed_90d: int = 0,
) -> dict:
    return {
        "file_path": path,
        "primary_owner_name": owner[0],
        "primary_owner_email": owner[1],
        "top_authors_json": authors,
        "bus_factor": bus_factor,
        "is_hotspot": hotspot,
        "commit_count_90d": changed_90d,
    }


def _commit(sha: str, who: tuple[str, str], days_before_head: int) -> dict:
    return {
        "sha": sha,
        "author_name": who[0],
        "author_email": who[1],
        "committed_at": _HEAD - timedelta(days=days_before_head),
    }


# Ada owns the core (one file under her noreply address); Bob owns lib and
# has gone quiet while it still changes; Cy owns one file; the bot owns two.
ROWS = [
    _row("core/a.py", _ADA, [_author(_ADA, 8), _author(_BOT, 10), _author(_BOB, 2)], hotspot=True),
    _row("core/b.py", _ADA_ALT, [_author(_ADA_ALT, 3), _author(_ADA, 3)]),
    _row("core/c.py", _ADA, [_author(_ADA, 5), _author(_CY, 5)], bus_factor=2),
    _row("lib/x.py", _BOB, [_author(_BOB, 9), _author(_ADA, 1)], changed_90d=3),
    _row("lib/y.py", _BOB, [_author(_BOB, 4)], changed_90d=1, hotspot=True),
    _row("tools/t.py", _CY, [_author(_CY, 2)]),
    _row("deps/lock.py", _BOT, [_author(_BOT, 40)]),
    _row("deps/pin.py", _BOT, [_author(_BOT, 12)]),
]
COMMITS = [
    _commit("s1", _ADA, 1),
    _commit("s2", _ADA_ALT, 5),
    _commit("s3", _CY, 30),
    _commit("s4", _BOT, 2),
    _commit("s5", _BOB, 200),
]


def _fold():
    resolve = people_resolver(ROWS, COMMITS)
    accs, _ = aggregate_owners(ROWS, [], COMMITS, total_commits=len(COMMITS), resolve=resolve)
    return resolve, accs


# ---------------------------------------------------------------------------
# Concentration
# ---------------------------------------------------------------------------


def test_owned_files_counts_people_and_leaves_automation_out() -> None:
    owned = owned_files(ROWS, people_resolver(ROWS, COMMITS))
    assert dict(owned.by_owner) == {"[email protected]": 3, "[email protected]": 2, "[email protected]": 1}
    assert owned.owned_total == 6
    assert owned.single_owner_files == 5
    assert sum(owned.module_totals.values()) == len(ROWS)


def test_truck_factor_silos_and_top_owners() -> None:
    owned = owned_files(ROWS, people_resolver(ROWS, COMMITS))
    # Ada's 3 of 6 is not more than half; Ada and Bob are.
    assert truck_factor(owned) == 2
    assert [(s.module, s.owner, s.owned, s.file_count) for s in module_silos(owned)] == [
        ("core", "[email protected]", 3, 3),
        ("lib", "[email protected]", 2, 2),
        ("tools", "[email protected]", 1, 1),
    ]
    assert top_owners(owned, 2) == [("[email protected]", 3), ("[email protected]", 2)]
    assert truck_factor(owned_files([], people_resolver())) is None


def test_build_people_reads_the_shared_concentration() -> None:
    people = build_people(ROWS, COMMITS)
    assert people == {
        "owner_count": 3,
        "tracked_files": 8,
        "single_owner_files": 5,
        "silo_count": 3,
        "truck_factor": 2,
    }


# ---------------------------------------------------------------------------
# Identity on the owner fold
# ---------------------------------------------------------------------------


def test_owner_fold_carries_kind_and_merged_identities() -> None:
    _resolve, accs = _fold()
    ada = accs["[email protected]"]
    assert ada.kind == "human"
    assert ada.alias_names == ["Ada Lovelace"]
    assert ada.alias_emails == ["[email protected]", "[email protected]"]
    bot = next(a for a in accs.values() if a.name.startswith("dependabot"))
    assert bot.kind == "bot"
    assert accs["[email protected]"].owned_changing_files == 2


# ---------------------------------------------------------------------------
# Summary
# ---------------------------------------------------------------------------


def test_summary_is_people_only() -> None:
    resolve, accs = _fold()
    summary = build_owner_summary(ROWS, resolve, accs)

    assert summary["truck_factor"] == build_people(ROWS, COMMITS)["truck_factor"] == 2
    assert (summary["people"], summary["automation_identities"]) == (3, 1)
    assert (summary["owned_files"], summary["tracked_files"]) == (6, 8)
    assert summary["single_owner_files"] == 5
    assert summary["single_owner_hotspots"] == 2

    concentration = summary["concentration"]
    # The bot's two files are in neither the numerator nor the denominator.
    assert concentration["share"] == 1.0
    assert [o["key"] for o in concentration["owners"]] == [
        "[email protected]",
        "[email protected]",
        "[email protected]",
    ]
    assert concentration["owners"][0]["share"] == 0.5
    assert [s["module"] for s in summary["silo_modules"]] == ["core", "lib", "tools"]
    assert summary["silo_modules"][0]["owner"] == {"key": "[email protected]", "name": "Ada Lovelace"}


def test_summary_activity_and_quiet_owners() -> None:
    resolve, accs = _fold()
    summary = build_owner_summary(ROWS, resolve, accs)
    assert summary["activity_complete"] is True
    # Ada and Cy committed in the window; the bot is not a person.
    assert summary["active_contributors"] == 2
    # Bob's last commit is 200 days old and he owns two files that still change.
    assert summary["quiet_owners_total"] == 1
    quiet = summary["quiet_owners"][0]
    assert (quiet["key"], quiet["changing_files_owned"], quiet["files_owned"]) == (
        "[email protected]",
        2,
        2,
    )


def test_summary_without_commit_rows_names_nobody_quiet() -> None:
    resolve = people_resolver(ROWS)
    accs, _ = aggregate_owners(ROWS, [], resolve=resolve)
    summary = build_owner_summary(ROWS, resolve, accs)
    assert summary["activity_complete"] is False
    assert summary["active_contributors"] == 0
    assert summary["quiet_owners"] == []


# ---------------------------------------------------------------------------
# Knowledge matrix
# ---------------------------------------------------------------------------


def test_file_author_shares_merge_people_and_drop_automation() -> None:
    resolve = people_resolver(ROWS, COMMITS)
    # 10 of core/a.py's 20 commits are the bot's: Ada holds 8 of the 10 human ones.
    assert file_author_shares(ROWS[0], resolve) == [
        ("[email protected]", 0.8),
        ("[email protected]", 0.2),
    ]
    # Ada's two addresses are one author holding the whole file.
    assert file_author_shares(ROWS[1], resolve) == [("[email protected]", 1.0)]
    assert file_author_shares(ROWS[6], resolve) == []
    assert person_owner(ROWS[1], resolve) == "[email protected]"
    assert person_owner(ROWS[6], resolve) is None


def test_file_author_shares_keep_the_top_n() -> None:
    people = [(f"Person {i}", f"p{i}@example.com") for i in range(7)]
    row = _row("x.py", people[0], [_author(p, 10 - i) for i, p in enumerate(people)])
    shares = file_author_shares(row, people_resolver([row]), top=5)
    assert [k for k, _ in shares] == [f"p{i}@example.com" for i in range(5)]
    assert round(sum(s for _, s in shares), 6) == round(40 / 49, 6)


def test_knowledge_matrix_rows_are_positional_and_indexed() -> None:
    resolve, accs = _fold()
    matrix = build_knowledge_matrix(
        ROWS, resolve, accs, {"core/a.py": (6.234, 120), "lib/x.py": (None, 40)}
    )
    authors = [a["key"] for a in matrix["authors"]]
    # Indexed by how many files each person appears on, most first.
    assert authors == ["[email protected]", "[email protected]", "[email protected]"]
    assert matrix["authors"][0]["active"] is True
    assert matrix["authors"][1]["active"] is False

    files = {
        (matrix["dirs"][row[0]] + "/" if matrix["dirs"][row[0]] else "") + row[1]: row
        for row in matrix["files"]
    }
    assert list(files) == sorted(r["file_path"] for r in ROWS)
    assert files["core/a.py"][:8] == (0, "a.py", 120, 6.2, True, 1, 0, [(0, 0.8), (1, 0.2)])
    assert files["lib/x.py"][2:4] == (40, None)
    # A bot-owned file keeps its row, with no owner and no authors.
    assert files["deps/lock.py"][6:8] == (None, [])
    # The last element says whether the file changed in the activity window.
    assert {path: row[8] for path, row in files.items()} == {
        r["file_path"]: (r.get("commit_count_90d") or 0) > 0 for r in ROWS
    }


def test_an_email_only_owner_owns_files_on_every_surface() -> None:
    rows = [_row("a.py", ("", "[email protected]"), [_author(("", "[email protected]"), 3)])]
    resolve = people_resolver(rows)
    accs, _ = aggregate_owners(rows, [], resolve=resolve)
    assert accs["[email protected]"].files_owned == 1
    assert dict(owned_files(rows, resolve).by_owner) == {"[email protected]": 1}
    assert person_owner(rows[0], resolve) == "[email protected]"


def test_a_file_without_history_is_not_a_single_owner_risk() -> None:
    rows = [*ROWS, _row("core/new.py", _ADA, [], bus_factor=0)]
    resolve = people_resolver(rows, COMMITS)
    accs, _ = aggregate_owners(rows, [], COMMITS, len(COMMITS), resolve)
    ada = accs["[email protected]"]
    # a.py and b.py have bus factor 1; c.py has 2 and new.py has none indexed.
    assert (ada.files_owned, ada.bus_factor_risk_files) == (4, 2)
    assert build_owner_summary(rows, resolve, accs)["single_owner_files"] == 5


def test_automation_and_unowned_files_are_not_single_owner_risks() -> None:
    rows = [
        *ROWS,
        _row("deps/hot.py", _BOT, [_author(_BOT, 30)], hotspot=True),
        _row("gen/out.py", ("", ""), [], hotspot=True),
    ]
    resolve = people_resolver(rows, COMMITS)
    accs, _ = aggregate_owners(rows, [], COMMITS, len(COMMITS), resolve)
    owned = owned_files(rows, resolve)
    assert (owned.single_owner_files, owned.single_owner_hotspots) == (5, 2)
    summary = build_owner_summary(rows, resolve, accs)
    assert (summary["single_owner_files"], summary["single_owner_hotspots"]) == (5, 2)