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

agent_code_guard/result_model.py

@@ -0,0 +1,128 @@
+"""Normalized results shared by Code Guard runners and guard modules."""
+
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from typing import Any
+
+
+STATE_RANK = {"pass": 0, "review": 1, "fail": 2}
+
+
+@dataclass(frozen=True)
+class Finding:
+    path: str
+    state: str
+    native_status: str
+    counted_loc: int
+    warn_at: int
+    fail_at: int
+    override_index: int | None = None
+    reason: str | None = None
+
+    def to_json(self) -> dict[str, Any]:
+        data = asdict(self)
+        return {
+            "path": data["path"],
+            "state": data["state"],
+            "nativeStatus": data["native_status"],
+            "countedLoc": data["counted_loc"],
+            "warnAt": data["warn_at"],
+            "failAt": data["fail_at"],
+            "overrideIndex": data["override_index"],
+            "reason": data["reason"],
+        }
+
+
+@dataclass(frozen=True)
+class CallableFinding:
+    """Additive result shape proven by analyzer research; unused by LOC."""
+
+    path: str
+    callable: str
+    start_line: int
+    end_line: int
+    measured: int
+    state: str
+    thresholds: dict[str, int] | None = None
+    details: dict[str, Any] | None = None
+    embedded_language: str | None = None
+
+    def to_json(self) -> dict[str, Any]:
+        value = {
+            "path": self.path,
+            "callable": self.callable,
+            "range": {"startLine": self.start_line, "endLine": self.end_line},
+            "measured": self.measured,
+            "state": self.state,
+            "thresholds": self.thresholds,
+        }
+        if self.details is not None:
+            value["details"] = self.details
+        if self.embedded_language is not None:
+            value["embeddedLanguage"] = self.embedded_language
+        return value
+
+
+@dataclass(frozen=True)
+class MarkdownDocumentFinding:
+    path: str
+    measured: int
+    state: str
+    thresholds: dict[str, int]
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "measured": self.measured,
+            "state": self.state,
+            "thresholds": self.thresholds,
+        }
+
+
+@dataclass(frozen=True)
+class MarkdownSectionFinding:
+    path: str
+    heading: str
+    level: int
+    start_line: int
+    end_line: int
+    measured: int
+    state: str
+    thresholds: dict[str, int]
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "path": self.path,
+            "heading": self.heading,
+            "level": self.level,
+            "range": {"startLine": self.start_line, "endLine": self.end_line},
+            "measured": self.measured,
+            "state": self.state,
+            "thresholds": self.thresholds,
+        }
+
+
+@dataclass(frozen=True)
+class GuardResult:
+    guard_id: str
+    state: str
+    findings: list[Finding | CallableFinding | MarkdownDocumentFinding | MarkdownSectionFinding]
+
+    @property
+    def required_policies(self) -> list[str]:
+        return [self.guard_id] if self.state in {"review", "fail"} else []
+
+    def to_json(self) -> dict[str, Any]:
+        return {
+            "state": self.state,
+            "findings": [finding.to_json() for finding in self.findings],
+        }
+
+
+def aggregate_state(results: list[GuardResult]) -> str:
+    return max((result.state for result in results), key=STATE_RANK.get, default="pass")
+
+
+def required_policies(results: list[GuardResult]) -> list[str]:
+    return sorted({policy for result in results for policy in result.required_policies})

agent_code_guard/skill_distribution.py

@@ -0,0 +1,96 @@
+"""Locate and export the version-coupled Code Guard skill payload."""
+
+from __future__ import annotations
+
+from importlib.metadata import distribution, version
+import json
+from pathlib import Path
+import shutil
+from urllib.parse import unquote, urlparse
+from urllib.request import url2pathname
+
+
+PAYLOAD_FILES = (
+    "SKILL.md",
+    "LICENSE.txt",
+    "agents/openai.yaml",
+    "references/callable-size-policy.md",
+    "references/complexity-policy.md",
+    "references/loc-policy.md",
+    "references/markdown-size-policy.md",
+    "references/nesting-policy.md",
+)
+
+
+def skill_path() -> Path:
+    """Return the installed canonical skill payload directory."""
+    package = distribution("agent-code-guard")
+    suffix = "share/agent-code-guard/skill/SKILL.md"
+    path = next(
+        (
+            Path(package.locate_file(item)).parent
+            for item in package.files or ()
+            if str(item).replace("\\", "/").endswith(suffix)
+        ),
+        None,
+    )
+    if path is None:
+        path = _editable_skill_path(package)
+    if path is None:
+        raise ValueError("installed distribution does not contain the Code Guard skill payload")
+    _validate_payload(path)
+    return path.resolve()
+
+
+def export_skill(target: Path) -> Path:
+    """Copy the installed payload into an empty caller-owned directory."""
+    target = target.expanduser().resolve()
+    if target.exists():
+        if not target.is_dir():
+            raise ValueError(f"skill export target is not a directory: {target}")
+        if any(target.iterdir()):
+            raise ValueError(f"skill export target is not empty: {target}")
+    else:
+        target.mkdir(parents=True)
+
+    source_root = skill_path()
+    for relative in PAYLOAD_FILES:
+        source = source_root / relative
+        if source.is_symlink() or not source.is_file():
+            raise ValueError(f"installed skill payload has an unsafe or missing file: {relative}")
+        destination = target / relative
+        destination.parent.mkdir(parents=True, exist_ok=True)
+        shutil.copyfile(source, destination)
+    (target / ".agent-code-guard-version").write_text(
+        f'{version("agent-code-guard")}\n', encoding="utf-8", newline="\n",
+    )
+    return target
+
+
+def _validate_payload(path: Path) -> None:
+    if path.is_symlink() or not path.is_dir():
+        raise ValueError(f"installed skill payload is missing: {path}")
+    for relative in PAYLOAD_FILES:
+        candidate = path / relative
+        relative_path = Path(relative)
+        parents = (
+            path.joinpath(*relative_path.parts[:index])
+            for index in range(1, len(relative_path.parts))
+        )
+        if any(parent.is_symlink() for parent in parents) or candidate.is_symlink() or not candidate.is_file():
+            raise ValueError(f"installed skill payload has an unsafe or missing file: {relative}")
+
+
+def _editable_skill_path(package) -> Path | None:
+    """Use PEP 610 metadata when setuptools omits data-files from editable wheels."""
+    direct_url = package.read_text("direct_url.json")
+    if direct_url is None:
+        return None
+    metadata = json.loads(direct_url)
+    if not metadata.get("dir_info", {}).get("editable"):
+        return None
+    parsed = urlparse(metadata.get("url", ""))
+    if parsed.scheme != "file":
+        return None
+    checkout = Path(url2pathname(unquote(parsed.path)))
+    return checkout / "skills" / "code-guard"

agent_code_guard-0.1.0.data/data/share/agent-code-guard/skill/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stef Karyotidis
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

agent_code_guard-0.1.0.data/data/share/agent-code-guard/skill/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: code-guard
+description: Use when creating, editing, reviewing, or refactoring supported code or Markdown documentation to run deterministic guardrails and load only the policy guidance required by triggered findings.
+license: Complete terms in LICENSE.txt
+---
+
+# Code Guard
+
+Use this skill whenever supported code or Markdown documentation artifacts are created, edited, reviewed, or refactored.
+
+Code Guard provides deterministic measurements that act as anchors for agent judgment. The measurement is objective; the response to a `REVIEW` finding still requires design judgment.
+
+## Result states
+
+- `PASS` — no special action is required.
+- `REVIEW` — inspect the finding and either accept it with a meaningful justification or improve the code when doing so improves real clarity, cohesion, or boundaries.
+- `FAIL` — do not declare normal completion until the condition is fixed or an explicitly permitted/user-approved exception applies.
+
+## Universal rules
+
+1. Never game a metric.
+2. Preserve readability and the repository's normal formatting/style conventions.
+3. Do not compress independent statements, remove useful structure/comments, obscure control flow, or minify handwritten source to lower a measurement.
+4. Do not create meaningless helpers, artificial files, unnecessary abstractions, or indirection mainly to reduce a metric.
+5. `REVIEW` is not an automatic refactor instruction.
+6. Refactor only when the change improves the code rather than merely improving the score.
+7. Do not create, broaden, or alter policy exceptions/configuration solely to make Code Guard pass without explicit user approval.
+8. Do not expand the current task to unrelated pre-existing debt. Normal development checks changed/current-work files; full-repository audit is separate.
+
+## Workflow
+
+With Git, run the installed Code Guard command after supported code or Markdown documentation edits:
+
+```bash
+code-guard . --changed-only
+```
+
+An installed Agent Code Guard distribution provides both the command and this
+version-matched skill payload. The skill's normal execution route is always the
+installed `code-guard` command.
+
+For repository development only, the compatibility runner remains available
+directly from a checkout. It is not part of the externally installed skill
+payload or the normal end-user execution route:
+
+```bash
+python3 skills/code-guard/scripts/code_guard.py . --changed-only
+```
+
+`pyproject.toml` canonically owns the production pins. Tree-sitter remains
+dormant during LOC-only execution; failure to load a required provider or
+grammar is a deterministic tool error during normal zero-config syntax analysis.
+Disabling every syntax guard preserves the lazy no-Tree-sitter path. A strictly
+LOC-only result also requires both Markdown guards to be explicitly disabled.
+
+Without Git or another VCS that can provide changed scope, pass exactly the files you created or modified. You are responsible for supplying the complete edited-file set:
+
+```bash
+code-guard src/Foo.py src/Bar.ts docs/guide.md
+```
+
+Do not create a manifest or temporary scope file. Specific positional files mean “inspect these artifacts.” A directory or `.` means a deliberate recursive audit when no Git selector is used. Positional files/directories bound the candidates selected by `--changed-only`, `--staged`, or `--base-ref`; Git selection fails outside a Git repository and never falls back to an audit.
+
+Recursive directory discovery does not follow symlinks. An explicitly supplied
+file symlink is treated as caller intent; an explicit directory symlink is
+rejected rather than recursively traversed.
+
+Prefer normal zero-config scope and respect project `scope.exclude`; do not
+remove or alter exclusions merely to silence findings. Repeated
+`--scope-exclude` is caller-supplied all-guard scope policy and composes with
+project exclusions. LOC `--exclude` remains LOC-specific. Explicit files may
+intentionally inspect Git-ignored or built-in-pruned artifacts, unless Code
+Guard `scope.exclude` or `--scope-exclude` removes them.
+
+When all guards return `PASS`, no detailed policy file needs to be loaded.
+
+When a guard returns `REVIEW` or `FAIL`, read only the policy file named by that finding. The runner returns required policy identifiers/files in both human-readable and JSON output.
+
+Policy references:
+
+- file LOC: `references/loc-policy.md`
+- callable size: `references/callable-size-policy.md`
+- nesting depth: `references/nesting-policy.md`
+- cyclomatic complexity: `references/complexity-policy.md`
+- Markdown document/section size: `references/markdown-size-policy.md`
+
+Do not load unrelated guard policies merely because they exist.
+
+## Scope
+
+Code Guard is intentionally limited to deterministic concerns that are broadly applicable across conventional programming languages.
+
+Guards:
+
+- file LOC (implemented and enabled by default);
+- source/container and syntax facts (production infrastructure, not a guard);
+- callable LOC (implemented and enabled by default; REVIEW greater than 80);
+- structural nesting (implemented and enabled by default; REVIEW greater than 4);
+- cyclomatic complexity (implemented and enabled by default; REVIEW greater than 15).
+- Markdown document physical size (implemented for `.md` and enabled by default; REVIEW greater than 800);
+- Markdown direct-section physical size (implemented for `.md` and enabled by default; REVIEW greater than 200).
+
+Callable LOC needs no invented configuration to activate it. Omission or
+`enabled: true` uses 80; an authorized positive-integer `reviewAt` overrides it,
+and `enabled: false` disables it. Exactly the effective threshold passes;
+larger callables review and never fail. Load
+`references/callable-size-policy.md` only when `callableSize` appears in
+`requiredPolicies`.
+
+Structural nesting is executable control-flow depth, not visual, markup, brace,
+or indentation depth. Omission or `enabled: true` uses 4; an authorized
+positive-integer `reviewAt` overrides it, and `enabled: false` disables it.
+Exactly the effective depth passes; greater depth reviews and never fails. Load `references/nesting-policy.md` only when `nesting`
+appears in `requiredPolicies`.
+
+Cyclomatic complexity is baseline 1 plus normalized decisions owned by the
+callable. Omission or `enabled: true` uses 15; an authorized positive-integer
+`reviewAt` overrides it, and `enabled: false` disables it. Short-circuit
+booleans and fallback/null-aware constructs contribute zero. Lambda boundaries
+are independent. Exactly the effective threshold passes; greater complexity
+reviews and never fails. Load `references/complexity-policy.md` only when
+`complexity` appears in `requiredPolicies`.
+
+Markdown document and direct-section size count all physical lines. Sections
+run from a supported heading through the line before the next heading of any
+level, or EOF. Exact effective thresholds pass; greater measurements review and
+never fail. Load `references/markdown-size-policy.md` when either
+`markdownDocumentSize` or `markdownSectionSize` appears in `requiredPolicies`.
+Review navigation and responsibility without mechanically splitting coherent
+specifications or gaming headings/formatting.
+
+Do not invent configuration, disable a guard, or raise its threshold
+merely to silence a finding. Respect built-ins and only project/user-authorized overrides.
+REVIEW requires inspection and justification, not mandatory refactoring.
+
+Agent Code Guard is the canonical LOC implementation. Agent LOC Guard is the completed prototype/reference whose mature behavior was migrated from commit `75ab39d261dbc65f78815836fac90add16d265d1`.
+
+Project-specific architecture rules, framework-specific checks, arbitrary style preferences, security scanners, and dependency auditing are outside the universal core.

agent_code_guard-0.1.0.data/data/share/agent-code-guard/skill/agents/openai.yaml

@@ -0,0 +1,8 @@
+interface:
+  display_name: "Code Guard"
+  short_description: "Deterministic code guardrails for agents"
+  brand_color: "#2563EB"
+  default_prompt: "Use $code-guard to check changed supported code and Markdown documentation, then load only the policies required by triggered findings."
+
+policy:
+  allow_implicit_invocation: true

agent_code_guard-0.1.0.data/data/share/agent-code-guard/skill/references/callable-size-policy.md

@@ -0,0 +1,39 @@
+# Callable Size Policy
+
+Callable size measures the physical LOC of a function, method, constructor, closure, or equivalent callable unit.
+
+This guard exists because a source file can remain modest in size while one operation grows large enough to become difficult to understand or change safely.
+
+## Status
+
+The calibrated universal default is REVIEW above 80 physical LOC. Exactly 80
+passes. Authorized project/user configuration may supply a positive
+`guards.callableSize.reviewAt` override or explicitly disable the guard. The
+guard has no FAIL threshold.
+
+## On REVIEW
+
+Inspect whether the callable:
+
+- performs one coherent operation;
+- mixes separable stages or responsibilities;
+- contains large regions that have meaningful names and independent contracts;
+- has accumulated error handling, branching, transformation, persistence, or orchestration that belongs elsewhere;
+- is long mainly because the operation is legitimately linear and easier to understand in one place.
+
+Extract code only when the extracted operation is genuinely cohesive and its name/interface improves comprehension.
+
+REVIEW requires inspection, not automatic refactoring. Examine the callable's
+cohesion, responsibility, and growth. Split it only when the resulting design is
+clearer, and preserve the project's conventions.
+
+## Anti-gaming
+
+Do not create tiny meaningless helper methods merely to reduce callable LOC. Do not move arbitrary chunks of a procedure behind names such as `ProcessPart1`, `HandleStuff`, or equivalent abstractions that add navigation without improving design.
+
+Do not compress formatting or combine independent statements onto fewer physical lines to lower the measurement.
+
+Do not alter the threshold or disable the guard merely to silence a finding.
+Only respect such a change when the project or user has authorized it.
+
+A lower callable LOC number is useful only when the resulting code is at least as readable and maintainable as before.

agent_code_guard-0.1.0.data/data/share/agent-code-guard/skill/references/complexity-policy.md

@@ -0,0 +1,39 @@
+# Cyclomatic Complexity Policy
+
+Cyclomatic complexity measures the number of independent control-flow paths through a callable.
+
+This guard exists because a callable can be short and only lightly nested while still containing enough branching and decision logic to be difficult to reason about or test safely.
+
+## Status
+
+Complexity is enabled by default. Exactly 15 passes and greater complexity
+reviews. It is REVIEW-only and never fails. An authorized project/user positive
+integer `reviewAt` may override the default, and explicit disablement is allowed.
+Short-circuit booleans deliberately contribute zero. Agents must not weaken or
+disable the guard merely to silence findings.
+
+## On REVIEW
+
+Inspect whether complexity comes from:
+
+- many genuinely independent execution paths;
+- accumulated conditional branching;
+- mixed responsibilities;
+- mode/type/state switches that should perhaps be modeled explicitly;
+- error handling mixed with core behavior;
+- legitimate parsers, protocol handling, state machines, or rule evaluation where branching may be inherent.
+
+Consider refactoring only when the resulting structure makes behavior easier to understand, test, or change.
+REVIEW is an inspection request, not an automatic decomposition instruction.
+
+## Anti-gaming
+
+Do not lower complexity by hiding decisions behind meaningless wrappers, opaque boolean expressions, lookup tricks, exception flow, or abstractions whose main purpose is changing the score.
+
+Do not split one coherent decision process into scattered helpers when that makes the execution model harder to follow.
+
+Do not convert clear branches into clever expressions or split coherent parsers,
+state machines, and protocol handlers merely to lower the number. Preserve
+project and language idioms.
+
+A lower complexity score is not an improvement unless the resulting behavior and structure are clearer.

agent_code_guard-0.1.0.data/data/share/agent-code-guard/skill/references/loc-policy.md

@@ -0,0 +1,40 @@
+# File LOC Policy
+
+This is the canonical Agent Code Guard policy for oversized handwritten source files. LOC is a deterministic review signal, not proof that every large file has poor architecture.
+
+## Core rule
+
+- Up to 400 counted LOC: `PASS`.
+- 401 through 600 counted LOC: `REVIEW`.
+- More than 600 counted LOC: `FAIL` by default unless an explicit approved exemption applies.
+- An existing applicable exemption is `PASS` with native `exempt` status and its reason retained.
+
+Counting and selection follow the canonical runner. By default, LOC is non-blank physical lines and comments count. Normal development uses `--changed-only`: staged, unstaged, and untracked current work relative to `HEAD`. A scan without a selection flag is an explicit full-repository audit.
+
+## REVIEW interpretation
+
+Inspect whether the file remains cohesive and single-responsibility, whether its size is necessary orchestration or linear structure, whether separable responsibilities are mixed, and whether expected near-term growth changes that judgment.
+
+`REVIEW` does not automatically require refactoring. Split only when doing so improves real responsibility boundaries or clarity; accept the warning when the file remains cohesive and a split would add harmful indirection.
+
+Report either `warning accepted with justification: ...` or `split performed because: ...`.
+
+## FAIL and exemptions
+
+For `FAIL`, refactor below the hard cap when that improves the design or obtain explicit user approval for a justified exemption. Otherwise report `hard cap reached; user approval required`.
+
+Existing `allowedLargeFiles` entries may be honored with their configured reasons. Agents must not create, broaden, modify, repurpose, or invent exemptions merely to pass. Threshold overrides are also explicit policy decisions; agents must not create, broaden, or relax them merely to bypass a finding without explicit approval or existing project policy.
+
+Do not infer approval from inconvenience, historical size, a nearby exemption, time pressure, or a request to finish the coding task.
+
+## Do not game LOC
+
+Project formatting conventions take priority. Never combine independent statements, compress control flow or expressions unusually, minify handwritten code, remove useful comments/structure, or fight the formatter merely to lower physical LOC.
+
+Legitimate reductions improve the code: remove redundancy or dead code, simplify control flow, consolidate duplication when appropriate, or split cohesive responsibilities. Prefer cohesive modules over artificial fragmentation.
+
+## Scope discipline
+
+Changed code is evaluated in its resulting form, including a legacy file modified by the task. Unrelated legacy debt belongs to explicit audit work and must not expand a normal change unnecessarily.
+
+Test files may exceed the review threshold when clearly grouped and navigable. They still require explicit approval above the hard cap.

agent_code_guard-0.1.0.data/data/share/agent-code-guard/skill/references/markdown-size-policy.md

@@ -0,0 +1,16 @@
+# Markdown Size Review Policy
+
+Use this policy when `markdownDocumentSize` or `markdownSectionSize` appears in
+`requiredPolicies`.
+
+A Markdown size REVIEW is an instruction to inspect navigation and
+responsibility, not an automatic instruction to split the document or section.
+`reviewed; coherent; keep` is a valid outcome for cohesive specifications,
+reference material, tables, procedures, and code-heavy sections.
+
+Improve navigation or responsibility boundaries only when the result is
+genuinely clearer. Do not add meaningless headings to lower section size,
+mechanically split coherent material, compress formatting or remove useful
+blank lines, or hide content in fenced code. Agents must not raise thresholds or
+disable either guard merely to silence a finding; project or user authority is
+required for configuration changes.

agent_code_guard-0.1.0.data/data/share/agent-code-guard/skill/references/nesting-policy.md

@@ -0,0 +1,37 @@
+# Nesting Depth Policy
+
+Nesting depth measures how deeply control-flow structures are nested within a callable.
+
+This guard exists because deeply nested code can be difficult to reason about even when the file and callable are not especially long.
+
+## Status
+
+The calibrated universal default is REVIEW above structural depth 4. Exactly 4
+passes. Authorized project/user configuration may supply a positive
+`guards.nesting.reviewAt` override or explicitly disable the guard. The guard
+has no FAIL threshold.
+
+## On REVIEW
+
+Inspect whether the nesting reflects:
+
+- avoidable conditional pyramids;
+- loops nested inside branches with additional branching;
+- validation/error paths that could be expressed more clearly with guard clauses or early exits;
+- multiple responsibilities entangled in one callable;
+- state-machine, parser, traversal, or other logic where deeper nesting may be inherent and still readable.
+
+REVIEW means inspect control-flow readability; it is not an automatic refactor.
+Consider guard clauses or extraction only when they improve clarity. Preserve
+idiomatic language and project structure.
+
+## Anti-gaming
+
+Do not flatten code merely to reduce the measured depth if the result becomes harder to follow.
+
+Do not hide nested decisions behind meaningless helper calls or obscure boolean expressions. Do not replace clear structured control flow with clever expressions, compressed conditionals, exception tricks, or other forms whose primary purpose is lowering the metric.
+
+Do not change or disable the configured threshold merely to silence a finding.
+Only respect such a change when the project or user has authorized it.
+
+The preferred outcome is clearer control flow, not a smaller number at any cost.