file-policy 0.1.0__tar.gz

file_policy-0.1.0/PKG-INFO

@@ -0,0 +1,59 @@
+Metadata-Version: 2.4
+Name: file-policy
+Version: 0.1.0
+Summary: Diff-scoped file policy runner with rule packs
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: tomli>=2.0; python_version < "3.11"
+Provides-Extra: dev
+Requires-Dist: pytest>=7; extra == "dev"
+
+# file_policy
+
+Diff-scoped **file policy runner** for verification rule packs. One combined git changed-path pass, per-path read cache, TOML rule registry, JSON-lines violations, and exit codes for CI.
+
+Rule pack corpora live in **agent-standards** (`file_policy/rule_packs/`) and are assembled into app repos as `file-policy/packs/`. This repo is the **engine only**.
+
+## Install
+
+**Engine development:**
+
+```bash
+pip install -e ".[dev]"
+```
+
+**App repos:** commit `file-policy/requirements.txt` with `file-policy==x.y.z`. Release: push tag `v*` → GitHub Actions publishes to **PyPI** (repo secret `PYPI_API_TOKEN`). `scripts/verify/file_policy.ps1` bootstraps `.venv-file-policy`.
+
+```bash
+pip install file-policy==0.1.0
+```
+
+**One-time publish setup:** [PyPI](https://pypi.org) account → API token → GitHub repo secret **`PYPI_API_TOKEN`** → push tag **`v0.1.0`** (or next version). **GitHub repo can stay private**; the PyPI wheel is public and needs no install auth.
+
+## CLI
+
+```bash
+python -m file_policy run --repo ROOT --packs PACKS_DIR [--git-base BASE] [--scope changed|full] [--verbose]
+python -m file_policy rule test SLUG --repo ROOT --packs PACKS_DIR
+python -m file_policy rule new SLUG --packs PACKS_DIR [--kind per-file|multi-file]
+```
+
+Exit codes: **0** clean, **1** violations, **2** usage/config errors.
+
+## Rule pack layout
+
+Each pack is a directory under `PACKS_DIR` (see agent-standards `file_policy/rule_packs/<slug>/`).
+
+## MDL (minimal data loading)
+
+```python
+from file_policy import run_minimal_data_loading
+
+violations = run_minimal_data_loading(repo_root, config_dict, git_base)
+```
+
+## Tests
+
+```bash
+python -m pytest tests/ -q
+```

file_policy-0.1.0/README.md

@@ -0,0 +1,49 @@
+# file_policy
+
+Diff-scoped **file policy runner** for verification rule packs. One combined git changed-path pass, per-path read cache, TOML rule registry, JSON-lines violations, and exit codes for CI.
+
+Rule pack corpora live in **agent-standards** (`file_policy/rule_packs/`) and are assembled into app repos as `file-policy/packs/`. This repo is the **engine only**.
+
+## Install
+
+**Engine development:**
+
+```bash
+pip install -e ".[dev]"
+```
+
+**App repos:** commit `file-policy/requirements.txt` with `file-policy==x.y.z`. Release: push tag `v*` → GitHub Actions publishes to **PyPI** (repo secret `PYPI_API_TOKEN`). `scripts/verify/file_policy.ps1` bootstraps `.venv-file-policy`.
+
+```bash
+pip install file-policy==0.1.0
+```
+
+**One-time publish setup:** [PyPI](https://pypi.org) account → API token → GitHub repo secret **`PYPI_API_TOKEN`** → push tag **`v0.1.0`** (or next version). **GitHub repo can stay private**; the PyPI wheel is public and needs no install auth.
+
+## CLI
+
+```bash
+python -m file_policy run --repo ROOT --packs PACKS_DIR [--git-base BASE] [--scope changed|full] [--verbose]
+python -m file_policy rule test SLUG --repo ROOT --packs PACKS_DIR
+python -m file_policy rule new SLUG --packs PACKS_DIR [--kind per-file|multi-file]
+```
+
+Exit codes: **0** clean, **1** violations, **2** usage/config errors.
+
+## Rule pack layout
+
+Each pack is a directory under `PACKS_DIR` (see agent-standards `file_policy/rule_packs/<slug>/`).
+
+## MDL (minimal data loading)
+
+```python
+from file_policy import run_minimal_data_loading
+
+violations = run_minimal_data_loading(repo_root, config_dict, git_base)
+```
+
+## Tests
+
+```bash
+python -m pytest tests/ -q
+```

file_policy-0.1.0/file_policy/__init__.py

@@ -0,0 +1,14 @@
+"""Diff-scoped file policy runner."""
+
+from file_policy.violations import Violation, violation_to_json_line
+from file_policy.runner import run_policy
+from file_policy.registry import load_rule_packs
+from file_policy.mdl.engine import run_minimal_data_loading
+
+__all__ = [
+    "Violation",
+    "violation_to_json_line",
+    "run_policy",
+    "load_rule_packs",
+    "run_minimal_data_loading",
+]

file_policy-0.1.0/file_policy/__main__.py

@@ -0,0 +1,4 @@
+from file_policy.cli import main
+
+if __name__ == "__main__":
+    raise SystemExit(main())

file_policy-0.1.0/file_policy/cache.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+
+class FileCache:
+    """Read each repo-relative path at most once."""
+
+    def __init__(self, repo_root: str | Path) -> None:
+        self.repo_root = Path(repo_root).resolve()
+        self._text: dict[str, str] = {}
+        self._lines: dict[str, list[str]] = {}
+
+    def read_text(self, relative_path: str) -> str:
+        key = relative_path.replace("\\", "/")
+        if key not in self._text:
+            full = self.repo_root / key
+            self._text[key] = full.read_text(encoding="utf-8", errors="replace")
+        return self._text[key]
+
+    def read_lines(self, relative_path: str) -> list[str]:
+        key = relative_path.replace("\\", "/")
+        if key not in self._lines:
+            self._lines[key] = self.read_text(key).splitlines()
+        return self._lines[key]
+
+    def paths_loaded(self) -> frozenset[str]:
+        return frozenset(self._text.keys())

file_policy-0.1.0/file_policy/cli.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+import argparse
+import sys
+
+from file_policy.rule_new import scaffold_rule
+from file_policy.rule_test import run_rule_test
+from file_policy.runner import run_policy
+from file_policy.violations import emit_violations
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="file_policy")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    run_p = sub.add_parser("run", help="Run rule packs against a repo")
+    run_p.add_argument("--repo", required=True, help="Repository root")
+    run_p.add_argument("--packs", required=True, help="Rule packs directory")
+    run_p.add_argument("--git-base", default=None, help="Git base ref for diff scope")
+    run_p.add_argument(
+        "--scope",
+        choices=["changed", "full"],
+        default="changed",
+        help="File scope (default: changed)",
+    )
+    run_p.add_argument("--verbose", action="store_true")
+
+    rule_p = sub.add_parser("rule", help="Rule pack utilities")
+    rule_sub = rule_p.add_subparsers(dest="rule_command", required=True)
+
+    test_p = rule_sub.add_parser("test", help="Test a rule pack fixtures")
+    test_p.add_argument("slug", help="Rule slug")
+    test_p.add_argument("--repo", required=True)
+    test_p.add_argument("--packs", required=True)
+
+    new_p = rule_sub.add_parser("new", help="Scaffold a new rule pack")
+    new_p.add_argument("slug", help="Rule slug")
+    new_p.add_argument("--packs", required=True)
+    new_p.add_argument(
+        "--kind",
+        choices=["per-file", "multi-file"],
+        default="per-file",
+    )
+
+    return parser
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    try:
+        if args.command == "run":
+            if args.scope == "changed" and not args.git_base:
+                print(
+                    "warning: --git-base not set; changed scope yields no files",
+                    file=sys.stderr,
+                )
+            violations = run_policy(
+                args.repo,
+                args.packs,
+                git_base=args.git_base,
+                scope=args.scope,
+            )
+            if args.verbose:
+                print(
+                    f"file_policy: {len(violations)} violation(s)",
+                    file=sys.stderr,
+                )
+            emit_violations(violations)
+            return 1 if violations else 0
+
+        if args.command == "rule":
+            if args.rule_command == "test":
+                errors = run_rule_test(args.slug, args.repo, args.packs)
+                if errors:
+                    for e in errors:
+                        print(e, file=sys.stderr)
+                    return 1
+                print(f"rule test {args.slug}: passed")
+                return 0
+
+            if args.rule_command == "new":
+                path = scaffold_rule(args.slug, args.packs, kind=args.kind)
+                print(f"created {path}")
+                return 0
+
+        parser.print_help()
+        return 2
+    except (FileNotFoundError, KeyError, ValueError, AttributeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

file_policy-0.1.0/file_policy/fixture_paths.py

@@ -0,0 +1,50 @@
+from __future__ import annotations
+
+from pathlib import Path
+
+FIXTURE_TIERS = frozenset({"bad", "good"})
+
+
+def fixture_virtual_rel(tier: str, language: str, case_id: str) -> str:
+    """Synthetic path for rule-test snippets (not a repo file path)."""
+    if tier not in FIXTURE_TIERS:
+        raise ValueError(f"fixture tier must be bad|good, got {tier!r}")
+    return f"{tier}/{language}/{case_id}"
+
+
+def fixture_repo_relpath(language: str, case_id: str) -> Path:
+    """Where a snippet is written in a temp repo so MDL surfaces pick it up."""
+    if language == "dart":
+        return Path("lib/features/fixture") / f"{case_id}_repository.dart"
+    if language == "rust":
+        return Path("api/src/db") / f"{case_id}.rs"
+    raise ValueError(f"unsupported fixture language: {language!r}")
+
+
+def is_fixture_virtual_path(path: str) -> bool:
+    norm = path.replace("\\", "/")
+    parts = norm.split("/")
+    if len(parts) != 3:
+        return False
+    tier, language, case_id = parts
+    if tier not in FIXTURE_TIERS or not case_id:
+        return False
+    return language in ("dart", "rust")
+
+
+def fixture_repo_path_from_virtual(fixture_rel: str) -> Path:
+    norm = fixture_rel.replace("\\", "/")
+    if is_fixture_virtual_path(norm):
+        _tier, language, case_id = norm.split("/", 2)
+        return fixture_repo_relpath(language, case_id)
+    return _legacy_fixture_repo_path(norm)
+
+
+def _legacy_fixture_repo_path(fixture_rel: str) -> Path:
+    """bad/foo.dart layout (deprecated)."""
+    name = Path(fixture_rel).name
+    if name.endswith("_repository.dart") or name.endswith(".dart"):
+        return Path("lib/features/fixture") / name.replace(".dart", "_repository.dart")
+    if name.endswith(".rs"):
+        return Path("api/src/db") / name
+    raise ValueError(f"unsupported fixture path: {fixture_rel}")

file_policy-0.1.0/file_policy/fixtures.py

@@ -0,0 +1,103 @@
+from __future__ import annotations
+
+import json
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+
+@dataclass(frozen=True)
+class FixtureCase:
+    id: str
+    language: str
+    tier: str  # "bad" | "good"
+    source: str
+    message_contains: tuple[str, ...] = ()
+
+
+def _load_toml(path: Path) -> dict[str, Any]:
+    text = path.read_text(encoding="utf-8")
+    if sys.version_info >= (3, 11):
+        import tomllib
+
+        return tomllib.loads(text)
+    import tomli
+
+    return tomli.loads(text)
+
+
+def load_pack_languages(pack_dir: Path) -> frozenset[str]:
+    """Languages this rule applies to (meta.toml, else config.json surfaces)."""
+    meta_path = pack_dir / "meta.toml"
+    if meta_path.is_file():
+        raw = _load_toml(meta_path)
+        langs = raw.get("languages")
+        if isinstance(langs, list) and all(isinstance(x, str) for x in langs):
+            return frozenset(langs)
+
+    config_path = pack_dir / "config.json"
+    if config_path.is_file():
+        cfg = json.loads(config_path.read_text(encoding="utf-8"))
+        from_surfaces: set[str] = set()
+        for surface in cfg.get("surfaces") or []:
+            lang = surface.get("language")
+            if isinstance(lang, str) and lang:
+                from_surfaces.add(lang)
+        if from_surfaces:
+            return frozenset(from_surfaces)
+
+    return frozenset()
+
+
+def load_fixture_cases(pack_dir: Path) -> list[FixtureCase]:
+    path = pack_dir / "fixtures.toml"
+    if not path.is_file():
+        return []
+    raw = _load_toml(path)
+    rows = raw.get("case")
+    if rows is None:
+        return []
+    if not isinstance(rows, list):
+        raise ValueError(f"fixtures.toml 'case' must be an array in {path}")
+
+    allowed = load_pack_languages(pack_dir)
+    cases: list[FixtureCase] = []
+    for i, row in enumerate(rows):
+        if not isinstance(row, dict):
+            raise ValueError(f"fixtures.toml case[{i}] must be a table in {path}")
+        tier = row.get("tier")
+        case_id = row.get("id")
+        language = row.get("language")
+        source = row.get("source")
+        if tier not in ("bad", "good"):
+            raise ValueError(f"fixtures.toml case[{i}].tier must be bad|good")
+        if not case_id or not isinstance(case_id, str):
+            raise ValueError(f"fixtures.toml case[{i}].id required")
+        if not language or not isinstance(language, str):
+            raise ValueError(f"fixtures.toml case[{i}].language required")
+        if allowed and language not in allowed:
+            raise ValueError(
+                f"fixtures.toml case[{i}].language {language!r} not in pack languages "
+                f"{sorted(allowed)!r} (meta.toml languages or config surfaces)"
+            )
+        if source is None or not isinstance(source, str):
+            raise ValueError(f"fixtures.toml case[{i}].source required")
+        msgs = row.get("message_contains", [])
+        if msgs is None:
+            msgs = []
+        if not isinstance(msgs, list):
+            raise ValueError(f"fixtures.toml case[{i}].message_contains must be a list")
+        body = source.strip()
+        if body and not body.endswith("\n"):
+            body += "\n"
+        cases.append(
+            FixtureCase(
+                id=case_id,
+                language=language,
+                tier=tier,
+                source=body,
+                message_contains=tuple(str(m) for m in msgs),
+            )
+        )
+    return cases

file_policy-0.1.0/file_policy/git_paths.py

@@ -0,0 +1,144 @@
+"""Single combined git pass for changed paths (merge-base diff triplets + untracked)."""
+
+from __future__ import annotations
+
+import subprocess
+from pathlib import Path
+
+
+def _normalize_repo_path(path: str) -> str:
+    return path.replace("\\", "/").strip()
+
+
+def _path_filter_suffix(git_path: str) -> list[str]:
+    """Git path limiter; omit trailing empty path (breaks `git diff`)."""
+    if git_path:
+        return ["--", git_path]
+    return []
+
+
+def _invoke_git(repo_root: Path, args: list[str]) -> list[str]:
+    try:
+        result = subprocess.run(
+            ["git", *args],
+            cwd=repo_root,
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+    except OSError:
+        return []
+    if result.returncode != 0:
+        return []
+    lines: list[str] = []
+    for line in result.stdout.splitlines():
+        line = line.strip()
+        if line:
+            lines.append(line)
+    return lines
+
+
+def git_changed_files(
+    repo: str | Path,
+    base: str | None,
+    *,
+    scope: str = "changed",
+    path_prefix: str = "",
+    include_regex: str | None = None,
+) -> set[str]:
+    """
+    Return normalized repo-relative paths changed vs base.
+
+    scope:
+      - ``changed``: diff vs base (three diff passes) + untracked under prefix
+      - ``full``: all tracked + untracked under prefix (ignores base for listing)
+    """
+    import re
+
+    repo_root = Path(repo).resolve()
+    prefix = _normalize_repo_path(path_prefix).rstrip("/")
+    git_path = f"{prefix}/" if prefix else ""
+
+    if scope == "full":
+        files: set[str] = set()
+        ls_args = ["ls-files", *([git_path] if git_path else [])]
+        for line in _invoke_git(repo_root, ls_args):
+            norm = _normalize_repo_path(line)
+            if include_regex and not re.search(include_regex, norm):
+                continue
+            files.add(norm)
+        untracked_args = ["ls-files", "--others", "--exclude-standard"]
+        if git_path:
+            untracked_args.append(git_path)
+        for line in _invoke_git(repo_root, untracked_args):
+            norm = _normalize_repo_path(line)
+            if include_regex and not re.search(include_regex, norm):
+                continue
+            files.add(norm)
+        return files
+
+    if scope != "changed":
+        raise ValueError(f"unknown scope: {scope!r}")
+
+    files_set: set[str] = set()
+    if not base:
+        return files_set
+
+    suffix = _path_filter_suffix(git_path)
+    diff_arg_sets = [
+        ["diff", "--name-only", f"{base}...HEAD", *suffix],
+        ["diff", "--name-only", "HEAD", *suffix],
+        ["diff", "--cached", "--name-only", *suffix],
+    ]
+    for args in diff_arg_sets:
+        for line in _invoke_git(repo_root, args):
+            norm = _normalize_repo_path(line)
+            if include_regex and not re.search(include_regex, norm):
+                continue
+            files_set.add(norm)
+
+    untracked_args = ["ls-files", "--others", "--exclude-standard"]
+    if git_path:
+        untracked_args.append(git_path)
+    for line in _invoke_git(repo_root, untracked_args):
+        norm = _normalize_repo_path(line)
+        if include_regex and not re.search(include_regex, norm):
+            continue
+        files_set.add(norm)
+
+    return files_set
+
+
+def git_changed_line_numbers(
+    repo: str | Path,
+    base: str | None,
+    relative_path: str,
+) -> set[int]:
+    """Line numbers (1-based) changed in relative_path vs base (three diff passes)."""
+    import re
+
+    repo_root = Path(repo).resolve()
+    lines_set: set[int] = set()
+    if not base:
+        return lines_set
+
+    path_arg = _normalize_repo_path(relative_path)
+    hunk_re = re.compile(r"^@@\s+-[0-9,]+\s+\+([0-9]+)(?:,([0-9]+))?\s+@@")
+
+    for args in (
+        ["diff", "-U0", f"{base}...HEAD", "--", path_arg],
+        ["diff", "-U0", "HEAD", "--", path_arg],
+        ["diff", "--cached", "-U0", "--", path_arg],
+    ):
+        for line in _invoke_git(repo_root, args):
+            m = hunk_re.match(line)
+            if not m:
+                continue
+            start = int(m.group(1))
+            count = int(m.group(2)) if m.group(2) else 1
+            if count <= 0:
+                continue
+            for n in range(start, start + count):
+                lines_set.add(n)
+
+    return lines_set

file_policy-0.1.0/file_policy/mdl/__init__.py

@@ -0,0 +1,3 @@
+from file_policy.mdl.engine import run_minimal_data_loading
+
+__all__ = ["run_minimal_data_loading"]