sourcepack 1.10.0a0__py3-none-any.whl

sourcepack/commands.py

@@ -0,0 +1,149 @@
+from __future__ import annotations
+
+import configparser
+import json
+import re
+from dataclasses import dataclass
+from pathlib import Path
+
+COMMAND_SCHEMA_VERSION = "sourcepack.command_resolver.v1"
+COMPOSE_FILES = ("compose.yml", "compose.yaml", "docker-compose.yml", "docker-compose.yaml")
+
+
+@dataclass(frozen=True)
+class CommandResolution:
+    verdict: str
+    reason_code: str | None
+    command: str
+    evidence_source: str | None = None
+    message: str = ""
+
+    def to_dict(self) -> dict:
+        return {"schema_version": COMMAND_SCHEMA_VERSION, "verdict": self.verdict, "reason_code": self.reason_code, "command": self.command, "evidence_source": self.evidence_source, "message": self.message}
+
+
+def _safe(root: Path, rel: str) -> Path | None:
+    p = (root / rel).resolve()
+    try:
+        p.relative_to(root.resolve())
+    except ValueError:
+        return None
+    return p
+
+
+def _read_json(path: Path) -> dict | None:
+    try:
+        return json.loads(path.read_text(encoding="utf-8"))
+    except Exception:
+        return None
+
+
+def _make_targets(text: str) -> set[str]:
+    return {m.group(1) for m in re.finditer(r"^([A-Za-z0-9_.-][^\s:=]*)\s*:(?!=)", text, re.M)}
+
+
+def _just_targets(text: str) -> set[str]:
+    return {m.group(1) for m in re.finditer(r"^([A-Za-z0-9_.-]+)\s*:", text, re.M)}
+
+
+def _taskfile_targets(data: dict) -> set[str]:
+    tasks = data.get("tasks") if isinstance(data, dict) else None
+    return set(tasks.keys()) if isinstance(tasks, dict) else set()
+
+
+def resolve_command(root: str | Path, command: str, *, added_manifests: dict[str, str] | None = None) -> CommandResolution:
+    root = Path(root).resolve(); added_manifests = added_manifests or {}; command = command.strip()
+    parts = command.split()
+    if not parts:
+        return CommandResolution("WARN", "command_check_inconclusive", command, message="empty command")
+    if len(parts) >= 3 and parts[0] == "npm" and parts[1] == "run":
+        script = parts[2]
+        pj = _safe(root, "package.json")
+        if "package.json" in added_manifests:
+            data = _read_json_from_text(added_manifests["package.json"])
+            if script in (data.get("scripts") or {}):
+                return CommandResolution("WARN", "declared_command", command, "package.json", "script added in patch")
+        if not pj or not pj.exists():
+            return CommandResolution("WARN", "command_manifest_missing", command, "package.json", "package.json missing")
+        data = _read_json(pj) or {}
+        return CommandResolution("PASS", None, command, "package.json", "script present") if script in (data.get("scripts") or {}) else CommandResolution("FAIL", "unsupported_command", command, "package.json", "npm script missing")
+    if len(parts) >= 3 and parts[0] == "docker" and parts[1] == "compose":
+        for name in COMPOSE_FILES:
+            p = _safe(root, name)
+            if p and p.exists():
+                return CommandResolution("PASS", None, command, name, "compose file present")
+        return CommandResolution("FAIL", "unsupported_command", command, ",".join(COMPOSE_FILES), "compose file missing")
+    if parts[0] == "make" and len(parts) >= 2:
+        p = _safe(root, "Makefile")
+        if not p or not p.exists():
+            return CommandResolution("WARN", "command_manifest_missing", command, "Makefile", "Makefile missing")
+        targets = _make_targets(p.read_text(encoding="utf-8", errors="ignore"))
+        return CommandResolution("PASS", None, command, "Makefile", "target present") if parts[1] in targets else CommandResolution("FAIL", "unsupported_command", command, "Makefile", "Make target missing")
+    if parts[0] == "just" and len(parts) >= 2:
+        p = _safe(root, "justfile") or _safe(root, "Justfile")
+        if not p or not p.exists():
+            return CommandResolution("WARN", "command_manifest_missing", command, "justfile", "justfile missing")
+        targets = _just_targets(p.read_text(encoding="utf-8", errors="ignore"))
+        return CommandResolution("PASS", None, command, str(p.name), "recipe present") if parts[1] in targets else CommandResolution("FAIL", "unsupported_command", command, str(p.name), "recipe missing")
+    if parts[0] == "task" and len(parts) >= 2:
+        for name in ("Taskfile.yml", "Taskfile.yaml"):
+            p = _safe(root, name)
+            if p and p.exists():
+                try:
+                    import yaml  # type: ignore
+                    data = yaml.safe_load(p.read_text(encoding="utf-8")) or {}
+                except Exception:
+                    data = _simple_taskfile_parse(p.read_text(encoding="utf-8", errors="ignore"))
+                targets = _taskfile_targets(data)
+                return CommandResolution("PASS", None, command, name, "task present") if parts[1] in targets else CommandResolution("FAIL", "unsupported_command", command, name, "task missing")
+        return CommandResolution("WARN", "command_manifest_missing", command, "Taskfile.yml", "Taskfile missing")
+    if parts[0] in {"pytest", "py.test"} or (len(parts) >= 3 and parts[0] == "python" and parts[1] == "-m" and parts[2] == "pytest"):
+        has_tests = any((root / name).exists() for name in ("tests", "test", "pytest.ini"))
+        if has_tests:
+            return CommandResolution("PASS", None, command, "tests", "pytest evidence present")
+        pyproject = _safe(root, "pyproject.toml")
+        requirements = list(root.glob("requirements*.txt"))
+        manifest_text = "\n".join(p.read_text(encoding="utf-8", errors="ignore") for p in ([pyproject] if pyproject and pyproject.exists() else []) + requirements)
+        if re.search(r"(?im)\bpytest\b", manifest_text):
+            return CommandResolution("PASS", None, command, "python dependency manifest", "pytest dependency present")
+        return CommandResolution("FAIL", "unsupported_command", command, "tests/pytest.ini/pyproject.toml", "pytest project evidence missing")
+    if parts[0] == "tox" and "-e" in parts:
+        env = parts[parts.index("-e") + 1] if parts.index("-e") + 1 < len(parts) else ""
+        p = _safe(root, "tox.ini")
+        if not p or not p.exists():
+            return CommandResolution("WARN", "command_check_inconclusive", command, "tox.ini", "tox.ini missing")
+        cp = configparser.ConfigParser(); cp.read(p)
+        raw = cp.get("tox", "envlist", fallback="")
+        if "{" in raw or "}" in raw or not raw:
+            return CommandResolution("WARN", "command_check_inconclusive", command, "tox.ini", "dynamic or missing envlist")
+        envs = {e.strip() for e in re.split(r"[,\n]", raw) if e.strip()}
+        return CommandResolution("PASS", None, command, "tox.ini", "env present") if env in envs else CommandResolution("FAIL", "unsupported_command", command, "tox.ini", "tox env missing")
+    if parts[0] == "nox" and "-s" in parts:
+        session = parts[parts.index("-s") + 1] if parts.index("-s") + 1 < len(parts) else ""
+        p = _safe(root, "noxfile.py")
+        if not p or not p.exists():
+            return CommandResolution("WARN", "command_manifest_missing", command, "noxfile.py", "noxfile missing")
+        text = p.read_text(encoding="utf-8", errors="ignore")
+        if re.search(r"@nox\.session(?:\([^)]*\))?\s*\ndef\s+" + re.escape(session) + r"\b", text):
+            return CommandResolution("PASS", None, command, "noxfile.py", "session present")
+        return CommandResolution("WARN", "command_check_inconclusive", command, "noxfile.py", "dynamic or missing nox session")
+    return CommandResolution("WARN", "command_check_inconclusive", command, message="command parser unsupported")
+
+
+def _read_json_from_text(text: str) -> dict:
+    try:
+        return json.loads(text)
+    except Exception:
+        return {}
+
+
+def _simple_taskfile_parse(text: str) -> dict:
+    tasks: dict[str, dict] = {}
+    in_tasks = False
+    for line in text.splitlines():
+        if re.match(r"^tasks:\s*$", line):
+            in_tasks = True; continue
+        if in_tasks:
+            m = re.match(r"^\s{2}([A-Za-z0-9_.-]+):", line)
+            if m: tasks[m.group(1)] = {}
+    return {"tasks": tasks}

sourcepack/dependencies.py

@@ -0,0 +1,98 @@
+from __future__ import annotations
+
+import ast, json, re, sys, tomllib
+from dataclasses import dataclass
+from pathlib import Path
+from .ecosystems.python import PY_IMPORT_ALIASES
+
+DEPENDENCY_SCHEMA_VERSION = "sourcepack.dependency_resolver.v1"
+UNSUPPORTED_ECOSYSTEM_MANIFESTS = {"Cargo.toml", "go.mod", "pom.xml", "build.gradle", "settings.gradle"}
+
+@dataclass(frozen=True)
+class DependencyResolution:
+    verdict: str
+    reason_code: str | None
+    dependency: str
+    evidence_source: str | None = None
+    message: str = ""
+    def to_dict(self) -> dict:
+        return {"schema_version": DEPENDENCY_SCHEMA_VERSION, "verdict": self.verdict, "reason_code": self.reason_code, "dependency": self.dependency, "evidence_source": self.evidence_source, "message": self.message}
+
+def normalize_python_package(name: str) -> str:
+    base = name.split(".")[0].replace("_", "-").lower()
+    return PY_IMPORT_ALIASES.get(base, base)
+
+def normalize_js_package(spec: str) -> str:
+    if spec.startswith(".") or spec.startswith("/"):
+        return spec
+    parts = spec.split("/")
+    return "/".join(parts[:2]) if spec.startswith("@") and len(parts) >= 2 else parts[0]
+
+def python_declared_dependencies(root: str | Path) -> dict[str, str]:
+    root = Path(root); found: dict[str, str] = {}
+    pyproject = root / "pyproject.toml"
+    if pyproject.exists():
+        try: data = tomllib.loads(pyproject.read_text(encoding="utf-8"))
+        except Exception: data = {}
+        for dep in data.get("project", {}).get("dependencies", []) or []: found[_dep_name(dep)] = "pyproject.toml"
+        for group, deps in (data.get("project", {}).get("optional-dependencies", {}) or {}).items():
+            for dep in deps or []: found.setdefault(_dep_name(dep), f"pyproject.toml optional:{group}")
+        for group, gdata in (data.get("dependency-groups", {}) or {}).items():
+            for dep in (gdata if isinstance(gdata, list) else []): found.setdefault(_dep_name(str(dep)), f"pyproject.toml group:{group}")
+        poetry = data.get("tool", {}).get("poetry", {}).get("dependencies", {}) or {}
+        for dep in poetry:
+            if dep.lower() != "python": found[_dep_name(dep)] = "pyproject.toml poetry"
+    for req in root.glob("requirements*.txt"):
+        for line in req.read_text(encoding="utf-8", errors="ignore").splitlines():
+            line = line.strip()
+            if line and not line.startswith("#") and not line.startswith("-"):
+                found[_dep_name(line)] = req.name
+    return found
+
+def js_declared_dependencies(root: str | Path) -> dict[str, str]:
+    pj = Path(root) / "package.json"; found: dict[str, str] = {}
+    if not pj.exists(): return found
+    try: data = json.loads(pj.read_text(encoding="utf-8"))
+    except Exception: return found
+    for section in ("dependencies", "devDependencies", "peerDependencies", "optionalDependencies"):
+        for dep in (data.get(section) or {}): found[dep] = f"package.json {section}"
+    return found
+
+def resolve_python_import(root: str | Path, imported: str, *, added_dependencies: set[str] | None = None) -> DependencyResolution:
+    root = Path(root); top = imported.split(".")[0]
+    if top in sys.stdlib_module_names: return DependencyResolution("PASS", None, imported, "python stdlib", "stdlib")
+    if (root / (top + ".py")).exists() or (root / top / "__init__.py").exists() or (root / "src" / top / "__init__.py").exists() or (root / "src" / (top + ".py")).exists(): return DependencyResolution("PASS", None, imported, "worktree", "local module")
+    pkg = normalize_python_package(imported); declared = python_declared_dependencies(root)
+    if pkg in (added_dependencies or set()): return DependencyResolution("WARN", "declared_dependency", pkg, "patch", "dependency added in same patch")
+    if pkg in declared:
+        source = declared[pkg]
+        if "optional:" in source or "group:" in source: return DependencyResolution("WARN", "dependency_scope_review", pkg, source, "declared outside runtime dependency scope")
+        return DependencyResolution("PASS", None, pkg, source, "declared")
+    return DependencyResolution("FAIL", "unsupported_dependency", pkg, None, "external dependency not declared")
+
+def resolve_js_import(root: str | Path, spec: str) -> DependencyResolution:
+    root = Path(root); pkg = normalize_js_package(spec)
+    if pkg.startswith(".") or pkg.startswith("/"): return DependencyResolution("PASS", None, spec, "relative import", "local relative import")
+    declared = js_declared_dependencies(root)
+    if pkg in declared:
+        src = declared[pkg]
+        if "devDependencies" in src: return DependencyResolution("WARN", "dependency_scope_review", pkg, src, "devDependency requires scope review")
+        return DependencyResolution("PASS", None, pkg, src, "declared")
+    if spec.startswith(("@/", "~/")):
+        return DependencyResolution("WARN", "js_alias_uncertain", spec, "tsconfig.json", "alias requires bounded resolver")
+    return DependencyResolution("FAIL", "unsupported_dependency", pkg, None, "package dependency not declared")
+
+def unsupported_ecosystems(root: str | Path) -> list[DependencyResolution]:
+    root = Path(root); return [DependencyResolution("WARN", "unsupported_ecosystem", m.name, m.name, "ecosystem detected but not semantically resolved") for m in root.iterdir() if m.name in UNSUPPORTED_ECOSYSTEM_MANIFESTS]
+
+def imports_from_python_source(text: str) -> set[str]:
+    out = set()
+    try: tree = ast.parse(text)
+    except SyntaxError: return out
+    for node in ast.walk(tree):
+        if isinstance(node, ast.Import): out.update(alias.name for alias in node.names)
+        elif isinstance(node, ast.ImportFrom) and node.level == 0 and node.module: out.add(node.module)
+    return out
+
+def _dep_name(spec: str) -> str:
+    return re.split(r"[<>=!~;\[\s]", str(spec).strip(), 1)[0].replace("_", "-").lower()

sourcepack/diff_parser.py

@@ -0,0 +1,122 @@
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+from pathlib import PurePosixPath
+
+@dataclass
+class PatchFileChange:
+    path: str
+    old_path: str | None
+    new_file: bool = False
+    deleted_file: bool = False
+    added_lines: list[str] | None = None
+    diff_lines: list[str] | None = None
+    unsafe_path: bool = False
+    operation: str = "modify"
+
+
+def normalize_diff_path(path: str) -> tuple[str, bool]:
+    raw = path.strip().replace("\\", "/")
+    if raw.startswith("a/") or raw.startswith("b/"):
+        raw = raw[2:]
+    if not raw or raw in {"a/", "b/"}:
+        return raw, True
+    if raw.startswith("/") or re.match(r"^[A-Za-z]:/", raw):
+        return raw, True
+    parts: list[str] = []
+    unsafe = False
+    for part in PurePosixPath(raw).parts:
+        if part in {"", "."}:
+            continue
+        if part == "..":
+            if not parts:
+                unsafe = True
+            else:
+                parts.pop()
+            continue
+        parts.append(part)
+    return "/".join(parts), unsafe
+
+
+def parse_unified_diff(text: str) -> list[PatchFileChange]:
+    changes: list[PatchFileChange] = []
+    current: PatchFileChange | None = None
+    old_path: str | None = None
+    new_path: str | None = None
+    new_file = False
+    deleted_file = False
+    operation = "modify"
+
+    malformed = False
+
+    def clean(path: str) -> tuple[str, bool]:
+        path = path.strip().split("\t", 1)[0]
+        return normalize_diff_path(path)
+
+    def flush():
+        nonlocal current
+        if current is not None:
+            changes.append(current)
+            current = None
+
+    for line in text.splitlines():
+        if line.startswith("diff --git "):
+            flush(); old_path = new_path = None; new_file = deleted_file = False; operation = "modify"
+            parts = line.split()
+            if len(parts) >= 4:
+                old_path, old_unsafe = clean(parts[2]); new_path, new_unsafe = clean(parts[3])
+                if old_unsafe or new_unsafe:
+                    malformed = True
+            else:
+                malformed = True
+        elif line.startswith("new file mode"):
+            new_file = True
+        elif line.startswith("deleted file mode"):
+            deleted_file = True
+        elif line.startswith("rename from "):
+            old_path, unsafe = clean(line.removeprefix("rename from "))
+            operation = "rename"
+            malformed = malformed or unsafe
+        elif line.startswith("rename to "):
+            new_path, unsafe = clean(line.removeprefix("rename to "))
+            operation = "rename"
+            malformed = malformed or unsafe
+            current = PatchFileChange(path=new_path or old_path or "", old_path=old_path, new_file=False, deleted_file=False, added_lines=[], diff_lines=[], unsafe_path=unsafe, operation=operation)
+        elif line.startswith("copy from "):
+            old_path, unsafe = clean(line.removeprefix("copy from "))
+            operation = "copy"
+            malformed = malformed or unsafe
+        elif line.startswith("copy to "):
+            new_path, unsafe = clean(line.removeprefix("copy to "))
+            operation = "copy"
+            malformed = malformed or unsafe
+            current = PatchFileChange(path=new_path or old_path or "", old_path=old_path, new_file=True, deleted_file=False, added_lines=[], diff_lines=[], unsafe_path=unsafe, operation=operation)
+        elif line.startswith("--- "):
+            val = line[4:].strip()
+            if val == "/dev/null":
+                old_path = None
+            else:
+                old_path, unsafe = clean(val)
+                malformed = malformed or unsafe
+        elif line.startswith("+++ "):
+            val = line[4:].strip()
+            if val == "/dev/null":
+                new_path = None
+                unsafe = False
+            else:
+                new_path, unsafe = clean(val)
+            malformed = malformed or unsafe
+            path = new_path or old_path or ""
+            current = PatchFileChange(path=path, old_path=old_path, new_file=new_file or old_path is None, deleted_file=deleted_file or new_path is None, added_lines=[], diff_lines=[], unsafe_path=unsafe, operation=operation)
+        elif line.startswith("@@ ") and current is None:
+            malformed = True
+        elif current is not None and line.startswith("+") and not line.startswith("+++"):
+            current.added_lines.append(line[1:])
+            current.diff_lines.append(line)
+        elif current is not None and (line.startswith("-") or line.startswith(" ") or line.startswith("@@")):
+            current.diff_lines.append(line)
+    flush()
+    if malformed:
+        changes.append(PatchFileChange(path="", old_path=None, added_lines=[], diff_lines=[], unsafe_path=True))
+    return changes

sourcepack/ecosystems/__init__.py

@@ -0,0 +1,3 @@
+from .python import PY_IMPORT_ALIASES
+
+__all__ = ["PY_IMPORT_ALIASES"]

sourcepack/ecosystems/generic.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+UNSUPPORTED_ECOSYSTEM_FILES = {
+    "Cargo.toml": "Rust/Cargo",
+    "go.mod": "Go modules",
+    "pom.xml": "Java/Maven",
+    "build.gradle": "Java/Gradle",
+    "Gemfile": "Ruby/Bundler",
+    "composer.json": "PHP/Composer",
+    "*.csproj": ".NET/NuGet",
+    "main.tf": "Terraform",
+    "flake.nix": "Nix",
+}

sourcepack/ecosystems/node.py

@@ -0,0 +1,3 @@
+from __future__ import annotations
+
+JS_SOURCE_EXTENSIONS = {".js", ".jsx", ".ts", ".tsx"}

sourcepack/ecosystems/python.py

@@ -0,0 +1,12 @@
+from __future__ import annotations
+
+PY_IMPORT_ALIASES: dict[str, str] = {
+    "yaml": "pyyaml",
+    "cv2": "opencv-python",
+    "pil": "pillow",
+    "sklearn": "scikit-learn",
+    "bs4": "beautifulsoup4",
+    "dotenv": "python-dotenv",
+    "jwt": "pyjwt",
+    "dateutil": "python-dateutil",
+}

sourcepack/errors.py

@@ -0,0 +1,19 @@
+from __future__ import annotations
+
+class SourcePackError(Exception):
+    """Base class for typed SourcePack core failures."""
+
+class BaselineMissingError(SourcePackError):
+    pass
+
+class BaselineCorruptError(SourcePackError):
+    pass
+
+class MalformedDiffError(SourcePackError):
+    pass
+
+class UnsafePathError(SourcePackError):
+    pass
+
+class UnsupportedEcosystemError(SourcePackError):
+    pass

sourcepack/evidence.py

@@ -0,0 +1,109 @@
+from __future__ import annotations
+
+from dataclasses import asdict, dataclass
+from enum import StrEnum
+from typing import Iterable
+
+EVIDENCE_SCHEMA_VERSION = "sourcepack.evidence.v1"
+
+
+class EvidenceClass(StrEnum):
+    TRUSTED_BASELINE = "trusted_baseline"
+    CURRENT_WORKTREE = "current_worktree"
+    DEPENDENCY_MANIFEST = "dependency_manifest"
+    COMMAND_MANIFEST = "command_manifest"
+    EXECUTION_LEDGER = "execution_ledger"
+    GIT_METADATA = "git_metadata"
+    PROMPT_CONTEXT = "prompt_context"
+    AI_ANSWER = "ai_answer"
+    USER_CONFIG = "user_config"
+    UNSUPPORTED = "unsupported"
+    NOT_CHECKED = "not_checked"
+
+
+TRUST_LEVELS = {
+    EvidenceClass.TRUSTED_BASELINE: "trusted",
+    EvidenceClass.CURRENT_WORKTREE: "local_observation",
+    EvidenceClass.DEPENDENCY_MANIFEST: "local_manifest",
+    EvidenceClass.COMMAND_MANIFEST: "local_manifest",
+    EvidenceClass.EXECUTION_LEDGER: "local_execution_record",
+    EvidenceClass.GIT_METADATA: "local_metadata",
+    EvidenceClass.USER_CONFIG: "user_policy",
+    EvidenceClass.PROMPT_CONTEXT: "advisory",
+    EvidenceClass.AI_ANSWER: "advisory",
+    EvidenceClass.UNSUPPORTED: "unsupported",
+    EvidenceClass.NOT_CHECKED: "not_checked",
+}
+
+ENFORCEMENT_CAPABLE = {
+    EvidenceClass.TRUSTED_BASELINE,
+    EvidenceClass.CURRENT_WORKTREE,
+    EvidenceClass.DEPENDENCY_MANIFEST,
+    EvidenceClass.COMMAND_MANIFEST,
+    EvidenceClass.EXECUTION_LEDGER,
+    EvidenceClass.GIT_METADATA,
+    EvidenceClass.USER_CONFIG,
+}
+
+
+@dataclass(frozen=True)
+class EvidenceRecord:
+    evidence_class: str
+    evidence_source: str
+    trust_level: str
+    checked_status: str
+    missing_evidence: str | None = None
+    required_evidence_class: str | None = None
+    supports_claim: str | None = None
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def normalize_evidence_class(value: str | EvidenceClass) -> EvidenceClass:
+    return value if isinstance(value, EvidenceClass) else EvidenceClass(str(value))
+
+
+def make_evidence(evidence_class: str | EvidenceClass, evidence_source: str, checked_status: str = "checked", *, missing_evidence: str | None = None, required_evidence_class: str | EvidenceClass | None = None, supports_claim: str | None = None) -> EvidenceRecord:
+    cls = normalize_evidence_class(evidence_class)
+    req = normalize_evidence_class(required_evidence_class).value if required_evidence_class else None
+    return EvidenceRecord(cls.value, evidence_source, TRUST_LEVELS[cls], checked_status, missing_evidence, req, supports_claim)
+
+
+def can_satisfy(evidence: EvidenceRecord | dict, required: str | EvidenceClass, claim: str | None = None) -> bool:
+    eclass = normalize_evidence_class(evidence["evidence_class"] if isinstance(evidence, dict) else evidence.evidence_class)
+    required_cls = normalize_evidence_class(required)
+    if eclass in {EvidenceClass.PROMPT_CONTEXT, EvidenceClass.AI_ANSWER, EvidenceClass.UNSUPPORTED, EvidenceClass.NOT_CHECKED}:
+        return False
+    if eclass != required_cls:
+        return False
+    if eclass == EvidenceClass.EXECUTION_LEDGER and claim not in {None, "local_execution"}:
+        return False
+    return eclass in ENFORCEMENT_CAPABLE
+
+
+def evidence_summary(records: Iterable[EvidenceRecord | dict]) -> dict:
+    checked: list[dict] = []
+    missing: list[dict] = []
+    advisory: list[dict] = []
+    not_checked: list[dict] = []
+    for rec in records:
+        item = rec if isinstance(rec, dict) else rec.to_dict()
+        cls = item.get("evidence_class")
+        status = item.get("checked_status")
+        if cls in {EvidenceClass.PROMPT_CONTEXT.value, EvidenceClass.AI_ANSWER.value}:
+            advisory.append(item)
+        elif cls == EvidenceClass.NOT_CHECKED.value or status == "not_checked":
+            not_checked.append(item)
+        elif item.get("missing_evidence") or status in {"missing", "unavailable"}:
+            missing.append(item)
+        else:
+            checked.append(item)
+    return {"schema_version": EVIDENCE_SCHEMA_VERSION, "checked_evidence": checked, "missing_evidence": missing, "advisory_evidence_ignored_for_enforcement": advisory, "not_checked": not_checked}
+
+
+def attach_evidence_to_finding(finding: dict, evidence_class: str | EvidenceClass, evidence_source: str, checked_status: str = "checked", **kwargs) -> dict:
+    result = dict(finding)
+    rec = make_evidence(evidence_class, evidence_source, checked_status, **kwargs).to_dict()
+    result.update(rec)
+    return result