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

agent_code_guard/config_validation.py

@@ -0,0 +1,90 @@
+"""Reject unsupported configuration properties before scope or guard work."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any
+
+ROOT_KEYS = {"version", "scope", "guards"}
+SCOPE_KEYS = {"exclude"}
+GUARD_KEYS = {
+    "loc",
+    "callableSize",
+    "nesting",
+    "cyclomaticComplexity",
+    "markdownDocumentSize",
+    "markdownSectionSize",
+}
+REVIEW_GUARD_NAMES = (
+    "callableSize",
+    "nesting",
+    "cyclomaticComplexity",
+    "markdownDocumentSize",
+    "markdownSectionSize",
+)
+REVIEW_GUARD_KEYS = {"enabled", "reviewAt"}
+LOC_KEYS = {
+    "enabled",
+    "warnAt",
+    "failAt",
+    "countBlankLines",
+    "countCommentLines",
+    "includeExtensions",
+    "exclude",
+    "allowedLargeFiles",
+    "overrides",
+}
+LOC_ALLOWED_LARGE_FILE_KEYS = {"path", "reason"}
+LOC_OVERRIDE_KEYS = {"match", "warnAt", "failAt"}
+
+
+def validate_configuration(config: str | None, start: Path) -> None:
+    """Load the configured document once and validate its known property names."""
+    path = Path(config) if config else start / ".agent-tools" / "code-guard.config.json"
+    if config and not path.exists():
+        raise FileNotFoundError(f"config file not found: {config}")
+    if not path.exists():
+        return
+    document = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(document, dict):
+        raise ValueError("configuration must be an object")
+    _reject_unknown(document, ROOT_KEYS, "")
+    _validate_object_keys(document.get("scope"), SCOPE_KEYS, "scope")
+
+    guards = document.get("guards")
+    if not isinstance(guards, dict):
+        return
+    _reject_unknown(guards, GUARD_KEYS, "guards")
+    for guard_name in REVIEW_GUARD_NAMES:
+        _validate_object_keys(guards.get(guard_name), REVIEW_GUARD_KEYS, f"guards.{guard_name}")
+    loc = guards.get("loc")
+    if not isinstance(loc, dict):
+        return
+    _reject_unknown(loc, LOC_KEYS, "guards.loc")
+    _validate_items(
+        loc.get("allowedLargeFiles"),
+        LOC_ALLOWED_LARGE_FILE_KEYS,
+        "guards.loc.allowedLargeFiles",
+    )
+    _validate_items(loc.get("overrides"), LOC_OVERRIDE_KEYS, "guards.loc.overrides")
+
+
+def _validate_object_keys(value: Any, allowed: set[str], path: str) -> None:
+    if isinstance(value, dict):
+        _reject_unknown(value, allowed, path)
+
+
+def _validate_items(value: Any, allowed: set[str], path: str) -> None:
+    if not isinstance(value, list):
+        return
+    for index, item in enumerate(value):
+        if isinstance(item, dict):
+            _reject_unknown(item, allowed, f"{path}[{index}]")
+
+
+def _reject_unknown(value: dict[str, Any], allowed: set[str], path: str) -> None:
+    unknown = sorted(key for key in value if key not in allowed)
+    if unknown:
+        property_path = f"{path}.{unknown[0]}" if path else unknown[0]
+        raise ValueError(f"unknown configuration property: {property_path}")

agent_code_guard/file_selection.py

@@ -0,0 +1,228 @@
+"""Resolve caller or Git scope before any guard applies its own filtering."""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Protocol
+
+from .path_matching import matches_path_glob, relative_or_absolute_path
+
+BUILTIN_PRUNED_DIRECTORIES = {".git", "node_modules", "bin", "obj"}
+
+
+class SelectionArgs(Protocol):
+    paths: list[str]
+    changed_only: bool
+    staged: bool
+    base_ref: str | None
+    config: str | None
+    scope_exclude: list[str]
+
+
+@dataclass(frozen=True)
+class ResolvedScope:
+    root: Path
+    files: tuple[Path, ...]
+
+
+def find_repo_root(start: Path) -> Path | None:
+    """Return the enclosing Git root, without inventing one when Git is absent."""
+    try:
+        result = subprocess.run(
+            ["git", "rev-parse", "--show-toplevel"], cwd=start, check=True,
+            text=True, capture_output=True,
+        )
+        return Path(result.stdout.strip()).resolve()
+    except Exception:
+        return None
+
+
+def resolve_scope(args: SelectionArgs, start: Path) -> ResolvedScope:
+    """Resolve and normalize the complete file scope shared by all guards."""
+    working_root = start.resolve()
+    git_root = find_repo_root(working_root)
+    root = git_root or working_root
+    validate_selection_args(args, git_root)
+    paths = resolve_explicit_paths(args.paths, working_root)
+
+    if args.base_ref is not None:
+        candidates = git_base_files(git_root, args.base_ref)
+        files = bound_git_candidates(existing_files(candidates), paths)
+    elif args.changed_only or args.staged:
+        candidates = git_files(git_root, staged=args.staged)
+        files = bound_git_candidates(existing_files(candidates), paths)
+    else:
+        files = existing_files(expand_paths(paths, git_root))
+
+    normalized = tuple(dict.fromkeys(path.resolve() for path in files))
+    exclusions = load_scope_exclusions(args, working_root)
+    filtered = tuple(
+        path for path in normalized
+        if not any(matches_path_glob(relative_or_absolute_path(path, root), pattern) for pattern in exclusions)
+    )
+    return ResolvedScope(root, filtered)
+
+
+def resolve_explicit_paths(values: list[str], working_root: Path) -> list[Path]:
+    """Resolve and validate positional paths against the caller's working directory."""
+    paths = [Path(value) if Path(value).is_absolute() else working_root / value for value in values]
+    missing = [value for value, path in zip(values, paths) if not path.exists()]
+    if missing:
+        raise FileNotFoundError(f"explicit path does not exist: {missing[0]}")
+    directory_links = [value for value, path in zip(values, paths) if path.is_symlink() and path.is_dir()]
+    if directory_links:
+        raise ValueError(
+            f"explicit directory symlink is not recursively traversed: {directory_links[0]}"
+        )
+    return paths
+
+
+def bound_git_candidates(candidates: list[Path], bounds: list[Path]) -> list[Path]:
+    """Intersect Git-selected files with the union of positional file/directory bounds."""
+    normalized_bounds = [(path.resolve(), path.is_dir()) for path in bounds]
+    return [
+        candidate for candidate in candidates
+        if any(
+            is_within(candidate, bound) if is_directory else candidate.resolve() == bound
+            for bound, is_directory in normalized_bounds
+        )
+    ]
+
+
+def load_scope_exclusions(args: SelectionArgs, start: Path) -> list[str]:
+    explicit_config = getattr(args, "config", None)
+    config_path = Path(explicit_config) if explicit_config else start / ".agent-tools" / "code-guard.config.json"
+    if explicit_config and not config_path.exists():
+        raise FileNotFoundError(f"config file not found: {explicit_config}")
+    document = json.loads(config_path.read_text(encoding="utf-8")) if config_path.exists() else {}
+    if not isinstance(document, dict):
+        raise ValueError("configuration must be an object")
+    scope = document.get("scope", {})
+    if not isinstance(scope, dict):
+        raise ValueError("scope must be an object")
+    exclude = scope.get("exclude", [])
+    if not isinstance(exclude, list) or any(not isinstance(pattern, str) for pattern in exclude):
+        raise ValueError("scope.exclude must be an array of strings")
+    combined = [*exclude, *getattr(args, "scope_exclude", [])]
+    if any(not isinstance(pattern, str) or not pattern.strip() for pattern in combined):
+        raise ValueError("scope.exclude patterns must be non-empty strings")
+    return combined
+
+
+def validate_selection_args(args: SelectionArgs, git_root: Path | None) -> None:
+    """Validate the runner-level scope independently of enabled guards."""
+    has_base_ref = args.base_ref is not None
+    if sum((args.changed_only, args.staged, has_base_ref)) > 1:
+        raise ValueError("use only one file-selection mode: --changed-only, --staged, or --base-ref")
+    if has_base_ref and not args.base_ref.strip():
+        raise ValueError("--base-ref must not be empty")
+    if (args.changed_only or args.staged or has_base_ref) and git_root is None:
+        raise RuntimeError("Git file-selection mode requires a Git repository")
+    if has_base_ref:
+        validate_base_ref(git_root, args.base_ref)
+
+
+def validate_base_ref(root: Path, base_ref: str) -> None:
+    try:
+        subprocess.run(
+            ["git", "merge-base", base_ref, "HEAD"], cwd=root, check=True,
+            capture_output=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        detail = os.fsdecode(exc.stderr).strip()
+        message = f"unable to compare base ref {base_ref!r} with HEAD"
+        raise RuntimeError(f"{message}: {detail}" if detail else message) from exc
+
+
+def git_files(root: Path, staged: bool) -> list[Path]:
+    has_head = subprocess.run(
+        ["git", "rev-parse", "--verify", "--quiet", "HEAD"], cwd=root,
+        check=False, capture_output=True,
+    ).returncode == 0
+    diff_target = ["--cached"] if staged or not has_head else ["HEAD"]
+    result = subprocess.run(
+        ["git", "diff", *diff_target, "--name-only", "--diff-filter=ACMR", "-z"],
+        cwd=root, check=True, capture_output=True,
+    )
+    files = [root / os.fsdecode(path) for path in result.stdout.split(b"\0") if path]
+    if not staged:
+        untracked = subprocess.run(
+            ["git", "ls-files", "--others", "--exclude-standard", "-z"],
+            cwd=root, check=True, capture_output=True,
+        )
+        files.extend(root / os.fsdecode(path) for path in untracked.stdout.split(b"\0") if path)
+    return files
+
+
+def git_base_files(root: Path, base_ref: str) -> list[Path]:
+    try:
+        result = subprocess.run(
+            ["git", "diff", "--name-only", "--diff-filter=ACMR", "-z", f"{base_ref}...HEAD", "--"],
+            cwd=root, check=True, capture_output=True,
+        )
+    except subprocess.CalledProcessError as exc:
+        detail = os.fsdecode(exc.stderr).strip()
+        message = f"unable to compare base ref {base_ref!r} with HEAD"
+        raise RuntimeError(f"{message}: {detail}" if detail else message) from exc
+    return [root / os.fsdecode(path) for path in result.stdout.split(b"\0") if path]
+
+
+def expand_paths(paths: list[Path], git_root: Path | None) -> list[Path]:
+    files: list[Path] = []
+    for path in paths:
+        if path.is_file():
+            files.append(path)
+        elif path.is_dir():
+            if git_root is not None and is_within(path, git_root):
+                files.extend(git_directory_files(git_root, path))
+            else:
+                files.extend(walk_directory_files(path))
+    return files
+
+
+def git_directory_files(root: Path, directory: Path) -> list[Path]:
+    relative = directory.resolve().relative_to(root.resolve())
+    pathspec = "." if not relative.parts else relative.as_posix()
+    result = subprocess.run(
+        ["git", "ls-files", "--cached", "--others", "--exclude-standard", "-z", "--", pathspec],
+        cwd=root, check=True, capture_output=True,
+    )
+    selected = [root / os.fsdecode(value) for value in result.stdout.split(b"\0") if value]
+    return [path for path in selected if not path.is_symlink() and not has_pruned_directory(path, root)]
+
+
+def walk_directory_files(directory: Path) -> list[Path]:
+    files: list[Path] = []
+    for current_root, dir_names, file_names in os.walk(directory):
+        current = Path(current_root)
+        dir_names[:] = sorted(
+            name for name in dir_names
+            if name not in BUILTIN_PRUNED_DIRECTORIES and not (current / name).is_symlink()
+        )
+        files.extend(
+            current / name for name in sorted(file_names)
+            if not (current / name).is_symlink()
+        )
+    return files
+
+
+def has_pruned_directory(path: Path, root: Path) -> bool:
+    relative = path.relative_to(root)
+    return any(part in BUILTIN_PRUNED_DIRECTORIES for part in relative.parts[:-1])
+
+
+def is_within(path: Path, root: Path) -> bool:
+    try:
+        path.resolve().relative_to(root.resolve())
+        return True
+    except ValueError:
+        return False
+
+
+def existing_files(paths: list[Path]) -> list[Path]:
+    """Ignore absent Git-derived entries while retaining every existing artifact."""
+    return [path for path in paths if path.exists() and path.is_file()]

agent_code_guard/guards/__init__.py

@@ -0,0 +1 @@
+"""Internal guard implementations for Agent Code Guard."""

agent_code_guard/guards/callable_size.py

@@ -0,0 +1,79 @@
+"""Callable physical LOC guard over shared provider-neutral analysis facts."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ..reporting import reporting_path
+from ..result_model import CallableFinding, GuardResult
+
+if TYPE_CHECKING:
+    from ..analysis.facts import AnalysisFacts, CallableFact
+
+DEFAULT_REVIEW_AT = 80
+
+
+@dataclass(frozen=True)
+class Config:
+    enabled: bool
+    review_at: int | None = None
+
+
+def load_config(args: argparse.Namespace) -> Config:
+    document: dict[str, Any] = {}
+    if args.config:
+        path = Path(args.config)
+        if not path.exists():
+            raise FileNotFoundError(f"config file not found: {args.config}")
+        document = json.loads(path.read_text(encoding="utf-8"))
+    else:
+        auto = Path(".agent-tools/code-guard.config.json")
+        if auto.exists():
+            document = json.loads(auto.read_text(encoding="utf-8"))
+    if not isinstance(document, dict):
+        raise ValueError("configuration must be an object")
+    guards = document.get("guards", {})
+    if not isinstance(guards, dict):
+        raise ValueError("guards must be an object")
+    data = guards.get("callableSize")
+    if data is None:
+        return Config(True, DEFAULT_REVIEW_AT)
+    if not isinstance(data, dict):
+        raise ValueError("guards.callableSize must be an object")
+    enabled = data.get("enabled", True)
+    if not isinstance(enabled, bool):
+        raise ValueError("guards.callableSize.enabled must be a boolean")
+    if not enabled:
+        return Config(False)
+    review_at = data.get("reviewAt", DEFAULT_REVIEW_AT)
+    if isinstance(review_at, bool) or not isinstance(review_at, int) or review_at <= 0:
+        raise ValueError("guards.callableSize.reviewAt must be a positive integer")
+    return Config(True, review_at)
+
+
+def run(root: Path, config: Config, analysis_facts: AnalysisFacts) -> GuardResult:
+    if not config.enabled:
+        return GuardResult("callableSize", "pass", [])
+    findings = [evaluate(root, config, fact) for fact in analysis_facts.callables]
+    findings.sort(key=lambda finding: (finding.path, finding.start_line, finding.end_line, finding.callable))
+    state = "review" if any(finding.state == "review" for finding in findings) else "pass"
+    return GuardResult("callableSize", state, findings)
+
+
+def evaluate(root: Path, config: Config, fact: CallableFact) -> CallableFinding:
+    assert config.review_at is not None
+    measured = fact.source_range.physical_loc
+    return CallableFinding(
+        path=reporting_path(fact.path, root),
+        callable=fact.identity,
+        start_line=fact.source_range.start_line,
+        end_line=fact.source_range.end_line,
+        measured=measured,
+        state="review" if measured > config.review_at else "pass",
+        thresholds={"reviewAt": config.review_at},
+        embedded_language=fact.embedded_language,
+    )

agent_code_guard/guards/complexity.py

@@ -0,0 +1,94 @@
+"""Cyclomatic complexity guard over shared normalized decision facts."""
+
+from __future__ import annotations
+
+import argparse
+from collections import Counter
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import TYPE_CHECKING, Any
+
+from ..reporting import reporting_path
+from ..result_model import CallableFinding, GuardResult
+
+if TYPE_CHECKING:
+    from ..analysis.facts import AnalysisFacts, CallableFact, DecisionFact
+
+DEFAULT_REVIEW_AT = 15
+
+
+@dataclass(frozen=True)
+class Config:
+    enabled: bool
+    review_at: int | None = None
+
+
+def load_config(args: argparse.Namespace) -> Config:
+    document: dict[str, Any] = {}
+    if args.config:
+        path = Path(args.config)
+        if not path.exists():
+            raise FileNotFoundError(f"config file not found: {args.config}")
+        document = json.loads(path.read_text(encoding="utf-8"))
+    else:
+        auto = Path(".agent-tools/code-guard.config.json")
+        if auto.exists():
+            document = json.loads(auto.read_text(encoding="utf-8"))
+    if not isinstance(document, dict):
+        raise ValueError("configuration must be an object")
+    guards = document.get("guards", {})
+    if not isinstance(guards, dict):
+        raise ValueError("guards must be an object")
+    data = guards.get("cyclomaticComplexity")
+    if data is None:
+        return Config(True, DEFAULT_REVIEW_AT)
+    if not isinstance(data, dict):
+        raise ValueError("guards.cyclomaticComplexity must be an object")
+    enabled = data.get("enabled", True)
+    if not isinstance(enabled, bool):
+        raise ValueError("guards.cyclomaticComplexity.enabled must be a boolean")
+    if not enabled:
+        return Config(False)
+    review_at = data.get("reviewAt", DEFAULT_REVIEW_AT)
+    if isinstance(review_at, bool) or not isinstance(review_at, int) or review_at <= 0:
+        raise ValueError("guards.cyclomaticComplexity.reviewAt must be a positive integer")
+    return Config(True, review_at)
+
+
+def run(root: Path, config: Config, analysis_facts: AnalysisFacts) -> GuardResult:
+    if not config.enabled:
+        return GuardResult("complexity", "pass", [])
+    decisions_by_callable: dict[object, list[DecisionFact]] = {}
+    for decision in analysis_facts.decisions:
+        decisions_by_callable.setdefault(decision.callable_key, []).append(decision)
+    findings = [
+        evaluate(root, config, callable_fact, decisions_by_callable.get(callable_fact.key, []))
+        for callable_fact in analysis_facts.callables
+    ]
+    findings.sort(key=lambda finding: (finding.path, finding.start_line, finding.end_line, finding.callable))
+    state = "review" if any(finding.state == "review" for finding in findings) else "pass"
+    return GuardResult("complexity", state, findings)
+
+
+def evaluate(
+    root: Path,
+    config: Config,
+    callable_fact: CallableFact,
+    decisions: list[DecisionFact] | tuple[DecisionFact, ...],
+) -> CallableFinding:
+    assert config.review_at is not None
+    counts = Counter(decision.category for decision in decisions)
+    breakdown = {category: counts[category] for category in sorted(counts) if counts[category]}
+    measured = 1 + len(decisions)
+    return CallableFinding(
+        path=reporting_path(callable_fact.path, root),
+        callable=callable_fact.identity,
+        start_line=callable_fact.source_range.start_line,
+        end_line=callable_fact.source_range.end_line,
+        measured=measured,
+        state="review" if measured > config.review_at else "pass",
+        thresholds={"reviewAt": config.review_at},
+        details={"boundaryKind": callable_fact.boundary_kind, "decisions": breakdown},
+        embedded_language=callable_fact.embedded_language,
+    )