open-code-review-toolkit 0.3.1__tar.gz → 0.4.1__tar.gz

{open_code_review_toolkit-0.3.1 → open_code_review_toolkit-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: open-code-review-toolkit
-Version: 0.3.1
+Version: 0.4.1
 Summary: Unofficial GitLab CI integration layer for Open Code Review
 Project-URL: Homepage, https://github.com/xeonvs/open-code-review-toolkit
 Project-URL: Repository, https://github.com/xeonvs/open-code-review-toolkit
@@ -217,21 +217,19 @@ Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Operating System :: MacOS
 Classifier: Operating System :: POSIX :: Linux
 Classifier: Programming Language :: Python :: 3 :: Only
-Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
 Classifier: Programming Language :: Python :: 3.14
 Classifier: Typing :: Typed
-Requires-Python: <3.15,>=3.10
+Requires-Python: <3.15,>=3.12
 Description-Content-Type: text/markdown
 
 # Open Code Review Toolkit
 
-Open Code Review Toolkit is an unofficial GitLab CI integration layer for [Alibaba Open Code Review](https://github.com/alibaba/open-code-review). It provides bounded repository context generation, environment-driven OCR configuration, preflight validation, and safe GitLab merge-request posting. It does **not** bundle or download the `ocr` binary.
+Open Code Review Toolkit is an unofficial GitLab CI integration layer for [Alibaba Open Code Review](https://github.com/alibaba/open-code-review). It provides bounded repository evidence, a compact review bootstrap, a built-in read-only MCP server, environment-driven OCR configuration, preflight validation, and safe GitLab merge-request posting. It does **not** bundle or download the `ocr` binary.
 
 > [!NOTE]
-> The project is under active development. It currently targets Python 3.10-3.14 on Linux and macOS; the public API, CLI, environment contract, and generated schemas may evolve before 1.0.
+> The project is under active development; the public API, CLI, environment contract, and generated schemas may evolve before 1.0.
 
 ## Install
 
@@ -243,9 +241,9 @@ ocr --version
 ocr-ci --help
 ```
 
-The current compatibility target is OCR `1.8.0`. CI should pin the release and verify its published checksum before execution.
+The current compatibility target is OCR `1.8.2`. CI should pin the release and verify its published checksum before execution.
 The [versioned compatibility policy](docs/compatibility.md) records tested assets and evidence and describes the conservative Dependabot-like qualification workflow for later upstream releases.
-Review output defaults to English. Set `OCR_REVIEW_LANGUAGE=Russian` to use Russian consistently in both OCR configuration and generated review context.
+Review output defaults to English. `OCR_REVIEW_LANGUAGE` accepts another explicit language name when a project needs localized review output; for example, `OCR_REVIEW_LANGUAGE=Russian`.
 
 Stable distributions are published to [PyPI](https://pypi.org/project/open-code-review-toolkit/) and mirrored as checksum-listed, provenance-attested assets in the corresponding [GitHub Release](https://github.com/xeonvs/open-code-review-toolkit/releases). Development snapshots are published only to TestPyPI.
 
@@ -255,7 +253,7 @@ On a successful rerun, the toolkit replaces untouched OCR-only notes instead of
 
 Suppression uses both the GitLab diff position and a stable finding fingerprint, so ordinary line shifts do not normally bring the same bug back. A materially changed finding can still receive a new discussion. See [GitLab review operations](docs/operations.md) for the complete lifecycle, posting modes, permissions, failure behavior, and Mermaid state diagram.
 
-Project-wide accepted tradeoffs can be recorded separately in `.opencodereview/accepted-decisions.md`; the context generator supplies them to OCR only when the current merge request is not changing that file. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) for the entry format, inline marker convention, security boundary, and limitations.
+Project-wide accepted tradeoffs can be recorded separately in `.opencodereview/accepted-decisions.md`; the evidence collector supplies target-ref decisions to OCR and never lets a source change self-authorize its own review. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) for the entry format, inline marker convention, security boundary, and limitations.
 
 ## Project development
 
@@ -270,13 +268,11 @@ The project is evolving from bounded background generation toward a shared Repos
 1. Configure protected/masked `GITLAB_API_TOKEN` and LLM variables in GitLab.
 2. Pin and checksum the OCR binary.
 3. Install this package.
-4. Run the five helper stages around `ocr review`:
+4. Run the four public helper stages around `ocr review`:
 
 ```console
 ocr-ci preflight
 ocr-ci configure
-ocr-ci mcp-config
-ocr-ci context --output .review-context/dependencies.md
 ocr-ci review --result /tmp/ocr-result.json --stderr /tmp/ocr-stderr.log -- ... --format json
 ocr-ci post --result /tmp/ocr-result.json --stderr /tmp/ocr-stderr.log
 ```

{open_code_review_toolkit-0.3.1 → open_code_review_toolkit-0.4.1}/README.md

@@ -1,9 +1,9 @@
 # Open Code Review Toolkit
 
-Open Code Review Toolkit is an unofficial GitLab CI integration layer for [Alibaba Open Code Review](https://github.com/alibaba/open-code-review). It provides bounded repository context generation, environment-driven OCR configuration, preflight validation, and safe GitLab merge-request posting. It does **not** bundle or download the `ocr` binary.
+Open Code Review Toolkit is an unofficial GitLab CI integration layer for [Alibaba Open Code Review](https://github.com/alibaba/open-code-review). It provides bounded repository evidence, a compact review bootstrap, a built-in read-only MCP server, environment-driven OCR configuration, preflight validation, and safe GitLab merge-request posting. It does **not** bundle or download the `ocr` binary.
 
 > [!NOTE]
-> The project is under active development. It currently targets Python 3.10-3.14 on Linux and macOS; the public API, CLI, environment contract, and generated schemas may evolve before 1.0.
+> The project is under active development; the public API, CLI, environment contract, and generated schemas may evolve before 1.0.
 
 ## Install
 
@@ -15,9 +15,9 @@ ocr --version
 ocr-ci --help
 ```
 
-The current compatibility target is OCR `1.8.0`. CI should pin the release and verify its published checksum before execution.
+The current compatibility target is OCR `1.8.2`. CI should pin the release and verify its published checksum before execution.
 The [versioned compatibility policy](docs/compatibility.md) records tested assets and evidence and describes the conservative Dependabot-like qualification workflow for later upstream releases.
-Review output defaults to English. Set `OCR_REVIEW_LANGUAGE=Russian` to use Russian consistently in both OCR configuration and generated review context.
+Review output defaults to English. `OCR_REVIEW_LANGUAGE` accepts another explicit language name when a project needs localized review output; for example, `OCR_REVIEW_LANGUAGE=Russian`.
 
 Stable distributions are published to [PyPI](https://pypi.org/project/open-code-review-toolkit/) and mirrored as checksum-listed, provenance-attested assets in the corresponding [GitHub Release](https://github.com/xeonvs/open-code-review-toolkit/releases). Development snapshots are published only to TestPyPI.
 
@@ -27,7 +27,7 @@ On a successful rerun, the toolkit replaces untouched OCR-only notes instead of
 
 Suppression uses both the GitLab diff position and a stable finding fingerprint, so ordinary line shifts do not normally bring the same bug back. A materially changed finding can still receive a new discussion. See [GitLab review operations](docs/operations.md) for the complete lifecycle, posting modes, permissions, failure behavior, and Mermaid state diagram.
 
-Project-wide accepted tradeoffs can be recorded separately in `.opencodereview/accepted-decisions.md`; the context generator supplies them to OCR only when the current merge request is not changing that file. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) for the entry format, inline marker convention, security boundary, and limitations.
+Project-wide accepted tradeoffs can be recorded separately in `.opencodereview/accepted-decisions.md`; the evidence collector supplies target-ref decisions to OCR and never lets a source change self-authorize its own review. See [Accepted project decisions](docs/configuration.md#accepted-project-decisions) for the entry format, inline marker convention, security boundary, and limitations.
 
 ## Project development
 
@@ -42,13 +42,11 @@ The project is evolving from bounded background generation toward a shared Repos
 1. Configure protected/masked `GITLAB_API_TOKEN` and LLM variables in GitLab.
 2. Pin and checksum the OCR binary.
 3. Install this package.
-4. Run the five helper stages around `ocr review`:
+4. Run the four public helper stages around `ocr review`:
 
 ```console
 ocr-ci preflight
 ocr-ci configure
-ocr-ci mcp-config
-ocr-ci context --output .review-context/dependencies.md
 ocr-ci review --result /tmp/ocr-result.json --stderr /tmp/ocr-stderr.log -- ... --format json
 ocr-ci post --result /tmp/ocr-result.json --stderr /tmp/ocr-stderr.log
 ```

{open_code_review_toolkit-0.3.1 → open_code_review_toolkit-0.4.1}/pyproject.toml

@@ -1,5 +1,5 @@
 [build-system]
-requires = ["hatchling>=1.27", "hatch-vcs>=0.4"]
+requires = ["hatchling>=1.31.0", "hatch-vcs>=0.5.0"]
 build-backend = "hatchling.build"
 
 [project]
@@ -7,7 +7,7 @@ name = "open-code-review-toolkit"
 dynamic = ["version"]
 description = "Unofficial GitLab CI integration layer for Open Code Review"
 readme = "README.md"
-requires-python = ">=3.10,<3.15"
+requires-python = ">=3.12,<3.15"
 license = { file = "LICENSE" }
 authors = [{ name = "Open Code Review Toolkit contributors" }]
 keywords = ["code-review", "gitlab", "ci", "open-code-review"]
@@ -18,8 +18,6 @@ classifiers = [
   "Operating System :: MacOS",
   "Operating System :: POSIX :: Linux",
   "Programming Language :: Python :: 3 :: Only",
-  "Programming Language :: Python :: 3.10",
-  "Programming Language :: Python :: 3.11",
   "Programming Language :: Python :: 3.12",
   "Programming Language :: Python :: 3.13",
   "Programming Language :: Python :: 3.14",
@@ -39,16 +37,16 @@ ocr-ci = "ocr_toolkit.cli:main"
 [dependency-groups]
 dev = [
   "bandit==1.9.4",
-  "build>=1.2.2",
-  "coverage[toml]>=7.6",
-  "hatch-vcs>=0.4",
-  "mypy>=1.15",
-  "pip-audit>=2.7",
-  "pytest>=8.3",
-  "pytest-cov>=6.0",
-  "ruff>=0.11",
-  "towncrier>=24.8",
-  "twine>=6.1",
+  "build>=1.5.0",
+  "coverage[toml]>=7.15.2",
+  "hatch-vcs>=0.5.0",
+  "mypy>=2.3.0",
+  "pip-audit>=2.10.1",
+  "pytest>=9.1.1",
+  "pytest-cov>=7.1.0",
+  "ruff>=0.16.0",
+  "towncrier>=25.8.0",
+  "twine>=7.0.0",
 ]
 
 [tool.hatch.version]
@@ -67,13 +65,15 @@ only-include = ["src", "README.md", "LICENSE", "pyproject.toml"]
 fallback_version = "0.3.0.dev0"
 
 [tool.ruff]
-target-version = "py310"
+target-version = "py312"
 line-length = 100
 src = ["src", "tests"]
 
 [tool.ruff.lint]
 select = ["E", "F", "I", "UP", "B", "SIM", "RUF"]
-ignore = ["E402", "E501", "E731", "B007", "B023", "B905", "SIM103", "SIM105", "SIM117", "RUF002", "RUF012", "UP022"]
+# These upgrade rules describe a separate future modernization of the existing
+# codebase; changing the minimum runtime must not silently rewrite public types.
+ignore = ["E402", "E501", "E731", "B007", "B023", "B905", "SIM103", "SIM105", "SIM117", "RUF002", "RUF012", "UP017", "UP022", "UP040", "UP042", "UP045", "UP047"]
 
 [tool.ruff.lint.per-file-ignores]
 "tests/**/*.py" = ["S101"]
@@ -83,7 +83,7 @@ ignore = ["E402", "E501", "E731", "B007", "B023", "B905", "SIM103", "SIM105", "S
 exclude = ["src/ocr_toolkit/_version.py"]
 
 [tool.mypy]
-python_version = "3.10"
+python_version = "3.12"
 strict = true
 files = ["src/ocr_toolkit"]
 exclude = ["src/ocr_toolkit/_version.py"]
@@ -124,12 +124,27 @@ underlines = ["", "", ""]
 
 [[tool.towncrier.type]]
 directory = "feature"
-name = "Features"
+name = "🚀 Features"
 showcontent = true
 
 [[tool.towncrier.type]]
 directory = "bugfix"
-name = "Bug fixes"
+name = "🐛 Bug Fixes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "refactor"
+name = "🔧 Refactoring"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "doc"
+name = "📖 Documentation"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "rules"
+name = "🧩 Rules"
 showcontent = true
 
 [[tool.towncrier.type]]
@@ -138,6 +153,11 @@ name = "Security"
 showcontent = true
 
 [[tool.towncrier.type]]
-directory = "doc"
-name = "Documentation"
+directory = "deprecation"
+name = "Deprecations"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removal"
+name = "Removals"
 showcontent = true

open_code_review_toolkit-0.4.1/src/ocr_toolkit/__init__.py

@@ -0,0 +1,10 @@
+"""Open Code Review CI helper package and centralized runtime metadata."""
+
+try:
+    from ocr_toolkit._version import __version__
+except ModuleNotFoundError:
+    # Hatch-vcs creates ``_version.py`` for editable/build installs. A raw source
+    # checkout must remain importable without introducing another release version.
+    __version__ = "0+unknown"
+
+__all__ = ["__version__"]

{open_code_review_toolkit-0.3.1 → open_code_review_toolkit-0.4.1}/src/ocr_toolkit/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.3.1'
-__version_tuple__ = version_tuple = (0, 3, 1)
+__version__ = version = '0.4.1'
+__version_tuple__ = version_tuple = (0, 4, 1)
 
 __commit_id__ = commit_id = None

{open_code_review_toolkit-0.3.1 → open_code_review_toolkit-0.4.1}/src/ocr_toolkit/cli.py

@@ -8,7 +8,6 @@ from collections.abc import Sequence
 from pathlib import Path
 
 from ocr_toolkit import configure, mcp_config, preflight, review_runner
-from ocr_toolkit.context import render as context_render
 from ocr_toolkit.posting.workflow import main as posting_main
 
 
@@ -32,15 +31,6 @@ def build_parser() -> argparse.ArgumentParser:
         "ocr_args", nargs=argparse.REMAINDER, help="OCR review arguments after --."
     )
 
-    context_parser = subparsers.add_parser(
-        "context", help="Generate bounded repository review context."
-    )
-    context_parser.add_argument(
-        "--output",
-        default=".review-context/dependencies.md",
-        help="Output markdown path.",
-    )
-
     post_parser = subparsers.add_parser("post", help="Publish an OCR result artifact to GitLab.")
     post_parser.add_argument(
         # The public GitLab example writes this fixed path inside an isolated CI job.
@@ -70,12 +60,10 @@ def main(argv: Sequence[str] | None = None) -> int:
     if args.command == "review":
         ocr_args = args.ocr_args[1:] if args.ocr_args[:1] == ["--"] else args.ocr_args
         try:
-            return review_runner.run_review(Path(args.result), Path(args.stderr), ocr_args)
+            return review_runner.run_evidence_review(Path(args.result), Path(args.stderr), ocr_args)
         except review_runner.ReviewRunnerError as exc:
             print(f"Cannot run Open Code Review: {exc}", file=sys.stderr)
             return 2
-    if args.command == "context":
-        return context_render.main(["--output", args.output])
     if args.command == "post":
         return posting_main([args.result, args.stderr])
     raise AssertionError(f"unhandled command: {args.command}")

open_code_review_toolkit-0.4.1/src/ocr_toolkit/common/git.py

@@ -0,0 +1,53 @@
+"""Shared trust-boundary controls for read-only Git plumbing."""
+
+from __future__ import annotations
+
+import os
+from pathlib import Path
+
+_PROCESS_OVERRIDE_KEYS = frozenset(
+    {
+        "GIT_ALTERNATE_OBJECT_DIRECTORIES",
+        "GIT_COMMON_DIR",
+        "GIT_CONFIG_COUNT",
+        "GIT_CONFIG_PARAMETERS",
+        "GIT_DIR",
+        "GIT_INDEX_FILE",
+        "GIT_OBJECT_DIRECTORY",
+        "GIT_REPLACE_REF_BASE",
+        "GIT_WORK_TREE",
+    }
+)
+
+
+def isolated_git_environment() -> dict[str, str]:
+    """Return an environment isolated from caller-controlled Git state."""
+
+    environment = {
+        key: value
+        for key, value in os.environ.items()
+        if key not in _PROCESS_OVERRIDE_KEYS
+        and not key.startswith(("GIT_CONFIG_KEY_", "GIT_CONFIG_VALUE_"))
+    }
+    environment.update(
+        {
+            "GIT_CONFIG_GLOBAL": os.devnull,
+            "GIT_CONFIG_NOSYSTEM": "1",
+            "GIT_CONFIG_SYSTEM": os.devnull,
+            "GIT_NO_REPLACE_OBJECTS": "1",
+            "GIT_OPTIONAL_LOCKS": "0",
+            "GIT_PAGER": "cat",
+            "GIT_TERMINAL_PROMPT": "0",
+            "LC_ALL": "C",
+        }
+    )
+    return environment
+
+
+def read_only_git_prefix(root: Path | None = None) -> list[str]:
+    """Return Git arguments that bind a root and disable repository hooks."""
+
+    prefix = ["git", "-c", "core.hooksPath=/dev/null"]
+    if root is not None:
+        prefix.extend(["-C", str(root)])
+    return prefix

{open_code_review_toolkit-0.3.1 → open_code_review_toolkit-0.4.1}/src/ocr_toolkit/config_writer.py

@@ -10,6 +10,8 @@ from collections.abc import Mapping
 from pathlib import Path
 from typing import Any
 
+MAX_OCR_CONFIG_BYTES = 1_000_000
+
 
 class OCRConfigError(Exception):
     """OCR configuration could not be read or written safely."""
@@ -25,16 +27,40 @@ def read_ocr_config(path: Path | None = None) -> dict[str, Any]:
     """Read OCR config JSON, returning an empty config when it is absent."""
 
     config_path = path or ocr_config_path()
-    if not config_path.exists():
+    flags = os.O_RDONLY
+    if hasattr(os, "O_NOFOLLOW"):
+        flags |= os.O_NOFOLLOW
+    descriptor = -1
+    try:
+        descriptor = os.open(config_path, flags)
+    except FileNotFoundError:
         return {}
+    except OSError as exc:
+        raise OCRConfigError(f"cannot read OCR config: {exc}") from exc
     try:
-        data = json.loads(config_path.read_text(encoding="utf-8"))
+        metadata = os.fstat(descriptor)
+        if not stat.S_ISREG(metadata.st_mode) or metadata.st_nlink != 1:
+            raise OCRConfigError("OCR config must be a private regular file with one link")
+        if metadata.st_size > MAX_OCR_CONFIG_BYTES:
+            raise OCRConfigError("OCR config exceeds the bounded byte limit")
+        chunks: list[bytes] = []
+        remaining = MAX_OCR_CONFIG_BYTES + 1
+        while remaining:
+            chunk = os.read(descriptor, min(64 * 1024, remaining))
+            if not chunk:
+                break
+            chunks.append(chunk)
+            remaining -= len(chunk)
+        raw = b"".join(chunks)
+        if len(raw) > MAX_OCR_CONFIG_BYTES:
+            raise OCRConfigError("OCR config exceeds the bounded byte limit")
+        data = json.loads(raw)
     except json.JSONDecodeError as exc:
         raise OCRConfigError(f"OCR config is not valid JSON: {exc}") from exc
     except UnicodeDecodeError as exc:
         raise OCRConfigError(f"OCR config is not valid UTF-8: {exc}") from exc
-    except OSError as exc:
-        raise OCRConfigError(f"cannot read OCR config: {exc}") from exc
+    finally:
+        os.close(descriptor)
     if not isinstance(data, dict):
         raise OCRConfigError("OCR config top-level value is not an object")
     return data
@@ -51,6 +77,8 @@ def write_ocr_config(config: Mapping[str, Any], path: Path | None = None) -> Non
         raise OCRConfigError(f"cannot prepare OCR config directory: {exc}") from exc
 
     payload = json.dumps(config, ensure_ascii=False, indent=4, sort_keys=True) + "\n"
+    if len(payload.encode("utf-8")) > MAX_OCR_CONFIG_BYTES:
+        raise OCRConfigError("OCR config exceeds the bounded byte limit")
     tmp_name = ""
     try:
         with tempfile.NamedTemporaryFile(

open_code_review_toolkit-0.4.1/src/ocr_toolkit/evidence/__init__.py

@@ -0,0 +1,35 @@
+"""Schema-versioned repository evidence contracts and projections."""
+
+from ocr_toolkit.evidence.model import (
+    Confidence,
+    EvidenceDelta,
+    EvidenceRecord,
+    EvidenceSnapshot,
+    RefRole,
+    Sensitivity,
+    TrustClass,
+)
+from ocr_toolkit.evidence.repository import (
+    GitRepositoryReader,
+    RepositoryEvidenceError,
+    build_file_snapshot,
+    file_deltas,
+)
+from ocr_toolkit.evidence.store import EvidenceStore, EvidenceStoreError, EvidenceStoreLimits
+
+__all__ = [
+    "Confidence",
+    "EvidenceDelta",
+    "EvidenceRecord",
+    "EvidenceSnapshot",
+    "EvidenceStore",
+    "EvidenceStoreError",
+    "EvidenceStoreLimits",
+    "GitRepositoryReader",
+    "RefRole",
+    "RepositoryEvidenceError",
+    "Sensitivity",
+    "TrustClass",
+    "build_file_snapshot",
+    "file_deltas",
+]

open_code_review_toolkit-0.4.1/src/ocr_toolkit/evidence/__main__.py

@@ -0,0 +1,14 @@
+"""Run the toolkit-owned repository evidence MCP server."""
+
+from ocr_toolkit.evidence.artifacts import repository_artifacts
+from ocr_toolkit.evidence.mcp import serve
+
+
+def main() -> int:
+    """Serve the fixed private evidence store for the current repository."""
+
+    return serve(repository_artifacts().store)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

open_code_review_toolkit-0.4.1/src/ocr_toolkit/evidence/ansible.py

@@ -0,0 +1,193 @@
+"""Derive bounded Ansible topology facts from immutable repository blobs."""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+MAX_TOPOLOGY_ITEMS = 256
+PLAYBOOK_KEY_RE = re.compile(r"^(?P<indent>\s*)[\"']?(?P<key>hosts|import_playbook)[\"']?\s*:")
+INI_GROUP_RE = re.compile(r"^\s*\[(?P<group>[^]#:]+)(?::children|:vars)?]\s*$")
+YAML_GROUP_RE = re.compile(r"^(?P<indent>\s*)(?P<group>[A-Za-z0-9_.:-]+):(?:\s*\{\s*})?\s*$")
+YAML_CHILDREN_RE = re.compile(r"^(?P<indent>\s*)children:\s*$")
+
+
+@dataclass(frozen=True, slots=True)
+class AnsibleTopologyFact:
+    """Describe one normalized Ansible path or inventory-group fact."""
+
+    kind: str
+    identity: str
+    value: dict[str, str]
+
+
+def topology_candidate(path: str) -> bool:
+    """Return whether a normalized path can contribute Ansible topology."""
+
+    parts = PurePosixPath(path).parts
+    if not parts:
+        return False
+    name = parts[-1].casefold()
+    return (
+        (len(parts) == 1 and name.endswith((".yml", ".yaml")))
+        or _role_surface(path) is not None
+        or _is_inventory_path(path)
+    )
+
+
+def _role_surface(path: str) -> tuple[str, str] | None:
+    """Return role name and supported topology surface for a canonical role path."""
+
+    parts = PurePosixPath(path).parts
+    folded = tuple(part.casefold() for part in parts)
+    if (
+        len(parts) == 4
+        and folded[0] == "roles"
+        and folded[2] in {"meta", "defaults", "vars"}
+        and folded[3] in {"main.yml", "main.yaml"}
+    ):
+        surface = "metadata" if folded[2] == "meta" else folded[2]
+        return parts[1], surface
+    return None
+
+
+def _is_inventory_path(path: str) -> bool:
+    """Recognize conventional inventory paths while excluding variable payloads."""
+
+    pure = PurePosixPath(path)
+    parts = pure.parts
+    if not parts:
+        return False
+    name = parts[-1].casefold()
+    folded = tuple(part.casefold() for part in parts)
+    if "group_vars" in folded or "host_vars" in folded:
+        return False
+    return name in {
+        "hosts",
+        "hosts.ini",
+        "hosts.yml",
+        "hosts.yaml",
+        "inventory",
+        "inventory.ini",
+        "inventory.yml",
+        "inventory.yaml",
+    } or (
+        ("inventory" in folded or "inventories" in folded)
+        and pure.suffix.casefold() in {"", ".ini", ".yml", ".yaml"}
+    )
+
+
+def _is_root_playbook(path: str, text: str) -> bool:
+    """Recognize a root-level playbook from bounded YAML structure signals."""
+
+    pure = PurePosixPath(path)
+    if len(pure.parts) != 1 or pure.suffix.casefold() not in {".yml", ".yaml"}:
+        return False
+    top_level_list_item = False
+    play_child_indent: int | None = None
+    for raw_line in text.splitlines():
+        line = raw_line.rstrip()
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#") or stripped in {"---", "..."}:
+            continue
+        indent = len(line) - len(line.lstrip(" "))
+        if indent == 0 and stripped.startswith("-"):
+            top_level_list_item = True
+            play_child_indent = None
+            if PLAYBOOK_KEY_RE.match(stripped[1:].lstrip()):
+                return True
+            continue
+        if indent == 0:
+            top_level_list_item = False
+            play_child_indent = None
+            continue
+        if not top_level_list_item:
+            continue
+        if play_child_indent is None:
+            play_child_indent = indent
+        if indent == play_child_indent and PLAYBOOK_KEY_RE.match(stripped):
+            return True
+    return False
+
+
+def _inventory_groups(text: str) -> tuple[str, ...]:
+    """Extract bounded INI and YAML inventory group names without a YAML runtime."""
+
+    groups: set[str] = set()
+    children_indent: int | None = None
+    group_indent: int | None = None
+    top_level_group: str | None = None
+    for raw_line in text.splitlines():
+        ini = INI_GROUP_RE.match(raw_line)
+        if ini:
+            groups.add(ini.group("group").strip())
+            if len(groups) >= MAX_TOPOLOGY_ITEMS:
+                break
+            continue
+        children = YAML_CHILDREN_RE.match(raw_line)
+        if children:
+            children_indent = len(children.group("indent"))
+            group_indent = None
+            continue
+        yaml_group = YAML_GROUP_RE.match(raw_line)
+        if yaml_group and len(yaml_group.group("indent")) == 0:
+            group = yaml_group.group("group")
+            top_level_group = group if group not in {"all", "ungrouped"} else None
+            children_indent = None
+            group_indent = None
+            continue
+        if (
+            yaml_group
+            and top_level_group is not None
+            and yaml_group.group("group") in {"hosts", "children", "vars"}
+        ):
+            groups.add(top_level_group)
+            if yaml_group.group("group") == "children":
+                children_indent = len(yaml_group.group("indent"))
+                group_indent = None
+            continue
+        if yaml_group and children_indent is not None:
+            indent = len(yaml_group.group("indent"))
+            if indent <= children_indent:
+                children_indent = None
+                group_indent = None
+            else:
+                # YAML indentation width is repository-defined; the first key
+                # below children establishes the sibling group depth.
+                if group_indent is None:
+                    group_indent = indent
+                if indent == group_indent:
+                    groups.add(yaml_group.group("group"))
+                    if len(groups) >= MAX_TOPOLOGY_ITEMS:
+                        break
+    return tuple(sorted(groups))
+
+
+def collect_topology(path: str, text: str) -> tuple[AnsibleTopologyFact, ...]:
+    """Collect typed Ansible topology facts for one immutable path and blob."""
+
+    facts = []
+    if _is_root_playbook(path, text):
+        facts.append(AnsibleTopologyFact("ansible.playbook", path, {"path": path, "scope": "root"}))
+    role_surface = _role_surface(path)
+    if role_surface is not None:
+        role, surface = role_surface
+        facts.append(
+            AnsibleTopologyFact(
+                f"ansible.role_{surface}",
+                path,
+                {"role": role, "path": path},
+            )
+        )
+    if _is_inventory_path(path):
+        facts.append(AnsibleTopologyFact("ansible.inventory", path, {"path": path}))
+        facts.extend(
+            AnsibleTopologyFact(
+                "ansible.inventory_group",
+                f"{path}:{group}",
+                {"path": path, "group": group},
+            )
+            for group in _inventory_groups(text)
+        )
+    return tuple(facts)