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.4 KB
Raw Blame

Change review API

The Python API for reviewing one change.

Everything the MCP tools and the CLI know about a change is computed by repowise.core, and that core is importable on its own. This page is for a program that wants the whole review in one object, not a rendered response: a bot commenting on a pull request, a CI job gating a merge, an editor extension, a service that never has a checkout to score from.

Two things make that practical:

  • No checkout required. The engine reads revision content through a RevisionSource. There is a Git one and a byte-backed one, and the analysis cannot tell them apart.
  • No server. Nothing here imports repowise.server, an MCP registry, a response budget, FastAPI or a database session. A test enforces it.
from repowise.core.analysis.change_review import ChangeReviewRequest, ChangeReviewService
from repowise.core.analysis.change_health import GitRevisionSource

service = ChangeReviewService(GitRevisionSource("."), repo_path=".")
bundle = service.review(ChangeReviewRequest(revspec="HEAD"))

print(bundle.directive.status)    # review_required | review_recommended | ...
print(bundle.directive.headline)  # a plain sentence, no Markdown
for entry in bundle.manifest:
    print(entry.status, entry.path, entry.added_line_count)

Reviewing a change you have no checkout of

This is the case for a service that receives changes over an API: the bytes arrived from an API or an artifact, and there is no repository on disk. Build a RevisionPair describing the change, hand over both sides' content, and the rest is identical: same analyzers, same verdict.

from repowise.core.analysis.change_health import (
    FileChange,
    MappingRevisionSource,
    RevisionPair,
)
from repowise.core.analysis.changed_lines import parse_unified_diff
from repowise.core.analysis.change_review import ChangeReviewRequest, ChangeReviewService

# Whatever your source calls them. A deletion has no head_path; a rename has
# both, and they differ.
diffs = parse_unified_diff(unified_diff_text)
pair = RevisionPair(
    base_ref="main",
    head_ref="pull/42/head",
    base_sha=base_sha,
    head_sha=head_sha,
    working_tree=False,
    changes=[
        FileChange(
            head_path="app/service.py",
            base_path="app/service.py",
            status="modified",
            diff=diffs.get("app/service.py"),
        )
    ],
)

source = MappingRevisionSource(
    pair,
    base={"app/service.py": base_bytes},
    head={"app/service.py": head_bytes},
)

# No repo_path: there is no checkout, so the shape score is reported as unsupported,
# not wrong. Every lane that works from content still answers.
bundle = ChangeReviewService(source).review(ChangeReviewRequest())

FileChange carries a diff_status for providers that cannot always supply a usable patch: set it to truncated for a size-capped API page and binary for a blob. Without it, "no lines changed" and "we never saw the lines" look identical downstream, which is the one thing this type exists to prevent.


Reusing work across comparisons

The health comparison keeps each file's parse and complexity walk by content, so a file seen in an earlier comparison (the same base on a re-run, or the previous commit's head in a scan) is not parsed or walked again. With a checkout that has a .repowise directory the cache lives in .repowise/change_health/. Elsewhere there is none unless you name a writable directory, and the results are the same either way:

from repowise.core.analysis.change_health import ChangeHealthDeltaService

delta_service = ChangeHealthDeltaService(source, cache_dir="/tmp/repowise-cache")
bundle = ChangeReviewService(source, delta_service=delta_service).review(ChangeReviewRequest())

Evidence status: the part to read first

A lane that was never consulted and a lane that found nothing are different claims, and this API never collapses them. Every lane in bundle.lanes carries one of five states:

State Meaning Reading it as "fine" would be
available Computed. An empty population is a real answer. correct
partial Some of the requested scope was analysed. wrong: the change is not cleared
unavailable The data was required and could not be read. wrong: this is a failure
degraded Computation failed or fell back to something weaker. wrong
unsupported Nobody asked, or this provider cannot answer at all. wrong: nothing was checked
for name in bundle.degraded_lanes:
    state = bundle.lane(name)
    print(f"{name}: {state.state}: {state.reason}")

The distinction that matters most in practice: unavailable is not available with an empty list. A bug-fix record that could not be read must never render the way "these files have never broken" renders.


What a bundle carries

Lane Field Notes
manifest bundle.manifest Every counted path, its status, diff reliability and added line spans. The one counted universe: the request's extension and exclude filters are applied here, once.
risk bundle.risk Diff shape ranked against the repository's recent commits. Needs a checkout or a pre-scored result.
health bundle.health What the change newly made worse, each finding naming its attribution basis.
contracts bundle.contracts Changed symbols whose callers sit outside the change, split into test and production callers. A signature change carries signature_effect (compatible, breaking, unknown) and a signature_reason naming the parameter, judged from the indexed parameter list and return type only; a text-only change is not reported as one.
tests bundle.tests Impacted tests, measured coverage kept distinct from graph-inferred candidates.
prior_fixes via bundle.risk The bug-fix history the risk walk already read.
independent_changes bundle.independent_changes When the diff is several changes the index does not connect.
branch_overlap bundle.branch_overlap Other open branches editing the same files.

Populations are uncapped. Core returns everything and says how much there is; deciding how many rows to show is a surface's job, not core's.

bundle.directive is the verdict, its reasons and its next actions, as data: a status, a plain factual headline, and ReviewActions with stable fingerprints so a caller can tell a repeated action from a new one. It carries no Markdown, no URLs and no tool-call syntax, because two surfaces that render it differently still have to reach the same conclusion.


Supplying evidence the service will not fetch

The service is synchronous and fetches nothing that needs a database session, a network call or a snapshot artifact. A caller collects those and hands them over; the service decides what they mean. A caller that collects nothing still gets a bundle, with those lanes marked unsupported.

from repowise.core.analysis.change_review import ChangeReviewEvidence, ContractInputs

bundle = service.review(
    ChangeReviewRequest(revspec="HEAD"),
    evidence=ChangeReviewEvidence(
        # Run the comparison alongside your other work and pass the result in,
        # so a synchronous lane does not cost you that concurrency.
        health=precomputed_delta,
        tests=await analyze_test_impact(session, repo_id, changed_paths),
        contracts=ContractInputs(
            graph=graph, base_parsed=base_parsed, head_parsed=head_parsed,
            # True when the base side came from the last indexed snapshot,
            # not this change's real base.
            base_is_snapshot=True,
        ),
    ),
)

ChangeReviewEvidence(skip=frozenset({"risk"})) drops a lane you do not want the cost of. It is reported as unsupported, never as empty.


Serializing it

bundle.as_dict() is a stable, JSON-safe projection. It always emits every lane name as a key, so a reader never has to infer "absent" from a missing one, and it leads with contract_version:

payload = bundle.as_dict()
assert payload["contract_version"] == 1

CHANGE_REVIEW_CONTRACT_VERSION is bumped when a serialized bundle stops being readable by the previous reader. Adding a field does not bump it; removing or renaming one, or changing what an existing field means, does.


Related

  • The same evidence rendered for an agent: MCP_TOOLS.md
  • repowise risk for the terminal, which reports the change-shape score and the independent-change split.