Codebase intelligence for AI and humans: code health scores, auto-generated docs, git analytics, dead code detection, and architectural decisions via MCP.
Python aicode-complexitycode-healthcode-intelligencecode-qualitydead-codedeveloper-toolsdocumentationgit-analyticsmcpopen-sourcepythonrefactoringstatic-analysistechnical-debt
"""CI renderings: markdown summary, GitHub annotations, SARIF, GitLab Code Quality."""
from __future__ import annotations
import json
from repowise.core.analysis.doc_drift.constants import DETECTION_BASIS
from repowise.core.analysis.doc_drift.gate import evaluate_gate
from repowise.core.analysis.doc_drift.render import (
SARIF_FINGERPRINT_KEY,
render_github_annotations,
render_gitlab,
render_markdown,
render_sarif,
)
from repowise.core.analysis.doc_drift.serialize import derive_doc_drift_fingerprint
from repowise.core.ci.github import ANNOTATION_LIMIT
from repowise.core.ci.markdown import ROW_LIMIT
def _f(
target: str,
confidence: float = 0.9,
*,
doc: str = "docs/a.md",
line: int = 3,
kind: str = "path",
reason: str | None = None,
suggestion: str = "",
) -> dict:
out = {
"file_path": doc,
"line_number": line,
"kind": kind,
"target": target,
"confidence": confidence,
"origin": "path_no_candidate",
"reason": reason or f"Document names {target}, which no longer exists.",
"raw": target,
"context": "",
}
if suggestion:
out["suggestion"] = suggestion
out["suggestion_basis"] = "package_split"
return out
# -- markdown ---------------------------------------------------------------
def test_passing_markdown_is_short_and_says_so():
findings = [_f("a.py", 0.5)]
md = render_markdown(findings, gate=evaluate_gate(findings), documents_scanned=4)
assert md.startswith("**No documentation drift at or above 0.70.**")
assert "|" not in md
assert "4 documents scanned" in md and "1 below the threshold" in md
assert DETECTION_BASIS in md
def test_failing_markdown_verdict_first_then_table():
findings = [_f("b.py", doc="docs/z.md"), _f("a.py", line=9), _f("c.py", 0.4)]
md = render_markdown(findings, gate=evaluate_gate(findings), suppressed=2)
first = md.splitlines()[0]
assert first.startswith("**Documentation drift: 2 findings fail the gate**")
assert "document" in first.lower()
assert "2 references suppressed inline" in md
rows = [line for line in md.splitlines() if line.startswith("| docs/")]
# Grouped by document, and the below-threshold finding stays out.
assert rows[0].startswith("| docs/a.md:9 ") and rows[1].startswith("| docs/z.md:3 ")
assert len(rows) == 2
def test_markdown_escapes_cells_and_shows_suggestion():
findings = [_f("a|b`c.py", suggestion="pkg/a/")]
md = render_markdown(findings, gate=evaluate_gate(findings))
row = next(line for line in md.splitlines() if line.startswith("| docs/"))
assert "a\\|b\\`c.py" in row
assert "| pkg/a/ |" in row
def test_markdown_caps_rows():
findings = [_f(f"f{i:02}.py", line=i + 1) for i in range(ROW_LIMIT + 5)]
md = render_markdown(findings, gate=evaluate_gate(findings))
rows = [line for line in md.splitlines() if line.startswith("| docs/")]
assert len(rows) == ROW_LIMIT
assert "and 5 more findings." in md
def test_markdown_without_gate_lists_everything():
assert render_markdown([], gate=None).startswith("**No documentation drift found.**")
md = render_markdown([_f("a.py", 0.4)], gate=None)
assert md.startswith("**Documentation drift: 1 finding.**")
assert "| docs/a.md:3 " in md
def test_markdown_reports_baselined_count():
findings = [_f("a.py")]
fp = derive_doc_drift_fingerprint("docs/a.md", "path", "a.py")
md = render_markdown(findings, gate=evaluate_gate(findings, baseline=frozenset({fp})))
assert md.startswith("**No documentation drift")
assert "1 accepted by the baseline" in md
# -- annotations ------------------------------------------------------------
def test_annotations_errors_first_and_escaped():
findings = [
_f("low.py", 0.4, doc="docs/a.md"),
_f("x.py", reason="50% broken\nnext", doc="docs/a,b:c.md", line=7, suggestion="y/"),
]
lines = render_github_annotations(findings, gate=evaluate_gate(findings))
assert lines[0] == (
"::error file=docs/a%2Cb%3Ac.md,line=7,title=Doc drift (path)"
"::50%25 broken%0Anext Likely now: y/."
)
assert lines[1].startswith("::warning file=docs/a.md,line=3,")
assert len(lines) == 2
def test_baselined_findings_are_not_annotated():
findings = [_f("a.py")]
fp = derive_doc_drift_fingerprint("docs/a.md", "path", "a.py")
assert render_github_annotations(
findings, gate=evaluate_gate(findings, baseline=frozenset({fp}))
) == []
def test_annotations_are_capped_with_errors_kept_and_the_overflow_counted():
findings = [_f(f"w{i}.py", 0.4, line=i + 1) for i in range(60)]
findings.append(_f("err.py", doc="docs/z.md"))
lines = render_github_annotations(findings, gate=evaluate_gate(findings))
assert len(lines) == ANNOTATION_LIMIT + 1
assert lines[0].startswith("::error ")
assert lines[-1].startswith("::notice::51 more documentation drift findings")
# -- SARIF ------------------------------------------------------------------
def test_sarif_required_fields():
findings = [_f("a.py", suggestion="pkg/a/"), _f("R.md#x", 0.5, kind="anchor")]
sarif = render_sarif(findings, tool_version="1.2.3")
assert sarif["$schema"] == "https://json.schemastore.org/sarif-2.1.0.json"
assert sarif["version"] == "2.1.0"
(run,) = sarif["runs"]
driver = run["tool"]["driver"]
assert driver["name"] == "repowise-doc-drift"
assert driver["version"] == "1.2.3"
assert driver["informationUri"] == "https://repowise.dev"
assert [r["id"] for r in driver["rules"]] == ["path", "link", "anchor", "command", "symbol"]
assert all(DETECTION_BASIS in r["fullDescription"]["text"] for r in driver["rules"])
by_rule = {r["ruleId"]: r for r in run["results"]}
path = by_rule["path"]
assert path["level"] == "error"
assert path["message"]["text"].endswith("Likely now: pkg/a/.")
loc = path["locations"][0]["physicalLocation"]
assert loc["artifactLocation"] == {"uri": "docs/a.md", "uriBaseId": "%SRCROOT%"}
assert loc["region"] == {"startLine": 3}
assert path["partialFingerprints"] == {
SARIF_FINGERPRINT_KEY: derive_doc_drift_fingerprint("docs/a.md", "path", "a.py")
}
assert path["properties"]["suggestion"] == "pkg/a/"
assert by_rule["anchor"]["level"] == "warning"
assert "suggestion" not in by_rule["anchor"]["properties"]
def test_sarif_level_follows_fail_on_and_uri_is_percent_encoded():
findings = [_f("a.py", 0.5, doc="docs/my notes#1.md")]
(result,) = render_sarif(findings, tool_version="x", fail_on=0.4)["runs"][0]["results"]
assert result["level"] == "error"
uri = result["locations"][0]["physicalLocation"]["artifactLocation"]["uri"]
assert uri == "docs/my%20notes%231.md"
(default,) = render_sarif(findings, tool_version="x")["runs"][0]["results"]
assert default["level"] == "warning"
def test_sarif_is_deterministic():
findings = [_f("b.py", doc="docs/z.md"), _f("a.py"), _f("c.py", line=1)]
one = json.dumps(render_sarif(findings, tool_version="x"), sort_keys=True)
two = json.dumps(render_sarif(list(reversed(findings)), tool_version="x"), sort_keys=True)
assert one == two
uris = [
(r["locations"][0]["physicalLocation"]["artifactLocation"]["uri"],
r["locations"][0]["physicalLocation"]["region"]["startLine"])
for r in render_sarif(findings, tool_version="x")["runs"][0]["results"]
]
assert uris == [("docs/a.md", 1), ("docs/a.md", 3), ("docs/z.md", 3)]
# -- GitLab Code Quality ------------------------------------------------------
def test_gitlab_severity_follows_the_gate_and_drops_the_baseline():
accepted = _f("gone.py")
findings = [_f("a.py", suggestion="pkg/a/"), _f("R.md#x", 0.5, kind="anchor"), accepted]
fp = derive_doc_drift_fingerprint("docs/a.md", "path", "gone.py")
issues = render_gitlab(findings, accepted=frozenset({fp}))
assert issues == [
{
"description": "Document names R.md#x, which no longer exists.",
"check_name": "repowise-doc-drift/anchor",
"fingerprint": derive_doc_drift_fingerprint("docs/a.md", "anchor", "R.md#x"),
"severity": "minor",
"location": {"path": "docs/a.md", "lines": {"begin": 3}},
},
{
"description": "Document names a.py, which no longer exists. Likely now: `pkg/a/`",
"check_name": "repowise-doc-drift/path",
"fingerprint": derive_doc_drift_fingerprint("docs/a.md", "path", "a.py"),
"severity": "major",
"location": {"path": "docs/a.md", "lines": {"begin": 3}},
},
]
(lowered,) = render_gitlab([_f("R.md#x", 0.5, kind="anchor")], fail_on=0.4)
assert lowered["severity"] == "major"
def test_gitlab_is_deterministic_and_unique():
findings = [_f("b.py", doc="docs/z.md"), _f("a.py"), _f("a.py", line=9)]
one = render_gitlab(findings)
assert one == render_gitlab(list(reversed(findings)))
fps = [i["fingerprint"] for i in one]
assert len(set(fps)) == 3 and fps[1] == fps[0] + ":2"
# -- placed suggestions -----------------------------------------------------
def _placed(**kw) -> dict:
out = _f("a.py", suggestion="pkg/a/", **kw)
out["suggested_line"] = "See `pkg/a/` here."
out["suggestion_columns"] = [[6, 10]]
return out
def _symbol(suggestion: str, line: str, spans: list) -> dict:
out = _f("Loader.parse_config", kind="symbol", suggestion=suggestion)
out["suggestion_basis"] = "symbol_rename"
out["suggested_line"] = line
out["suggestion_columns"] = spans
return out
def test_sarif_declares_utf16_columns():
(run,) = render_sarif([_placed()], tool_version="x")["runs"]
assert run["columnKind"] == "utf16CodeUnits"
def test_sarif_carries_a_fix_on_the_exact_span():
(result,) = render_sarif([_placed()], tool_version="x")["runs"][0]["results"]
(fix,) = result["fixes"]
(change,) = fix["artifactChanges"]
assert change["artifactLocation"] == {"uri": "docs/a.md", "uriBaseId": "%SRCROOT%"}
(replacement,) = change["replacements"]
assert replacement == {
"deletedRegion": {"startLine": 3, "startColumn": 6, "endLine": 3, "endColumn": 10},
"insertedContent": {"text": "pkg/a/"},
}
assert fix["description"]["text"] == "Replace with pkg/a/"
def test_sarif_replaces_every_copy_of_a_repeated_token():
finding = _symbol(
"Loader.parse_conf()", "`Loader.parse_conf()` and `Loader.parse_conf()`", [[2, 23], [30, 51]]
)
(result,) = render_sarif([finding], tool_version="x")["runs"][0]["results"]
regions = [r["deletedRegion"] for r in result["fixes"][0]["artifactChanges"][0]["replacements"]]
assert [(r["startColumn"], r["endColumn"]) for r in regions] == [(2, 23), (30, 51)]
def test_sarif_has_no_fix_without_a_placed_suggestion():
(result,) = render_sarif([_f("a.py", suggestion="pkg/a/")], tool_version="x")["runs"][0][
"results"
]
assert "fixes" not in result
def test_markdown_puts_a_suggestion_block_with_the_whole_line_under_its_document():
md = render_markdown([_placed(), _f("b.py", line=9)], gate=None)
assert "**Suggested edits**" in md
block = md.split("**Suggested edits**", 1)[1]
assert "`docs/a.md`" in block
assert "Line 3: likely now `pkg/a/`" in block
assert "```suggestion\nSee `pkg/a/` here.\n```" in block
assert "Line 9" not in block
def test_markdown_suggestion_block_for_a_symbol():
finding = _symbol("Loader.parse_conf()", "Call `Loader.parse_conf()` first.", [[7, 28]])
md = render_markdown([finding], gate=None)
assert "Line 3: likely now `Loader.parse_conf()`" in md
assert "```suggestion\nCall `Loader.parse_conf()` first.\n```" in md
assert "| Loader.parse_config | symbol |" in md
def test_markdown_fence_outgrows_backticks_in_the_line():
finding = _placed()
finding["suggested_line"] = "Run ```pkg/a/``` now."
md = render_markdown([finding], gate=None)
assert "````suggestion\nRun ```pkg/a/``` now.\n````" in md
def test_a_backtick_in_a_suggestion_never_breaks_the_code_span():
finding = _placed()
finding["suggestion"] = "make `x`"
md = render_markdown([finding], gate=None)
assert "likely now `` make `x` ``" in md
(issue,) = render_gitlab([finding])
assert issue["description"].endswith("Likely now: `` make `x` ``")
def test_gitlab_description_ends_with_the_suggestion():
(issue,) = render_gitlab([_placed()])
assert issue["description"].endswith("Likely now: `pkg/a/`")