From 922e607cd4b36eb3c2f826b7b0a6f802c97c36b9 Mon Sep 17 00:00:00 2001 From: Stef Kariotidis Date: Wed, 26 Aug 2026 22:54:50 +0300 Subject: [PATCH 1/3] WIP: extract completed analysis presentation (checkpoint) --- src/agent_code_guard/code_guard.py | 88 +------------------ src/agent_code_guard/human_output.py | 122 +++++++++++++++++++++++++++ 2 files changed, 124 insertions(+), 86 deletions(-) create mode 100644 src/agent_code_guard/human_output.py diff --git a/src/agent_code_guard/code_guard.py b/src/agent_code_guard/code_guard.py index f8ea1dc..70e07d7 100644 --- a/src/agent_code_guard/code_guard.py +++ b/src/agent_code_guard/code_guard.py @@ -14,6 +14,7 @@ from .config_validation import validate_configuration from .file_selection import resolve_scope from .guards import callable_size, complexity, loc, markdown_document_size, markdown_section_size, nesting +from .human_output import format_completed_analysis from . import loc_baseline from .result_model import GuardResult, aggregate_state, required_policies from .skill_distribution import export_skill, skill_path as installed_skill_path @@ -357,92 +358,7 @@ def _empty_markdown_facts(): def print_text(data: dict[str, object]) -> None: - scope = data["scope"] - print( - f"{str(data['overall']).upper()}: {scope['selected']} selected; {scope['analyzed']} analyzed; " - f"{scope['inapplicable']} inapplicable; {scope['excluded']} excluded." - ) - loc_result = data["guards"]["loc"] - for finding in loc_result["findings"]: - if finding["nativeStatus"] == "ok" and finding.get("baselineLoc") is None: - continue - label = ( - "RATCHET" if finding["nativeStatus"] == "grandfathered" else - "EXEMPT" if finding["nativeStatus"] == "exempt" else finding["state"].upper() - ) - baseline_detail = "" - if finding.get("baselineLoc") is not None: - status = { - "within": "within", "exceeded": "exceeded", "notNeeded": "no longer needed", - }[finding["ratchetStatus"]] - baseline_detail = f"; baseline {finding['baselineLoc']}, {status}" - print( - f"{label}: {finding['path']} — {finding['countedLoc']} LOC " - f"(warn {finding['warnAt']}, fail {finding['failAt']}{baseline_detail})" - ) - if finding["overrideIndex"] is not None: - print(f" Threshold override: {finding['overrideIndex']}") - if finding["reason"]: - print(f" Reason: {finding['reason']}") - callable_result = data["guards"].get("callableSize") - if callable_result: - for finding in callable_result["findings"]: - if finding["state"] != "review": - continue - print( - f"REVIEW: {finding['path']}:{finding['range']['startLine']}-{finding['range']['endLine']} " - f"— {finding['callable']} is {finding['measured']} LOC " - f"(review {finding['thresholds']['reviewAt']})" - ) - nesting_result = data["guards"].get("nesting") - if nesting_result: - for finding in nesting_result["findings"]: - if finding["state"] != "review": - continue - deepest = finding.get("details", {}).get("deepestLine") - explanation = f"; deepest at line {deepest}" if deepest is not None else "" - print( - f"REVIEW: {finding['path']}:{finding['range']['startLine']}-{finding['range']['endLine']} " - f"— {finding['callable']} nesting depth {finding['measured']} " - f"(review {finding['thresholds']['reviewAt']}{explanation})" - ) - complexity_result = data["guards"].get("complexity") - if complexity_result: - for finding in complexity_result["findings"]: - if finding["state"] != "review": - continue - print( - f"REVIEW: {finding['path']}:{finding['range']['startLine']}-{finding['range']['endLine']} " - f"— {finding['callable']} complexity {finding['measured']} " - f"(review {finding['thresholds']['reviewAt']})" - ) - _print_markdown_findings(data) - policies = data["requiredPolicies"] - if policies: - print(f"Required policies: {', '.join(policies)}") - print("Required action: inspect each actionable finding using its policy guidance.") - - -def _print_markdown_findings(data: dict[str, object]) -> None: - markdown_document_result = data["guards"].get("markdownDocumentSize") - if markdown_document_result: - for finding in markdown_document_result["findings"]: - if finding["state"] != "review": - continue - print( - f"REVIEW: {finding['path']} — Markdown document is {finding['measured']} lines " - f"(review {finding['thresholds']['reviewAt']})" - ) - markdown_section_result = data["guards"].get("markdownSectionSize") - if markdown_section_result: - for finding in markdown_section_result["findings"]: - if finding["state"] != "review": - continue - print( - f"REVIEW: {finding['path']}:{finding['range']['startLine']}-{finding['range']['endLine']} " - f"— section {json.dumps(finding['heading'], ensure_ascii=False)} is {finding['measured']} lines " - f"(review {finding['thresholds']['reviewAt']})" - ) + print(format_completed_analysis(data)) def exit_code(overall: str, ci: bool) -> int: diff --git a/src/agent_code_guard/human_output.py b/src/agent_code_guard/human_output.py new file mode 100644 index 0000000..5843fcb --- /dev/null +++ b/src/agent_code_guard/human_output.py @@ -0,0 +1,122 @@ +"""Human presentation for completed normal-analysis payloads.""" + +from __future__ import annotations + +import json + + +def _loc_lines(data: dict[str, object]) -> list[str]: + lines = [] + loc_result = data["guards"]["loc"] + for finding in loc_result["findings"]: + if finding["nativeStatus"] == "ok" and finding.get("baselineLoc") is None: + continue + label = ( + "RATCHET" if finding["nativeStatus"] == "grandfathered" else + "EXEMPT" if finding["nativeStatus"] == "exempt" else finding["state"].upper() + ) + baseline_detail = "" + if finding.get("baselineLoc") is not None: + status = { + "within": "within", "exceeded": "exceeded", "notNeeded": "no longer needed", + }[finding["ratchetStatus"]] + baseline_detail = f"; baseline {finding['baselineLoc']}, {status}" + lines.append( + f"{label}: {finding['path']} — {finding['countedLoc']} LOC " + f"(warn {finding['warnAt']}, fail {finding['failAt']}{baseline_detail})" + ) + if finding["overrideIndex"] is not None: + lines.append(f" Threshold override: {finding['overrideIndex']}") + if finding["reason"]: + lines.append(f" Reason: {finding['reason']}") + return lines + + +def _callable_size_lines(data: dict[str, object]) -> list[str]: + lines = [] + result = data["guards"].get("callableSize") + if result: + for finding in result["findings"]: + if finding["state"] != "review": + continue + lines.append( + f"REVIEW: {finding['path']}:{finding['range']['startLine']}-{finding['range']['endLine']} " + f"— {finding['callable']} is {finding['measured']} LOC " + f"(review {finding['thresholds']['reviewAt']})" + ) + return lines + + +def _nesting_lines(data: dict[str, object]) -> list[str]: + lines = [] + result = data["guards"].get("nesting") + if result: + for finding in result["findings"]: + if finding["state"] != "review": + continue + deepest = finding.get("details", {}).get("deepestLine") + explanation = f"; deepest at line {deepest}" if deepest is not None else "" + lines.append( + f"REVIEW: {finding['path']}:{finding['range']['startLine']}-{finding['range']['endLine']} " + f"— {finding['callable']} nesting depth {finding['measured']} " + f"(review {finding['thresholds']['reviewAt']}{explanation})" + ) + return lines + + +def _complexity_lines(data: dict[str, object]) -> list[str]: + lines = [] + result = data["guards"].get("complexity") + if result: + for finding in result["findings"]: + if finding["state"] != "review": + continue + lines.append( + f"REVIEW: {finding['path']}:{finding['range']['startLine']}-{finding['range']['endLine']} " + f"— {finding['callable']} complexity {finding['measured']} " + f"(review {finding['thresholds']['reviewAt']})" + ) + return lines + + +def _markdown_lines(data: dict[str, object]) -> list[str]: + lines = [] + document_result = data["guards"].get("markdownDocumentSize") + if document_result: + for finding in document_result["findings"]: + if finding["state"] != "review": + continue + lines.append( + f"REVIEW: {finding['path']} — Markdown document is {finding['measured']} lines " + f"(review {finding['thresholds']['reviewAt']})" + ) + section_result = data["guards"].get("markdownSectionSize") + if section_result: + for finding in section_result["findings"]: + if finding["state"] != "review": + continue + lines.append( + f"REVIEW: {finding['path']}:{finding['range']['startLine']}-{finding['range']['endLine']} " + f"— section {json.dumps(finding['heading'], ensure_ascii=False)} is {finding['measured']} lines " + f"(review {finding['thresholds']['reviewAt']})" + ) + return lines + + +def format_completed_analysis(data: dict[str, object]) -> str: + """Return the complete human report for an existing completed payload.""" + scope = data["scope"] + lines = [ + f"{str(data['overall']).upper()}: {scope['selected']} selected; {scope['analyzed']} analyzed; " + f"{scope['inapplicable']} inapplicable; {scope['excluded']} excluded." + ] + lines.extend(_loc_lines(data)) + lines.extend(_callable_size_lines(data)) + lines.extend(_nesting_lines(data)) + lines.extend(_complexity_lines(data)) + lines.extend(_markdown_lines(data)) + policies = data["requiredPolicies"] + if policies: + lines.append(f"Required policies: {', '.join(policies)}") + lines.append("Required action: inspect each actionable finding using its policy guidance.") + return "\n".join(lines) From ec02d9e393b061d7798bbcfbdccca0123a927380 Mon Sep 17 00:00:00 2001 From: Stef Kariotidis Date: Wed, 26 Aug 2026 23:00:42 +0300 Subject: [PATCH 2/3] Complete human presentation extraction --- tests/test_human_output.py | 67 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 67 insertions(+) create mode 100644 tests/test_human_output.py diff --git a/tests/test_human_output.py b/tests/test_human_output.py new file mode 100644 index 0000000..5321739 --- /dev/null +++ b/tests/test_human_output.py @@ -0,0 +1,67 @@ +from __future__ import annotations + +import unittest +from pathlib import Path +import sys + +REPO_ROOT = Path(__file__).resolve().parents[1] +sys.path.insert(0, str(REPO_ROOT / "src")) + +from agent_code_guard.human_output import format_completed_analysis + + +class CompletedAnalysisOutputTests(unittest.TestCase): + def test_formats_one_complete_mixed_report_exactly(self) -> None: + data = { + "overall": "review", + "scope": {"selected": 3, "analyzed": 3, "inapplicable": 0, "excluded": 0}, + "guards": { + "loc": {"findings": [{ + "path": "large.py", "countedLoc": 450, "warnAt": 400, "failAt": 600, + "state": "review", "nativeStatus": "grandfathered", "baselineLoc": 460, + "ratchetStatus": "within", "overrideIndex": 2, "reason": "Generated boundary", + }]}, + "callableSize": {"findings": [{ + "path": "large.py", "range": {"startLine": 10, "endLine": 95}, + "callable": "large.run", "measured": 86, "state": "review", + "thresholds": {"reviewAt": 80}, + }]}, + "nesting": {"findings": [{ + "path": "nested.py", "range": {"startLine": 3, "endLine": 20}, + "callable": "nested.walk", "measured": 5, "state": "review", + "thresholds": {"reviewAt": 4}, "details": {"deepestLine": 12}, + }]}, + "complexity": {"findings": [{ + "path": "large.py", "range": {"startLine": 10, "endLine": 95}, + "callable": "large.run", "measured": 16, "state": "review", + "thresholds": {"reviewAt": 15}, + }]}, + "markdownDocumentSize": {"findings": [{ + "path": "guide.md", "measured": 801, "state": "review", + "thresholds": {"reviewAt": 800}, + }]}, + "markdownSectionSize": {"findings": [{ + "path": "guide.md", "range": {"startLine": 2, "endLine": 205}, + "heading": "Hé said \"hello\"", "measured": 204, "state": "review", + "thresholds": {"reviewAt": 200}, + }]}, + }, + "requiredPolicies": ["loc", "callableSize", "nesting", "complexity", "markdownDocumentSize"], + } + + self.assertEqual(format_completed_analysis(data), "\n".join([ + "REVIEW: 3 selected; 3 analyzed; 0 inapplicable; 0 excluded.", + "RATCHET: large.py — 450 LOC (warn 400, fail 600; baseline 460, within)", + " Threshold override: 2", " Reason: Generated boundary", + "REVIEW: large.py:10-95 — large.run is 86 LOC (review 80)", + "REVIEW: nested.py:3-20 — nested.walk nesting depth 5 (review 4; deepest at line 12)", + "REVIEW: large.py:10-95 — large.run complexity 16 (review 15)", + "REVIEW: guide.md — Markdown document is 801 lines (review 800)", + 'REVIEW: guide.md:2-205 — section "Hé said \\"hello\\"" is 204 lines (review 200)', + "Required policies: loc, callableSize, nesting, complexity, markdownDocumentSize", + "Required action: inspect each actionable finding using its policy guidance.", + ])) + + +if __name__ == "__main__": + unittest.main() From aa8a542062886cb37096577a2c48b1999888c023 Mon Sep 17 00:00:00 2001 From: Stef Kariotidis Date: Wed, 26 Aug 2026 23:04:06 +0300 Subject: [PATCH 3/3] Harden mixed output regression isolation --- tests/test_human_output.py | 95 ++++++++++++++++---------------------- 1 file changed, 39 insertions(+), 56 deletions(-) diff --git a/tests/test_human_output.py b/tests/test_human_output.py index 5321739..bf27f56 100644 --- a/tests/test_human_output.py +++ b/tests/test_human_output.py @@ -1,67 +1,50 @@ from __future__ import annotations -import unittest +import json +import tempfile from pathlib import Path -import sys -REPO_ROOT = Path(__file__).resolve().parents[1] -sys.path.insert(0, str(REPO_ROOT / "src")) +from helpers import CodeGuardTestCase -from agent_code_guard.human_output import format_completed_analysis - -class CompletedAnalysisOutputTests(unittest.TestCase): +class CompletedAnalysisOutputTests(CodeGuardTestCase): def test_formats_one_complete_mixed_report_exactly(self) -> None: - data = { - "overall": "review", - "scope": {"selected": 3, "analyzed": 3, "inapplicable": 0, "excluded": 0}, - "guards": { - "loc": {"findings": [{ - "path": "large.py", "countedLoc": 450, "warnAt": 400, "failAt": 600, - "state": "review", "nativeStatus": "grandfathered", "baselineLoc": 460, - "ratchetStatus": "within", "overrideIndex": 2, "reason": "Generated boundary", - }]}, - "callableSize": {"findings": [{ - "path": "large.py", "range": {"startLine": 10, "endLine": 95}, - "callable": "large.run", "measured": 86, "state": "review", - "thresholds": {"reviewAt": 80}, - }]}, - "nesting": {"findings": [{ - "path": "nested.py", "range": {"startLine": 3, "endLine": 20}, - "callable": "nested.walk", "measured": 5, "state": "review", - "thresholds": {"reviewAt": 4}, "details": {"deepestLine": 12}, - }]}, - "complexity": {"findings": [{ - "path": "large.py", "range": {"startLine": 10, "endLine": 95}, - "callable": "large.run", "measured": 16, "state": "review", - "thresholds": {"reviewAt": 15}, - }]}, - "markdownDocumentSize": {"findings": [{ - "path": "guide.md", "measured": 801, "state": "review", - "thresholds": {"reviewAt": 800}, - }]}, - "markdownSectionSize": {"findings": [{ - "path": "guide.md", "range": {"startLine": 2, "endLine": 205}, - "heading": "Hé said \"hello\"", "measured": 204, "state": "review", - "thresholds": {"reviewAt": 200}, - }]}, - }, - "requiredPolicies": ["loc", "callableSize", "nesting", "complexity", "markdownDocumentSize"], - } - - self.assertEqual(format_completed_analysis(data), "\n".join([ - "REVIEW: 3 selected; 3 analyzed; 0 inapplicable; 0 excluded.", - "RATCHET: large.py — 450 LOC (warn 400, fail 600; baseline 460, within)", - " Threshold override: 2", " Reason: Generated boundary", - "REVIEW: large.py:10-95 — large.run is 86 LOC (review 80)", - "REVIEW: nested.py:3-20 — nested.walk nesting depth 5 (review 4; deepest at line 12)", - "REVIEW: large.py:10-95 — large.run complexity 16 (review 15)", - "REVIEW: guide.md — Markdown document is 801 lines (review 800)", - 'REVIEW: guide.md:2-205 — section "Hé said \\"hello\\"" is 204 lines (review 200)', - "Required policies: loc, callableSize, nesting, complexity, markdownDocumentSize", - "Required action: inspect each actionable finding using its policy guidance.", - ])) + with tempfile.TemporaryDirectory() as temp: + root = Path(temp) + (root / "sample.py").write_text( + "def sample(value):\n if value:\n if value > 1:\n" + " return value\n return 0\n", + encoding="utf-8", + ) + (root / "guide.md").write_text('# Hé said `"hello`"\nbody\nbody\n', encoding="utf-8") + config = root / "code-guard.config.json" + config.write_text(json.dumps({"version": 1, "guards": { + "loc": {"warnAt": 1, "failAt": 99}, + "callableSize": {"reviewAt": 3}, + "nesting": {"reviewAt": 1}, + "cyclomaticComplexity": {"reviewAt": 1}, + "markdownDocumentSize": {"reviewAt": 2}, + "markdownSectionSize": {"reviewAt": 2}, + }}), encoding="utf-8") + + result = self.run_guard(root, ".", "--config", str(config)) + + self.assertEqual(result.returncode, 1) + self.assertEqual(result.stderr, "") + self.assertEqual(result.stdout, "\n".join([ + "REVIEW: 3 selected; 2 analyzed; 1 inapplicable; 0 excluded.", + "REVIEW: sample.py — 5 LOC (warn 1, fail 99)", + "REVIEW: sample.py:1-5 — sample.sample is 5 LOC (review 3)", + "REVIEW: sample.py:1-5 — sample.sample nesting depth 2 (review 1; deepest at line 3)", + "REVIEW: sample.py:1-5 — sample.sample complexity 3 (review 1)", + "REVIEW: guide.md — Markdown document is 3 lines (review 2)", + 'REVIEW: guide.md:1-3 — section "Hé said `\\"hello`\\"" is 3 lines (review 2)', + "Required policies: callableSize, complexity, loc, markdownDocumentSize, markdownSectionSize, nesting", + "Required action: inspect each actionable finding using its policy guidance.", + "", + ])) if __name__ == "__main__": + import unittest unittest.main()