agent-code-guard 0.3.0__tar.gz → 0.4.0__tar.gz

{agent_code_guard-0.3.0/src/agent_code_guard.egg-info → agent_code_guard-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agent-code-guard
-Version: 0.3.0
+Version: 0.4.0
 Summary: Deterministic cross-language guardrails for agent-assisted development
 License-Expression: MIT
 Project-URL: Source, https://github.com/stef-k/agent-code-guard
@@ -21,9 +21,13 @@ Dynamic: license-file
 Deterministic maintainability guardrails for source code and Markdown changed by
 a human or coding agent.
 
+[Documentation](https://stef-k.github.io/agent-code-guard/) ·
+[Get started](https://stef-k.github.io/agent-code-guard/#get-started) ·
+[Releases](https://github.com/stef-k/agent-code-guard/releases)
+
 [![Production Analysis](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml/badge.svg)](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml)
 [![PyPI](https://img.shields.io/pypi/v/agent-code-guard?logo=pypi&logoColor=white)](https://pypi.org/project/agent-code-guard/)
-[![Python 3.10–3.14](https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
+[![Python 3.10–3.14](https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://stef-k.github.io/agent-code-guard/platform-support.html)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/stef-k/agent-code-guard/blob/main/LICENSE)
 
 Agent Code Guard measures file size, callable size, structural nesting,
@@ -75,7 +79,7 @@ code-guard doctor
 ```
 
 `--version` confirms the installed distribution identity. `doctor` checks the
-active installation's health. See the [usage guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for virtual
+active installation's health. See the [usage guide](https://stef-k.github.io/agent-code-guard/usage.html) for virtual
 environment, uv, and developer alternatives.
 
 ### Ask your agent to adopt it
@@ -89,13 +93,13 @@ Copy this prompt to a coding agent:
 > activating or exporting its installed, version-matched skill for the current
 > agent environment. Verify `code-guard --version` and run `code-guard doctor`,
 > then locate the skill with `code-guard --skill-path`. Follow the
-> [skill activation guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md):
+> [skill activation guide](https://stef-k.github.io/agent-code-guard/skill-distribution.html):
 > activate that installed path when the platform supports it, or export it with
 > `code-guard --export-skill <target-directory>` to the platform's documented
 > skill directory. Do not guess a target or overwrite an existing export; verify
 > that `.agent-code-guard-version` matches the installed distribution. Follow the
-> [agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
-> without creating a LOC baseline. After meaningful source or Markdown edits, run
+> [agent workflow](https://stef-k.github.io/agent-code-guard/agent-workflow.html)
+> without creating an adoption baseline. After meaningful source or Markdown edits, run
 > `code-guard . --changed-only --json --json-mode compact`; outside Git, pass the
 > exact edited files. Inspect REVIEW and FAIL findings, make only genuine
 > improvements, rerun the check, and report the result. Never weaken thresholds,
@@ -118,7 +122,7 @@ No configuration is needed. A REVIEW asks for inspection and judgment, not an
 automatic refactor. Outside Git, pass the exact edited files instead, such as
 `code-guard src/app.py docs/guide.md`.
 
-See the [agent workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) for repeated human and
+See the [agent workflow guide](https://stef-k.github.io/agent-code-guard/agent-workflow.html) for repeated human and
 agent use.
 
 ## Recommended workflow
@@ -140,7 +144,7 @@ report the result before completion
 Use `code-guard . --changed-only --json --json-mode compact` for a structured,
 low-noise manual agent check. Hooks are optional, platform-owned, and require
 user authorization; Code Guard does not install them. The
-[workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) owns the complete manual and
+[workflow guide](https://stef-k.github.io/agent-code-guard/agent-workflow.html) owns the complete manual and
 hook-assisted process.
 
 ## Interpreting results
@@ -177,7 +181,7 @@ measurement. A REVIEW is not proof of a defect or a mandatory refactor.
 Comparisons are strictly greater-than, so equality passes. All guards except
 file LOC are REVIEW-only; only file LOC can FAIL. A new guard must provide
 distinct, deterministic value rather than duplicate conventional tooling. See
-[Guard admission](https://github.com/stef-k/agent-code-guard/blob/main/docs/guard-admission.md).
+[Guard admission](https://stef-k.github.io/agent-code-guard/guard-admission.html).
 
 ### Result and JSON reference
 
@@ -186,7 +190,7 @@ all-guard-excluded file counts. Bare `--json` is the compatible full output;
 `--json-mode debug` is byte-identical for the same completed invocation, while
 `--json-mode compact` removes only normalized `pass` findings and retains the
 result, scope, required policies, guards, ordering, and actionable findings.
-Named modes require `--json`. See [Usage](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for the schema and
+Named modes require `--json`. See [Usage](https://stef-k.github.io/agent-code-guard/usage.html) for the schema and
 option contract.
 
 Known per-file syntax or provider failures instead produce `overall:
@@ -221,7 +225,7 @@ Generic `.h` files are not syntax-dispatched; `.markdown` is not enabled; Vue
 template and style regions are not executable syntax input; and unsupported
 artifacts are inapplicable. Malformed applicable syntax or a required provider
 failure is unavailable evidence, distinct from both an inapplicable file and a
-completed FAIL finding. See [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md).
+completed FAIL finding. See [Language support](https://stef-k.github.io/agent-code-guard/language-support.html).
 
 ### Skill integration
 
@@ -233,38 +237,45 @@ code-guard --export-skill <target-directory>
 ```
 
 Skill activation is platform-specific and is not performed by pipx or Code
-Guard. See [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md). The checkout
+Guard. See [Skill distribution](https://stef-k.github.io/agent-code-guard/skill-distribution.html). The checkout
 compatibility runner is for repository development, not normal installation.
 
 ### Configuration
 
 Built-in defaults require no configuration. Configure a project only for a
-concrete policy reason; see the [configuration guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md).
+concrete policy reason; see the [configuration guide](https://stef-k.github.io/agent-code-guard/configuration.html).
 The LOC baseline is an explicit adoption tool for established legacy
 repositories, not an ordinary-use requirement or a way to silence findings.
 Its default `ratchetAt: "fail"` policy freezes files above `failAt`; choose
 `ratchetAt: "review"` only when every established file above `warnAt` must be
 non-increasing while ordinary findings in that range remain REVIEW.
 
+Reviewed oversized Markdown documents have a separate, explicit
+[document-size ratchet](https://stef-k.github.io/agent-code-guard/usage.html#reviewed-markdown-document-ratchet).
+`--create-markdown-baseline` records accepted physical-line counts;
+`--update-markdown-baseline` only lowers or prunes them. Documents within their
+allowance pass the document-size guard; growth produces REVIEW. Section
+findings remain active, and ordinary analysis never writes either baseline.
+
 ## Trust, CI, and platform support
 
 CI installs Agent Code Guard and analyzes its own real checkout. REVIEW findings
 remain visible but non-blocking, while FAIL findings and tool errors block the
-workflow; the repository intentionally uses no LOC baseline.
+workflow; the repository intentionally uses no adoption baseline.
 
 The maintained interpreter range is **CPython 3.10–3.14**. See
-[Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md) for supported binary platforms and
+[Platform support](https://stef-k.github.io/agent-code-guard/platform-support.html) for supported binary platforms and
 source-build boundaries.
 
 ## Documentation
 
-- [Documentation index](https://github.com/stef-k/agent-code-guard/blob/main/docs/README.md)
-- [Agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
-- [Usage and CLI reference](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md)
-- [Configuration](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md)
-- [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md)
-- [Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
-- [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md)
+- [Documentation index](https://stef-k.github.io/agent-code-guard/)
+- [Agent workflow](https://stef-k.github.io/agent-code-guard/agent-workflow.html)
+- [Usage and CLI reference](https://stef-k.github.io/agent-code-guard/usage.html)
+- [Configuration](https://stef-k.github.io/agent-code-guard/configuration.html)
+- [Language support](https://stef-k.github.io/agent-code-guard/language-support.html)
+- [Platform support](https://stef-k.github.io/agent-code-guard/platform-support.html)
+- [Skill distribution](https://stef-k.github.io/agent-code-guard/skill-distribution.html)
 
 ## Feedback, security, and license
 

{agent_code_guard-0.3.0 → agent_code_guard-0.4.0}/README.md

@@ -7,9 +7,13 @@
 Deterministic maintainability guardrails for source code and Markdown changed by
 a human or coding agent.
 
+[Documentation](https://stef-k.github.io/agent-code-guard/) ·
+[Get started](https://stef-k.github.io/agent-code-guard/#get-started) ·
+[Releases](https://github.com/stef-k/agent-code-guard/releases)
+
 [![Production Analysis](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml/badge.svg)](https://github.com/stef-k/agent-code-guard/actions/workflows/analysis.yml)
 [![PyPI](https://img.shields.io/pypi/v/agent-code-guard?logo=pypi&logoColor=white)](https://pypi.org/project/agent-code-guard/)
-[![Python 3.10–3.14](https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
+[![Python 3.10–3.14](https://img.shields.io/badge/Python-3.10%E2%80%933.14-3776AB?logo=python&logoColor=white)](https://stef-k.github.io/agent-code-guard/platform-support.html)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://github.com/stef-k/agent-code-guard/blob/main/LICENSE)
 
 Agent Code Guard measures file size, callable size, structural nesting,
@@ -61,7 +65,7 @@ code-guard doctor
 ```
 
 `--version` confirms the installed distribution identity. `doctor` checks the
-active installation's health. See the [usage guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for virtual
+active installation's health. See the [usage guide](https://stef-k.github.io/agent-code-guard/usage.html) for virtual
 environment, uv, and developer alternatives.
 
 ### Ask your agent to adopt it
@@ -75,13 +79,13 @@ Copy this prompt to a coding agent:
 > activating or exporting its installed, version-matched skill for the current
 > agent environment. Verify `code-guard --version` and run `code-guard doctor`,
 > then locate the skill with `code-guard --skill-path`. Follow the
-> [skill activation guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md):
+> [skill activation guide](https://stef-k.github.io/agent-code-guard/skill-distribution.html):
 > activate that installed path when the platform supports it, or export it with
 > `code-guard --export-skill <target-directory>` to the platform's documented
 > skill directory. Do not guess a target or overwrite an existing export; verify
 > that `.agent-code-guard-version` matches the installed distribution. Follow the
-> [agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
-> without creating a LOC baseline. After meaningful source or Markdown edits, run
+> [agent workflow](https://stef-k.github.io/agent-code-guard/agent-workflow.html)
+> without creating an adoption baseline. After meaningful source or Markdown edits, run
 > `code-guard . --changed-only --json --json-mode compact`; outside Git, pass the
 > exact edited files. Inspect REVIEW and FAIL findings, make only genuine
 > improvements, rerun the check, and report the result. Never weaken thresholds,
@@ -104,7 +108,7 @@ No configuration is needed. A REVIEW asks for inspection and judgment, not an
 automatic refactor. Outside Git, pass the exact edited files instead, such as
 `code-guard src/app.py docs/guide.md`.
 
-See the [agent workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) for repeated human and
+See the [agent workflow guide](https://stef-k.github.io/agent-code-guard/agent-workflow.html) for repeated human and
 agent use.
 
 ## Recommended workflow
@@ -126,7 +130,7 @@ report the result before completion
 Use `code-guard . --changed-only --json --json-mode compact` for a structured,
 low-noise manual agent check. Hooks are optional, platform-owned, and require
 user authorization; Code Guard does not install them. The
-[workflow guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md) owns the complete manual and
+[workflow guide](https://stef-k.github.io/agent-code-guard/agent-workflow.html) owns the complete manual and
 hook-assisted process.
 
 ## Interpreting results
@@ -163,7 +167,7 @@ measurement. A REVIEW is not proof of a defect or a mandatory refactor.
 Comparisons are strictly greater-than, so equality passes. All guards except
 file LOC are REVIEW-only; only file LOC can FAIL. A new guard must provide
 distinct, deterministic value rather than duplicate conventional tooling. See
-[Guard admission](https://github.com/stef-k/agent-code-guard/blob/main/docs/guard-admission.md).
+[Guard admission](https://stef-k.github.io/agent-code-guard/guard-admission.html).
 
 ### Result and JSON reference
 
@@ -172,7 +176,7 @@ all-guard-excluded file counts. Bare `--json` is the compatible full output;
 `--json-mode debug` is byte-identical for the same completed invocation, while
 `--json-mode compact` removes only normalized `pass` findings and retains the
 result, scope, required policies, guards, ordering, and actionable findings.
-Named modes require `--json`. See [Usage](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md) for the schema and
+Named modes require `--json`. See [Usage](https://stef-k.github.io/agent-code-guard/usage.html) for the schema and
 option contract.
 
 Known per-file syntax or provider failures instead produce `overall:
@@ -207,7 +211,7 @@ Generic `.h` files are not syntax-dispatched; `.markdown` is not enabled; Vue
 template and style regions are not executable syntax input; and unsupported
 artifacts are inapplicable. Malformed applicable syntax or a required provider
 failure is unavailable evidence, distinct from both an inapplicable file and a
-completed FAIL finding. See [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md).
+completed FAIL finding. See [Language support](https://stef-k.github.io/agent-code-guard/language-support.html).
 
 ### Skill integration
 
@@ -219,38 +223,45 @@ code-guard --export-skill <target-directory>
 ```
 
 Skill activation is platform-specific and is not performed by pipx or Code
-Guard. See [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md). The checkout
+Guard. See [Skill distribution](https://stef-k.github.io/agent-code-guard/skill-distribution.html). The checkout
 compatibility runner is for repository development, not normal installation.
 
 ### Configuration
 
 Built-in defaults require no configuration. Configure a project only for a
-concrete policy reason; see the [configuration guide](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md).
+concrete policy reason; see the [configuration guide](https://stef-k.github.io/agent-code-guard/configuration.html).
 The LOC baseline is an explicit adoption tool for established legacy
 repositories, not an ordinary-use requirement or a way to silence findings.
 Its default `ratchetAt: "fail"` policy freezes files above `failAt`; choose
 `ratchetAt: "review"` only when every established file above `warnAt` must be
 non-increasing while ordinary findings in that range remain REVIEW.
 
+Reviewed oversized Markdown documents have a separate, explicit
+[document-size ratchet](https://stef-k.github.io/agent-code-guard/usage.html#reviewed-markdown-document-ratchet).
+`--create-markdown-baseline` records accepted physical-line counts;
+`--update-markdown-baseline` only lowers or prunes them. Documents within their
+allowance pass the document-size guard; growth produces REVIEW. Section
+findings remain active, and ordinary analysis never writes either baseline.
+
 ## Trust, CI, and platform support
 
 CI installs Agent Code Guard and analyzes its own real checkout. REVIEW findings
 remain visible but non-blocking, while FAIL findings and tool errors block the
-workflow; the repository intentionally uses no LOC baseline.
+workflow; the repository intentionally uses no adoption baseline.
 
 The maintained interpreter range is **CPython 3.10–3.14**. See
-[Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md) for supported binary platforms and
+[Platform support](https://stef-k.github.io/agent-code-guard/platform-support.html) for supported binary platforms and
 source-build boundaries.
 
 ## Documentation
 
-- [Documentation index](https://github.com/stef-k/agent-code-guard/blob/main/docs/README.md)
-- [Agent workflow](https://github.com/stef-k/agent-code-guard/blob/main/docs/agent-workflow.md)
-- [Usage and CLI reference](https://github.com/stef-k/agent-code-guard/blob/main/docs/usage.md)
-- [Configuration](https://github.com/stef-k/agent-code-guard/blob/main/docs/configuration.md)
-- [Language support](https://github.com/stef-k/agent-code-guard/blob/main/docs/language-support.md)
-- [Platform support](https://github.com/stef-k/agent-code-guard/blob/main/docs/platform-support.md)
-- [Skill distribution](https://github.com/stef-k/agent-code-guard/blob/main/docs/skill-distribution.md)
+- [Documentation index](https://stef-k.github.io/agent-code-guard/)
+- [Agent workflow](https://stef-k.github.io/agent-code-guard/agent-workflow.html)
+- [Usage and CLI reference](https://stef-k.github.io/agent-code-guard/usage.html)
+- [Configuration](https://stef-k.github.io/agent-code-guard/configuration.html)
+- [Language support](https://stef-k.github.io/agent-code-guard/language-support.html)
+- [Platform support](https://stef-k.github.io/agent-code-guard/platform-support.html)
+- [Skill distribution](https://stef-k.github.io/agent-code-guard/skill-distribution.html)
 
 ## Feedback, security, and license
 

{agent_code_guard-0.3.0 → agent_code_guard-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "agent-code-guard"
-version = "0.3.0"
+version = "0.4.0"
 description = "Deterministic cross-language guardrails for agent-assisted development"
 readme = "README.md"
 requires-python = ">=3.10"

{agent_code_guard-0.3.0 → agent_code_guard-0.4.0}/skills/code-guard/SKILL.md

@@ -148,8 +148,9 @@ reviews and never fails. Load `references/complexity-policy.md` only when
 
 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
+level, or EOF. Exact effective thresholds pass; greater measurements normally
+review and never fail. A document measurement within an explicitly accepted
+Markdown document baseline passes the document-size guard. 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.
@@ -161,3 +162,20 @@ 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.
+
+## Reviewed Markdown document baselines
+
+After explicit acceptance of a cohesive oversized document, use
+`code-guard docs/architecture.md --create-markdown-baseline` to record its current
+physical-line count in `.agent-tools/code-guard.markdown-baseline.json` at the
+analysis root. Normal analysis reads this file without writing. Unchanged or
+smaller accepted documents pass `markdownDocumentSize`; growth above both the
+allowance and effective threshold returns REVIEW. `markdownSectionSize` remains
+independent and has no baseline support.
+
+`--update-markdown-baseline` only lowers or prunes existing allowances within
+positional bounds; it never adds or increases one. Neither write command is
+part of routine checks. Do not create, replace, remove, or increase allowances
+merely to silence findings. Review and commit explicit acceptance decisions.
+Human/full JSON output retains acceptance context; compact omits accepted PASS
+findings. Load the Markdown policy for actionable document or section reviews.

agent_code_guard-0.4.0/skills/code-guard/references/markdown-size-policy.md

@@ -0,0 +1,33 @@
+# 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.
+
+## Explicit document acceptance
+
+An explicitly reviewed, cohesive oversized document may use a source-controlled
+allowance created with `--create-markdown-baseline`. The separate
+`.agent-tools/code-guard.markdown-baseline.json` records exact root-relative paths
+and current physical-line counts. Within that allowance the document finding
+passes; growth above both the allowance and effective threshold is REVIEW,
+never FAIL. At or below the ordinary threshold, an allowance is no longer needed.
+
+This applies only to `markdownDocumentSize`. Inspect section REVIEW findings
+independently; document acceptance does not exempt sections. Normal analysis
+never changes a baseline. After reductions or deletions,
+`--update-markdown-baseline` can explicitly lower or prune existing entries but
+cannot add or increase allowances. Agents must not create or replace baselines,
+remove allowances, raise thresholds, or add exclusions merely to silence growth.
+Baseline acceptance requires explicit authority and source-control review.

{agent_code_guard-0.3.0 → agent_code_guard-0.4.0}/src/agent_code_guard/analysis/adapters.py

@@ -116,11 +116,11 @@ def _range_end_node(node, language: str):
 
 def _callable_range(node, region: ExecutableRegion) -> SourceRange:
     """Snapshot provider points once before mapping them to original source."""
-    start_row, start_column = callable_source_start(node, region.language).start_point
-    end_row, end_column = _range_end_node(node, region.language).end_point
+    start = callable_source_start(node, region.language)
+    end = _range_end_node(node, region.language)
     return SourceRange(
-        region.original_point(start_row, start_column),
-        region.original_point(end_row, end_column),
+        region.original_point_at_byte(start.start_byte),
+        region.original_point_at_byte(end.end_byte),
     )
 
 

{agent_code_guard-0.3.0 → agent_code_guard-0.4.0}/src/agent_code_guard/analysis/callable_identity.py

@@ -272,8 +272,7 @@ def _javascript_lexical_name(node, source: bytes) -> str | None:
 
 
 def _callback_name(node, region: ExecutableRegion) -> str:
-    row, column = node.start_point
-    point = region.original_point(row, column)
+    point = region.original_point_at_byte(node.start_byte)
     return f"<callback@{point.line}:{point.byte_column}>"
 
 

{agent_code_guard-0.3.0 → agent_code_guard-0.4.0}/src/agent_code_guard/analysis/facts.py

@@ -2,8 +2,10 @@
 
 from __future__ import annotations
 
-from dataclasses import dataclass
+from dataclasses import dataclass, field
 from pathlib import Path
+from types import MappingProxyType
+from typing import Mapping
 
 
 @dataclass(frozen=True, order=True)
@@ -82,11 +84,20 @@ class FileFacts:
     controls: tuple[ControlFlowFact, ...]
     decisions: tuple[DecisionFact, ...]
     region_count: int
+    reporting_path: str | None = None
 
 
 @dataclass(frozen=True)
 class AnalysisFacts:
     files: tuple[FileFacts, ...]
+    _reporting_paths: Mapping[Path, str] = field(init=False, repr=False, compare=False)
+
+    def __post_init__(self) -> None:
+        object.__setattr__(self, "_reporting_paths", MappingProxyType({
+            file.path: file.reporting_path
+            for file in self.files
+            if file.reporting_path is not None
+        }))
 
     @property
     def callables(self) -> tuple[CallableFact, ...]:
@@ -99,3 +110,12 @@ class AnalysisFacts:
     @property
     def decisions(self) -> tuple[DecisionFact, ...]:
         return tuple(fact for file in self.files for fact in file.decisions)
+
+    def reporting_path_for(self, path: Path, root: Path | None = None) -> str:
+        stored = self._reporting_paths.get(path)
+        if stored is not None:
+            return stored
+        try:
+            return path.relative_to(root).as_posix() if root is not None else path.as_posix()
+        except ValueError:
+            return path.as_posix()

{agent_code_guard-0.3.0 → agent_code_guard-0.4.0}/src/agent_code_guard/analysis/pipeline.py

@@ -5,6 +5,8 @@ from __future__ import annotations
 from dataclasses import dataclass
 from pathlib import Path
 
+from ..invocation import SelectedFile
+
 from .adapters import extract_facts
 from .csharp_compat import corrected_csharp_root
 from .errors import ProviderUnavailableError, SyntaxAnalysisError
@@ -13,16 +15,20 @@ 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:
+def analyze_files(files: tuple[SelectedFile, ...] | list[SelectedFile], provider: ParserProvider | None = None) -> AnalysisFacts:
     """Analyze only applicable entries from the already-resolved caller scope."""
     active_provider = provider or TreeSitterProvider()
-    results = [_analyze_file(Path(path), active_provider) for path in files if is_applicable(Path(path))]
+    results = [
+        _analyze_file(selected.physical_path, active_provider, selected.reporting_path)
+        for selected in files if is_applicable(selected.physical_path)
+    ]
     return AnalysisFacts(tuple(results))
 
 
 @dataclass(frozen=True)
 class UnavailableAnalysis:
     path: Path
+    reporting_path: str
     language: str
     kind: str
     message: str
@@ -35,27 +41,27 @@ class BatchAnalysis:
 
 
 def analyze_files_for_runner(
-    files: tuple[Path, ...] | list[Path], provider: ParserProvider | None = None,
+    files: tuple[SelectedFile, ...], provider: ParserProvider | None = None,
 ) -> BatchAnalysis:
     """Analyze selected files independently while retaining only known unavailable evidence."""
     active_provider = provider or TreeSitterProvider()
     results: list[FileFacts] = []
     unavailable: list[UnavailableAnalysis] = []
-    for value in files:
-        path = Path(value)
+    for selected in files:
+        path = selected.physical_path
         if not is_applicable(path):
             continue
         try:
-            results.append(_analyze_file(path, active_provider))
+            results.append(_analyze_file(path, active_provider, selected.reporting_path))
         except (SyntaxAnalysisError, ProviderUnavailableError) as exc:
             if exc.language is None:
                 raise
             kind = "syntax" if isinstance(exc, SyntaxAnalysisError) else "provider"
-            unavailable.append(UnavailableAnalysis(path, exc.language, kind, str(exc)))
+            unavailable.append(UnavailableAnalysis(path, selected.reporting_path, exc.language, kind, str(exc)))
     return BatchAnalysis(AnalysisFacts(tuple(results)), tuple(unavailable))
 
 
-def _analyze_file(path: Path, provider: ParserProvider) -> FileFacts:
+def _analyze_file(path: Path, provider: ParserProvider, reporting_path: str | None = None) -> FileFacts:
     callables = []
     controls = []
     decisions = []
@@ -83,4 +89,4 @@ def _analyze_file(path: Path, provider: ParserProvider) -> FileFacts:
         callables.extend(region_callables)
         controls.extend(region_controls)
         decisions.extend(region_decisions)
-    return FileFacts(path, tuple(callables), tuple(controls), tuple(decisions), len(regions))
+    return FileFacts(path, tuple(callables), tuple(controls), tuple(decisions), len(regions), reporting_path)

{agent_code_guard-0.3.0 → agent_code_guard-0.4.0}/src/agent_code_guard/analysis/regions.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 from dataclasses import dataclass
+from bisect import bisect_right
 from pathlib import Path
 
 from .errors import SyntaxAnalysisError
@@ -29,21 +30,31 @@ class ExecutableRegion:
     source: bytes
     original_source: bytes
     original_byte_offset: int = 0
+    original_line_starts: tuple[int, ...] | None = None
+    local_line_starts: tuple[int, ...] | None = None
+
+    def __post_init__(self) -> None:
+        if self.original_line_starts is None:
+            object.__setattr__(self, "original_line_starts", _line_starts(self.original_source))
+        if self.local_line_starts is None:
+            object.__setattr__(self, "local_line_starts", _line_starts(self.source))
 
     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
+        local_offset = self.local_line_starts[local_row] + local_byte_column
+        return self.original_point_at_byte(local_offset)
+
+    def original_point_at_byte(self, local_byte_offset: int) -> SourcePoint:
+        """Map a parser byte offset without reconstructing its local row prefix."""
+        absolute = self.original_byte_offset + local_byte_offset
+        row = bisect_right(self.original_line_starts, absolute) - 1
+        line = row + 1
+        byte_column = absolute - self.original_line_starts[row] + 1
         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),
+            self.original_point_at_byte(node.start_byte),
+            self.original_point_at_byte(node.end_byte),
         )
 
 
@@ -69,6 +80,7 @@ def _vue_regions(path: Path, source: bytes, provider: ParserProvider) -> tuple[E
             f"unable to parse {path}: Vue container syntax tree contains errors", language="vue",
         )
     regions: list[ExecutableRegion] = []
+    original_line_starts = _line_starts(source)
     for element in root.named_children:
         if element.type != "script_element":
             continue
@@ -83,15 +95,13 @@ def _vue_regions(path: Path, source: bytes, provider: ParserProvider) -> tuple[E
         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,
+                original_line_starts,
             ))
     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 _line_starts(source: bytes) -> tuple[int, ...]:
+    return (0, *(index + 1 for index, value in enumerate(source) if value == 10))
 
 
 def _attributes(start_tag, source: bytes) -> dict[str, str | None]: