agent-code-guard 0.1.0__py3-none-any.whl

agent_code_guard/analysis/facts.py

@@ -0,0 +1,101 @@
+"""Immutable, parser-provider-neutral syntax facts consumed by future guards."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True, order=True)
+class SourcePoint:
+    """A one-based line and one-based UTF-8 byte column in the original file."""
+
+    line: int
+    byte_column: int
+    byte_offset: int
+
+
+@dataclass(frozen=True, order=True)
+class SourceRange:
+    """A half-open original-source byte range with inclusive physical lines."""
+
+    start: SourcePoint
+    end: SourcePoint
+
+    @property
+    def start_line(self) -> int:
+        return self.start.line
+
+    @property
+    def end_line(self) -> int:
+        return self.end.line if self.end.byte_column > 1 else max(self.start.line, self.end.line - 1)
+
+    @property
+    def physical_loc(self) -> int:
+        return self.end_line - self.start_line + 1
+
+
+@dataclass(frozen=True)
+class CallableKey:
+    path: Path
+    embedded_language: str
+    identity: str
+    source_range: SourceRange
+
+
+@dataclass(frozen=True)
+class CallableFact:
+    path: Path
+    embedded_language: str
+    identity: str
+    source_range: SourceRange
+    parent_callable: str | None
+    boundary_kind: str
+    key: CallableKey
+    parent_key: CallableKey | None
+
+
+@dataclass(frozen=True)
+class ControlFlowFact:
+    callable_identity: str
+    callable_key: CallableKey
+    category: str
+    provider_kind: str
+    source_range: SourceRange
+    parent_control_range: SourceRange | None
+    increases_nesting: bool = True
+
+
+@dataclass(frozen=True)
+class DecisionFact:
+    callable_identity: str
+    callable_key: CallableKey
+    category: str
+    provider_kind: str
+    source_range: SourceRange
+
+
+@dataclass(frozen=True)
+class FileFacts:
+    path: Path
+    callables: tuple[CallableFact, ...]
+    controls: tuple[ControlFlowFact, ...]
+    decisions: tuple[DecisionFact, ...]
+    region_count: int
+
+
+@dataclass(frozen=True)
+class AnalysisFacts:
+    files: tuple[FileFacts, ...]
+
+    @property
+    def callables(self) -> tuple[CallableFact, ...]:
+        return tuple(fact for file in self.files for fact in file.callables)
+
+    @property
+    def controls(self) -> tuple[ControlFlowFact, ...]:
+        return tuple(fact for file in self.files for fact in file.controls)
+
+    @property
+    def decisions(self) -> tuple[DecisionFact, ...]:
+        return tuple(fact for file in self.files for fact in file.decisions)

agent_code_guard/analysis/language_specs.py

@@ -0,0 +1,82 @@
+"""Declarative Tree-sitter node mappings for supported executable languages."""
+
+CALLABLE_TYPES = {
+    "python": {"function_definition", "lambda"},
+    "go": {"function_declaration", "method_declaration", "func_literal"},
+    "kotlin": {"function_declaration", "secondary_constructor", "lambda_literal", "anonymous_function"},
+    "csharp": {"method_declaration", "constructor_declaration", "local_function_statement", "lambda_expression", "anonymous_method_expression"},
+    "java": {"method_declaration", "constructor_declaration", "lambda_expression"},
+    "javascript": {"function_declaration", "method_definition", "arrow_function", "function_expression"},
+    "typescript": {"function_declaration", "method_definition", "arrow_function", "function_expression"},
+    "tsx": {"function_declaration", "method_definition", "arrow_function", "function_expression"},
+    "cpp": {"function_definition", "lambda_expression"}, "rust": {"function_item", "closure_expression"},
+    "php": {"function_definition", "method_declaration", "anonymous_function", "arrow_function"},
+    "swift": {"function_declaration", "init_declaration", "lambda_literal", "protocol_function_declaration"},
+    "dart": {"function_signature", "method_signature", "function_expression", "lambda_expression"},
+}
+
+OPAQUE_LAMBDA_TYPES = {
+    "python": set(), "go": set(), "kotlin": set(), "csharp": set(), "java": set(),
+    "javascript": set(), "typescript": set(), "tsx": set(), "cpp": set(), "rust": set(),
+    "php": set(), "swift": set(), "dart": set(),
+}
+
+CONTROL_CATEGORIES = {
+    "if_statement": "condition", "if_expression": "condition", "elif_clause": "condition",
+    "else_if_clause": "condition", "guard_statement": "condition", "for_statement": "loop",
+    "foreach_statement": "loop", "enhanced_for_statement": "loop", "for_in_statement": "loop",
+    "while_statement": "loop", "do_statement": "loop", "do_while_statement": "loop",
+    "loop_expression": "loop", "while_expression": "loop", "for_expression": "loop",
+    "repeat_while_statement": "loop", "match_statement": "selection", "match_expression": "selection",
+    "when_expression": "selection", "switch_statement": "selection", "switch_expression": "selection",
+    "expression_switch_statement": "selection", "type_switch_statement": "selection",
+    "select_statement": "selection", "try_statement": "exception", "try_expression": "exception",
+}
+
+CONTROL_TYPES = {
+    "python": {"if_statement", "elif_clause", "for_statement", "while_statement", "match_statement", "try_statement"},
+    "go": {"if_statement", "for_statement", "expression_switch_statement", "type_switch_statement", "select_statement"},
+    "kotlin": {"if_expression", "for_statement", "while_statement", "do_while_statement", "when_expression", "try_expression"},
+    "csharp": {"if_statement", "for_statement", "foreach_statement", "while_statement", "do_statement", "switch_statement", "try_statement"},
+    "java": {"if_statement", "for_statement", "enhanced_for_statement", "while_statement", "do_statement", "switch_expression", "try_statement"},
+    "javascript": {"if_statement", "for_statement", "for_in_statement", "while_statement", "do_statement", "switch_statement", "try_statement"},
+    "typescript": {"if_statement", "for_statement", "for_in_statement", "while_statement", "do_statement", "switch_statement", "try_statement"},
+    "tsx": {"if_statement", "for_statement", "for_in_statement", "while_statement", "do_statement", "switch_statement", "try_statement"},
+    "cpp": {"if_statement", "for_statement", "range_based_for_statement", "while_statement", "do_statement", "switch_statement", "try_statement"},
+    "rust": {"if_expression", "loop_expression", "while_expression", "for_expression", "match_expression"},
+    "php": {"if_statement", "else_if_clause", "for_statement", "foreach_statement", "while_statement", "do_statement", "switch_statement", "match_expression", "try_statement"},
+    "swift": {"if_statement", "guard_statement", "for_statement", "while_statement", "repeat_while_statement", "switch_statement", "do_statement"},
+    "dart": {"if_statement", "for_statement", "while_statement", "do_statement", "switch_statement", "try_statement"},
+}
+
+DECISION_CATEGORIES = {
+    "if_statement": "condition", "if_expression": "condition", "elif_clause": "condition",
+    "else_if_clause": "condition", "guard_statement": "condition", "for_statement": "loop",
+    "foreach_statement": "loop", "enhanced_for_statement": "loop", "for_in_statement": "loop",
+    "while_statement": "loop", "do_statement": "loop", "do_while_statement": "loop",
+    "loop_expression": "loop", "while_expression": "loop", "for_expression": "loop",
+    "repeat_while_statement": "loop", "except_clause": "catch", "catch_clause": "catch",
+    "catch_block": "catch", "conditional_expression": "ternary", "ternary_expression": "ternary",
+    "list_comprehension": "comprehension", "set_comprehension": "comprehension",
+    "dictionary_comprehension": "comprehension", "generator_expression": "comprehension",
+    "case_clause": "switch_arm", "expression_case": "switch_arm", "type_case": "switch_arm",
+    "communication_case": "switch_arm", "when_entry": "switch_arm", "switch_expression_arm": "switch_arm",
+    "match_arm": "switch_arm", "match_conditional_expression": "switch_arm", "switch_entry": "switch_arm",
+    "switch_statement_case": "switch_arm", "case_statement": "switch_arm",
+}
+
+DECISION_TYPES = {
+    "python": {"if_statement", "elif_clause", "for_statement", "while_statement", "except_clause", "conditional_expression", "list_comprehension", "set_comprehension", "dictionary_comprehension", "generator_expression", "case_clause"},
+    "go": {"if_statement", "for_statement", "expression_case", "type_case", "communication_case"},
+    "kotlin": {"if_expression", "for_statement", "while_statement", "do_while_statement", "catch_block", "when_entry"},
+    "csharp": {"if_statement", "for_statement", "foreach_statement", "while_statement", "do_statement", "catch_clause", "conditional_expression", "switch_expression_arm"},
+    "java": {"if_statement", "for_statement", "enhanced_for_statement", "while_statement", "do_statement", "catch_clause", "ternary_expression"},
+    "javascript": {"if_statement", "for_statement", "for_in_statement", "while_statement", "do_statement", "catch_clause", "ternary_expression"},
+    "typescript": {"if_statement", "for_statement", "for_in_statement", "while_statement", "do_statement", "catch_clause", "ternary_expression"},
+    "tsx": {"if_statement", "for_statement", "for_in_statement", "while_statement", "do_statement", "catch_clause", "ternary_expression"},
+    "cpp": {"if_statement", "for_statement", "range_based_for_statement", "while_statement", "do_statement", "catch_clause", "conditional_expression"},
+    "rust": {"if_expression", "loop_expression", "while_expression", "for_expression", "match_arm"},
+    "php": {"if_statement", "else_if_clause", "for_statement", "foreach_statement", "while_statement", "do_statement", "catch_clause", "conditional_expression", "match_conditional_expression"},
+    "swift": {"if_statement", "guard_statement", "for_statement", "while_statement", "repeat_while_statement", "catch_block", "ternary_expression", "switch_entry"},
+    "dart": {"if_statement", "for_statement", "while_statement", "do_statement", "catch_clause", "conditional_expression", "switch_statement_case"},
+}

agent_code_guard/analysis/pipeline.py

@@ -0,0 +1,37 @@
+"""Parse applicable selected files once and return reusable immutable facts."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .adapters import extract_facts
+from .errors import SyntaxAnalysisError
+from .facts import AnalysisFacts, FileFacts
+from .provider import ParserProvider, TreeSitterProvider
+from .regions import executable_regions, is_applicable
+
+
+def analyze_files(files: tuple[Path, ...] | list[Path], provider: ParserProvider | None = None) -> AnalysisFacts:
+    """Analyze only applicable entries from the already-resolved caller scope."""
+    active_provider = provider or TreeSitterProvider()
+    results: list[FileFacts] = []
+    for path in files:
+        path = Path(path)
+        if not is_applicable(path):
+            continue
+        callables = []
+        controls = []
+        decisions = []
+        regions = executable_regions(path, active_provider)
+        for region in regions:
+            tree = active_provider.parse(region.language, region.source)
+            if tree.root_node.has_error:
+                raise SyntaxAnalysisError(
+                    f"unable to parse {path}: embedded {region.language} syntax tree contains errors"
+                )
+            region_callables, region_controls, region_decisions = extract_facts(tree.root_node, region)
+            callables.extend(region_callables)
+            controls.extend(region_controls)
+            decisions.extend(region_decisions)
+        results.append(FileFacts(path, tuple(callables), tuple(controls), tuple(decisions), len(regions)))
+    return AnalysisFacts(tuple(results))

agent_code_guard/analysis/provider.py

@@ -0,0 +1,45 @@
+"""Tree-sitter provider hidden behind a small cached parser boundary."""
+
+from __future__ import annotations
+
+from typing import Protocol
+
+from .errors import ProviderUnavailableError
+
+
+class ParserProvider(Protocol):
+    def parse(self, language: str, source: bytes): ...
+
+
+class TreeSitterProvider:
+    """Load each embedded-language parser once per analysis provider."""
+
+    def __init__(self, parser_factory=None) -> None:
+        self._parsers: dict[str, object] = {}
+        self._parser_factory = parser_factory
+
+    @property
+    def cached_languages(self) -> tuple[str, ...]:
+        return tuple(self._parsers)
+
+    def parse(self, language: str, source: bytes):
+        parser = self._parsers.get(language)
+        if parser is None:
+            try:
+                if self._parser_factory is None:
+                    from tree_sitter_language_pack import get_parser
+                    self._parser_factory = get_parser
+                parser = self._parser_factory(language)
+            except (ImportError, LookupError, OSError, RuntimeError) as exc:
+                raise ProviderUnavailableError(
+                    f"syntax provider unavailable for supported language {language!r}: {exc}; "
+                    "reinstall Agent Code Guard"
+                ) from exc
+            self._parsers[language] = parser
+        try:
+            return parser.parse(source)
+        except Exception as exc:
+            raise ProviderUnavailableError(
+                f"syntax provider failed for supported language {language!r}: {exc}; "
+                "verify the Agent Code Guard installation"
+            ) from exc

agent_code_guard/analysis/regions.py

@@ -0,0 +1,108 @@
+"""Source/container adaptation into byte-mapped executable regions."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from .errors import SyntaxAnalysisError
+from .facts import SourcePoint, SourceRange
+from .provider import ParserProvider
+
+
+LANGUAGE_BY_SUFFIX = {
+    ".py": "python", ".go": "go", ".kt": "kotlin", ".cs": "csharp",
+    ".java": "java", ".js": "javascript", ".jsx": "javascript",
+    ".ts": "typescript", ".tsx": "tsx",
+    ".cpp": "cpp", ".cc": "cpp", ".cxx": "cpp",
+    ".hpp": "cpp", ".hh": "cpp", ".hxx": "cpp",
+    ".rs": "rust", ".php": "php", ".swift": "swift", ".dart": "dart",
+}
+APPLICABLE_SUFFIXES = frozenset((*LANGUAGE_BY_SUFFIX, ".vue"))
+
+
+@dataclass(frozen=True)
+class ExecutableRegion:
+    original_path: Path
+    language: str
+    source: bytes
+    original_source: bytes
+    original_byte_offset: int = 0
+
+    def original_point(self, local_row: int, local_byte_column: int) -> SourcePoint:
+        absolute = self.original_byte_offset + _byte_at_point(self.source, local_row, local_byte_column)
+        prefix = self.original_source[:absolute]
+        line = prefix.count(b"\n") + 1
+        newline = prefix.rfind(b"\n")
+        byte_column = absolute + 1 if newline < 0 else absolute - newline
+        return SourcePoint(line, byte_column, absolute)
+
+    def original_range(self, node) -> SourceRange:
+        start_row, start_column = node.start_point
+        end_row, end_column = node.end_point
+        return SourceRange(
+            self.original_point(start_row, start_column),
+            self.original_point(end_row, end_column),
+        )
+
+
+def is_applicable(path: Path) -> bool:
+    return path.suffix.lower() in APPLICABLE_SUFFIXES
+
+
+def executable_regions(path: Path, provider: ParserProvider) -> tuple[ExecutableRegion, ...]:
+    source = path.read_bytes()
+    suffix = path.suffix.lower()
+    if suffix == ".vue":
+        return _vue_regions(path, source, provider)
+    language = LANGUAGE_BY_SUFFIX.get(suffix)
+    if language is None:
+        return ()
+    return (ExecutableRegion(path, language, source, source),)
+
+
+def _vue_regions(path: Path, source: bytes, provider: ParserProvider) -> tuple[ExecutableRegion, ...]:
+    root = provider.parse("vue", source).root_node
+    if root.has_error:
+        raise SyntaxAnalysisError(f"unable to parse {path}: Vue container syntax tree contains errors")
+    regions: list[ExecutableRegion] = []
+    for element in root.named_children:
+        if element.type != "script_element":
+            continue
+        start_tag = next(child for child in element.named_children if child.type == "start_tag")
+        attributes = _attributes(start_tag, source)
+        if "src" in attributes:
+            raise SyntaxAnalysisError(f"unable to analyze {path}: external Vue script regions are unsupported")
+        language = _script_language(path, attributes.get("lang"))
+        raw_text = next((child for child in element.named_children if child.type == "raw_text"), None)
+        if raw_text is not None:
+            regions.append(ExecutableRegion(
+                path, language, source[raw_text.start_byte:raw_text.end_byte], source, raw_text.start_byte,
+            ))
+    return tuple(regions)
+
+
+def _byte_at_point(source: bytes, row: int, column: int) -> int:
+    position = 0
+    for _ in range(row):
+        position = source.index(b"\n", position) + 1
+    return position + column
+
+
+def _attributes(start_tag, source: bytes) -> dict[str, str | None]:
+    values: dict[str, str | None] = {}
+    for attribute in (child for child in start_tag.named_children if child.type == "attribute"):
+        name_node = next(child for child in attribute.named_children if child.type == "attribute_name")
+        value_node = next((child for child in attribute.named_children if child.type == "quoted_attribute_value"), None)
+        name = source[name_node.start_byte:name_node.end_byte].decode("utf-8").lower()
+        value = None if value_node is None else source[value_node.start_byte:value_node.end_byte].decode("utf-8")[1:-1].lower()
+        values[name] = value
+    return values
+
+
+def _script_language(path: Path, value: str | None) -> str:
+    if value in {None, "js", "javascript"}:
+        return "javascript"
+    if value in {"ts", "typescript"}:
+        return "typescript"
+    raise SyntaxAnalysisError(f"unable to analyze {path}: unsupported Vue script language: {value}")

agent_code_guard/code_guard.py

@@ -0,0 +1,236 @@
+#!/usr/bin/env python3
+"""Single public runner for Agent Code Guard."""
+
+from __future__ import annotations
+
+import argparse
+from importlib import import_module
+import json
+import sys
+from pathlib import Path
+
+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 .result_model import GuardResult, aggregate_state, required_policies
+from .skill_distribution import export_skill, skill_path as installed_skill_path
+
+
+def parser() -> argparse.ArgumentParser:
+    value = argparse.ArgumentParser(description="Run deterministic Code Guard checks.")
+    value.add_argument(
+        "paths", nargs="*", default=[],
+        help="Files or directories to inspect; bounds files selected by a Git selection mode.",
+    )
+    value.add_argument("--config", help="Path to code-guard.config.json.")
+    value.add_argument("--warn", type=int, help="Override the global LOC warning threshold.")
+    value.add_argument("--fail", type=int, help="Override the global LOC failure threshold.")
+    value.add_argument("--json", action="store_true", help="Emit normalized JSON.")
+    value.add_argument("--ci", action="store_true", help="Do not fail solely on REVIEW.")
+    value.add_argument("--changed-only", action="store_true", help="Inspect staged, unstaged, and untracked files.")
+    value.add_argument("--staged", action="store_true", help="Inspect index-only changes.")
+    value.add_argument("--base-ref", help="Inspect committed ACMR changes from <ref>...HEAD.")
+    value.add_argument("--include", action="append", default=[], help="Extra LOC extension.")
+    value.add_argument("--exclude", action="append", default=[], help="Extra LOC exclusion glob.")
+    value.add_argument(
+        "--scope-exclude", action="append", default=[],
+        help="All-guards scope exclusion glob; repeat to add patterns (unlike LOC-only --exclude).",
+    )
+    value.add_argument("--count-blank-lines", action="store_true", help="Count blank lines for LOC.")
+    value.add_argument("--ignore-comment-lines", action="store_true", help="Ignore simple comment-only lines.")
+    value.add_argument(
+        "--skill-path", action="store_true",
+        help="Print the absolute path to this distribution's bundled Code Guard skill.",
+    )
+    value.add_argument(
+        "--export-skill", metavar="TARGET_DIRECTORY",
+        help="Copy this distribution's bundled Code Guard skill into an empty target directory.",
+    )
+    return value
+
+
+def _management_mode(args: argparse.Namespace) -> int | None:
+    if not args.skill_path and args.export_skill is None:
+        args.paths = args.paths or ["."]
+        return None
+    incompatible = (
+        args.skill_path and args.export_skill is not None
+        or bool(args.paths)
+        or args.config is not None
+        or args.warn is not None
+        or args.fail is not None
+        or args.json
+        or args.ci
+        or args.changed_only
+        or args.staged
+        or args.base_ref is not None
+        or bool(args.include)
+        or bool(args.exclude)
+        or bool(args.scope_exclude)
+        or args.count_blank_lines
+        or args.ignore_comment_lines
+    )
+    if incompatible:
+        raise ValueError("skill management options cannot be combined with guard execution options or paths")
+    if args.skill_path:
+        print(installed_skill_path())
+    else:
+        print(export_skill(Path(args.export_skill)))
+    return 0
+
+
+def payload(results: list[GuardResult]) -> dict[str, object]:
+    return {
+        "overall": aggregate_state(results),
+        "requiredPolicies": required_policies(results),
+        "guards": {result.guard_id: result.to_json() for result in results},
+    }
+
+
+def run_guards(scope, args: argparse.Namespace) -> list[GuardResult]:
+    """Load guard configuration, then construct shared syntax facts at most once."""
+    loc_config = loc.load_config(args)
+    callable_size_config = callable_size.load_config(args)
+    nesting_config = nesting.load_config(args)
+    complexity_config = complexity.load_config(args)
+    markdown_document_config = markdown_document_size.load_config(args)
+    markdown_section_config = markdown_section_size.load_config(args)
+    results = [loc.run(scope.root, loc_config, scope.files)]
+    needs_analysis = callable_size_config.enabled or nesting_config.enabled or complexity_config.enabled
+    if needs_analysis:
+        analysis = import_module("agent_code_guard.analysis.pipeline")
+        facts = analysis.analyze_files(scope.files)
+        if callable_size_config.enabled:
+            results.append(callable_size.run(scope.root, callable_size_config, facts))
+        if nesting_config.enabled:
+            results.append(nesting.run(scope.root, nesting_config, facts))
+        if complexity_config.enabled:
+            results.append(complexity.run(scope.root, complexity_config, facts))
+    needs_markdown = markdown_document_config.enabled or markdown_section_config.enabled
+    markdown_files = tuple(path for path in scope.files if path.suffix.lower() == ".md") if needs_markdown else ()
+    if markdown_files:
+        markdown = import_module("agent_code_guard.markdown")
+        markdown_facts = markdown.analyze_files(markdown_files)
+        if markdown_document_config.enabled:
+            results.append(markdown_document_size.run(scope.root, markdown_document_config, markdown_facts))
+        if markdown_section_config.enabled:
+            results.append(markdown_section_size.run(scope.root, markdown_section_config, markdown_facts))
+    else:
+        if markdown_document_config.enabled:
+            results.append(markdown_document_size.run(scope.root, markdown_document_config, _empty_markdown_facts()))
+        if markdown_section_config.enabled:
+            results.append(markdown_section_size.run(scope.root, markdown_section_config, _empty_markdown_facts()))
+    return results
+
+
+def _empty_markdown_facts():
+    """Avoid importing the scanner family for scopes with no applicable files."""
+    from types import SimpleNamespace
+    return SimpleNamespace(documents=())
+
+
+def print_text(data: dict[str, object]) -> None:
+    print(str(data["overall"]).upper())
+    loc_result = data["guards"]["loc"]
+    for finding in loc_result["findings"]:
+        if finding["nativeStatus"] == "ok":
+            continue
+        label = "EXEMPT" if finding["nativeStatus"] == "exempt" else finding["state"].upper()
+        print(f"{label}: {finding['path']} — {finding['countedLoc']} LOC (warn {finding['warnAt']}, fail {finding['failAt']})")
+        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']})"
+            )
+
+
+def exit_code(overall: str, ci: bool) -> int:
+    if overall == "fail":
+        return 2
+    if overall == "review" and not ci:
+        return 1
+    return 0
+
+
+def main() -> int:
+    args = parser().parse_args()
+    try:
+        management_result = _management_mode(args)
+        if management_result is not None:
+            return management_result
+        validate_configuration(args.config, Path.cwd())
+        scope = resolve_scope(args, Path.cwd())
+        data = payload(run_guards(scope, args))
+        if args.json:
+            print(json.dumps(data, indent=2))
+        else:
+            print_text(data)
+        return exit_code(data["overall"], args.ci)
+    except Exception as exc:
+        if args.json:
+            print(json.dumps({"error": str(exc)}, indent=2))
+        else:
+            print(f"Code Guard error: {exc}", file=sys.stderr)
+        return 3
+
+
+if __name__ == "__main__":
+    sys.exit(main())