stacklatch 0.1.0a1__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
stacklatch/v21.py ADDED
@@ -0,0 +1,273 @@
1
+ """Bounded V2.1 adapters for pinned public Python repositories.
2
+
3
+ Source is parsed on the host but imported and executed only inside Docker.
4
+ The AST policy is deliberately narrow; it is not a general Python security proof.
5
+ """
6
+ from __future__ import annotations
7
+
8
+ import ast
9
+ import hashlib
10
+ import json
11
+ import math
12
+ import re
13
+ import subprocess
14
+ import tempfile
15
+ import tomllib
16
+ from dataclasses import asdict
17
+ from pathlib import Path
18
+ from typing import Any
19
+
20
+ from .core import (Analysis, DOCKER_IMAGE, InspectionError, _copy_checked,
21
+ _sandbox_command, _write_deterministic_zip, inspect_tree)
22
+
23
+ _NAME = re.compile(r"[A-Za-z_][A-Za-z0-9_]*\Z")
24
+ _FORBIDDEN = {"eval", "exec", "compile", "open", "__import__", "globals", "locals",
25
+ "getattr", "setattr", "delattr", "breakpoint", "input"}
26
+
27
+
28
+ def _module_path(path: str) -> str:
29
+ parts = Path(path).parts
30
+ if not parts or parts[-1] == "setup.py" or parts[-1] == "__init__.py":
31
+ raise InspectionError("Unsupported module path")
32
+ if parts[0] == "src":
33
+ parts = parts[1:]
34
+ if not parts or not parts[-1].endswith(".py"):
35
+ raise InspectionError("Unsupported module path")
36
+ names = [*parts[:-1], parts[-1][:-3]]
37
+ if not all(_NAME.fullmatch(name) and not name.startswith("_") for name in names):
38
+ raise InspectionError("Invalid module identifier")
39
+ return ".".join(names)
40
+
41
+
42
+ def inspect_function(root: Path, analysis: Analysis, path: str, name: str) -> dict[str, Any]:
43
+ """Parse a selected, hashed module without importing it."""
44
+ if path not in analysis.api or name.startswith("_") or not _NAME.fullmatch(name):
45
+ raise InspectionError("Selected function is outside inspected source")
46
+ raw = (root / path).read_bytes()
47
+ if hashlib.sha256(raw).hexdigest() != analysis.file_sha256[path]:
48
+ raise InspectionError("Source changed before AST inspection")
49
+ try:
50
+ tree = ast.parse(raw, filename=path)
51
+ except (SyntaxError, UnicodeError) as exc:
52
+ raise InspectionError("Invalid Python source") from exc
53
+ for node in tree.body:
54
+ if isinstance(node, ast.Import):
55
+ if any(alias.name != "re" or alias.asname for alias in node.names):
56
+ raise InspectionError("Only direct stdlib re import is audited")
57
+ elif isinstance(node, ast.ImportFrom):
58
+ if node.module != "__future__" or any(a.name != "annotations" for a in node.names):
59
+ raise InspectionError("Unsupported source import")
60
+ elif isinstance(node, ast.Assign):
61
+ if len(node.targets) != 1 or not isinstance(node.targets[0], ast.Name):
62
+ raise InspectionError("Unsupported module constant")
63
+ try:
64
+ ast.literal_eval(node.value)
65
+ except (ValueError, TypeError, SyntaxError) as exc:
66
+ raise InspectionError("Module constants must be literal") from exc
67
+ elif isinstance(node, ast.FunctionDef):
68
+ if node.decorator_list or node.args.posonlyargs or node.args.kwonlyargs or node.args.vararg or node.args.kwarg:
69
+ raise InspectionError("Unsupported function signature")
70
+ for default in node.args.defaults:
71
+ try:
72
+ ast.literal_eval(default)
73
+ except (ValueError, TypeError, SyntaxError) as exc:
74
+ raise InspectionError("Function defaults must be literal") from exc
75
+ for annotation in [*(arg.annotation for arg in node.args.args), node.returns]:
76
+ if annotation is not None and not (isinstance(annotation, ast.Name)
77
+ and annotation.id in {"str", "int", "float", "bool", "dict"}):
78
+ raise InspectionError("Unsupported evaluated annotation")
79
+ elif not (isinstance(node, ast.Expr) and isinstance(node.value, ast.Constant)
80
+ and isinstance(node.value.value, str)):
81
+ raise InspectionError("Unsupported module-level statement")
82
+ for node in ast.walk(tree):
83
+ if isinstance(node, (ast.Import, ast.ImportFrom)) and node not in tree.body:
84
+ raise InspectionError("Nested imports are prohibited")
85
+ if isinstance(node, ast.Name) and (node.id in _FORBIDDEN or node.id.startswith("__")):
86
+ raise InspectionError("Unsafe source name")
87
+ if isinstance(node, ast.Attribute) and node.attr.startswith("_"):
88
+ raise InspectionError("Unsafe source attribute")
89
+ if isinstance(node, ast.Call) and isinstance(node.func, ast.Name) and node.func.id in _FORBIDDEN:
90
+ raise InspectionError("Unsafe source call")
91
+ selected = [node for node in tree.body if isinstance(node, ast.FunctionDef) and node.name == name]
92
+ if len(selected) != 1 or len(selected[0].args.args) != 1:
93
+ raise InspectionError("Selected interface must be a unique unary function")
94
+ return {"path": path, "module": _module_path(path), "name": name,
95
+ "parameter": selected[0].args.args[0].arg,
96
+ "annotation": ast.unparse(selected[0].args.args[0].annotation)
97
+ if selected[0].args.args[0].annotation else "unknown",
98
+ "returns": ast.unparse(selected[0].returns) if selected[0].returns else "unknown"}
99
+
100
+
101
+ def _checked_cases(cases: Any) -> list[dict[str, Any]]:
102
+ if not isinstance(cases, list) or len(cases) < 2 or len(cases) > 20:
103
+ raise InspectionError("At least two independent acceptance cases are required")
104
+ for case in cases:
105
+ if not isinstance(case, dict) or ("input" not in case) or (("expected" in case) == ("error" in case)):
106
+ raise InspectionError("Each case needs input and exactly one expectation")
107
+ if set(case) - {"input", "expected", "error", "abs_tol"}:
108
+ raise InspectionError("Unsupported acceptance field")
109
+ if "error" in case and (not isinstance(case["error"], str) or
110
+ not _NAME.fullmatch(case["error"]) or "abs_tol" in case):
111
+ raise InspectionError("Invalid expected error")
112
+ if "abs_tol" in case and (not isinstance(case["abs_tol"], (int, float))
113
+ or isinstance(case["abs_tol"], bool)
114
+ or not math.isfinite(case["abs_tol"]) or case["abs_tol"] < 0):
115
+ raise InspectionError("Invalid numerical tolerance")
116
+ json.dumps(cases, allow_nan=False)
117
+ return cases
118
+
119
+
120
+ def _metadata(root: Path, analysis: Analysis) -> None:
121
+ """Bound setup.py and Poetry dependency declarations without running build scripts."""
122
+ for manifest in analysis.manifests:
123
+ if manifest.endswith("pyproject.toml"):
124
+ data = tomllib.loads((root / manifest).read_text(encoding="utf-8"))
125
+ poetry = data.get("tool", {}).get("poetry", {}).get("dependencies", {})
126
+ if not isinstance(poetry, dict) or set(poetry) - {"python"}:
127
+ raise InspectionError("Poetry runtime dependencies are unsupported")
128
+ if manifest.endswith("setup.py"):
129
+ tree = ast.parse((root / manifest).read_bytes(), filename=manifest)
130
+ calls = [node for node in ast.walk(tree) if isinstance(node, ast.Call)
131
+ and isinstance(node.func, ast.Name) and node.func.id == "setup"]
132
+ if len(calls) != 1 or calls[0].args or any(keyword.arg is None for keyword in calls[0].keywords):
133
+ raise InspectionError("Ambiguous setup.py metadata")
134
+ for keyword in calls[0].keywords:
135
+ if keyword.arg in {"install_requires", "extras_require", "setup_requires"}:
136
+ try:
137
+ value = ast.literal_eval(keyword.value)
138
+ except (ValueError, TypeError, SyntaxError) as exc:
139
+ raise InspectionError("Dynamic setup.py dependencies are unsupported") from exc
140
+ if value:
141
+ raise InspectionError("setup.py runtime dependencies are unsupported")
142
+
143
+
144
+ def make_plan(left: Analysis, right: Analysis, left_root: Path, right_root: Path,
145
+ goal: str, selectors: list[dict[str, str]], mapping: dict[str, str],
146
+ cases: list[dict[str, Any]], input_type: str) -> dict[str, Any]:
147
+ if not goal.strip() or any(a.language != "python" or a.license != "MIT-like (heuristic)"
148
+ or a.dependencies for a in (left, right)):
149
+ raise InspectionError("Python, bounded dependencies and MIT-like text are required")
150
+ if any(a.provenance != "fetched_git_commit" for a in (left, right)):
151
+ raise InspectionError("V2.1 requires fetched pinned Git commits")
152
+ _metadata(left_root, left)
153
+ _metadata(right_root, right)
154
+ if not isinstance(selectors, list) or len(selectors) != 2:
155
+ raise InspectionError("Two explicit selectors are required")
156
+ functions = [inspect_function(root, analysis, selector["path"], selector["name"])
157
+ for root, analysis, selector in zip((left_root, right_root), (left, right), selectors, strict=True)]
158
+ if not isinstance(mapping, dict) or mapping != {functions[1]["parameter"]: "$output"}:
159
+ raise InspectionError("Explicit target parameter mapping is required")
160
+ if input_type not in {"str", "number"}:
161
+ raise InspectionError("Explicit str or number input contract is required")
162
+ _checked_cases(cases)
163
+ return {"schema_version": 21, "goal": goal, "proposed": True, "verified": False,
164
+ "sources": [{"url": a.source, "commit": a.commit, "kind": a.provenance,
165
+ "content_sha256": a.content_sha256, "file_sha256": a.file_sha256}
166
+ for a in (left, right)],
167
+ "selected_functions": functions, "argument_mapping": mapping, "input_type": input_type,
168
+ "tests": cases, "risk_flags": ["MIT-like text matching is not legal review",
169
+ "Expected values are supplied acceptance assertions"]}
170
+
171
+
172
+ def _provenance(root: Path, original: Analysis) -> Analysis:
173
+ actual = subprocess.run(["git", "-C", str(root), "rev-parse", "HEAD"],
174
+ capture_output=True, text=True, timeout=10, check=True).stdout.strip()
175
+ kind = subprocess.run(["git", "-C", str(root), "cat-file", "-t", "HEAD"],
176
+ capture_output=True, text=True, timeout=10, check=True).stdout.strip()
177
+ if actual != original.commit or kind != "commit":
178
+ raise InspectionError("Pinned Git HEAD changed")
179
+ analysis = inspect_tree(root, original.source, original.commit, _fetched_git=True, v21=True)
180
+ if analysis.content_sha256 != original.content_sha256 or analysis.file_sha256 != original.file_sha256:
181
+ raise InspectionError("Fetched source content changed")
182
+ return analysis
183
+
184
+
185
+ def _generate(roots: tuple[Path, Path], analyses: tuple[Analysis, Analysis],
186
+ artifact: Path, plan: dict[str, Any]) -> None:
187
+ artifact.mkdir()
188
+ for i, (root, analysis, fn) in enumerate(zip(roots, analyses, plan["selected_functions"], strict=True)):
189
+ rel = Path(*fn["module"].split(".")).with_suffix(".py")
190
+ _copy_checked(root, fn["path"], artifact / f"source_{i}" / rel,
191
+ analysis.file_sha256[fn["path"]])
192
+ if hashlib.sha256((artifact / f"source_{i}" / rel).read_bytes()).hexdigest() != analysis.file_sha256[fn["path"]]:
193
+ raise InspectionError("Staged source mismatch")
194
+ first, second = plan["selected_functions"]
195
+ code = (f"from source_0.{first['module']} import {first['name']} as first\n"
196
+ f"from source_1.{second['module']} import {second['name']} as second\n"
197
+ "import json, sys\n\n"
198
+ "def integrate(value):\n"
199
+ + (" if not isinstance(value, str):\n raise TypeError('Expected str input')\n"
200
+ if plan["input_type"] == "str" else
201
+ " if isinstance(value, bool) or not isinstance(value, (int, float)):\n"
202
+ " raise TypeError('Expected numeric input')\n")
203
+ + " intermediate = first(value)\n"
204
+ f" return second({second['parameter']}=intermediate)\n\n"
205
+ "if __name__ == '__main__':\n"
206
+ " try:\n print(json.dumps({'ok': True, 'value': integrate(json.loads(sys.argv[1]))}))\n"
207
+ " except Exception as exc:\n print(json.dumps({'ok': False, 'error': type(exc).__name__}))\n")
208
+ (artifact / "run.py").write_text(code, encoding="utf-8")
209
+ (artifact / "integration_plan.json").write_text(json.dumps(plan, sort_keys=True, indent=2), encoding="utf-8")
210
+
211
+
212
+ def _execute(artifact: Path, value: Any) -> dict[str, Any]:
213
+ command, backend = _sandbox_command(artifact)
214
+ if backend != "docker":
215
+ raise InspectionError("V2.1 acceptance requires Docker")
216
+ command = command[:-2] + ["-B", "run.py", json.dumps(value, allow_nan=False)]
217
+ try:
218
+ result = subprocess.run(command, capture_output=True, text=True, timeout=30)
219
+ except subprocess.TimeoutExpired as exc:
220
+ subprocess.run(["docker", "rm", "-f", command[4]], capture_output=True, timeout=10)
221
+ raise InspectionError("Docker execution timed out") from exc
222
+ if result.returncode:
223
+ raise InspectionError(f"Docker exited {result.returncode}: {result.stderr[:300]}")
224
+ try:
225
+ return json.loads(result.stdout)
226
+ except json.JSONDecodeError as exc:
227
+ raise InspectionError("Sandbox emitted invalid JSON") from exc
228
+
229
+
230
+ def verify_and_package(roots: tuple[Path, Path], originals: tuple[Analysis, Analysis],
231
+ out: Path, proposed: dict[str, Any]) -> dict[str, Any]:
232
+ out.mkdir(parents=True, exist_ok=True)
233
+ archive = out / "prototype.zip"
234
+ archive.unlink(missing_ok=True)
235
+ report: dict[str, Any] = {"status": "failed", "verified": False, "tests": [],
236
+ "runtime_image": DOCKER_IMAGE}
237
+ try:
238
+ analyses = tuple(_provenance(root, original) for root, original in zip(roots, originals, strict=True))
239
+ selectors = [{"path": f["path"], "name": f["name"]} for f in proposed["selected_functions"]]
240
+ canonical = make_plan(*analyses, *roots, proposed["goal"], selectors,
241
+ proposed["argument_mapping"], proposed["tests"], proposed["input_type"])
242
+ if proposed != canonical:
243
+ raise InspectionError("Plan differs from validated source-derived plan")
244
+ with tempfile.TemporaryDirectory() as tmp:
245
+ artifact = Path(tmp) / "prototype"
246
+ _generate(roots, analyses, artifact, canonical)
247
+ for index, case in enumerate(canonical["tests"]):
248
+ actual = _execute(artifact, case["input"])
249
+ passed = (actual == {"ok": False, "error": case["error"]} if "error" in case
250
+ else actual.get("ok") is True and
251
+ (math.isclose(actual["value"], case["expected"], rel_tol=0,
252
+ abs_tol=case.get("abs_tol", 0))
253
+ if "abs_tol" in case and type(actual.get("value")) in (float, int)
254
+ and type(case["expected"]) in (float, int)
255
+ else actual.get("value") == case["expected"]))
256
+ report["tests"].append({"index": index, "input": case["input"],
257
+ "expected": {k: v for k, v in case.items() if k != "input"},
258
+ "actual": actual, "passed": passed, "backend": "docker"})
259
+ if not passed:
260
+ raise InspectionError(f"Acceptance case {index} failed")
261
+ report["files_sha256"] = _write_deterministic_zip(artifact, archive)
262
+ report["archive_sha256"] = hashlib.sha256(archive.read_bytes()).hexdigest()
263
+ report["sources_provenance"] = canonical["sources"]
264
+ report["status"], report["verified"] = "passed", True
265
+ except Exception as exc:
266
+ archive.unlink(missing_ok=True)
267
+ report["error"] = f"{type(exc).__name__}: {exc}"
268
+ report.pop("archive_sha256", None)
269
+ report.pop("files_sha256", None)
270
+ (out / "report.json").write_text(json.dumps(report, indent=2), encoding="utf-8")
271
+ (out / "report.md").write_text("# StackLatch V2.1 validation\n\n" +
272
+ json.dumps(report, indent=2) + "\n", encoding="utf-8")
273
+ return report