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

agent_code_guard/guards/loc.py

@@ -0,0 +1,235 @@
+"""Canonical LOC guard, migrated from Agent LOC Guard commit 75ab39d."""
+
+from __future__ import annotations
+
+import argparse
+import json
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from ..result_model import Finding, GuardResult
+from ..path_matching import matches_path_glob, relative_or_absolute_path
+
+DEFAULT_WARN_AT = 400
+DEFAULT_FAIL_AT = 600
+DEFAULT_INCLUDE_EXTENSIONS = {
+    ".cs", ".cshtml", ".razor", ".js", ".jsx", ".ts", ".tsx", ".py", ".java",
+    ".kt", ".kts", ".scala", ".go", ".rs", ".swift", ".dart", ".zig", ".cpp",
+    ".c", ".h", ".hpp", ".m", ".mm", ".fs", ".fsx", ".vb", ".css", ".scss",
+    ".html", ".vue", ".php", ".rb", ".ex", ".exs", ".erl", ".hrl", ".clj",
+    ".cljs", ".cljc", ".lua", ".sql", ".sh", ".ps1",
+}
+DEFAULT_EXCLUDES = [
+    "**/.git/**", "**/.vs/**", "**/.idea/**", "**/.vscode/**", "**/bin/**", "**/obj/**",
+    "**/node_modules/**", "**/dist/**", "**/build/**", "**/coverage/**", "**/generated/**",
+    "**/Generated/**", "**/vendor/**", "**/Vendor/**", "**/Migrations/**", "**/*.g.cs",
+    "**/*.generated.cs", "**/*.Designer.cs", "**/*.designer.cs", "**/*.min.js", "**/*.min.css",
+]
+COMMENT_PREFIXES = {
+    ".cs": ["//"], ".cshtml": ["@*"], ".razor": ["@*", "//"], ".js": ["//"],
+    ".jsx": ["//"], ".ts": ["//"], ".tsx": ["//"], ".py": ["#"], ".java": ["//"],
+    ".kt": ["//"], ".kts": ["//"], ".scala": ["//"], ".go": ["//"], ".rs": ["//"],
+    ".swift": ["//"], ".dart": ["//"], ".zig": ["//"], ".cpp": ["//"], ".c": ["//"],
+    ".h": ["//"], ".hpp": ["//"], ".m": ["//"], ".mm": ["//"], ".fs": ["//"],
+    ".fsx": ["//"], ".vb": ["'"], ".css": ["/*"], ".scss": ["//", "/*"],
+    ".html": ["<!--"], ".vue": ["<!--"], ".php": ["//", "#"], ".rb": ["#"],
+    ".ex": ["#"], ".exs": ["#"], ".erl": ["%"], ".hrl": ["%"], ".clj": [";"],
+    ".cljs": [";"], ".cljc": [";"], ".lua": ["--"], ".sql": ["--"], ".sh": ["#"],
+    ".ps1": ["#"],
+}
+
+
+@dataclass(frozen=True)
+class AllowedLargeFile:
+    path: str
+    reason: str
+
+
+@dataclass(frozen=True)
+class ThresholdOverride:
+    match: list[str]
+    warn_at: int
+    fail_at: int
+
+
+@dataclass(frozen=True)
+class Config:
+    enabled: bool
+    warn_at: int
+    fail_at: int
+    count_blank_lines: bool
+    count_comment_lines: bool
+    include_extensions: set[str]
+    exclude: list[str]
+    allowed_large_files: list[AllowedLargeFile]
+    overrides: list[ThresholdOverride]
+
+
+def load_config(args: argparse.Namespace) -> Config:
+    document: dict[str, Any] = {}
+    config_path = args.config
+    if config_path:
+        path = Path(config_path)
+        if not path.exists():
+            raise FileNotFoundError(f"config file not found: {config_path}")
+        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("loc", {})
+    if not isinstance(data, dict):
+        raise ValueError("guards.loc must be an object")
+    enabled = data.get("enabled", True)
+    if not isinstance(enabled, bool):
+        raise ValueError("guards.loc.enabled must be a boolean")
+
+    warn_at = args.warn if args.warn is not None else data.get("warnAt", DEFAULT_WARN_AT)
+    fail_at = args.fail if args.fail is not None else data.get("failAt", DEFAULT_FAIL_AT)
+    warn_at = parse_positive_integer(warn_at, "guards.loc.warnAt")
+    fail_at = parse_positive_integer(fail_at, "guards.loc.failAt")
+    if warn_at >= fail_at:
+        raise ValueError("guards.loc.warnAt must be lower than guards.loc.failAt")
+    extensions = data.get("includeExtensions", list(DEFAULT_INCLUDE_EXTENSIONS))
+    if not isinstance(extensions, list) or any(not isinstance(value, str) for value in extensions):
+        raise ValueError("guards.loc.includeExtensions must be an array of strings")
+    include_extensions = {normalise_extension(value) for value in extensions}
+    include_extensions.update(normalise_extension(value) for value in args.include)
+    exclude = data.get("exclude", DEFAULT_EXCLUDES)
+    if not isinstance(exclude, list) or any(not isinstance(value, str) for value in exclude):
+        raise ValueError("guards.loc.exclude must be an array of strings")
+    exclude = list(exclude) + args.exclude
+    count_blank = data.get("countBlankLines", False)
+    count_comments = data.get("countCommentLines", True)
+    if not isinstance(count_blank, bool) or not isinstance(count_comments, bool):
+        raise ValueError("guards.loc line-count options must be booleans")
+    return Config(
+        enabled, warn_at, fail_at, count_blank or args.count_blank_lines,
+        False if args.ignore_comment_lines else count_comments, include_extensions, exclude,
+        parse_allowed_large_files(data.get("allowedLargeFiles", [])),
+        parse_overrides(data.get("overrides", [])),
+    )
+
+
+def parse_allowed_large_files(value: Any) -> list[AllowedLargeFile]:
+    if not isinstance(value, list):
+        raise ValueError("guards.loc.allowedLargeFiles must be an array")
+    allowed = []
+    for index, item in enumerate(value):
+        location = f"guards.loc.allowedLargeFiles[{index}]"
+        if not isinstance(item, dict):
+            raise ValueError(f"{location} must be an object")
+        path = item.get("path")
+        reason = item.get("reason")
+        if not isinstance(path, str) or not path.strip():
+            raise ValueError(f"{location}.path must be a non-empty string")
+        if not isinstance(reason, str) or not reason.strip():
+            raise ValueError(f"{location}.reason must be a non-empty string")
+        allowed.append(AllowedLargeFile(path.replace("\\", "/"), reason))
+    return allowed
+
+
+def parse_overrides(value: Any) -> list[ThresholdOverride]:
+    if not isinstance(value, list):
+        raise ValueError("guards.loc.overrides must be an array")
+    overrides = []
+    for index, item in enumerate(value):
+        location = f"guards.loc.overrides[{index}]"
+        if not isinstance(item, dict):
+            raise ValueError(f"{location} must be an object")
+        patterns = item.get("match")
+        if not isinstance(patterns, list) or not patterns or any(
+            not isinstance(pattern, str) or not pattern.strip() for pattern in patterns
+        ):
+            raise ValueError(f"{location}.match must be a non-empty array of non-empty strings")
+        warn_at = parse_positive_integer(item.get("warnAt"), f"{location}.warnAt")
+        fail_at = parse_positive_integer(item.get("failAt"), f"{location}.failAt")
+        if warn_at >= fail_at:
+            raise ValueError(f"{location}.warnAt must be lower than {location}.failAt")
+        overrides.append(ThresholdOverride([pattern.replace("\\", "/") for pattern in patterns], warn_at, fail_at))
+    return overrides
+
+
+def parse_positive_integer(value: Any, location: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value <= 0:
+        raise ValueError(f"{location} must be a positive integer")
+    return value
+
+
+def normalise_extension(value: str) -> str:
+    value = value.strip()
+    return value if not value or value.startswith(".") else f".{value}"
+
+
+def run(root: Path, config: Config, selected_files: tuple[Path, ...]) -> GuardResult:
+    if not config.enabled:
+        return GuardResult("loc", "pass", [])
+    files = [path for path in selected_files if should_include(path, config, root)]
+    findings = [evaluate(path, config, root) for path in sorted(set(files), key=lambda p: relative_path(p, root))]
+    state = "fail" if any(item.state == "fail" for item in findings) else (
+        "review" if any(item.state == "review" for item in findings) else "pass"
+    )
+    return GuardResult("loc", state, findings)
+
+
+def should_include(path: Path, config: Config, root: Path) -> bool:
+    return path.suffix in config.include_extensions and not any(
+        matches_path_glob(relative_path(path, root), pattern) for pattern in config.exclude
+    )
+
+
+def evaluate(path: Path, config: Config, root: Path) -> Finding:
+    rel = relative_path(path, root)
+    counted = count_loc(path, config)
+    warn_at, fail_at, override_index = effective_thresholds(rel, config)
+    allowed = next((item for item in config.allowed_large_files if matches_path_glob(rel, item.path)), None)
+    if allowed and counted > warn_at:
+        native_status, state, reason = "exempt", "pass", allowed.reason
+    elif counted > fail_at:
+        native_status, state, reason = "fail", "fail", None
+    elif counted > warn_at:
+        native_status, state, reason = "warn", "review", None
+    else:
+        native_status, state, reason = "ok", "pass", None
+    return Finding(rel, state, native_status, counted, warn_at, fail_at, override_index, reason)
+
+
+def count_loc(path: Path, config: Config) -> int:
+    count = 0
+    prefixes = COMMENT_PREFIXES.get(path.suffix, [])
+    with path.open("r", encoding="utf-8", errors="ignore") as handle:
+        for raw_line in handle:
+            stripped = raw_line.rstrip("\n\r").strip()
+            if not config.count_blank_lines and not stripped:
+                continue
+            if not config.count_comment_lines and is_simple_comment_line(stripped, prefixes, path.suffix):
+                continue
+            count += 1
+    return count
+
+
+def is_simple_comment_line(stripped: str, prefixes: list[str], extension: str) -> bool:
+    if not stripped or (extension == ".php" and stripped.startswith("#[")):
+        return False
+    return any(stripped.startswith(prefix) for prefix in prefixes)
+
+
+def effective_thresholds(rel: str, config: Config) -> tuple[int, int, int | None]:
+    selected = None
+    for index, override in enumerate(config.overrides):
+        if any(matches_path_glob(rel, pattern) for pattern in override.match):
+            selected = (index, override)
+    if selected is None:
+        return config.warn_at, config.fail_at, None
+    index, override = selected
+    return override.warn_at, override.fail_at, index
+
+
+def relative_path(path: Path, root: Path) -> str:
+    return relative_or_absolute_path(path, root)

agent_code_guard/guards/markdown_document_size.py

@@ -0,0 +1,66 @@
+"""Markdown document physical-size review guard."""
+
+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 GuardResult, MarkdownDocumentFinding
+
+if TYPE_CHECKING:
+    from ..markdown.facts import MarkdownFacts
+
+DEFAULT_REVIEW_AT = 800
+
+
+@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("markdownDocumentSize")
+    if data is None:
+        return Config(True, DEFAULT_REVIEW_AT)
+    if not isinstance(data, dict):
+        raise ValueError("guards.markdownDocumentSize must be an object")
+    enabled = data.get("enabled", True)
+    if not isinstance(enabled, bool):
+        raise ValueError("guards.markdownDocumentSize.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.markdownDocumentSize.reviewAt must be a positive integer")
+    return Config(True, review_at)
+
+
+def run(root: Path, config: Config, facts: MarkdownFacts) -> GuardResult:
+    assert config.review_at is not None
+    findings = [MarkdownDocumentFinding(
+        reporting_path(fact.path, root), fact.physical_lines,
+        "review" if fact.physical_lines > config.review_at else "pass",
+        {"reviewAt": config.review_at},
+    ) for fact in facts.documents]
+    findings.sort(key=lambda finding: finding.path)
+    return GuardResult("markdownDocumentSize", "review" if any(item.state == "review" for item in findings) else "pass", findings)

agent_code_guard/guards/markdown_section_size.py

@@ -0,0 +1,66 @@
+"""Markdown heading-delimited direct-section physical-size review guard."""
+
+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 GuardResult, MarkdownSectionFinding
+
+if TYPE_CHECKING:
+    from ..markdown.facts import MarkdownFacts
+
+DEFAULT_REVIEW_AT = 200
+
+
+@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("markdownSectionSize")
+    if data is None:
+        return Config(True, DEFAULT_REVIEW_AT)
+    if not isinstance(data, dict):
+        raise ValueError("guards.markdownSectionSize must be an object")
+    enabled = data.get("enabled", True)
+    if not isinstance(enabled, bool):
+        raise ValueError("guards.markdownSectionSize.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.markdownSectionSize.reviewAt must be a positive integer")
+    return Config(True, review_at)
+
+
+def run(root: Path, config: Config, facts: MarkdownFacts) -> GuardResult:
+    assert config.review_at is not None
+    findings = [MarkdownSectionFinding(
+        reporting_path(document.path, root), section.heading, section.level,
+        section.start_line, section.end_line, section.physical_lines,
+        "review" if section.physical_lines > config.review_at else "pass", {"reviewAt": config.review_at},
+    ) for document in facts.documents for section in document.sections]
+    findings.sort(key=lambda finding: (finding.path, finding.start_line, finding.end_line, finding.heading))
+    return GuardResult("markdownSectionSize", "review" if any(item.state == "review" for item in findings) else "pass", findings)

agent_code_guard/guards/nesting.py

@@ -0,0 +1,109 @@
+"""Structural nesting guard over shared provider-neutral control-flow 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, ControlFlowFact, SourceRange
+
+DEFAULT_REVIEW_AT = 4
+
+
+@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("nesting")
+    if data is None:
+        return Config(True, DEFAULT_REVIEW_AT)
+    if not isinstance(data, dict):
+        raise ValueError("guards.nesting must be an object")
+    enabled = data.get("enabled", True)
+    if not isinstance(enabled, bool):
+        raise ValueError("guards.nesting.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.nesting.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("nesting", "pass", [])
+    controls_by_callable: dict[object, list[ControlFlowFact]] = {}
+    for control in analysis_facts.controls:
+        controls_by_callable.setdefault(control.callable_key, []).append(control)
+    findings = [
+        evaluate(root, config, callable_fact, controls_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("nesting", state, findings)
+
+
+def evaluate(
+    root: Path,
+    config: Config,
+    callable_fact: CallableFact,
+    controls: list[ControlFlowFact] | tuple[ControlFlowFact, ...],
+) -> CallableFinding:
+    assert config.review_at is not None
+    depth, deepest_line = _maximum_depth(controls)
+    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=depth,
+        state="review" if depth > config.review_at else "pass",
+        thresholds={"reviewAt": config.review_at},
+        details={"deepestLine": deepest_line} if deepest_line is not None else None,
+        embedded_language=callable_fact.embedded_language,
+    )
+
+
+def _maximum_depth(controls: list[ControlFlowFact] | tuple[ControlFlowFact, ...]) -> tuple[int, int | None]:
+    depth_by_range: dict[SourceRange, int] = {}
+    maximum = 0
+    deepest_line: int | None = None
+    ordered = sorted(
+        controls,
+        key=lambda fact: (fact.source_range.start.byte_offset, fact.source_range.end.byte_offset),
+    )
+    for fact in ordered:
+        parent_depth = depth_by_range.get(fact.parent_control_range, 0)
+        depth = parent_depth + int(fact.increases_nesting)
+        depth_by_range[fact.source_range] = depth
+        if depth > maximum:
+            maximum = depth
+            deepest_line = fact.source_range.start_line
+    return maximum, deepest_line

agent_code_guard/markdown/__init__.py

@@ -0,0 +1,6 @@
+"""Immutable Markdown structure facts from a bounded standard-library scan."""
+
+from .facts import MarkdownDocumentFact, MarkdownFacts, MarkdownSectionFact
+from .scanner import analyze_files, scan_text
+
+__all__ = ["MarkdownDocumentFact", "MarkdownFacts", "MarkdownSectionFact", "analyze_files", "scan_text"]

agent_code_guard/markdown/facts.py

@@ -0,0 +1,27 @@
+"""Concrete immutable facts for Markdown size guards."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+
+@dataclass(frozen=True)
+class MarkdownSectionFact:
+    heading: str
+    level: int
+    start_line: int
+    end_line: int
+    physical_lines: int
+
+
+@dataclass(frozen=True)
+class MarkdownDocumentFact:
+    path: Path
+    physical_lines: int
+    sections: tuple[MarkdownSectionFact, ...]
+
+
+@dataclass(frozen=True)
+class MarkdownFacts:
+    documents: tuple[MarkdownDocumentFact, ...]

agent_code_guard/markdown/scanner.py

@@ -0,0 +1,109 @@
+"""Bounded CommonMark-informed scanner for admitted Markdown size facts."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+from .facts import MarkdownDocumentFact, MarkdownFacts, MarkdownSectionFact
+
+_ATX = re.compile(r"^ {0,3}(#{1,6})(?:[ \t]+(.*?)|[ \t]*)$")
+_SETEXT = re.compile(r"^ {0,3}(=+|-+)[ \t]*$")
+_FENCE_OPEN = re.compile(r"^ {0,3}(`{3,}|~{3,})(.*)$")
+_BLOCK_PREFIX = re.compile(r"^ {0,3}(?:>|[-+*][ \t]+|\d{1,9}[.)][ \t]+|<)")
+
+
+@dataclass(frozen=True)
+class _Heading:
+    text: str
+    level: int
+    start_line: int
+    end_line: int
+
+
+@dataclass(frozen=True)
+class _Fence:
+    marker: str
+    length: int
+
+
+def analyze_files(files: tuple[Path, ...] | list[Path]) -> MarkdownFacts:
+    applicable = sorted(
+        {path.resolve() for path in files if path.suffix.lower() == ".md"},
+        key=lambda path: path.as_posix(),
+    )
+    return MarkdownFacts(tuple(scan_text(path, path.read_text(encoding="utf-8")) for path in applicable))
+
+
+def scan_text(path: Path, text: str) -> MarkdownDocumentFact:
+    lines = text.splitlines()
+    headings = _scan_headings(lines)
+    sections = []
+    for index, heading in enumerate(headings):
+        end_line = headings[index + 1].start_line - 1 if index + 1 < len(headings) else len(lines)
+        sections.append(MarkdownSectionFact(
+            heading.text, heading.level, heading.start_line, end_line,
+            end_line - heading.start_line + 1,
+        ))
+    return MarkdownDocumentFact(path, len(lines), tuple(sections))
+
+
+def _scan_headings(lines: list[str]) -> list[_Heading]:
+    headings: list[_Heading] = []
+    fence: _Fence | None = None
+    for index, line in enumerate(lines):
+        line_number = index + 1
+        if fence:
+            if _closes_fence(line, fence):
+                fence = None
+            continue
+        opened = _opens_fence(line)
+        if opened:
+            fence = opened
+            continue
+        atx = _atx_heading(line, line_number)
+        if atx:
+            headings.append(atx)
+            continue
+        setext = _setext_heading(lines, index)
+        if setext and (not headings or headings[-1].end_line != line_number - 1):
+            headings.append(setext)
+    return headings
+
+
+def _opens_fence(line: str) -> _Fence | None:
+    match = _FENCE_OPEN.match(line)
+    if not match:
+        return None
+    run, info = match.groups()
+    if run[0] == "`" and "`" in info:
+        return None
+    return _Fence(run[0], len(run))
+
+
+def _closes_fence(line: str, fence: _Fence) -> bool:
+    return bool(re.match(rf"^ {{0,3}}{re.escape(fence.marker)}{{{fence.length},}}[ \t]*$", line))
+
+
+def _atx_heading(line: str, line_number: int) -> _Heading | None:
+    match = _ATX.match(line)
+    if not match:
+        return None
+    hashes, raw_text = match.groups()
+    text = re.sub(r"[ \t]+#+[ \t]*$", "", raw_text or "").strip()
+    return _Heading(text, len(hashes), line_number, line_number)
+
+
+def _setext_heading(lines: list[str], index: int) -> _Heading | None:
+    match = _SETEXT.match(lines[index]) if index else None
+    if not match:
+        return None
+    title = lines[index - 1]
+    if index >= 2 and lines[index - 2].strip():
+        return None
+    if not title.strip() or len(title) - len(title.lstrip(" ")) >= 4:
+        return None
+    if _ATX.match(title) or _FENCE_OPEN.match(title) or _BLOCK_PREFIX.match(title):
+        return None
+    return _Heading(title.strip(), 1 if match.group(1)[0] == "=" else 2, index, index + 1)

agent_code_guard/path_matching.py

@@ -0,0 +1,25 @@
+"""Shared normalized path matching for common scope and guard policies."""
+
+from __future__ import annotations
+
+import fnmatch
+from pathlib import Path
+
+
+def matches_path_glob(path: str, pattern: str) -> bool:
+    normalised_path = path.replace("\\", "/").removeprefix("./")
+    normalised_pattern = pattern.replace("\\", "/").removeprefix("./")
+    if normalised_path == normalised_pattern:
+        return True
+    candidates = [normalised_pattern]
+    while normalised_pattern.startswith("**/"):
+        normalised_pattern = normalised_pattern[3:]
+        candidates.append(normalised_pattern)
+    return any(fnmatch.fnmatch(normalised_path, candidate) for candidate in candidates)
+
+
+def relative_or_absolute_path(path: Path, root: Path) -> str:
+    try:
+        return path.resolve().relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return path.resolve().as_posix()

agent_code_guard/reporting.py

@@ -0,0 +1,11 @@
+"""Small shared helpers for stable result reporting."""
+
+from pathlib import Path
+
+
+def reporting_path(path: Path, root: Path) -> str:
+    resolved = path.resolve()
+    try:
+        return resolved.relative_to(root.resolve()).as_posix()
+    except ValueError:
+        return resolved.as_posix()