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.

perf(update): fold lifetime churn onto an anchor instead of re-walking history (#1379)

Raghav Chamadiya30ea3093649c
diff --git a/packages/core/alembic/versions/0049_churn_anchor.py b/packages/core/alembic/versions/0049_churn_anchor.py
new file mode 100644
index 000000000..8017e8e4c
--- /dev/null
+++ b/packages/core/alembic/versions/0049_churn_anchor.py
@@ -0,0 +1,51 @@
+"""Anchor lifetime churn so an update folds instead of re-walking the history.
+
+``repositories.total_lines_added`` / ``total_lines_deleted`` (0043) were
+recomputed on every update by ``git log --shortstat`` over the entire history —
+the one O(history) call on the update path, 2.1s on a 2.2k-commit checkout and
+growing linearly with age, to move a total by one commit's worth of lines.
+
+``churn_anchor_sha`` records the commit those totals were computed at, so the
+next capture can add only ``anchor..HEAD``. It is written only alongside a churn
+figure, and only believed when the next capture re-proves both that it is still
+an ancestor of HEAD (rebase, force-push, branch swap) and that
+``prior_count + count(anchor..HEAD)`` equals the current commit count (a shallow
+clone that has since been deepened keeps the anchor an ancestor while adding
+history *below* it). Either check failing falls back to the full walk, so the
+stored totals can go stale only by being recomputed correctly.
+
+NULL on every index written before this, which costs one full walk and then
+anchors itself.
+
+``init_db``'s additive schema reconciler picks the column up from the model for
+local SQLite stores that never run Alembic; this migration covers the managed
+Postgres ones.
+
+Revision ID: 0049
+Revises: 0048
+Create Date: 2026-08-10
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+
+import sqlalchemy as sa
+from alembic import op
+
+# revision identifiers
+revision: str = "0049"
+down_revision: str | None = "0048"
+branch_labels: str | Sequence[str] | None = None
+depends_on: str | Sequence[str] | None = None
+
+
+def upgrade() -> None:
+ op.add_column(
+ "repositories",
+ sa.Column("churn_anchor_sha", sa.String(length=40), nullable=True),
+ )
+
+
+def downgrade() -> None:
+ op.drop_column("repositories", "churn_anchor_sha")
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/indexer.py b/packages/core/src/repowise/core/ingestion/git_indexer/indexer.py
index ca4298876..abbaac44b 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/indexer.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/indexer.py
@@ -790,13 +790,17 @@ class GitIndexer:
record_git_episodes(self.repo_path, walk)
- def capture_repo_totals(self) -> Any:
+ def capture_repo_totals(self, prior: Any = None) -> Any:
"""Whole-history :class:`RepoTotals` for this repo (opens its own repo).
The incremental counterpart to the capture ``index_repo`` runs inline:
``repowise update`` calls this so true project age / commit / contributor
counts stay fresh between full re-indexes. Returns an all-``None``
``RepoTotals`` when git is unavailable rather than raising.
+
+ *prior* is the previously stored ``RepoTotals``; it only lets lifetime
+ churn resume from its anchor rather than re-walk the history. ``None``
+ (the default, and what a full index passes) forces the whole walk.
"""
from .records import RepoTotals
@@ -804,7 +808,7 @@ class GitIndexer:
if repo is None:
return RepoTotals()
try:
- return capture_repo_totals(repo)
+ return capture_repo_totals(repo, prior)
finally:
with contextlib.suppress(Exception):
repo.close()
diff --git a/packages/core/src/repowise/core/ingestion/git_indexer/records.py b/packages/core/src/repowise/core/ingestion/git_indexer/records.py
index b64265d2d..b3e013742 100644
--- a/packages/core/src/repowise/core/ingestion/git_indexer/records.py
+++ b/packages/core/src/repowise/core/ingestion/git_indexer/records.py
@@ -85,11 +85,20 @@ def _tz_offset_minutes(iso: str) -> int | None:
"""Minutes east of UTC for a git ``%cI`` timestamp, or ``None``.
Only the offset is kept — the instant itself already rides on ``%ct``. Git
- always emits a numeric offset (never a name), so the tail is ``±HH:MM``.
+ never emits a zone *name*, so the tail is either ``±HH:MM`` or a bare ``Z``:
+ ``%cI`` is strict ISO 8601, which spells a zero offset ``Z`` rather than
+ ``+00:00``. Reading ``Z`` as unparseable is not a cosmetic miss — it makes
+ every commit authored at UTC (CI bots, the GitHub web editor) indistinguishable
+ from one indexed before the column existed, so the backfill in
+ ``pipeline.incremental.reconcile_commit_offsets`` re-selects and re-looks-up
+ the same commits on every update and never converges.
+
Parsed by hand rather than via ``fromisoformat`` because this runs once per
commit on every index and the string shape is fixed.
"""
iso = iso.strip()
+ if iso.endswith("Z"):
+ return 0
if len(iso) < 6:
return None
sign, hh, mm = iso[-6], iso[-5:-3], iso[-2:]
@@ -234,6 +243,13 @@ class RepoTotals:
first_commit_subject: str | None = None
total_lines_added: int | None = None
total_lines_deleted: int | None = None
+ # The commit the churn totals above were computed at. Carried back out so the
+ # caller can store it, and passed back in on the next capture so the walk can
+ # start there instead of at the root. Set only when the churn walk actually
+ # produced numbers, so the anchor can never advance past the totals it
+ # anchors. Doubles as this capture's *prior* record — see
+ # :func:`capture_repo_totals`.
+ churn_anchor_sha: str | None = None
# Lifetime churn walks every commit's shortstat, so unlike the other totals it
@@ -243,25 +259,36 @@ class RepoTotals:
# to pay for the walk.
_CHURN_COMMIT_CEILING = 50_000
+# How many commits a folded total may ride before the walk is redone from the
+# root. Folding assumes a past commit's churn is fixed, and it is not: ``git log
+# --shortstat`` resolves diff attributes from the *working tree*, so committing
+# ``*.min.js -diff`` retroactively changes what every historical commit touching
+# those paths contributed. Nothing in the commit graph moves, so no ancestry or
+# count check can see it — and without a re-walk the wrong total becomes the next
+# fold's base and the error grows forever. Re-anchoring on a fixed stride bounds
+# the drift instead of trying to enumerate its causes (``git replace`` and an
+# uncommitted ``.gitattributes`` edit do the same thing by different routes).
+#
+# Ceiling: the bound is in commits, not in time, so a repo that stops receiving
+# commits keeps a drifted total until it gets some or is re-indexed. Amortised
+# cost is one full walk per stride — on a 9.3k-commit repo, 13.3s spread over 100
+# updates rather than 13.3s on every one.
+_CHURN_REANCHOR_STRIDE = 100
+
# ``git log --shortstat`` summary line, e.g.
# " 3 files changed, 41 insertions(+), 9 deletions(-)". Either half can be absent.
_SHORTSTAT_RE = re.compile(r"(\d+) insertions?\(\+\)|(\d+) deletions?\(-\)")
-def _lifetime_churn(repo: Any, commit_count: int | None) -> tuple[int | None, int | None]:
- """Total lines ever added / deleted across the whole history.
-
- One ``git log --shortstat`` pass, summed here. The per-commit ``git_commits``
- table cannot answer this: it is bounded to the newest N commits, so summing
- it silently understates a repo with more history than the window.
+def _walk_churn(repo: Any, rev: str) -> tuple[int | None, int | None]:
+ """Sum ``git log --shortstat`` over *rev*, or ``(None, None)`` if git failed.
- Skipped above :data:`_CHURN_COMMIT_CEILING` commits — returns ``(None, None)``
- so the caller stores nothing and the UI omits the figure.
+ *rev* is either a single commit (the whole history reachable from it) or a
+ ``a..b`` range. Merge commits contribute nothing either way — ``git log``
+ shows no diff for them without ``-m`` — so the two forms compose exactly.
"""
- if commit_count is None or commit_count > _CHURN_COMMIT_CEILING:
- return None, None
try:
- out = repo.git.log("--shortstat", "--pretty=tformat:", "HEAD")
+ out = repo.git.log("--shortstat", "--pretty=tformat:", rev)
except Exception:
return None, None
added = deleted = 0
@@ -273,20 +300,139 @@ def _lifetime_churn(repo: Any, commit_count: int | None) -> tuple[int | None, in
return added, deleted
-def capture_repo_totals(repo: Any) -> RepoTotals:
+def _folded_churn(
+ repo: Any, commit_count: int, head_sha: str | None, prior: RepoTotals | None
+) -> tuple[int, int] | None:
+ """Lifetime churn as *prior* plus only the commits it has not seen.
+
+ ``None`` means the fold is not safe here and the caller must walk the whole
+ history.
+
+ Three things have to hold, and the third is the one that keeps the other two
+ honest.
+
+ *The commit set may only have grown at the top.* That is
+ ``prior_count + count(anchor..head) == count(head)``. Writing *shared* for
+ the commits both reach and *dropped* for those only the anchor reaches,
+ ``count(anchor..head) == count(head) - shared`` and
+ ``prior_count == shared + dropped``, so the two sides differ by exactly
+ *dropped* — plus anything fetched *below* the anchor since, which inflates
+ the anchor's true reach past the stored ``prior_count``. The equality
+ therefore holds only when nothing was dropped and nothing appeared
+ underneath: a rebase, a force-push, a branch swap and an ``--unshallow``
+ all break it. That is why the check is on counts and not just on ancestry.
+
+ *The anchor is still an ancestor.* ``merge-base --is-ancestor`` runs first
+ because it is cheaper than the count, it rejects an anchor whose object git
+ can no longer resolve, and it keeps the fold from depending on a stored
+ count being right about a history it no longer describes.
+
+ *The stored total has not ridden too long.* Neither check above can see the
+ one way a fold goes wrong without the commit graph moving at all: churn is
+ not a function of the commit set. See :data:`_CHURN_REANCHOR_STRIDE`.
+
+ All three fail closed: any git error falls back to the full walk.
+ """
+ if prior is None or not prior.churn_anchor_sha:
+ return None
+ # No resolved HEAD means the caller is working from the bare name, which is
+ # not a range endpoint worth trusting and would leave totals moving while
+ # the anchor stayed put.
+ if not head_sha:
+ return None
+ if (
+ prior.total_lines_added is None
+ or prior.total_lines_deleted is None
+ or prior.total_commit_count is None
+ ):
+ return None
+
+ # An unmoved HEAD is deliberately *not* short-circuited here. It is the one
+ # shape where history can change underneath a still-valid anchor without the
+ # anchor moving — deepening a shallow clone — and the count check below is
+ # what catches that. The empty range costs one no-op ``git log``.
+ anchor = prior.churn_anchor_sha
+ try:
+ # Raises (non-zero exit) when the anchor is not an ancestor, which is
+ # the answer we want rather than an error.
+ repo.git.merge_base("--is-ancestor", anchor, head_sha)
+ since_count = int(repo.git.rev_list("--count", f"{anchor}..{head_sha}").strip())
+ except Exception:
+ return None
+
+ if prior.total_commit_count + since_count != commit_count:
+ return None
+ if (
+ prior.total_commit_count // _CHURN_REANCHOR_STRIDE
+ != commit_count // _CHURN_REANCHOR_STRIDE
+ ):
+ return None
+
+ added, deleted = _walk_churn(repo, f"{anchor}..{head_sha}")
+ if added is None or deleted is None:
+ return None
+ return prior.total_lines_added + added, prior.total_lines_deleted + deleted
+
+
+def _lifetime_churn(
+ repo: Any, commit_count: int | None, rev: str, head_sha: str | None, prior: RepoTotals | None
+) -> tuple[int | None, int | None]:
+ """Total lines ever added / deleted across the whole history.
+
+ ``git log --shortstat`` over the whole history, which is the one O(history)
+ call in the capture — 2.1s on a 2.2k-commit checkout, and it ran on every
+ update to recompute a total that had moved by one commit's worth. So when
+ *prior* carries a usable anchor the walk is folded instead: the stored total
+ plus the range since that anchor (see :func:`_folded_churn`). A full walk
+ stays the fallback for every case where the fold cannot be proven safe, for
+ the first capture on a repo that has no anchor yet, and on a fixed commit
+ stride so that a total which drifted for a reason no check can see is
+ corrected rather than compounded.
+
+ *rev* is what a full walk covers (a resolved sha, or the bare name ``HEAD``
+ when it would not resolve); *head_sha* is the resolved sha alone, and its
+ absence is what stops the fold from using a name as a range endpoint.
+
+ The per-commit ``git_commits`` table cannot answer this: it is bounded to the
+ newest N commits, so summing it silently understates a repo with more history
+ than the window.
+
+ Skipped above :data:`_CHURN_COMMIT_CEILING` commits — returns ``(None, None)``
+ so the caller stores nothing and the UI omits the figure.
+ """
+ if commit_count is None or commit_count > _CHURN_COMMIT_CEILING:
+ return None, None
+ folded = _folded_churn(repo, commit_count, head_sha, prior)
+ if folded is not None:
+ return folded
+ return _walk_churn(repo, rev)
+
+
+def capture_repo_totals(repo: Any, prior: RepoTotals | None = None) -> RepoTotals:
"""Whole-history stats for *repo* via a handful of cheap git calls.
+ *prior* is the last capture's own return value, read back from storage. It
+ is used for one thing: letting lifetime churn start from the commit it was
+ last computed at instead of from the root (see :func:`_folded_churn`). Pass
+ ``None`` — as a full index does — to force the whole-history walk.
+
+ Every call is pinned to a single resolved HEAD sha rather than to the name
+ ``HEAD``, so a commit landing mid-capture cannot leave the count describing
+ one history and the churn another. (It can still leave the *stored* pair
+ describing a HEAD that has since moved; that is what the next capture's
+ count reconciliation is for.)
+
The first three git calls are O(1) in subprocess count and independent of
the indexer's ``commit_limit``, so they stay cheap no matter how deep the
history is:
- - ``git rev-list --count HEAD`` — the true total commit count.
+ - ``git rev-list --count`` — the true total commit count.
- the root commit(s) — earliest committed date (project age), the founding
author's name, and that commit's subject. Multiple roots (merged
histories) use the earliest root.
- - ``git shortlog -sn HEAD`` — one line per mailmap-folded author, so its
- line count is the true all-time contributor count. Passing ``HEAD``
- keeps shortlog from blocking on stdin.
+ - ``git shortlog -sn`` — one line per mailmap-folded author, so its line
+ count is the true all-time contributor count. It is passed a revision
+ (rather than left to read stdin, which would block).
Lifetime churn is the one exception: it walks the history, so it is capped
(see :func:`_lifetime_churn`).
@@ -296,11 +442,18 @@ def capture_repo_totals(repo: Any) -> RepoTotals:
"""
totals = RepoTotals()
+ head_sha: str | None = None
+ with contextlib.suppress(Exception):
+ head_sha = repo.head.commit.hexsha
+ # An unresolvable HEAD (unborn, no repo) leaves every call below on the name,
+ # exactly as before; the anchor is simply not stored for such a capture.
+ rev = head_sha or "HEAD"
+
with contextlib.suppress(Exception):
- totals.total_commit_count = int(repo.git.rev_list("--count", "HEAD").strip())
+ totals.total_commit_count = int(repo.git.rev_list("--count", rev).strip())
try:
- roots = repo.git.rev_list("--max-parents=0", "HEAD").split()
+ roots = repo.git.rev_list("--max-parents=0", rev).split()
root_commits = [repo.commit(sha) for sha in roots if sha]
if root_commits:
oldest = min(root_commits, key=lambda c: c.committed_datetime)
@@ -319,14 +472,19 @@ def capture_repo_totals(repo: Any) -> RepoTotals:
pass
try:
- out = repo.git.shortlog("-sn", "HEAD")
+ out = repo.git.shortlog("-sn", rev)
totals.total_contributor_count = sum(1 for line in out.splitlines() if line.strip())
except Exception:
pass
totals.total_lines_added, totals.total_lines_deleted = _lifetime_churn(
- repo, totals.total_commit_count
+ repo, totals.total_commit_count, rev, head_sha, prior
)
+ # Only a capture that produced churn gets to move the anchor. Storing one for
+ # a skipped or failed walk would leave the next fold adding a range onto
+ # totals that never covered its start.
+ if head_sha and totals.total_lines_added is not None:
+ totals.churn_anchor_sha = head_sha
return totals
diff --git a/packages/core/src/repowise/core/persistence/crud/repository.py b/packages/core/src/repowise/core/persistence/crud/repository.py
index 361024ff3..ba3c33ca3 100644
--- a/packages/core/src/repowise/core/persistence/crud/repository.py
+++ b/packages/core/src/repowise/core/persistence/crud/repository.py
@@ -139,6 +139,7 @@ async def update_repo_git_totals(
first_commit_subject: str | None = None,
total_lines_added: int | None = None,
total_lines_deleted: int | None = None,
+ churn_anchor_sha: str | None = None,
) -> None:
"""Store a repo's whole-history git totals, captured at index time (#730).
@@ -156,6 +157,11 @@ async def update_repo_git_totals(
"first_commit_subject": first_commit_subject,
"total_lines_added": total_lines_added,
"total_lines_deleted": total_lines_deleted,
+ # Rides with the churn pair by construction: the capture sets it only
+ # when the walk produced numbers, so "applied only when non-None" keeps
+ # anchor and totals moving together rather than letting one advance
+ # past the other.
+ "churn_anchor_sha": churn_anchor_sha,
}
if all(v is None for v in updates.values()):
return
diff --git a/packages/core/src/repowise/core/persistence/models.py b/packages/core/src/repowise/core/persistence/models.py
index 171be1c2d..09f450db6 100644
--- a/packages/core/src/repowise/core/persistence/models.py
+++ b/packages/core/src/repowise/core/persistence/models.py
@@ -70,6 +70,14 @@ class Repository(Base):
first_commit_subject: Mapped[str | None] = mapped_column(Text, nullable=True)
total_lines_added: Mapped[int | None] = mapped_column(Integer, nullable=True)
total_lines_deleted: Mapped[int | None] = mapped_column(Integer, nullable=True)
+ # The commit the two churn totals above were computed at, so the next capture
+ # can add the range since it instead of re-walking the whole history (the
+ # walk was the single most expensive git call on the update path). Written
+ # only together with a churn figure, and only trusted after the next capture
+ # re-proves it is still an ancestor of HEAD and that the commit counts
+ # reconcile. NULL on indexes written before this, which just means the next
+ # capture walks once and anchors itself.
+ churn_anchor_sha: Mapped[str | None] = mapped_column(String(40), nullable=True)
settings_json: Mapped[str] = mapped_column(Text, nullable=False, default="{}")
created_at: Mapped[datetime] = mapped_column(
DateTime(timezone=True), nullable=False, default=_now_utc
diff --git a/packages/core/src/repowise/core/pipeline/incremental.py b/packages/core/src/repowise/core/pipeline/incremental.py
index c8eaeeca5..776a8b6c1 100644
--- a/packages/core/src/repowise/core/pipeline/incremental.py
+++ b/packages/core/src/repowise/core/pipeline/incremental.py
@@ -573,6 +573,7 @@ async def persist_incremental_commits(session: Any, repo_id: str, repo_path: Any
from repowise.core.ingestion.git_indexer import GitIndexer
from repowise.core.persistence.crud import (
get_latest_commit_committed_at,
+ get_repository,
update_repo_git_totals,
upsert_git_commits_bulk,
)
@@ -610,8 +611,12 @@ async def persist_incremental_commits(session: Any, repo_id: str, repo_path: Any
# Refresh the repo-level whole-history totals so age / commit / contributor
# counts keep growing between full re-indexes (#730). Cheap git calls, and
- # cheap to run every update since they don't touch the bounded sample.
- totals = await asyncio.to_thread(indexer.capture_repo_totals)
+ # cheap to run every update since they don't touch the bounded sample —
+ # except lifetime churn, which walks the history. Handing the capture what
+ # was stored last time lets it add only the range since, and it re-proves
+ # that range is safe to add before doing so.
+ prior = _churn_prior(await get_repository(session, repo_id))
+ totals = await asyncio.to_thread(indexer.capture_repo_totals, prior)
await update_repo_git_totals(
session,
repo_id,
@@ -622,11 +627,35 @@ async def persist_incremental_commits(session: Any, repo_id: str, repo_path: Any
first_commit_subject=totals.first_commit_subject,
total_lines_added=totals.total_lines_added,
total_lines_deleted=totals.total_lines_deleted,
+ churn_anchor_sha=totals.churn_anchor_sha,
)
await persist_incremental_fix_events(session, repo_id, indexer)
+def _churn_prior(repo_row: Any) -> Any:
+ """The stored totals lifetime churn can resume from, or ``None``.
+
+ Only the four fields the fold reads are carried across, so this never
+ becomes a second way to read repo-level git facts. ``None`` for a repo row
+ that is missing or has no anchor yet, which makes the capture walk the whole
+ history exactly as it always did.
+ """
+ from repowise.core.ingestion.git_indexer.records import RepoTotals
+
+ if repo_row is None:
+ return None
+ anchor = getattr(repo_row, "churn_anchor_sha", None)
+ if not anchor:
+ return None
+ return RepoTotals(
+ total_commit_count=repo_row.total_commit_count,
+ total_lines_added=repo_row.total_lines_added,
+ total_lines_deleted=repo_row.total_lines_deleted,
+ churn_anchor_sha=anchor,
+ )
+
+
async def reconcile_commit_experience(session: Any, repo_id: str, indexer: Any) -> None:
"""Re-tally author experience across the whole commit table and re-score.
diff --git a/packages/core/src/repowise/core/pipeline/persist.py b/packages/core/src/repowise/core/pipeline/persist.py
index 523f26a5f..fb5446481 100644
--- a/packages/core/src/repowise/core/pipeline/persist.py
+++ b/packages/core/src/repowise/core/pipeline/persist.py
@@ -1431,6 +1431,7 @@ async def persist_git(result: Any, session: Any, repo_id: str) -> None:
first_commit_subject=totals.first_commit_subject,
total_lines_added=totals.total_lines_added,
total_lines_deleted=totals.total_lines_deleted,
+ churn_anchor_sha=getattr(totals, "churn_anchor_sha", None),
)
diff --git a/tests/unit/ingestion/test_repo_totals_churn.py b/tests/unit/ingestion/test_repo_totals_churn.py
new file mode 100644
index 000000000..f672b536a
--- /dev/null
+++ b/tests/unit/ingestion/test_repo_totals_churn.py
@@ -0,0 +1,406 @@
+"""Lifetime churn folds onto its anchor, and refuses to when that is unsafe.
+
+``capture_repo_totals`` used to re-walk the whole history on every update to
+recompute a total that had moved by one commit. It now resumes from the commit
+the last capture recorded. The property every test here asserts is the same
+one: **a folded capture equals a from-scratch capture, byte for byte.** The
+interesting cases are the histories where folding would be wrong, and each of
+those has to fall back rather than produce a plausible number.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import os
+import subprocess
+
+import pytest
+
+from repowise.core.ingestion.git_indexer.records import (
+ _CHURN_REANCHOR_STRIDE as _STRIDE,
+)
+from repowise.core.ingestion.git_indexer.records import (
+ RepoTotals,
+ _tz_offset_minutes,
+ capture_repo_totals,
+)
+
+
+def _git(path, *args: str) -> str:
+ out = subprocess.run(
+ ["git", *args],
+ cwd=str(path),
+ capture_output=True,
+ text=True,
+ encoding="utf-8",
+ check=True,
+ )
+ return out.stdout.strip()
+
+
+def _init(path):
+ import git as gitpython
+
+ repo = gitpython.Repo.init(path)
+ repo.config_writer().set_value("user", "name", "Ada Lovelace").release()
+ repo.config_writer().set_value("user", "email", "[email protected]").release()
+ return repo
+
+
+def _commit(repo, path, name: str, content: str) -> None:
+ (path / name).write_text(content, encoding="utf-8")
+ repo.index.add([name])
+ repo.index.commit(f"feat: {name} -> {len(content)}")
+
+
+def _churn(totals: RepoTotals) -> tuple[int | None, int | None]:
+ return totals.total_lines_added, totals.total_lines_deleted
+
+
+def _fresh(repo) -> RepoTotals:
+ """A capture with no prior: the whole-history walk, i.e. the ground truth."""
+ return capture_repo_totals(repo)
+
+
+# ---------------------------------------------------------------------------
+# The fold itself
+# ---------------------------------------------------------------------------
+
+
+def test_folded_capture_equals_a_full_recapture(tmp_path) -> None:
+ repo = _init(tmp_path)
+ _commit(repo, tmp_path, "a.py", "x = 1\n")
+ _commit(repo, tmp_path, "b.py", "y = 2\ny = 3\n")
+
+ first = capture_repo_totals(repo)
+ assert first.churn_anchor_sha == repo.head.commit.hexsha
+ assert _churn(first) == (3, 0)
+
+ _commit(repo, tmp_path, "c.py", "z = 4\nz = 5\nz = 6\n")
+ (tmp_path / "a.py").write_text("", encoding="utf-8")
+ repo.index.add(["a.py"])
+ repo.index.commit("chore: empty a")
+
+ folded = capture_repo_totals(repo, first)
+ assert folded == _fresh(repo)
+ assert _churn(folded) == (6, 1)
+ assert folded.churn_anchor_sha == repo.head.commit.hexsha
+
+
+def test_an_unmoved_head_re_affirms_the_stored_pair(tmp_path) -> None:
+ """The no-op update: same HEAD, no range to walk, same answer."""
+ repo = _init(tmp_path)
+ _commit(repo, tmp_path, "a.py", "x = 1\n")
+
+ first = capture_repo_totals(repo)
+ assert capture_repo_totals(repo, first) == _fresh(repo)
+
+
+class _SpyGit:
+ """Records the rev every ``--shortstat`` log is asked for, passes the rest on.
+
+ A wrapper rather than a monkeypatch: GitPython's ``Git`` dispatches command
+ names through ``__getattr__`` over ``__slots__``, so there is no ``log``
+ attribute to replace.
+ """
+
+ def __init__(self, git, revs: list[str]) -> None:
+ self._git, self._revs = git, revs
+
+ def log(self, *args, **kwargs):
+ if "--shortstat" in args:
+ self._revs.append(args[-1])
+ return self._git.log(*args, **kwargs)
+
+ def __getattr__(self, name):
+ return getattr(self._git, name)
+
+
+class _SpyRepo:
+ def __init__(self, repo, revs: list[str]) -> None:
+ self._repo = repo
+ self.git = _SpyGit(repo.git, revs)
+
+ def __getattr__(self, name):
+ return getattr(self._repo, name)
+
+
+def test_a_fold_never_runs_the_whole_history_walk(tmp_path) -> None:
+ """Pins the point of the change: the second capture must not walk from root.
+
+ Without this, every assertion above still passes on an implementation that
+ quietly re-walks and ignores the anchor.
+ """
+ repo = _init(tmp_path)
+ _commit(repo, tmp_path, "a.py", "x = 1\n")
+ first = capture_repo_totals(repo)
+ _commit(repo, tmp_path, "b.py", "y = 2\n")
+
+ revs: list[str] = []
+ capture_repo_totals(_SpyRepo(repo, revs), first)
+
+ assert revs == [f"{first.churn_anchor_sha}..{repo.head.commit.hexsha}"]
+
+
+# ---------------------------------------------------------------------------
+# The histories where folding would be wrong
+# ---------------------------------------------------------------------------
+
+
+def test_a_rewritten_history_falls_back_to_the_full_walk(tmp_path) -> None:
+ """The anchor stops being an ancestor: rebase, force-push, branch swap."""
+ repo = _init(tmp_path)
+ _commit(repo, tmp_path, "a.py", "x = 1\n")
+ _commit(repo, tmp_path, "b.py", "y = 2\ny = 3\n")
+ keep = repo.head.commit.hexsha
+ _commit(repo, tmp_path, "c.py", "z = 4\nz = 5\nz = 6\nz = 7\n")
+
+ anchored = capture_repo_totals(repo)
+ assert _churn(anchored) == (7, 0)
+
+ # Drop the anchored commit and build a different one in its place.
+ _git(tmp_path, "reset", "--hard", keep)
+ _commit(repo, tmp_path, "d.py", "w = 8\n")
+
+ folded = capture_repo_totals(repo, anchored)
+ truth = _fresh(repo)
+ assert folded == truth
+ # The whole point: 4 added, not the 8 a blind fold would have reported.
+ assert _churn(folded) == (4, 0)
+
+
+def test_a_rebased_branch_in_the_history_falls_back(tmp_path) -> None:
+ """A real rebase, then more work on top of it.
+
+ The acceptance case for the phase: the anchor was captured on the pre-rebase
+ history, so the fold must refuse, and the refusal must land on the same
+ numbers a from-scratch capture produces.
+ """
+ repo = _init(tmp_path)
+ _commit(repo, tmp_path, "base.py", "b = 1\n")
+ base = repo.head.commit.hexsha
+ _commit(repo, tmp_path, "main1.py", "m = 1\nm = 2\n")
+
+ _git(tmp_path, "checkout", "-q", "-b", "feature", base)
+ _commit(repo, tmp_path, "feat1.py", "f = 1\nf = 2\nf = 3\n")
+
+ anchored = capture_repo_totals(repo) # anchored on the pre-rebase feature tip
+ assert _churn(anchored) == (4, 0)
+
+ _git(tmp_path, "rebase", "-q", "master")
+ revs: list[str] = []
+ folded = capture_repo_totals(_SpyRepo(repo, revs), anchored)
+
+ assert folded == _fresh(repo)
+ assert _churn(folded) == (6, 0)
+ # Asserting only the number would pass on an implementation that never
+ # folds at all. This asserts the *refusal*: a walk from the root, not a
+ # range off the stale anchor.
+ assert revs == [repo.head.commit.hexsha]
+
+ # And the capture after the rebase is a usable anchor again.
+ _commit(repo, tmp_path, "feat2.py", "g = 1\n")
+ assert capture_repo_totals(repo, folded) == _fresh(repo)
+
+
+def test_deepening_a_shallow_clone_falls_back_to_the_full_walk(tmp_path) -> None:
+ """The case only the commit-count check can see.
+
+ The anchor stays a perfectly good ancestor of HEAD and ``anchor..HEAD`` does
+ not change; what changed is the history *underneath* it. An ancestry check
+ alone would fold and drop the newly fetched churn silently, forever.
+ """
+ origin = tmp_path / "origin"
+ origin.mkdir()
+ repo = _init(origin)
+ # The middle commit *rewrites* a line, so lifetime churn (which counts every
+ # commit's diff) and the shallow tip's single diff-against-nothing disagree.
+ # Without that they coincide and the test proves nothing.
+ _commit(repo, origin, "a.py", "x = 1\nx = 2\nx = 3\n")
+ _commit(repo, origin, "a.py", "x = 1\nx = 9\nx = 3\n")
+ _commit(repo, origin, "c.py", "z = 1\n")
+
+ clone = tmp_path / "clone"
+ subprocess.run(
+ ["git", "clone", "-q", "--depth", "1", "file://" + str(origin).replace("\\", "/"), str(clone)],
+ capture_output=True,
+ text=True,
+ check=True,
+ )
+
+ import git as gitpython
+
+ shallow = gitpython.Repo(clone)
+ anchored = capture_repo_totals(shallow)
+ # Only the fetched tip is visible, and it diffs against nothing, so
+ # "lifetime" churn is the whole tree at one commit deep.
+ assert anchored.total_commit_count == 1
+ assert _churn(anchored) == (4, 0)
+
+ _git(clone, "fetch", "-q", "--unshallow")
+ revs: list[str] = []
+ folded = capture_repo_totals(_SpyRepo(shallow, revs), anchored)
+
+ assert revs == [shallow.head.commit.hexsha] # refused, not folded
+ assert folded == _fresh(shallow)
+ assert folded.total_commit_count == 3
+ # HEAD never moved, so a fold that trusted ancestry alone would still be
+ # reporting the shallow tip's 4.
+ assert _churn(folded) == (5, 1)
+ shallow.close()
+ repo.close()
+
+
+def test_a_skipped_churn_walk_stores_no_anchor(tmp_path, monkeypatch) -> None:
+ """Above the ceiling there is no churn figure, so there must be no anchor.
+
+ An anchor written without the totals it anchors is the one way this can go
+ quietly wrong: the next capture would add a range onto a base that never
+ covered its start.
+ """
+ monkeypatch.setattr(
+ "repowise.core.ingestion.git_indexer.records._CHURN_COMMIT_CEILING", 0
+ )
+ repo = _init(tmp_path)
+ _commit(repo, tmp_path, "a.py", "x = 1\n")
+
+ totals = capture_repo_totals(repo)
+ assert _churn(totals) == (None, None)
+ assert totals.churn_anchor_sha is None
+
+
+def test_a_prior_without_churn_totals_is_not_folded(tmp_path) -> None:
+ """A hand-edited or half-written row must not be treated as a base."""
+ repo = _init(tmp_path)
+ _commit(repo, tmp_path, "a.py", "x = 1\nx = 2\n")
+ head = repo.head.commit.hexsha
+
+ for broken in (
+ RepoTotals(total_commit_count=1, total_lines_added=None, churn_anchor_sha=head),
+ RepoTotals(total_commit_count=None, total_lines_added=99, total_lines_deleted=0,
+ churn_anchor_sha=head),
+ RepoTotals(total_commit_count=1, total_lines_added=99, total_lines_deleted=0),
+ ):
+ assert capture_repo_totals(repo, broken) == _fresh(repo)
+
+
+def test_a_retroactive_gitattributes_change_is_corrected_by_the_stride(tmp_path) -> None:
+ """The failure no ancestry or count check can see, and its bound.
+
+ ``git log --shortstat`` resolves diff attributes from the working tree, so
+ committing ``gen.min.js -diff`` retroactively changes what an *already
+ anchored* commit contributed. The commit graph does not move, the counts
+ still reconcile, and a fold therefore reports a number that is not just
+ wrong but becomes the next fold's base. Only the periodic re-walk recovers.
+ """
+ repo = _init(tmp_path)
+ (tmp_path / "gen.min.js").write_text("a\nb\nc\nd\ne\n", encoding="utf-8")
+ repo.index.add(["gen.min.js"])
+ repo.index.commit("feat: generated")
+ _commit(repo, tmp_path, "b.txt", "x\n")
+
+ anchored = capture_repo_totals(repo)
+ assert _churn(anchored) == (6, 0)
+
+ (tmp_path / ".gitattributes").write_text("gen.min.js -diff\n", encoding="utf-8")
+ repo.index.add([".gitattributes"])
+ repo.index.commit("chore: stop diffing the bundle")
+
+ drifted = capture_repo_totals(repo, anchored)
+ truth = _fresh(repo)
+ assert _churn(truth) == (2, 0)
+ assert _churn(drifted) == (7, 0), "documents the drift the stride exists to bound"
+
+ # Crossing the stride boundary re-walks and lands on the truth again.
+ assert capture_repo_totals(
+ repo, dataclasses.replace(drifted, total_commit_count=_STRIDE - 1)
+ ) == truth
+
+
+def test_the_stride_is_the_only_thing_that_re_anchors_a_clean_history(tmp_path) -> None:
+ """Pins the stride's trigger, so it cannot be tuned away by accident."""
+ repo = _init(tmp_path)
+ _commit(repo, tmp_path, "a.py", "x = 1\n")
+ first = capture_repo_totals(repo)
+ _commit(repo, tmp_path, "b.py", "y = 2\n")
+
+ revs: list[str] = []
+ capture_repo_totals(_SpyRepo(repo, revs), first)
+ assert revs == [f"{first.churn_anchor_sha}..{repo.head.commit.hexsha}"]
+
+ # Same history, but the stored count sits just under a stride boundary.
+ revs.clear()
+ capture_repo_totals(
+ _SpyRepo(repo, revs), dataclasses.replace(first, total_commit_count=_STRIDE - 1)
+ )
+ assert revs == [repo.head.commit.hexsha]
+
+
+def test_an_unresolvable_head_never_folds(tmp_path) -> None:
+ """A capture that could not resolve HEAD must not fold against the name.
+
+ It stores no anchor, so folding would let the totals advance while the
+ anchor stayed where it was — the one direction the write rule cannot catch.
+ """
+ repo = _init(tmp_path)
+ _commit(repo, tmp_path, "a.py", "x = 1\nx = 2\n")
+ anchored = capture_repo_totals(repo)
+
+ class _NoHead(_SpyRepo):
+ @property
+ def head(self):
+ raise ValueError("unborn")
+
+ revs: list[str] = []
+ totals = capture_repo_totals(_NoHead(repo, revs), anchored)
+ assert revs == ["HEAD"]
+ assert totals.churn_anchor_sha is None
+
+
+# ---------------------------------------------------------------------------
+# The offset that never converged
+# ---------------------------------------------------------------------------
+
+
+ ("iso", "expected"),
+ [
+ ("2026-05-29T16:54:14Z", 0),
+ ("2026-05-29T17:54:14+02:00", 120),
+ ("2026-05-29T11:54:14-05:00", -300),
+ ("2026-05-29T16:54:14", None),
+ ("", None),
+ ],
+)
+def test_tz_offset_reads_gits_utc_form(iso: str, expected: int | None) -> None:
+ """``%cI`` is strict ISO 8601, which spells a zero offset ``Z``.
+
+ Reading that as unparseable left every UTC commit's offset NULL, which is
+ the same state as "indexed before the column existed" — so the update-time
+ backfill re-selected and re-looked-up the same commits on every run and
+ never converged.
+ """
+ assert _tz_offset_minutes(iso) == expected
+
+
+def test_a_utc_commit_captures_an_offset(tmp_path) -> None:
+ """End to end through the real capture, not just the parser."""
+ from repowise.core.ingestion.git_indexer import GitIndexer
+
+ repo = _init(tmp_path)
+ env = {"GIT_AUTHOR_DATE": "2026-01-02T03:04:05+0000",
+ "GIT_COMMITTER_DATE": "2026-01-02T03:04:05+0000"}
+ (tmp_path / "a.py").write_text("x = 1\n", encoding="utf-8")
+ repo.index.add(["a.py"])
+ subprocess.run(
+ ["git", "commit", "-q", "-m", "feat: a"],
+ cwd=str(tmp_path),
+ capture_output=True,
+ text=True,
+ env={**os.environ, **env},
+ check=True,
+ )
+ sha = repo.head.commit.hexsha
+
+ offsets = GitIndexer(tmp_path).capture_commit_offsets([sha])
+ assert offsets == {sha: 0}
diff --git a/tests/unit/persistence/test_churn_anchor_roundtrip.py b/tests/unit/persistence/test_churn_anchor_roundtrip.py
new file mode 100644
index 000000000..dc6d48c20
--- /dev/null
+++ b/tests/unit/persistence/test_churn_anchor_roundtrip.py
@@ -0,0 +1,82 @@
+"""The churn anchor survives the round trip through the ``repositories`` row.
+
+The rest of the fold is covered against real git repositories in
+``tests/unit/ingestion/test_repo_totals_churn.py``. Those tests call
+``capture_repo_totals`` directly, so every one of them still passes if the
+anchor never reaches storage or never comes back — and the whole point of the
+change is a git walk that stops happening on the update path. This is the wiring
+in between: ``update_repo_git_totals`` writes it, ``_churn_prior`` reads it back
+into the shape the capture expects.
+"""
+
+from __future__ import annotations
+
+import pytest
+
+from repowise.core.persistence.crud import get_repository, update_repo_git_totals
+from repowise.core.pipeline.incremental import _churn_prior
+from tests.unit.persistence.helpers import insert_repo
+
+_SHA = "a" * 40
+
+
+async def test_totals_round_trip_into_a_usable_prior(async_session) -> None:
+ repo = await insert_repo(async_session)
+
+ await update_repo_git_totals(
+ async_session,
+ repo.id,
+ total_commit_count=2218,
+ total_lines_added=651587,
+ total_lines_deleted=273403,
+ churn_anchor_sha=_SHA,
+ )
+
+ prior = _churn_prior(await get_repository(async_session, repo.id))
+ assert prior is not None
+ assert prior.churn_anchor_sha == _SHA
+ assert prior.total_commit_count == 2218
+ assert (prior.total_lines_added, prior.total_lines_deleted) == (651587, 273403)
+
+
+async def test_a_repo_with_no_anchor_yet_has_no_prior(async_session) -> None:
+ """Every index written before the column existed takes this path: it walks
+ the whole history once and anchors itself."""
+ repo = await insert_repo(async_session)
+ await update_repo_git_totals(
+ async_session, repo.id, total_commit_count=10, total_lines_added=5
+ )
+
+ assert _churn_prior(await get_repository(async_session, repo.id)) is None
+ assert _churn_prior(None) is None
+
+
+async def test_a_capture_that_skipped_churn_leaves_the_stored_pair_alone(
+ async_session,
+) -> None:
+ """The write rule the fold's safety rests on.
+
+ A capture above the commit ceiling, or one whose git call failed, returns
+ ``None`` for churn *and* for the anchor. Neither may be blanked, and — the
+ part that matters — the anchor must not be able to move on its own.
+ """
+ repo = await insert_repo(async_session)
+ await update_repo_git_totals(
+ async_session,
+ repo.id,
+ total_commit_count=100,
+ total_lines_added=900,
+ total_lines_deleted=100,
+ churn_anchor_sha=_SHA,
+ )
+
+ # The shape a skipped churn walk produces: a fresh count, no churn, no anchor.
+ await update_repo_git_totals(async_session, repo.id, total_commit_count=140)
+
+ row = await get_repository(async_session, repo.id)
+ assert row.total_commit_count == 140
+ assert (row.total_lines_added, row.total_lines_deleted) == (900, 100)
+ assert row.churn_anchor_sha == _SHA