feat: complete M2 content workspace and inspector
This commit is contained in:
1 parent
931f561e7f
commit
cf6eaba534
438 files changed
+59749
-19043
No files matched your search
Executable
+127
@@ -0,0 +1,127 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Enforce Blacksite's module-size debt ratchet."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import tempfile
|
||||
import tomllib
|
||||
from pathlib import Path
|
||||
|
||||
|
||||
def nonblank_lines(path: Path) -> int:
|
||||
return sum(1 for line in path.read_text(encoding="utf-8").splitlines() if line.strip())
|
||||
|
||||
|
||||
def module_limit(relative: str, policy: dict) -> int:
|
||||
if relative in policy.get("shells", {}):
|
||||
return int(policy["limits"]["ui_shell"])
|
||||
if relative.startswith("crates/editor/src/ui/"):
|
||||
return int(policy["limits"]["ui_module"])
|
||||
return int(policy["limits"]["production_rust_module"])
|
||||
|
||||
|
||||
def validate_exception(entry: dict) -> list[str]:
|
||||
required = ("path", "issue", "rationale", "maximum", "extraction_target", "expiry_milestone")
|
||||
missing = [name for name in required if not entry.get(name)]
|
||||
errors = [f"invalid exception for {entry.get('path', '<unknown>')}: missing {name}" for name in missing]
|
||||
if entry.get("issue") and not str(entry["issue"]).startswith("#"):
|
||||
errors.append(f"invalid exception for {entry['path']}: issue must be a tracker reference")
|
||||
return errors
|
||||
|
||||
|
||||
def audit(root: Path, policy: dict) -> tuple[list[str], list[str]]:
|
||||
errors: list[str] = []
|
||||
notes: list[str] = []
|
||||
baselines = {str(path): int(value) for path, value in policy.get("baselines", {}).items()}
|
||||
exceptions = {entry.get("path"): entry for entry in policy.get("exceptions", [])}
|
||||
for entry in policy.get("exceptions", []):
|
||||
errors.extend(validate_exception(entry))
|
||||
|
||||
for path in sorted((root / "crates").glob("**/*.rs")):
|
||||
relative = path.relative_to(root).as_posix()
|
||||
count = nonblank_lines(path)
|
||||
limit = module_limit(relative, policy)
|
||||
baseline = baselines.get(relative)
|
||||
exception = exceptions.get(relative)
|
||||
|
||||
if baseline is not None and count > baseline:
|
||||
errors.append(f"{relative}: {count} nonblank lines exceeds frozen baseline {baseline}")
|
||||
continue
|
||||
if baseline is not None and count < baseline:
|
||||
notes.append(f"{relative}: shrank from baseline {baseline} to {count}")
|
||||
if count <= limit:
|
||||
continue
|
||||
if baseline is not None:
|
||||
continue
|
||||
if exception is not None and count <= int(exception["maximum"]):
|
||||
notes.append(f"{relative}: temporary {exception['issue']} exception ({count}/{exception['maximum']})")
|
||||
continue
|
||||
errors.append(f"{relative}: {count} nonblank lines exceeds module budget {limit}")
|
||||
return errors, notes
|
||||
|
||||
|
||||
def load_policy(path: Path) -> dict:
|
||||
with path.open("rb") as handle:
|
||||
policy = tomllib.load(handle)
|
||||
if policy.get("version") != 1:
|
||||
raise SystemExit(f"unsupported architecture policy version in {path}")
|
||||
return policy
|
||||
|
||||
|
||||
def self_test() -> int:
|
||||
with tempfile.TemporaryDirectory(prefix="blacksite-architecture-audit-") as directory:
|
||||
root = Path(directory)
|
||||
(root / "crates/editor/src/ui").mkdir(parents=True)
|
||||
policy = {
|
||||
"limits": {"ui_shell": 2, "ui_module": 3, "production_rust_module": 4},
|
||||
"shells": {"crates/editor/src/ui/shell.rs": 2},
|
||||
"baselines": {"crates/editor/src/ui/legacy.rs": 5},
|
||||
"exceptions": [],
|
||||
}
|
||||
(root / "crates/editor/src/ui/new.rs").write_text("a\nb\nc\nd\n", encoding="utf-8")
|
||||
errors, _ = audit(root, policy)
|
||||
assert any("new.rs" in error for error in errors)
|
||||
(root / "crates/editor/src/ui/new.rs").write_text("a\nb\n", encoding="utf-8")
|
||||
(root / "crates/editor/src/ui/legacy.rs").write_text("a\nb\nc\nd\ne\nf\n", encoding="utf-8")
|
||||
errors, _ = audit(root, policy)
|
||||
assert any("frozen baseline" in error for error in errors)
|
||||
(root / "crates/editor/src/ui/legacy.rs").write_text("a\nb\nc\nd\n", encoding="utf-8")
|
||||
errors, notes = audit(root, policy)
|
||||
assert not errors and any("shrank" in note for note in notes)
|
||||
policy["exceptions"] = [{
|
||||
"path": "crates/editor/src/ui/new.rs", "issue": "#1", "rationale": "test",
|
||||
"maximum": 4, "extraction_target": "test module", "expiry_milestone": "M2",
|
||||
}]
|
||||
(root / "crates/editor/src/ui/new.rs").write_text("a\nb\nc\nd\n", encoding="utf-8")
|
||||
errors, _ = audit(root, policy)
|
||||
assert not errors
|
||||
policy["exceptions"][0]["issue"] = "missing-prefix"
|
||||
errors, _ = audit(root, policy)
|
||||
assert any("tracker reference" in error for error in errors)
|
||||
print("PASS architecture-audit self-test")
|
||||
return 0
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser()
|
||||
parser.add_argument("command", choices=("check", "self-test"), nargs="?", default="check")
|
||||
parser.add_argument("--root", type=Path, default=Path(__file__).resolve().parents[2])
|
||||
arguments = parser.parse_args()
|
||||
if arguments.command == "self-test":
|
||||
return self_test()
|
||||
root = arguments.root.resolve()
|
||||
policy = load_policy(root / ".codex/architecture.toml")
|
||||
errors, notes = audit(root, policy)
|
||||
for note in notes:
|
||||
print(f"NOTE {note}")
|
||||
if errors:
|
||||
for error in errors:
|
||||
print(f"FAIL {error}")
|
||||
return 1
|
||||
print("PASS architecture-audit")
|
||||
return 0
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Executable
+1745
File diff suppressed because it is too large.
Load diff
Executable
+848
@@ -0,0 +1,848 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Resolve and execute Cargo commands in bounded, signature-stable build lanes.
|
||||
|
||||
This module intentionally uses only the Python standard library. It is also
|
||||
imported by build_storage.py, so lane identity and sentinel validation have one
|
||||
implementation.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import hashlib
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import shlex
|
||||
import shutil
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
from dataclasses import asdict, dataclass
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
from typing import Any, Iterable, Mapping, Sequence
|
||||
|
||||
try:
|
||||
import tomllib
|
||||
except ModuleNotFoundError as error: # pragma: no cover - Python < 3.11
|
||||
raise SystemExit("cargo_lane.py requires Python 3.11 or newer") from error
|
||||
|
||||
|
||||
SCHEMA_VERSION = 1
|
||||
SENTINEL_NAME = ".blacksite-cargo-lane.json"
|
||||
LANE_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
|
||||
SEPARATE_BUILD_DIR_MINIMUM = (1, 91, 0)
|
||||
|
||||
DEFAULT_BUILD_STORAGE: dict[str, Any] = {
|
||||
"cache_root": "cargo-cache-home",
|
||||
"workspace_partition": "canonical-path-hash",
|
||||
"dev_target_dir": "target",
|
||||
"exceptional_target_root": "target/lanes",
|
||||
"persistent_lane": "dev",
|
||||
"candidate_lane": "candidate",
|
||||
"hot_reload_lane": "hot-reload",
|
||||
"full_debug_lane": "full-debug",
|
||||
"package_lane": "package",
|
||||
}
|
||||
|
||||
|
||||
class LaneError(RuntimeError):
|
||||
"""A lane cannot be resolved or safely reused."""
|
||||
|
||||
|
||||
def utc_now() -> str:
|
||||
return datetime.now(timezone.utc).isoformat(timespec="seconds")
|
||||
|
||||
|
||||
def canonical_path(path: Path | str) -> Path:
|
||||
return Path(path).expanduser().resolve(strict=False)
|
||||
|
||||
|
||||
def workspace_root(start: Path | None = None) -> Path:
|
||||
override = os.environ.get("BLACKSITE_WORKSPACE_ROOT")
|
||||
if override:
|
||||
candidate = canonical_path(override)
|
||||
elif start is not None:
|
||||
candidate = canonical_path(start)
|
||||
else:
|
||||
candidate = canonical_path(Path(__file__).parents[2])
|
||||
|
||||
for current in (candidate, *candidate.parents):
|
||||
if (current / "Cargo.toml").is_file() and (current / ".git").exists():
|
||||
return current
|
||||
raise LaneError(f"could not locate a Cargo workspace from {candidate}")
|
||||
|
||||
|
||||
def workspace_hash(root: Path) -> str:
|
||||
return hashlib.sha256(os.fsencode(str(canonical_path(root)))).hexdigest()[:20]
|
||||
|
||||
|
||||
def cargo_home() -> Path:
|
||||
return canonical_path(os.environ.get("CARGO_HOME", Path.home() / ".cargo"))
|
||||
|
||||
|
||||
def load_workflow(root: Path) -> dict[str, Any]:
|
||||
path = root / ".codex" / "workflow.toml"
|
||||
document: dict[str, Any] = {}
|
||||
if path.is_file():
|
||||
with path.open("rb") as handle:
|
||||
loaded = tomllib.load(handle)
|
||||
if not isinstance(loaded, dict):
|
||||
raise LaneError(f"workflow config is not a TOML table: {path}")
|
||||
document = loaded
|
||||
|
||||
storage = dict(DEFAULT_BUILD_STORAGE)
|
||||
configured = document.get("build_storage", {})
|
||||
if configured:
|
||||
if not isinstance(configured, dict):
|
||||
raise LaneError("[build_storage] must be a TOML table")
|
||||
storage.update(configured)
|
||||
|
||||
verification = document.get("verification", {})
|
||||
if isinstance(verification, dict):
|
||||
for source, destination in (
|
||||
("persistent_lane", "persistent_lane"),
|
||||
("candidate_lane", "candidate_lane"),
|
||||
("hot_reload_lane", "hot_reload_lane"),
|
||||
("full_debug_lane", "full_debug_lane"),
|
||||
("package_lane", "package_lane"),
|
||||
):
|
||||
if source in verification:
|
||||
storage[destination] = verification[source]
|
||||
|
||||
document["build_storage"] = storage
|
||||
return document
|
||||
|
||||
|
||||
def _configured_path(root: Path, value: str, *, base: Path | None = None) -> Path:
|
||||
expanded = Path(os.path.expandvars(os.path.expanduser(value)))
|
||||
if expanded.is_absolute():
|
||||
return canonical_path(expanded)
|
||||
return canonical_path((base or root) / expanded)
|
||||
|
||||
|
||||
def cache_root(root: Path, workflow: Mapping[str, Any]) -> Path:
|
||||
override = os.environ.get("BLACKSITE_BUILD_CACHE_ROOT")
|
||||
if override:
|
||||
return canonical_path(override)
|
||||
|
||||
storage = workflow["build_storage"]
|
||||
configured = str(storage.get("cache_root", "cargo-cache-home"))
|
||||
if configured == "cargo-cache-home":
|
||||
return cargo_home() / "blacksite-build"
|
||||
if configured == "workspace-parent-cache":
|
||||
return canonical_path(root.parent / ".blacksite-build-cache")
|
||||
return _configured_path(root, configured)
|
||||
|
||||
|
||||
def parse_version(text: str) -> tuple[int, int, int]:
|
||||
match = re.search(r"\b(\d+)\.(\d+)\.(\d+)", text)
|
||||
if not match:
|
||||
return (0, 0, 0)
|
||||
return tuple(int(part) for part in match.groups()) # type: ignore[return-value]
|
||||
|
||||
|
||||
def _capture(command: Sequence[str]) -> str:
|
||||
try:
|
||||
completed = subprocess.run(
|
||||
command,
|
||||
check=False,
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.STDOUT,
|
||||
text=True,
|
||||
)
|
||||
except OSError as error:
|
||||
return f"unavailable: {error}"
|
||||
return completed.stdout.strip()
|
||||
|
||||
|
||||
def toolchain_info() -> dict[str, Any]:
|
||||
cargo_text = _capture(["cargo", "-Vv"])
|
||||
rustc_text = _capture(["rustc", "-Vv"])
|
||||
host = "unknown"
|
||||
for line in rustc_text.splitlines():
|
||||
if line.startswith("host:"):
|
||||
host = line.partition(":")[2].strip()
|
||||
break
|
||||
version = parse_version(cargo_text)
|
||||
return {
|
||||
"cargo": cargo_text.splitlines()[0] if cargo_text else "unavailable",
|
||||
"cargo_version": ".".join(str(part) for part in version),
|
||||
"rustc": rustc_text.splitlines()[0] if rustc_text else "unavailable",
|
||||
"host": host,
|
||||
"separate_build_dir": version >= SEPARATE_BUILD_DIR_MINIMUM,
|
||||
}
|
||||
|
||||
|
||||
def _repo_target_config(root: Path, target: str) -> dict[str, Any]:
|
||||
path = root / ".cargo" / "config.toml"
|
||||
result: dict[str, Any] = {"linker": None, "rustflags": []}
|
||||
if path.is_file():
|
||||
with path.open("rb") as handle:
|
||||
config = tomllib.load(handle)
|
||||
target_table = config.get("target", {})
|
||||
if isinstance(target_table, dict):
|
||||
values = target_table.get(target, {})
|
||||
if isinstance(values, dict):
|
||||
result["linker"] = values.get("linker")
|
||||
flags = values.get("rustflags", [])
|
||||
if isinstance(flags, list):
|
||||
result["rustflags"] = [str(flag) for flag in flags]
|
||||
encoded_flags = os.environ.get("CARGO_ENCODED_RUSTFLAGS")
|
||||
if encoded_flags:
|
||||
result["rustflags"] = [flag for flag in encoded_flags.split("\x1f") if flag]
|
||||
result["rustflags_source"] = "CARGO_ENCODED_RUSTFLAGS"
|
||||
elif os.environ.get("RUSTFLAGS"):
|
||||
result["rustflags"] = shlex.split(os.environ["RUSTFLAGS"])
|
||||
result["rustflags_source"] = "environment"
|
||||
else:
|
||||
result["rustflags_source"] = str(path) if path.is_file() else "cargo-default"
|
||||
result["rustc_wrapper"] = os.environ.get("RUSTC_WRAPPER")
|
||||
linker_variable = "CARGO_TARGET_" + target.upper().replace("-", "_") + "_LINKER"
|
||||
if os.environ.get(linker_variable):
|
||||
result["linker"] = os.environ[linker_variable]
|
||||
return result
|
||||
|
||||
|
||||
def validate_lane_name(lane: str) -> str:
|
||||
if not LANE_RE.fullmatch(lane):
|
||||
raise LaneError(
|
||||
f"invalid lane {lane!r}; use lowercase letters, digits, and hyphens"
|
||||
)
|
||||
return lane
|
||||
|
||||
|
||||
def profile_directory(profile: str) -> str:
|
||||
if profile in {"dev", "test"}:
|
||||
return "debug"
|
||||
if profile in {"release", "bench"}:
|
||||
return "release"
|
||||
return profile
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class CommandContext:
|
||||
profile: str
|
||||
profile_dir: str
|
||||
feature_signature: str
|
||||
cargo_subcommand: str | None
|
||||
target_triple: str | None
|
||||
|
||||
|
||||
PROJECT_ALIAS_SUBCOMMANDS = {
|
||||
"bake-navigation",
|
||||
"package-project",
|
||||
"process-assets",
|
||||
"upgrade-project",
|
||||
"validate-levels",
|
||||
"validate-samples",
|
||||
}
|
||||
|
||||
|
||||
def command_context(command: Sequence[str], lane: str) -> CommandContext:
|
||||
args = list(command)
|
||||
cargo_index: int | None = None
|
||||
for index, value in enumerate(args[:2]):
|
||||
if Path(value).name == "cargo":
|
||||
cargo_index = index
|
||||
break
|
||||
|
||||
cargo_args = args[cargo_index + 1 :] if cargo_index is not None else []
|
||||
subcommand = next((arg for arg in cargo_args if not arg.startswith("-")), None)
|
||||
# Arguments following Blacksite's Cargo aliases are forwarded to the xtask
|
||||
# binary by the alias's trailing `--`. They are not Cargo options. In
|
||||
# particular, `cargo package-project --profile package-qa` selects the
|
||||
# package manifest profile and must not repartition the Cargo build lane.
|
||||
cargo_options = (
|
||||
cargo_args[: cargo_args.index(subcommand) + 1]
|
||||
if subcommand in PROJECT_ALIAS_SUBCOMMANDS
|
||||
else cargo_args
|
||||
)
|
||||
if "--release" in cargo_options:
|
||||
profile = "release"
|
||||
else:
|
||||
profile = "test" if subcommand == "test" else "dev"
|
||||
for index, value in enumerate(cargo_options):
|
||||
if value.startswith("--profile="):
|
||||
profile = value.partition("=")[2]
|
||||
elif value == "--profile" and index + 1 < len(cargo_options):
|
||||
profile = cargo_options[index + 1]
|
||||
|
||||
features: set[str] = set()
|
||||
all_features = "--all-features" in cargo_options
|
||||
no_default = "--no-default-features" in cargo_options
|
||||
for index, value in enumerate(cargo_options):
|
||||
raw: str | None = None
|
||||
if value.startswith("--features="):
|
||||
raw = value.partition("=")[2]
|
||||
elif value.startswith("-F") and value != "-F":
|
||||
raw = value[2:]
|
||||
elif value in {"--features", "-F"} and index + 1 < len(cargo_options):
|
||||
raw = cargo_options[index + 1]
|
||||
if raw:
|
||||
features.update(part for part in re.split(r"[ ,]+", raw) if part)
|
||||
|
||||
target_triple: str | None = None
|
||||
for index, value in enumerate(cargo_options):
|
||||
if value.startswith("--target="):
|
||||
target_triple = value.partition("=")[2]
|
||||
elif value == "--target" and index + 1 < len(cargo_options):
|
||||
target_triple = cargo_options[index + 1]
|
||||
|
||||
if all_features:
|
||||
feature_signature = "all-features"
|
||||
else:
|
||||
parts = ["no-default" if no_default else "default"]
|
||||
if features:
|
||||
parts.append("features=" + ",".join(sorted(features)))
|
||||
feature_signature = ";".join(parts)
|
||||
|
||||
# These disposable lanes intentionally contain a bounded family of
|
||||
# package-specific feature sets. Hot reload needs the editor's
|
||||
# `dev,hot-reload` build and `game_hot`'s `dylib` build in one isolated
|
||||
# runtime lane; package aliases likewise expand to different internal
|
||||
# features. They must never spill into the persistent default-feature lane.
|
||||
if lane == "hot-reload":
|
||||
if all_features:
|
||||
raise LaneError("all-features belongs in the candidate lane")
|
||||
feature_signature = "hot-reload-family"
|
||||
elif lane == "package":
|
||||
feature_signature = "package-family"
|
||||
|
||||
if lane == "dev" and (all_features or "hot-reload" in features):
|
||||
raise LaneError(
|
||||
"the persistent dev lane cannot be used for all-features or hot-reload"
|
||||
)
|
||||
if lane == "candidate" and subcommand is not None and not all_features:
|
||||
raise LaneError("the candidate lane requires --all-features")
|
||||
|
||||
return CommandContext(
|
||||
profile=profile,
|
||||
profile_dir=profile_directory(profile),
|
||||
feature_signature=feature_signature,
|
||||
cargo_subcommand=subcommand,
|
||||
target_triple=target_triple,
|
||||
)
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class LaneLayout:
|
||||
workspace: str
|
||||
workspace_hash: str
|
||||
lane: str
|
||||
mode: str
|
||||
cache_root: str
|
||||
lane_root: str
|
||||
target_dir: str
|
||||
build_dir: str
|
||||
profile: str
|
||||
profile_dir: str
|
||||
runtime_deps: str
|
||||
feature_signature: str
|
||||
toolchain: dict[str, Any]
|
||||
linker: str | None
|
||||
rustflags: list[str]
|
||||
rustflags_source: str
|
||||
rustc_wrapper: str | None
|
||||
target_triple: str
|
||||
|
||||
|
||||
def lane_layout(
|
||||
root: Path,
|
||||
lane: str,
|
||||
workflow: Mapping[str, Any],
|
||||
command: Sequence[str] = (),
|
||||
*,
|
||||
toolchain: Mapping[str, Any] | None = None,
|
||||
) -> LaneLayout:
|
||||
lane = validate_lane_name(lane)
|
||||
root = canonical_path(root)
|
||||
info = dict(toolchain or toolchain_info())
|
||||
context = command_context(command, lane)
|
||||
storage = workflow["build_storage"]
|
||||
cache = canonical_path(cache_root(root, workflow))
|
||||
partition = cache / workspace_hash(root)
|
||||
lane_root = partition / lane
|
||||
separate = bool(info.get("separate_build_dir"))
|
||||
effective_target = context.target_triple or str(info.get("host", "unknown"))
|
||||
if (
|
||||
context.target_triple
|
||||
and context.target_triple != info.get("host")
|
||||
and not lane.startswith("cross-")
|
||||
):
|
||||
raise LaneError("cross-target Cargo commands require a cross-* disposable lane")
|
||||
|
||||
persistent = str(storage.get("persistent_lane", "dev"))
|
||||
if separate:
|
||||
if lane == persistent:
|
||||
target = _configured_path(
|
||||
root, str(storage.get("dev_target_dir", "target"))
|
||||
)
|
||||
else:
|
||||
exceptional = _configured_path(
|
||||
root, str(storage.get("exceptional_target_root", "target/lanes"))
|
||||
)
|
||||
target = exceptional / lane
|
||||
build = lane_root
|
||||
mode = "separate-build-dir"
|
||||
else:
|
||||
target = lane_root / "target"
|
||||
build = target
|
||||
mode = "external-target-dir-fallback"
|
||||
|
||||
target_config = _repo_target_config(root, effective_target)
|
||||
profile_path = Path(context.profile_dir)
|
||||
if context.target_triple:
|
||||
profile_path = Path(context.target_triple) / profile_path
|
||||
return LaneLayout(
|
||||
workspace=str(root),
|
||||
workspace_hash=workspace_hash(root),
|
||||
lane=lane,
|
||||
mode=mode,
|
||||
cache_root=str(cache),
|
||||
lane_root=str(lane_root),
|
||||
target_dir=str(target),
|
||||
build_dir=str(build),
|
||||
profile=context.profile,
|
||||
profile_dir=context.profile_dir,
|
||||
runtime_deps=str(build / profile_path / "deps"),
|
||||
feature_signature=context.feature_signature,
|
||||
toolchain=info,
|
||||
linker=target_config.get("linker"),
|
||||
rustflags=list(target_config.get("rustflags", [])),
|
||||
rustflags_source=str(target_config.get("rustflags_source")),
|
||||
rustc_wrapper=target_config.get("rustc_wrapper"),
|
||||
target_triple=effective_target,
|
||||
)
|
||||
|
||||
|
||||
def lane_environment(layout: LaneLayout) -> dict[str, str]:
|
||||
environment = {
|
||||
"CARGO_TARGET_DIR": layout.target_dir,
|
||||
"BLACKSITE_CARGO_LANE": layout.lane,
|
||||
"BLACKSITE_WORKSPACE_HASH": layout.workspace_hash,
|
||||
}
|
||||
if layout.mode == "separate-build-dir":
|
||||
environment["CARGO_BUILD_BUILD_DIR"] = layout.build_dir
|
||||
if layout.lane in {"candidate", "package", "full-debug"}:
|
||||
environment["CARGO_INCREMENTAL"] = "0"
|
||||
if layout.lane == "full-debug":
|
||||
environment["CARGO_PROFILE_DEV_DEBUG"] = "full"
|
||||
environment["CARGO_PROFILE_TEST_DEBUG"] = "full"
|
||||
return environment
|
||||
|
||||
|
||||
def sentinel_path(path: Path) -> Path:
|
||||
return path / SENTINEL_NAME
|
||||
|
||||
|
||||
def read_sentinel(path: Path) -> dict[str, Any] | None:
|
||||
marker = sentinel_path(path)
|
||||
if not marker.is_file() or marker.is_symlink():
|
||||
return None
|
||||
try:
|
||||
with marker.open("r", encoding="utf-8") as handle:
|
||||
value = json.load(handle)
|
||||
except (OSError, json.JSONDecodeError):
|
||||
return None
|
||||
return value if isinstance(value, dict) else None
|
||||
|
||||
|
||||
def validate_sentinel(
|
||||
path: Path,
|
||||
document: Mapping[str, Any],
|
||||
*,
|
||||
root: Path,
|
||||
lane: str,
|
||||
role: str,
|
||||
) -> list[str]:
|
||||
errors: list[str] = []
|
||||
expected = {
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
"workspace": str(canonical_path(root)),
|
||||
"workspace_hash": workspace_hash(root),
|
||||
"lane": lane,
|
||||
"role": role,
|
||||
"path": str(canonical_path(path)),
|
||||
}
|
||||
for key, value in expected.items():
|
||||
if document.get(key) != value:
|
||||
errors.append(f"{key}: expected {value!r}, found {document.get(key)!r}")
|
||||
return errors
|
||||
|
||||
|
||||
def _signature(layout: LaneLayout) -> dict[str, Any]:
|
||||
# The persistent development and candidate lanes intentionally serve both
|
||||
# Cargo's `dev` and `test` profiles. Cargo fingerprints those profiles
|
||||
# independently, while keeping them in one bounded ordinary/candidate lane
|
||||
# avoids multiplying the Bevy dependency graph into permanent caches.
|
||||
profile_signature = "dev-test" if layout.profile in {"dev", "test"} else layout.profile
|
||||
return {
|
||||
"toolchain": layout.toolchain,
|
||||
"target_triple": layout.target_triple,
|
||||
"linker": layout.linker,
|
||||
"rustflags": layout.rustflags,
|
||||
"rustc_wrapper": layout.rustc_wrapper,
|
||||
"feature_signature": layout.feature_signature,
|
||||
"profile_signature": profile_signature,
|
||||
"mode": layout.mode,
|
||||
"lane_environment": lane_environment(layout),
|
||||
}
|
||||
|
||||
|
||||
def _signature_compatible(existing: object, requested: Mapping[str, Any]) -> bool:
|
||||
if existing == requested:
|
||||
return True
|
||||
if not isinstance(existing, Mapping):
|
||||
return False
|
||||
previous = dict(existing)
|
||||
current = dict(requested)
|
||||
previous_profile = previous.pop("profile_signature", None)
|
||||
current_profile = current.pop("profile_signature", None)
|
||||
return (
|
||||
previous == current
|
||||
and previous_profile in {"dev", "test"}
|
||||
and current_profile == "dev-test"
|
||||
)
|
||||
|
||||
|
||||
def _atomic_json(path: Path, document: Mapping[str, Any]) -> None:
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
descriptor, temporary = tempfile.mkstemp(
|
||||
prefix=f".{path.name}.", suffix=".tmp", dir=path.parent
|
||||
)
|
||||
try:
|
||||
with os.fdopen(descriptor, "w", encoding="utf-8") as handle:
|
||||
json.dump(document, handle, indent=2, sort_keys=True)
|
||||
handle.write("\n")
|
||||
handle.flush()
|
||||
os.fsync(handle.fileno())
|
||||
os.replace(temporary, path)
|
||||
finally:
|
||||
try:
|
||||
os.unlink(temporary)
|
||||
except FileNotFoundError:
|
||||
pass
|
||||
|
||||
|
||||
def _prepare_marker(
|
||||
path: Path, layout: LaneLayout, role: str, *, allow_create: bool
|
||||
) -> dict[str, Any]:
|
||||
if path.is_symlink():
|
||||
raise LaneError(f"refusing symlinked lane path: {path}")
|
||||
if allow_create:
|
||||
path.mkdir(parents=True, exist_ok=True)
|
||||
if not path.is_dir():
|
||||
raise LaneError(f"lane path does not exist: {path}")
|
||||
|
||||
existing = read_sentinel(path)
|
||||
now = utc_now()
|
||||
signature = _signature(layout)
|
||||
if existing is not None:
|
||||
errors = validate_sentinel(
|
||||
path, existing, root=Path(layout.workspace), lane=layout.lane, role=role
|
||||
)
|
||||
if errors:
|
||||
raise LaneError(
|
||||
f"invalid lane sentinel at {path}: " + "; ".join(errors)
|
||||
)
|
||||
if not _signature_compatible(existing.get("signature"), signature):
|
||||
raise LaneError(
|
||||
"lane signature changed; select the correct exceptional lane or reset "
|
||||
f"the whole lane after a dry run: {layout.lane}"
|
||||
)
|
||||
document = dict(existing)
|
||||
document["signature"] = signature
|
||||
document["last_use"] = now
|
||||
document["last_profile"] = layout.profile
|
||||
else:
|
||||
document = {
|
||||
"schema_version": SCHEMA_VERSION,
|
||||
"workspace": layout.workspace,
|
||||
"workspace_hash": layout.workspace_hash,
|
||||
"lane": layout.lane,
|
||||
"role": role,
|
||||
"path": str(canonical_path(path)),
|
||||
"target_dir": layout.target_dir,
|
||||
"build_dir": layout.build_dir,
|
||||
"signature": signature,
|
||||
"created_at": now,
|
||||
"last_use": now,
|
||||
"last_profile": layout.profile,
|
||||
}
|
||||
_atomic_json(sentinel_path(path), document)
|
||||
return document
|
||||
|
||||
|
||||
def prepare_lane(layout: LaneLayout) -> None:
|
||||
lane_root = Path(layout.lane_root)
|
||||
_prepare_marker(lane_root, layout, "build", allow_create=True)
|
||||
|
||||
target = Path(layout.target_dir)
|
||||
workspace_target = Path(layout.workspace) / "target"
|
||||
if target != workspace_target and target != Path(layout.build_dir):
|
||||
_prepare_marker(target, layout, "target", allow_create=True)
|
||||
|
||||
|
||||
def require_prepared_lane(layout: LaneLayout) -> None:
|
||||
lane_root = Path(layout.lane_root)
|
||||
marker = read_sentinel(lane_root)
|
||||
if marker is None:
|
||||
raise LaneError(
|
||||
f"lane {layout.lane!r} has not been built through cargo_lane.py"
|
||||
)
|
||||
errors = validate_sentinel(
|
||||
lane_root,
|
||||
marker,
|
||||
root=Path(layout.workspace),
|
||||
lane=layout.lane,
|
||||
role="build",
|
||||
)
|
||||
if errors:
|
||||
raise LaneError("invalid prepared lane: " + "; ".join(errors))
|
||||
|
||||
|
||||
def layout_document(layout: LaneLayout) -> dict[str, Any]:
|
||||
document = asdict(layout)
|
||||
document["environment"] = lane_environment(layout)
|
||||
document["sentinel"] = str(sentinel_path(Path(layout.lane_root)))
|
||||
return document
|
||||
|
||||
|
||||
def _shell_environment(values: Mapping[str, str]) -> str:
|
||||
return "\n".join(
|
||||
f"export {name}={shlex.quote(value)}" for name, value in sorted(values.items())
|
||||
)
|
||||
|
||||
|
||||
def _run_command(layout: LaneLayout, command: Sequence[str], *, dry_run: bool) -> int:
|
||||
if not command:
|
||||
raise LaneError("missing command after --")
|
||||
if dry_run:
|
||||
print(
|
||||
json.dumps(
|
||||
{"layout": layout_document(layout), "command": list(command)},
|
||||
indent=2,
|
||||
sort_keys=True,
|
||||
)
|
||||
)
|
||||
return 0
|
||||
prepare_lane(layout)
|
||||
environment = os.environ.copy()
|
||||
environment.update(lane_environment(layout))
|
||||
return subprocess.run(command, cwd=layout.workspace, env=environment).returncode
|
||||
|
||||
|
||||
def _resolve_runtime_command(layout: LaneLayout, command: Sequence[str]) -> list[str]:
|
||||
if not command:
|
||||
raise LaneError("missing runtime command after --")
|
||||
resolved = list(command)
|
||||
executable = Path(resolved[0])
|
||||
if not executable.is_absolute():
|
||||
parts = executable.parts
|
||||
if parts and parts[0] == "target":
|
||||
executable = Path(layout.target_dir).joinpath(*parts[1:])
|
||||
elif "/" in resolved[0]:
|
||||
executable = Path(layout.workspace) / executable
|
||||
resolved[0] = str(canonical_path(executable)) if "/" in str(executable) else str(executable)
|
||||
return resolved
|
||||
|
||||
|
||||
def _run_runtime(layout: LaneLayout, command: Sequence[str], *, dry_run: bool) -> int:
|
||||
require_prepared_lane(layout)
|
||||
resolved = _resolve_runtime_command(layout, command)
|
||||
environment = os.environ.copy()
|
||||
dependencies = layout.runtime_deps
|
||||
existing = environment.get("LD_LIBRARY_PATH")
|
||||
environment["LD_LIBRARY_PATH"] = (
|
||||
dependencies if not existing else dependencies + os.pathsep + existing
|
||||
)
|
||||
environment.update(lane_environment(layout))
|
||||
if dry_run:
|
||||
print(
|
||||
json.dumps(
|
||||
{
|
||||
"layout": layout_document(layout),
|
||||
"command": resolved,
|
||||
"LD_LIBRARY_PATH": environment["LD_LIBRARY_PATH"],
|
||||
},
|
||||
indent=2,
|
||||
sort_keys=True,
|
||||
)
|
||||
)
|
||||
return 0
|
||||
os.chdir(layout.workspace)
|
||||
os.execvpe(resolved[0], resolved, environment)
|
||||
raise AssertionError("os.execvpe unexpectedly returned") # pragma: no cover
|
||||
|
||||
|
||||
def _self_test() -> dict[str, Any]:
|
||||
checks: list[str] = []
|
||||
assert parse_version("cargo 1.97.0 (abc)") == (1, 97, 0)
|
||||
checks.append("cargo-version-parsing")
|
||||
assert profile_directory("test") == "debug"
|
||||
assert profile_directory("package-qa") == "package-qa"
|
||||
checks.append("profile-directory-mapping")
|
||||
try:
|
||||
validate_lane_name("../escape")
|
||||
except LaneError:
|
||||
checks.append("lane-name-traversal-rejected")
|
||||
else: # pragma: no cover
|
||||
raise AssertionError("unsafe lane name accepted")
|
||||
|
||||
with tempfile.TemporaryDirectory(prefix="blacksite-lane-self-test-") as temporary:
|
||||
root = Path(temporary) / "workspace"
|
||||
(root / ".git").mkdir(parents=True)
|
||||
(root / "Cargo.toml").write_text("[workspace]\nmembers = []\n", encoding="utf-8")
|
||||
workflow = {"build_storage": dict(DEFAULT_BUILD_STORAGE)}
|
||||
workflow["build_storage"]["cache_root"] = str(Path(temporary) / "cache")
|
||||
fake_toolchain = {
|
||||
"cargo": "cargo 1.97.0",
|
||||
"cargo_version": "1.97.0",
|
||||
"rustc": "rustc 1.97.0",
|
||||
"host": "x86_64-unknown-linux-gnu",
|
||||
"separate_build_dir": True,
|
||||
}
|
||||
layout = lane_layout(root, "dev", workflow, ["cargo", "check"], toolchain=fake_toolchain)
|
||||
prepare_lane(layout)
|
||||
marker = read_sentinel(Path(layout.lane_root))
|
||||
assert marker is not None
|
||||
assert not validate_sentinel(
|
||||
Path(layout.lane_root), marker, root=root, lane="dev", role="build"
|
||||
)
|
||||
checks.append("sentinel-round-trip")
|
||||
assert Path(layout.target_dir) == root / "target"
|
||||
assert Path(layout.build_dir) != Path(layout.target_dir)
|
||||
checks.append("separate-build-dir-layout")
|
||||
test_layout = lane_layout(
|
||||
root, "dev", workflow, ["cargo", "test"], toolchain=fake_toolchain
|
||||
)
|
||||
prepare_lane(test_layout)
|
||||
assert read_sentinel(Path(layout.lane_root))["signature"]["profile_signature"] == "dev-test"
|
||||
checks.append("dev-and-test-share-persistent-lane")
|
||||
hot_editor = lane_layout(
|
||||
root,
|
||||
"hot-reload",
|
||||
workflow,
|
||||
["cargo", "build", "-p", "editor", "--features", "dev,hot-reload"],
|
||||
toolchain=fake_toolchain,
|
||||
)
|
||||
hot_game = lane_layout(
|
||||
root,
|
||||
"hot-reload",
|
||||
workflow,
|
||||
["cargo", "build", "-p", "game_hot", "--features", "dylib"],
|
||||
toolchain=fake_toolchain,
|
||||
)
|
||||
assert hot_editor.feature_signature == hot_game.feature_signature == "hot-reload-family"
|
||||
checks.append("hot-reload-feature-family-isolated")
|
||||
package = lane_layout(
|
||||
root,
|
||||
"package",
|
||||
workflow,
|
||||
["cargo", "package-project", "--project", ".", "--profile", "package-qa"],
|
||||
toolchain=fake_toolchain,
|
||||
)
|
||||
assert package.profile == "dev"
|
||||
assert package.feature_signature == "package-family"
|
||||
checks.append("project-alias-options-not-cargo-options")
|
||||
|
||||
fallback_toolchain = dict(fake_toolchain)
|
||||
fallback_toolchain["cargo_version"] = "1.90.0"
|
||||
fallback_toolchain["separate_build_dir"] = False
|
||||
fallback = lane_layout(
|
||||
root,
|
||||
"candidate",
|
||||
workflow,
|
||||
["cargo", "test", "--all-features"],
|
||||
toolchain=fallback_toolchain,
|
||||
)
|
||||
assert fallback.mode == "external-target-dir-fallback"
|
||||
assert Path(fallback.target_dir) == Path(fallback.lane_root) / "target"
|
||||
assert fallback.build_dir == fallback.target_dir
|
||||
checks.append("external-target-dir-fallback")
|
||||
|
||||
cross = lane_layout(
|
||||
root,
|
||||
"cross-wasm",
|
||||
workflow,
|
||||
["cargo", "check", "--target", "wasm32-unknown-unknown"],
|
||||
toolchain=fake_toolchain,
|
||||
)
|
||||
assert cross.target_triple == "wasm32-unknown-unknown"
|
||||
assert "wasm32-unknown-unknown" in cross.runtime_deps
|
||||
checks.append("cross-target-partition")
|
||||
|
||||
return {"ok": True, "checks": checks}
|
||||
|
||||
|
||||
def _command_tail(values: Iterable[str]) -> list[str]:
|
||||
result = list(values)
|
||||
if result and result[0] == "--":
|
||||
result.pop(0)
|
||||
return result
|
||||
|
||||
|
||||
def build_parser() -> argparse.ArgumentParser:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--workspace", type=Path, help="workspace root override")
|
||||
subparsers = parser.add_subparsers(dest="action", required=True)
|
||||
|
||||
env_parser = subparsers.add_parser("env", help="describe a lane environment")
|
||||
env_parser.add_argument("lane")
|
||||
env_parser.add_argument("--json", action="store_true")
|
||||
|
||||
exec_parser = subparsers.add_parser("exec", help="execute a command in a lane")
|
||||
exec_parser.add_argument("lane")
|
||||
exec_parser.add_argument("--dry-run", action="store_true")
|
||||
exec_parser.add_argument("command", nargs=argparse.REMAINDER)
|
||||
|
||||
run_parser = subparsers.add_parser("run", help="run an existing lane artifact")
|
||||
run_parser.add_argument("lane")
|
||||
run_parser.add_argument("--dry-run", action="store_true")
|
||||
run_parser.add_argument("command", nargs=argparse.REMAINDER)
|
||||
|
||||
subparsers.add_parser("self-test", help="run temp-directory safety checks")
|
||||
return parser
|
||||
|
||||
|
||||
def main(argv: Sequence[str] | None = None) -> int:
|
||||
arguments = build_parser().parse_args(argv)
|
||||
if arguments.action == "self-test":
|
||||
print(json.dumps(_self_test(), indent=2, sort_keys=True))
|
||||
return 0
|
||||
|
||||
try:
|
||||
root = workspace_root(arguments.workspace)
|
||||
workflow = load_workflow(root)
|
||||
raw_command = list(getattr(arguments, "command", []))
|
||||
# argparse.REMAINDER intentionally preserves arbitrary child-command
|
||||
# flags. Accept our one wrapper flag after the lane as well as before it.
|
||||
if arguments.action in {"exec", "run"} and "--dry-run" in raw_command:
|
||||
separator = raw_command.index("--") if "--" in raw_command else len(raw_command)
|
||||
if raw_command.index("--dry-run") < separator:
|
||||
arguments.dry_run = True
|
||||
raw_command.remove("--dry-run")
|
||||
command = _command_tail(raw_command)
|
||||
layout = lane_layout(root, arguments.lane, workflow, command)
|
||||
|
||||
if arguments.action == "env":
|
||||
document = layout_document(layout)
|
||||
if arguments.json:
|
||||
print(json.dumps(document, indent=2, sort_keys=True))
|
||||
else:
|
||||
print(_shell_environment(document["environment"]))
|
||||
return 0
|
||||
if arguments.action == "exec":
|
||||
return _run_command(layout, command, dry_run=arguments.dry_run)
|
||||
if arguments.action == "run":
|
||||
return _run_runtime(layout, command, dry_run=arguments.dry_run)
|
||||
except LaneError as error:
|
||||
print(f"cargo-lane: {error}", file=sys.stderr)
|
||||
return 2
|
||||
return 2
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Executable
+315
@@ -0,0 +1,315 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Validate Blacksite documentation authority coverage and lifecycle banners."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import fnmatch
|
||||
import json
|
||||
import re
|
||||
import subprocess
|
||||
import sys
|
||||
import tomllib
|
||||
from collections import Counter
|
||||
from dataclasses import dataclass
|
||||
from pathlib import Path
|
||||
from typing import Any
|
||||
|
||||
|
||||
AUTHORITY_PATH = Path("docs/authority.toml")
|
||||
BANNER_MARKERS = {
|
||||
"active-plan": "**active plan",
|
||||
"evidence": "**evidence record",
|
||||
"historical": "**historical",
|
||||
"superseded": "**superseded",
|
||||
}
|
||||
LINK_RE = re.compile(r"\[[^\]]+\]\(([^)]+)\)")
|
||||
|
||||
|
||||
@dataclass(frozen=True)
|
||||
class Rule:
|
||||
id: str
|
||||
classification: str
|
||||
priority: int
|
||||
path: str | None = None
|
||||
prefix: str | None = None
|
||||
role: str | None = None
|
||||
replacement: str | None = None
|
||||
topics: tuple[str, ...] = ()
|
||||
|
||||
def matches(self, candidate: str) -> bool:
|
||||
if self.path is not None:
|
||||
return candidate == self.path
|
||||
if self.prefix is not None:
|
||||
return candidate.startswith(self.prefix)
|
||||
return False
|
||||
|
||||
|
||||
def repository_root() -> Path:
|
||||
current = Path(__file__).resolve()
|
||||
for parent in current.parents:
|
||||
if (parent / AUTHORITY_PATH).is_file():
|
||||
return parent
|
||||
raise RuntimeError(f"cannot locate repository root containing {AUTHORITY_PATH}")
|
||||
|
||||
|
||||
def load_authority(root: Path) -> tuple[dict[str, Any], list[Rule]]:
|
||||
raw = tomllib.loads((root / AUTHORITY_PATH).read_text(encoding="utf-8"))
|
||||
rules: list[Rule] = []
|
||||
for item in raw.get("rules", []):
|
||||
selectors = [name for name in ("path", "prefix") if item.get(name) is not None]
|
||||
if len(selectors) != 1:
|
||||
raise ValueError(f"rule {item.get('id', '<unknown>')} must set exactly one path or prefix")
|
||||
rules.append(
|
||||
Rule(
|
||||
id=item["id"],
|
||||
classification=item["classification"],
|
||||
priority=int(item.get("priority", 0)),
|
||||
path=item.get("path"),
|
||||
prefix=item.get("prefix"),
|
||||
role=item.get("role"),
|
||||
replacement=item.get("replacement"),
|
||||
topics=tuple(item.get("topics", [])),
|
||||
)
|
||||
)
|
||||
return raw, rules
|
||||
|
||||
|
||||
def discover_documents(root: Path, authority: dict[str, Any]) -> list[str]:
|
||||
discovery = authority.get("discovery", {})
|
||||
found: set[str] = set()
|
||||
for relative in discovery.get("paths", []):
|
||||
path = root / relative
|
||||
if path.is_file() and path.suffix == ".md":
|
||||
found.add(path.relative_to(root).as_posix())
|
||||
for relative in discovery.get("trees", []):
|
||||
tree = root / relative
|
||||
if tree.is_dir():
|
||||
found.update(path.relative_to(root).as_posix() for path in tree.rglob("*.md"))
|
||||
return sorted(found)
|
||||
|
||||
|
||||
def resolve_rule(path: str, rules: list[Rule]) -> tuple[Rule | None, str | None]:
|
||||
matches = [rule for rule in rules if rule.matches(path)]
|
||||
if not matches:
|
||||
return None, None
|
||||
highest = max(rule.priority for rule in matches)
|
||||
winners = [rule for rule in matches if rule.priority == highest]
|
||||
classifications = {rule.classification for rule in winners}
|
||||
if len(classifications) != 1:
|
||||
names = ", ".join(rule.id for rule in winners)
|
||||
return None, f"equal-priority rules disagree: {names}"
|
||||
winners.sort(key=lambda rule: (rule.path is not None, len(rule.path or rule.prefix or "")), reverse=True)
|
||||
return winners[0], None
|
||||
|
||||
|
||||
def normalized_link_target(root: Path, document: Path, raw_target: str) -> str | None:
|
||||
target = raw_target.split("#", 1)[0].strip().strip("<>")
|
||||
if not target or "://" in target or target.startswith("mailto:"):
|
||||
return None
|
||||
resolved = (document.parent / target).resolve()
|
||||
try:
|
||||
return resolved.relative_to(root.resolve()).as_posix()
|
||||
except ValueError:
|
||||
return None
|
||||
|
||||
|
||||
def path_matches(path: str, pattern: str) -> bool:
|
||||
if pattern.endswith("/**"):
|
||||
return path.startswith(pattern[:-2])
|
||||
return fnmatch.fnmatchcase(path, pattern)
|
||||
|
||||
|
||||
def validate_links(root: Path, relative: str) -> list[str]:
|
||||
path = root / relative
|
||||
text = path.read_text(encoding="utf-8")
|
||||
errors: list[str] = []
|
||||
for raw_target in LINK_RE.findall(text):
|
||||
target = raw_target.split("#", 1)[0].strip().strip("<>")
|
||||
if not target or "://" in target or target.startswith(("mailto:", "#")):
|
||||
continue
|
||||
normalized = normalized_link_target(root, path, raw_target)
|
||||
if normalized is None:
|
||||
errors.append(f"link escapes the repository: {raw_target}")
|
||||
continue
|
||||
if not (root / normalized).exists():
|
||||
errors.append(f"broken relative link: {raw_target}")
|
||||
return errors
|
||||
|
||||
|
||||
def changed_documents(root: Path) -> set[str]:
|
||||
changed: set[str] = set()
|
||||
commands = [
|
||||
["git", "diff", "--name-only", "--relative", "HEAD"],
|
||||
["git", "ls-files", "--others", "--exclude-standard"],
|
||||
]
|
||||
for command in commands:
|
||||
result = subprocess.run(command, cwd=root, check=False, capture_output=True, text=True)
|
||||
if result.returncode != 0:
|
||||
raise RuntimeError(f"failed to query changed files: {' '.join(command)}")
|
||||
changed.update(line.strip() for line in result.stdout.splitlines() if line.strip())
|
||||
return changed
|
||||
|
||||
|
||||
def validate_banner(root: Path, relative: str, rule: Rule) -> list[str]:
|
||||
if rule.classification == "current":
|
||||
return []
|
||||
path = root / relative
|
||||
text = path.read_text(encoding="utf-8")
|
||||
head = "\n".join(text.splitlines()[:180])
|
||||
lowered = head.lower()
|
||||
marker = BANNER_MARKERS[rule.classification]
|
||||
if marker not in lowered:
|
||||
# ADR 0019 predates Markdown heading style but has an explicit first-line status.
|
||||
if not (rule.classification == "superseded" and lowered.startswith("status: superseded")):
|
||||
return [f"missing {rule.classification} banner near the start of the document"]
|
||||
|
||||
if rule.classification not in {"evidence", "historical", "superseded"}:
|
||||
return []
|
||||
links = {
|
||||
normalized
|
||||
for target in LINK_RE.findall(head)
|
||||
if (normalized := normalized_link_target(root, path, target)) is not None
|
||||
}
|
||||
if not links:
|
||||
return ["lifecycle banner must link to current canonical guidance"]
|
||||
if rule.replacement and rule.replacement not in links:
|
||||
return [f"lifecycle banner must link to configured replacement {rule.replacement}"]
|
||||
return []
|
||||
|
||||
|
||||
def audit(root: Path, *, changed_only: bool = False, topic: str | None = None) -> dict[str, Any]:
|
||||
authority, rules = load_authority(root)
|
||||
allowed = set(authority.get("classifications", []))
|
||||
allowed_roles = set(authority.get("roles", []))
|
||||
errors: list[str] = []
|
||||
warnings: list[str] = []
|
||||
|
||||
if authority.get("version") != 1:
|
||||
errors.append("docs/authority.toml: unsupported or missing version")
|
||||
if allowed != {"current", "active-plan", "evidence", "historical", "superseded"}:
|
||||
errors.append("docs/authority.toml: classifications must be the five workflow classes")
|
||||
|
||||
for rule in rules:
|
||||
if rule.classification not in allowed:
|
||||
errors.append(f"rule {rule.id}: unknown classification {rule.classification}")
|
||||
if not rule.role or rule.role not in allowed_roles:
|
||||
errors.append(f"rule {rule.id}: unknown or missing role {rule.role}")
|
||||
if rule.path and not (root / rule.path).is_file():
|
||||
errors.append(f"rule {rule.id}: exact path does not exist: {rule.path}")
|
||||
if rule.replacement and not (root / rule.replacement).is_file():
|
||||
errors.append(f"rule {rule.id}: replacement does not exist: {rule.replacement}")
|
||||
|
||||
counts: Counter[str] = Counter()
|
||||
documents: list[dict[str, str]] = []
|
||||
resolved: list[tuple[str, Rule]] = []
|
||||
for relative in discover_documents(root, authority):
|
||||
rule, conflict = resolve_rule(relative, rules)
|
||||
if conflict:
|
||||
errors.append(f"{relative}: {conflict}")
|
||||
continue
|
||||
if rule is None:
|
||||
errors.append(f"{relative}: unclassified")
|
||||
continue
|
||||
resolved.append((relative, rule))
|
||||
counts[rule.classification] += 1
|
||||
documents.append(
|
||||
{
|
||||
"path": relative,
|
||||
"classification": rule.classification,
|
||||
"rule": rule.id,
|
||||
"role": rule.role or "",
|
||||
"topics": ",".join(rule.topics),
|
||||
}
|
||||
)
|
||||
|
||||
canonical_owners: dict[str, list[str]] = {}
|
||||
for relative, rule in resolved:
|
||||
if rule.role == "canonical" and rule.classification == "current":
|
||||
for owned_topic in rule.topics:
|
||||
canonical_owners.setdefault(owned_topic, []).append(relative)
|
||||
for owned_topic, owners in sorted(canonical_owners.items()):
|
||||
if len(owners) > 1:
|
||||
errors.append(f"topic {owned_topic}: multiple canonical owners: {', '.join(owners)}")
|
||||
|
||||
selected = resolved
|
||||
if changed_only:
|
||||
changed = changed_documents(root)
|
||||
if AUTHORITY_PATH.as_posix() not in changed:
|
||||
selected = [(path, rule) for path, rule in selected if path in changed]
|
||||
if topic:
|
||||
selected = [(path, rule) for path, rule in selected if topic in rule.topics]
|
||||
if not selected:
|
||||
errors.append(f"topic {topic}: no classified documents")
|
||||
|
||||
stale_terms = authority.get("stale_terms", [])
|
||||
for relative, rule in selected:
|
||||
for error in validate_banner(root, relative, rule):
|
||||
errors.append(f"{relative}: {error}")
|
||||
for error in validate_links(root, relative):
|
||||
errors.append(f"{relative}: {error}")
|
||||
|
||||
if rule.classification != "current":
|
||||
continue
|
||||
text = (root / relative).read_text(encoding="utf-8")
|
||||
lowered = text.lower()
|
||||
for stale in stale_terms:
|
||||
if any(path_matches(relative, allowed_path) for allowed_path in stale.get("allowed_paths", [])):
|
||||
continue
|
||||
pattern = stale["pattern"]
|
||||
if pattern.lower() in lowered:
|
||||
errors.append(
|
||||
f"{relative}: stale term {pattern!r}; use {stale.get('replacement', 'current terminology')}"
|
||||
)
|
||||
if rule.role == "canonical":
|
||||
if re.search(r"(?im)^\s*- \[ \]", text):
|
||||
warnings.append(f"{relative}: unchecked checklist in canonical documentation; review status semantics")
|
||||
if re.search(r"(?i)\bnot implemented\b|\((?:still\s+)?planned\)", text):
|
||||
warnings.append(f"{relative}: possible future-status language in canonical documentation; review semantically")
|
||||
|
||||
return {
|
||||
"ok": not errors,
|
||||
"authority": AUTHORITY_PATH.as_posix(),
|
||||
"documents": documents,
|
||||
"counts": dict(sorted(counts.items())),
|
||||
"errors": errors,
|
||||
"warnings": warnings,
|
||||
"selected": len(selected),
|
||||
}
|
||||
|
||||
|
||||
def main() -> int:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--json", action="store_true", help="emit the complete machine-readable report")
|
||||
parser.add_argument("--list", action="store_true", help="list every classified document")
|
||||
parser.add_argument("--changed", action="store_true", help="check lifecycle, links, and terms only in changed documents")
|
||||
parser.add_argument("--topic", help="check lifecycle, links, and terms only for one configured topic")
|
||||
args = parser.parse_args()
|
||||
|
||||
try:
|
||||
result = audit(repository_root(), changed_only=args.changed, topic=args.topic)
|
||||
except (OSError, RuntimeError, ValueError, tomllib.TOMLDecodeError) as error:
|
||||
print(f"FAIL docs-authority — {error}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
if args.json:
|
||||
print(json.dumps(result, indent=2, sort_keys=True))
|
||||
else:
|
||||
status = "PASS" if result["ok"] else "FAIL"
|
||||
counts = ", ".join(f"{name}={count}" for name, count in result["counts"].items())
|
||||
print(
|
||||
f"{status} docs-authority — {len(result['documents'])} classified, "
|
||||
f"{result['selected']} checked — {counts}"
|
||||
)
|
||||
if args.list:
|
||||
for document in result["documents"]:
|
||||
print(f"{document['classification']:11} {document['path']} ({document['rule']})")
|
||||
for error in result["errors"]:
|
||||
print(f"ERROR {error}", file=sys.stderr)
|
||||
for warning in result["warnings"]:
|
||||
print(f"WARN {warning}", file=sys.stderr)
|
||||
return 0 if result["ok"] else 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Executable
+348
@@ -0,0 +1,348 @@
|
||||
#!/usr/bin/env bash
|
||||
set -euo pipefail
|
||||
|
||||
ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd -P)"
|
||||
SCENARIO_ROOT="$ROOT/.agents/skills/blacksite-native-qa/references/scenarios"
|
||||
STATE_ROOT="$ROOT/.codex/session"
|
||||
EVIDENCE_ROOT="$ROOT/.codex/evidence"
|
||||
|
||||
usage() {
|
||||
echo "usage: $0 plan|launch|attach|capture|record|status|restore|close <scenario-name> [arguments]" >&2
|
||||
exit 2
|
||||
}
|
||||
|
||||
[[ $# -ge 2 ]] || usage
|
||||
ACTION="$1"
|
||||
NAME="$2"
|
||||
SCENARIO="$SCENARIO_ROOT/$NAME.yaml"
|
||||
[[ -f "$SCENARIO" ]] || { echo "native-qa: unknown scenario $NAME" >&2; exit 2; }
|
||||
|
||||
field() {
|
||||
local key="$1"
|
||||
sed -n "s/^${key}:[[:space:]]*//p" "$SCENARIO" | head -n 1
|
||||
}
|
||||
|
||||
LANE="$(field build_lane)"
|
||||
[[ -n "$LANE" ]] || LANE="dev"
|
||||
FIXTURE="$(field fixture)"
|
||||
mkdir -p "$STATE_ROOT" "$EVIDENCE_ROOT"
|
||||
|
||||
lane_json() {
|
||||
python "$ROOT/scripts/codex/cargo_lane.py" env "$LANE" --json
|
||||
}
|
||||
|
||||
list_section() {
|
||||
local section="$1"
|
||||
awk -v section="$section" '
|
||||
$0 == section ":" { active = 1; next }
|
||||
active && /^[^[:space:]]/ { exit }
|
||||
active && /^[[:space:]]+-[[:space:]]+/ {
|
||||
sub(/^[[:space:]]+-[[:space:]]+/, "")
|
||||
print
|
||||
}
|
||||
' "$SCENARIO"
|
||||
}
|
||||
|
||||
snapshot_fixture() {
|
||||
local record="$STATE_ROOT/native-$NAME.json"
|
||||
local snapshot="$STATE_ROOT/native-$NAME.fixture.snapshot"
|
||||
python - "$ROOT" "$FIXTURE" "$record" "$snapshot" "$LANE" "$SCENARIO" <<'PY'
|
||||
import hashlib, json, os, pathlib, shutil, sys, time
|
||||
|
||||
root = pathlib.Path(sys.argv[1]).resolve()
|
||||
fixture_text, record_text, snapshot_text, lane, scenario = sys.argv[2:]
|
||||
record = pathlib.Path(record_text)
|
||||
snapshot = pathlib.Path(snapshot_text)
|
||||
if record.is_file():
|
||||
previous = json.loads(record.read_text(encoding="utf-8"))
|
||||
pid = previous.get("pid")
|
||||
if pid:
|
||||
try:
|
||||
os.kill(int(pid), 0)
|
||||
except ProcessLookupError:
|
||||
pass
|
||||
except PermissionError:
|
||||
raise SystemExit(f"native-qa: cannot verify existing runner PID {pid}; refusing launch")
|
||||
else:
|
||||
raise SystemExit(f"native-qa: existing runner PID {pid} is still active")
|
||||
old_fixture = previous.get("fixture")
|
||||
if old_fixture and not old_fixture.get("restored"):
|
||||
raise SystemExit("native-qa: restore the previous fixture before launching this scenario again")
|
||||
record.unlink()
|
||||
snapshot.unlink(missing_ok=True)
|
||||
data = {
|
||||
"pid": None,
|
||||
"lane": lane,
|
||||
"scenario": scenario,
|
||||
"spawned_by_runner": False,
|
||||
"prepared_at": time.time(),
|
||||
"assertions": {},
|
||||
"evidence": [],
|
||||
}
|
||||
if fixture_text:
|
||||
fixture = (root / fixture_text).resolve()
|
||||
if fixture != root and root not in fixture.parents:
|
||||
raise SystemExit(f"fixture escapes workspace: {fixture}")
|
||||
if fixture.exists() and not fixture.is_file():
|
||||
raise SystemExit(f"fixture is not a regular file: {fixture}")
|
||||
existed = fixture.is_file()
|
||||
baseline = hashlib.sha256(fixture.read_bytes()).hexdigest() if existed else None
|
||||
if existed:
|
||||
shutil.copy2(fixture, snapshot)
|
||||
data["fixture"] = {
|
||||
"path": str(fixture),
|
||||
"existed": existed,
|
||||
"baseline_sha256": baseline,
|
||||
"snapshot": str(snapshot) if existed else None,
|
||||
"restored": False,
|
||||
}
|
||||
record.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
|
||||
PY
|
||||
}
|
||||
|
||||
case "$ACTION" in
|
||||
plan)
|
||||
LANE_JSON="$(lane_json)" python - "$SCENARIO" "$FIXTURE" <<'PY'
|
||||
import json, os, pathlib, sys
|
||||
layout = json.loads(os.environ["LANE_JSON"])
|
||||
scenario = pathlib.Path(sys.argv[1])
|
||||
fixture = sys.argv[2]
|
||||
binary = pathlib.Path(layout["target_dir"]) / layout["profile_dir"] / "editor"
|
||||
print(f"PASS native-qa-plan — {scenario.stem}")
|
||||
print(f"Lane: {layout['lane']} ({layout['mode']})")
|
||||
print(f"Binary: {binary}")
|
||||
print(f"Runtime deps: {layout['runtime_deps']}")
|
||||
print(f"Fixture: {fixture or 'scenario-defined'}")
|
||||
print("Visual interaction remains manual/user-controlled until explicitly delegated.")
|
||||
PY
|
||||
echo "Purpose: $(field purpose)"
|
||||
echo "Preconditions: $(field preconditions)"
|
||||
echo "Steps:"
|
||||
list_section steps | nl -w2 -s'. '
|
||||
echo "Assertions:"
|
||||
list_section assertions | nl -w2 -s'. '
|
||||
echo "Evidence: $(field evidence)"
|
||||
echo "Cleanup: $(field cleanup)"
|
||||
;;
|
||||
launch)
|
||||
snapshot_fixture
|
||||
python "$ROOT/scripts/codex/build_storage.py" enforce --phase pre
|
||||
python "$ROOT/scripts/codex/summarize_command.py" \
|
||||
--gate "native-$NAME-build" \
|
||||
--log "$ROOT/.codex/logs/native-$NAME-build.log" \
|
||||
--json-result "$ROOT/.codex/logs/native-$NAME-build.json" \
|
||||
-- python "$ROOT/scripts/codex/cargo_lane.py" exec "$LANE" -- cargo build -p editor --bin editor
|
||||
python "$ROOT/scripts/codex/build_storage.py" enforce --phase post
|
||||
nohup python "$ROOT/scripts/codex/cargo_lane.py" run "$LANE" -- \
|
||||
target/debug/editor --project "$ROOT" \
|
||||
>"$ROOT/.codex/logs/native-$NAME-launch.log" 2>&1 &
|
||||
PID=$!
|
||||
python - "$STATE_ROOT/native-$NAME.json" "$PID" <<'PY'
|
||||
import json, pathlib, sys, time
|
||||
path = pathlib.Path(sys.argv[1])
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
data.update({"pid": int(sys.argv[2]), "spawned_at": time.time(), "spawned_by_runner": True})
|
||||
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
|
||||
PY
|
||||
echo "PASS native-qa-launch — $NAME — PID $PID"
|
||||
;;
|
||||
attach)
|
||||
[[ $# -eq 3 ]] || usage
|
||||
PID="$3"
|
||||
kill -0 "$PID" 2>/dev/null || { echo "native-qa: PID $PID is not running" >&2; exit 2; }
|
||||
CMDLINE="$(tr '\0' ' ' <"/proc/$PID/cmdline")"
|
||||
[[ "$CMDLINE" == *"editor"* ]] || { echo "native-qa: refusing unexpected process: $CMDLINE" >&2; exit 2; }
|
||||
snapshot_fixture
|
||||
python - "$STATE_ROOT/native-$NAME.json" "$PID" <<'PY'
|
||||
import json, pathlib, sys, time
|
||||
path = pathlib.Path(sys.argv[1])
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
data.update({"pid": int(sys.argv[2]), "attached_at": time.time(), "spawned_by_runner": False})
|
||||
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
|
||||
PY
|
||||
echo "PASS native-qa-attach — $NAME — PID $PID"
|
||||
;;
|
||||
capture)
|
||||
[[ $# -eq 3 ]] || usage
|
||||
PID="$3"
|
||||
kill -0 "$PID" 2>/dev/null || { echo "native-qa: PID $PID is not running" >&2; exit 2; }
|
||||
CLIENTS="$(hyprctl clients -j)"
|
||||
GEOMETRY="$(CLIENTS_JSON="$CLIENTS" python - "$PID" <<'PY'
|
||||
import json, os, sys
|
||||
pid = int(sys.argv[1])
|
||||
matches = [c for c in json.loads(os.environ["CLIENTS_JSON"]) if c.get("pid") == pid]
|
||||
if len(matches) != 1:
|
||||
raise SystemExit(f"expected one Hyprland window for PID {pid}, found {len(matches)}")
|
||||
client = matches[0]
|
||||
x, y = client["at"]
|
||||
w, h = client["size"]
|
||||
if w <= 0 or h <= 0:
|
||||
raise SystemExit("target window has invalid geometry")
|
||||
print(f"{x},{y} {w}x{h}")
|
||||
PY
|
||||
)"
|
||||
STAMP="$(date -u +%Y%m%dT%H%M%SZ)"
|
||||
IMAGE="$EVIDENCE_ROOT/$NAME-$STAMP.png"
|
||||
grim -g "$GEOMETRY" "$IMAGE"
|
||||
HASH="$(sha256sum "$IMAGE" | awk '{print $1}')"
|
||||
python - "$STATE_ROOT/native-$NAME-evidence.json" "$PID" "$IMAGE" "$HASH" "$GEOMETRY" <<'PY'
|
||||
import json, pathlib, sys, time
|
||||
path = pathlib.Path(sys.argv[1])
|
||||
path.write_text(json.dumps({
|
||||
"pid": int(sys.argv[2]), "image": sys.argv[3], "sha256": sys.argv[4],
|
||||
"geometry": sys.argv[5], "captured_at": time.time(),
|
||||
}, indent=2) + "\n", encoding="utf-8")
|
||||
PY
|
||||
python - "$STATE_ROOT/native-$NAME.json" "$IMAGE" "$HASH" "$GEOMETRY" <<'PY'
|
||||
import json, pathlib, sys, time
|
||||
path = pathlib.Path(sys.argv[1])
|
||||
if not path.is_file():
|
||||
raise SystemExit("native-qa: missing runner record")
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
data.setdefault("evidence", []).append({
|
||||
"image": sys.argv[2], "sha256": sys.argv[3], "geometry": sys.argv[4],
|
||||
"captured_at": time.time(),
|
||||
})
|
||||
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
|
||||
PY
|
||||
echo "PASS native-qa-capture — $NAME — $IMAGE — $HASH"
|
||||
;;
|
||||
record)
|
||||
[[ $# -ge 4 && $# -le 5 ]] || usage
|
||||
INDEX="$3"
|
||||
RESULT="$4"
|
||||
NOTE="${5:-}"
|
||||
[[ "$INDEX" =~ ^[1-9][0-9]*$ ]] || { echo "native-qa: assertion index must be positive" >&2; exit 2; }
|
||||
[[ "$RESULT" = "pass" || "$RESULT" = "fail" ]] || { echo "native-qa: result must be pass or fail" >&2; exit 2; }
|
||||
ASSERTION_COUNT="$(list_section assertions | wc -l)"
|
||||
(( INDEX <= ASSERTION_COUNT )) || { echo "native-qa: assertion $INDEX exceeds count $ASSERTION_COUNT" >&2; exit 2; }
|
||||
ASSERTION_TEXT="$(list_section assertions | sed -n "${INDEX}p")"
|
||||
python - "$STATE_ROOT/native-$NAME.json" "$INDEX" "$RESULT" "$NOTE" "$ASSERTION_TEXT" <<'PY'
|
||||
import json, pathlib, sys, time
|
||||
path = pathlib.Path(sys.argv[1])
|
||||
if not path.is_file():
|
||||
raise SystemExit("native-qa: missing runner record")
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
data.setdefault("assertions", {})[sys.argv[2]] = {
|
||||
"result": sys.argv[3], "note": sys.argv[4], "text": sys.argv[5],
|
||||
"recorded_at": time.time(),
|
||||
}
|
||||
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
|
||||
PY
|
||||
echo "PASS native-qa-record — $NAME — assertion $INDEX = $RESULT"
|
||||
;;
|
||||
status)
|
||||
[[ $# -eq 2 ]] || usage
|
||||
RECORD="$STATE_ROOT/native-$NAME.json"
|
||||
[[ -f "$RECORD" ]] || { echo "native-qa: no runner record for $NAME" >&2; exit 2; }
|
||||
ASSERTION_COUNT="$(list_section assertions | wc -l)"
|
||||
python - "$RECORD" "$ASSERTION_COUNT" <<'PY'
|
||||
import json, pathlib, sys, time
|
||||
path = pathlib.Path(sys.argv[1])
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
expected = int(sys.argv[2])
|
||||
results = data.get("assertions", {})
|
||||
passed = sum(item.get("result") == "pass" for item in results.values())
|
||||
failed = sum(item.get("result") == "fail" for item in results.values())
|
||||
print(f"native-qa-status — assertions {passed} pass, {failed} fail, {expected - len(results)} unrecorded")
|
||||
print(f"evidence: {len(data.get('evidence', []))} capture(s)")
|
||||
fixture = data.get("fixture")
|
||||
if fixture:
|
||||
print(f"fixture restored: {bool(fixture.get('restored'))}")
|
||||
complete = not failed and len(results) == expected and bool(data.get("evidence"))
|
||||
data["scenario_result"] = {"result": "PASS" if complete else "FAIL", "recorded_at": time.time()}
|
||||
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
|
||||
if not complete:
|
||||
raise SystemExit(1)
|
||||
PY
|
||||
;;
|
||||
restore)
|
||||
[[ $# -eq 3 ]] || usage
|
||||
MODE="$3"
|
||||
[[ "$MODE" = "--dry-run" || "$MODE" = "--apply" ]] || usage
|
||||
RECORD="$STATE_ROOT/native-$NAME.json"
|
||||
[[ -f "$RECORD" ]] || { echo "native-qa: no runner record for $NAME" >&2; exit 2; }
|
||||
python - "$RECORD" "$MODE" "$ROOT" <<'PY'
|
||||
import hashlib, json, os, pathlib, shutil, sys, tempfile, time
|
||||
|
||||
record = pathlib.Path(sys.argv[1])
|
||||
apply = sys.argv[2] == "--apply"
|
||||
root = pathlib.Path(sys.argv[3]).resolve()
|
||||
data = json.loads(record.read_text(encoding="utf-8"))
|
||||
fixture = data.get("fixture")
|
||||
if not fixture:
|
||||
print("PASS native-qa-restore — scenario has no fixture")
|
||||
raise SystemExit(0)
|
||||
path = pathlib.Path(fixture["path"]).resolve()
|
||||
if path != root and root not in path.parents:
|
||||
raise SystemExit(f"native-qa: fixture escapes workspace: {path}")
|
||||
pid = data.get("pid")
|
||||
if apply and pid:
|
||||
try:
|
||||
os.kill(int(pid), 0)
|
||||
except ProcessLookupError:
|
||||
pass
|
||||
except PermissionError:
|
||||
raise SystemExit(f"native-qa: cannot verify runner PID {pid}; refusing fixture restore")
|
||||
else:
|
||||
raise SystemExit(f"native-qa: close runner PID {pid} before restoring the fixture")
|
||||
current = hashlib.sha256(path.read_bytes()).hexdigest() if path.is_file() else None
|
||||
baseline = fixture.get("baseline_sha256")
|
||||
action = "restore snapshot" if fixture.get("existed") else "remove scenario-created fixture"
|
||||
print(f"native-qa-restore-plan — {action}")
|
||||
print(f"fixture: {path}")
|
||||
print(f"baseline sha256: {baseline or '(absent)'}")
|
||||
print(f"current sha256: {current or '(absent)'}")
|
||||
sys.stdout.flush()
|
||||
if not apply:
|
||||
raise SystemExit(0)
|
||||
if fixture.get("existed"):
|
||||
snapshot = pathlib.Path(fixture["snapshot"])
|
||||
if not snapshot.is_file():
|
||||
raise SystemExit(f"native-qa: missing fixture snapshot: {snapshot}")
|
||||
snapshot_hash = hashlib.sha256(snapshot.read_bytes()).hexdigest()
|
||||
if snapshot_hash != baseline:
|
||||
raise SystemExit("native-qa: fixture snapshot hash does not match recorded baseline")
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
with tempfile.NamedTemporaryFile(dir=path.parent, prefix=f".{path.name}.", delete=False) as handle:
|
||||
temp = pathlib.Path(handle.name)
|
||||
handle.write(snapshot.read_bytes())
|
||||
os.replace(temp, path)
|
||||
else:
|
||||
if path.exists() and not path.is_file():
|
||||
raise SystemExit(f"native-qa: refusing to remove non-file fixture path: {path}")
|
||||
path.unlink(missing_ok=True)
|
||||
fixture["restored"] = True
|
||||
fixture["restored_at"] = time.time()
|
||||
record.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
|
||||
print("PASS native-qa-restore")
|
||||
PY
|
||||
;;
|
||||
close)
|
||||
[[ $# -eq 3 ]] || usage
|
||||
PID="$3"
|
||||
RECORD="$STATE_ROOT/native-$NAME.json"
|
||||
[[ -f "$RECORD" ]] || { echo "native-qa: no runner record for $NAME" >&2; exit 2; }
|
||||
RECORDED="$(python -c 'import json,sys; print(json.load(open(sys.argv[1]))["pid"])' "$RECORD")"
|
||||
[[ "$RECORDED" = "$PID" ]] || { echo "native-qa: PID does not match runner record" >&2; exit 2; }
|
||||
SPAWNED="$(python -c 'import json,sys; print(str(bool(json.load(open(sys.argv[1])).get("spawned_by_runner"))).lower())' "$RECORD")"
|
||||
if [[ "$SPAWNED" = "true" ]] && kill -0 "$PID" 2>/dev/null; then
|
||||
CMDLINE="$(tr '\0' ' ' <"/proc/$PID/cmdline")"
|
||||
[[ "$CMDLINE" == *"editor"* ]] || { echo "native-qa: refusing to stop unexpected process: $CMDLINE" >&2; exit 2; }
|
||||
kill -TERM "$PID"
|
||||
fi
|
||||
python - "$RECORD" <<'PY'
|
||||
import json, pathlib, time, sys
|
||||
path = pathlib.Path(sys.argv[1])
|
||||
data = json.loads(path.read_text(encoding="utf-8"))
|
||||
data["closed_at"] = time.time()
|
||||
data["detached_only"] = not bool(data.get("spawned_by_runner"))
|
||||
if data["detached_only"]:
|
||||
data["detached_pid"] = data.get("pid")
|
||||
data["pid"] = None
|
||||
path.write_text(json.dumps(data, indent=2) + "\n", encoding="utf-8")
|
||||
PY
|
||||
echo "PASS native-qa-close — $NAME — PID $PID"
|
||||
;;
|
||||
*) usage ;;
|
||||
esac
|
||||
Executable
+995
@@ -0,0 +1,995 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Maintain Blacksite's compact, resumable Codex session state.
|
||||
|
||||
The state is intentionally Markdown rather than an opaque database so a resumed
|
||||
agent can read it cheaply. This module uses only the Python standard library.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import contextlib
|
||||
import copy
|
||||
import hashlib
|
||||
import io
|
||||
import os
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import tomllib
|
||||
from dataclasses import dataclass, field
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
from typing import Any, Iterable, Sequence
|
||||
|
||||
|
||||
TITLE = "# Codex session state"
|
||||
WORKFLOW_PATH = Path(".codex/workflow.toml")
|
||||
VALID_STATES = (
|
||||
"Implementing",
|
||||
"Engineering-complete",
|
||||
"Acceptance-in-progress",
|
||||
"Candidate-ready",
|
||||
)
|
||||
CLASSIFICATIONS = {
|
||||
"active-slice-refinement": "active-slice refinement",
|
||||
"active-slice refinement": "active-slice refinement",
|
||||
"newly-discovered-blocker": "newly discovered blocker",
|
||||
"newly discovered blocker": "newly discovered blocker",
|
||||
"discovered-blocker": "newly discovered blocker",
|
||||
"added-acceptance-criterion": "added acceptance criterion",
|
||||
"added acceptance criterion": "added acceptance criterion",
|
||||
"separate-follow-up": "separate follow-up",
|
||||
"separate follow-up": "separate follow-up",
|
||||
}
|
||||
|
||||
|
||||
class StateError(RuntimeError):
|
||||
"""The state operation cannot be completed safely."""
|
||||
|
||||
|
||||
def clean_text(value: str | None, default: str = "None.") -> str:
|
||||
"""Keep state entries single-line and compact."""
|
||||
|
||||
if value is None:
|
||||
return default
|
||||
compact = " ".join(value.split())
|
||||
return compact or default
|
||||
|
||||
|
||||
def utc_now() -> str:
|
||||
return datetime.now(timezone.utc).isoformat(timespec="seconds")
|
||||
|
||||
|
||||
def find_repository(start: Path | None = None) -> Path:
|
||||
"""Locate the nearest repository containing the workflow configuration."""
|
||||
|
||||
override = os.environ.get("BLACKSITE_WORKSPACE_ROOT")
|
||||
configured = None
|
||||
config_path = (start or Path.cwd()) / ".codex/config.toml"
|
||||
if not override and config_path.is_file():
|
||||
with config_path.open("rb") as handle:
|
||||
configured = tomllib.load(handle).get("workspace_root")
|
||||
candidates = [Path(override or configured)] if (override or configured) else [start or Path.cwd()]
|
||||
if start is None and not override:
|
||||
candidates.append(Path(__file__).parent)
|
||||
|
||||
visited: set[Path] = set()
|
||||
for candidate in candidates:
|
||||
candidate = candidate.expanduser().absolute()
|
||||
for current in (candidate, *candidate.parents):
|
||||
canonical = current.resolve(strict=False)
|
||||
if canonical in visited:
|
||||
continue
|
||||
visited.add(canonical)
|
||||
if (current / WORKFLOW_PATH).is_file():
|
||||
return current
|
||||
searched = ", ".join(str(path) for path in candidates)
|
||||
raise StateError(f"could not locate {WORKFLOW_PATH} from {searched}")
|
||||
|
||||
|
||||
def load_workflow(root: Path) -> dict[str, Any]:
|
||||
path = root / WORKFLOW_PATH
|
||||
try:
|
||||
with path.open("rb") as handle:
|
||||
workflow = tomllib.load(handle)
|
||||
except OSError as error:
|
||||
raise StateError(f"cannot read workflow configuration {path}: {error}") from error
|
||||
except tomllib.TOMLDecodeError as error:
|
||||
raise StateError(f"invalid workflow configuration {path}: {error}") from error
|
||||
if workflow.get("version") != 1:
|
||||
raise StateError(f"unsupported or missing workflow version in {path}")
|
||||
return workflow
|
||||
|
||||
|
||||
def configured_path(root: Path, raw: str, *, label: str) -> Path:
|
||||
candidate = Path(os.path.expandvars(os.path.expanduser(raw)))
|
||||
if not candidate.is_absolute():
|
||||
candidate = root / candidate
|
||||
candidate = candidate.absolute()
|
||||
try:
|
||||
candidate.resolve(strict=False).relative_to(root.resolve(strict=False))
|
||||
except ValueError as error:
|
||||
raise StateError(f"configured {label} must remain inside the repository: {candidate}") from error
|
||||
return candidate
|
||||
|
||||
|
||||
def state_path(root: Path, workflow: dict[str, Any]) -> Path:
|
||||
session = workflow.get("session", {})
|
||||
if not isinstance(session, dict):
|
||||
raise StateError("[session] must be a TOML table")
|
||||
raw = session.get("state_file", ".codex/session/STATE.md")
|
||||
if not isinstance(raw, str) or not raw:
|
||||
raise StateError("session.state_file must be a non-empty path string")
|
||||
return configured_path(root, raw, label="session.state_file")
|
||||
|
||||
|
||||
def max_state_lines(workflow: dict[str, Any]) -> int:
|
||||
session = workflow.get("session", {})
|
||||
value = session.get("max_state_lines", 180) if isinstance(session, dict) else 180
|
||||
if not isinstance(value, int) or value < 48:
|
||||
raise StateError("session.max_state_lines must be an integer of at least 48")
|
||||
return value
|
||||
|
||||
|
||||
def run_git(root: Path, *arguments: str, check: bool = True) -> subprocess.CompletedProcess[str]:
|
||||
try:
|
||||
result = subprocess.run(
|
||||
["git", "-C", str(root), *arguments],
|
||||
check=False,
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.PIPE,
|
||||
text=True,
|
||||
)
|
||||
except OSError as error:
|
||||
raise StateError(f"cannot execute git: {error}") from error
|
||||
if check and result.returncode != 0:
|
||||
detail = clean_text(result.stderr or result.stdout, "git command failed")
|
||||
raise StateError(detail)
|
||||
return result
|
||||
|
||||
|
||||
def worktree_summary(root: Path) -> str:
|
||||
lines = run_git(root, "status", "--porcelain=v1", "--untracked-files=normal").stdout.splitlines()
|
||||
if not lines:
|
||||
return "clean"
|
||||
|
||||
staged = modified = deleted = untracked = conflicts = 0
|
||||
conflict_codes = {"DD", "AU", "UD", "UA", "DU", "AA", "UU"}
|
||||
for line in lines:
|
||||
if len(line) < 2:
|
||||
continue
|
||||
code = line[:2]
|
||||
if code == "??":
|
||||
untracked += 1
|
||||
continue
|
||||
if code in conflict_codes:
|
||||
conflicts += 1
|
||||
if code[0] not in {" ", "?"}:
|
||||
staged += 1
|
||||
if code[1] not in {" ", "?"}:
|
||||
modified += 1
|
||||
if "D" in code:
|
||||
deleted += 1
|
||||
return (
|
||||
"dirty "
|
||||
f"(staged={staged}, modified={modified}, deleted={deleted}, "
|
||||
f"untracked={untracked}, conflicts={conflicts})"
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class RepositoryState:
|
||||
root: str
|
||||
real_path: str
|
||||
branch: str
|
||||
head: str
|
||||
worktree: str
|
||||
active_processes: str = "None recorded."
|
||||
|
||||
|
||||
def repository_snapshot(root: Path, active_processes: str = "None recorded.") -> RepositoryState:
|
||||
git_root = Path(run_git(root, "rev-parse", "--show-toplevel").stdout.strip())
|
||||
real_path = git_root.resolve(strict=False)
|
||||
branch_result = run_git(root, "symbolic-ref", "--quiet", "--short", "HEAD", check=False)
|
||||
branch = branch_result.stdout.strip() if branch_result.returncode == 0 else "(detached)"
|
||||
head = run_git(root, "rev-parse", "HEAD").stdout.strip()
|
||||
return RepositoryState(
|
||||
root=str(git_root),
|
||||
real_path=str(real_path),
|
||||
branch=branch,
|
||||
head=head,
|
||||
worktree=worktree_summary(root),
|
||||
active_processes=clean_text(active_processes, "None recorded."),
|
||||
)
|
||||
|
||||
|
||||
@dataclass
|
||||
class AcceptanceCriterion:
|
||||
text: str
|
||||
checked: bool = False
|
||||
|
||||
|
||||
@dataclass
|
||||
class ScopeDelta:
|
||||
title: str
|
||||
source: str
|
||||
classification: str
|
||||
requirement: str
|
||||
evidence_valid: str
|
||||
invalidated_gates: str
|
||||
tracker_sync: str
|
||||
|
||||
|
||||
@dataclass
|
||||
class IntentionalFile:
|
||||
path: str
|
||||
reason: str
|
||||
|
||||
|
||||
@dataclass
|
||||
class GateRecord:
|
||||
gate: str
|
||||
status: str
|
||||
digest: str
|
||||
command: str
|
||||
date: str
|
||||
|
||||
|
||||
@dataclass
|
||||
class SessionState:
|
||||
repository: RepositoryState
|
||||
goal: str
|
||||
current_state: str = "Implementing"
|
||||
issues: str = "None."
|
||||
milestone: str = "None."
|
||||
active_slice: str = "None."
|
||||
non_goals: str = "None."
|
||||
acceptance: list[AcceptanceCriterion] = field(default_factory=list)
|
||||
deltas: list[ScopeDelta] = field(default_factory=list)
|
||||
files: list[IntentionalFile] = field(default_factory=list)
|
||||
gates: list[GateRecord] = field(default_factory=list)
|
||||
native_evidence: list[str] = field(default_factory=list)
|
||||
decisions: list[str] = field(default_factory=list)
|
||||
remote_actions: list[str] = field(default_factory=list)
|
||||
next_action: str = "Define the next action."
|
||||
|
||||
|
||||
def section_map(text: str) -> dict[str, list[str]]:
|
||||
sections: dict[str, list[str]] = {}
|
||||
current: str | None = None
|
||||
for line in text.splitlines():
|
||||
if line.startswith("## "):
|
||||
current = line[3:].strip()
|
||||
sections[current] = []
|
||||
elif current is not None:
|
||||
sections[current].append(line)
|
||||
return sections
|
||||
|
||||
|
||||
def field_value(lines: Iterable[str], name: str, default: str = "None.") -> str:
|
||||
prefix = f"- {name}:"
|
||||
for line in lines:
|
||||
if line.startswith(prefix):
|
||||
return clean_text(line[len(prefix) :], default)
|
||||
return default
|
||||
|
||||
|
||||
def bullet_values(lines: Iterable[str]) -> list[str]:
|
||||
values: list[str] = []
|
||||
for line in lines:
|
||||
if line.startswith("- ") and not line.startswith("- ["):
|
||||
value = clean_text(line[2:])
|
||||
if value != "None.":
|
||||
values.append(value)
|
||||
return values
|
||||
|
||||
|
||||
def parse_deltas(lines: list[str]) -> list[ScopeDelta]:
|
||||
chunks: list[tuple[str, list[str]]] = []
|
||||
title: str | None = None
|
||||
body: list[str] = []
|
||||
for line in lines:
|
||||
if line.startswith("### Delta "):
|
||||
if title is not None:
|
||||
chunks.append((title, body))
|
||||
heading = line.partition("—")[2].strip()
|
||||
title = heading or "Untitled scope delta"
|
||||
body = []
|
||||
elif title is not None:
|
||||
body.append(line)
|
||||
if title is not None:
|
||||
chunks.append((title, body))
|
||||
|
||||
return [
|
||||
ScopeDelta(
|
||||
title=clean_text(title),
|
||||
source=field_value(body, "Source"),
|
||||
classification=field_value(body, "Classification"),
|
||||
requirement=field_value(body, "Added/changed requirement"),
|
||||
evidence_valid=field_value(body, "Prior evidence still valid"),
|
||||
invalidated_gates=field_value(body, "Invalidated gates"),
|
||||
tracker_sync=field_value(body, "Tracker sync required", "no"),
|
||||
)
|
||||
for title, body in chunks
|
||||
]
|
||||
|
||||
|
||||
def parse_state(text: str) -> SessionState:
|
||||
if not text.startswith(TITLE):
|
||||
raise StateError(f"state file must begin with {TITLE!r}")
|
||||
sections = section_map(text)
|
||||
repository_lines = sections.get("Repository", [])
|
||||
task_lines = sections.get("Active task", [])
|
||||
repository = RepositoryState(
|
||||
root=field_value(repository_lines, "Root"),
|
||||
real_path=field_value(repository_lines, "Real path"),
|
||||
branch=field_value(repository_lines, "Branch"),
|
||||
head=field_value(repository_lines, "HEAD"),
|
||||
worktree=field_value(repository_lines, "Worktree status summary"),
|
||||
active_processes=field_value(repository_lines, "Active processes/windows", "None recorded."),
|
||||
)
|
||||
|
||||
acceptance: list[AcceptanceCriterion] = []
|
||||
for line in sections.get("Acceptance target", []):
|
||||
stripped = line.strip()
|
||||
if stripped.startswith("- [ ] "):
|
||||
acceptance.append(AcceptanceCriterion(clean_text(stripped[6:])))
|
||||
elif stripped.lower().startswith("- [x] "):
|
||||
acceptance.append(AcceptanceCriterion(clean_text(stripped[6:]), checked=True))
|
||||
|
||||
files: list[IntentionalFile] = []
|
||||
for value in bullet_values(sections.get("Files intentionally changed", [])):
|
||||
path, separator, reason = value.partition(" — ")
|
||||
files.append(IntentionalFile(path, reason if separator else "Reason not recorded."))
|
||||
|
||||
gates: list[GateRecord] = []
|
||||
for value in bullet_values(sections.get("Verification ledger summary", [])):
|
||||
parts = value.split(" — ", 4)
|
||||
if len(parts) == 5:
|
||||
gates.append(GateRecord(*parts))
|
||||
|
||||
next_values = bullet_values(sections.get("Exact next action", []))
|
||||
return SessionState(
|
||||
repository=repository,
|
||||
goal=field_value(task_lines, "Goal"),
|
||||
current_state=field_value(task_lines, "Current state", "Implementing"),
|
||||
issues=field_value(task_lines, "Gitea issue(s)"),
|
||||
milestone=field_value(task_lines, "Gitea milestone"),
|
||||
active_slice=field_value(task_lines, "Active slice"),
|
||||
non_goals=field_value(task_lines, "Non-goals"),
|
||||
acceptance=acceptance,
|
||||
deltas=parse_deltas(sections.get("Scope deltas", [])),
|
||||
files=files,
|
||||
gates=gates,
|
||||
native_evidence=bullet_values(sections.get("Native evidence", [])),
|
||||
decisions=bullet_values(sections.get("Decisions", [])),
|
||||
remote_actions=bullet_values(sections.get("Remote actions already performed", [])),
|
||||
next_action=next_values[0] if next_values else "Define the next action.",
|
||||
)
|
||||
|
||||
|
||||
def render_lines(state: SessionState) -> list[str]:
|
||||
lines = [
|
||||
TITLE,
|
||||
"",
|
||||
"## Repository",
|
||||
f"- Root: {clean_text(state.repository.root)}",
|
||||
f"- Real path: {clean_text(state.repository.real_path)}",
|
||||
f"- Branch: {clean_text(state.repository.branch)}",
|
||||
f"- HEAD: {clean_text(state.repository.head)}",
|
||||
f"- Worktree status summary: {clean_text(state.repository.worktree)}",
|
||||
f"- Active processes/windows: {clean_text(state.repository.active_processes, 'None recorded.')}",
|
||||
"",
|
||||
"## Active task",
|
||||
f"- Goal: {clean_text(state.goal)}",
|
||||
f"- Current state: {clean_text(state.current_state, 'Implementing')}",
|
||||
f"- Gitea issue(s): {clean_text(state.issues)}",
|
||||
f"- Gitea milestone: {clean_text(state.milestone)}",
|
||||
f"- Active slice: {clean_text(state.active_slice)}",
|
||||
f"- Non-goals: {clean_text(state.non_goals)}",
|
||||
"",
|
||||
"## Acceptance target",
|
||||
]
|
||||
lines.extend(
|
||||
f"- [{'x' if criterion.checked else ' '}] {clean_text(criterion.text)}"
|
||||
for criterion in state.acceptance
|
||||
)
|
||||
lines.extend(["", "## Scope deltas"])
|
||||
for index, delta in enumerate(state.deltas, start=1):
|
||||
lines.extend(
|
||||
[
|
||||
f"### Delta {index} — {clean_text(delta.title)}",
|
||||
f"- Source: {clean_text(delta.source)}",
|
||||
f"- Classification: {clean_text(delta.classification)}",
|
||||
f"- Added/changed requirement: {clean_text(delta.requirement)}",
|
||||
f"- Prior evidence still valid: {clean_text(delta.evidence_valid)}",
|
||||
f"- Invalidated gates: {clean_text(delta.invalidated_gates)}",
|
||||
f"- Tracker sync required: {clean_text(delta.tracker_sync, 'no')}",
|
||||
"",
|
||||
]
|
||||
)
|
||||
lines.extend(["## Files intentionally changed"])
|
||||
lines.extend(f"- {clean_text(item.path)} — {clean_text(item.reason)}" for item in state.files)
|
||||
lines.extend(["", "## Verification ledger summary"])
|
||||
lines.extend(
|
||||
f"- {clean_text(item.gate)} — {clean_text(item.status)} — {clean_text(item.digest)} — "
|
||||
f"{clean_text(item.command)} — {clean_text(item.date)}"
|
||||
for item in state.gates
|
||||
)
|
||||
lines.extend(["", "## Native evidence"])
|
||||
lines.extend(f"- {clean_text(item)}" for item in state.native_evidence)
|
||||
lines.extend(["", "## Decisions"])
|
||||
lines.extend(f"- {clean_text(item)}" for item in state.decisions)
|
||||
lines.extend(["", "## Remote actions already performed"])
|
||||
lines.extend(f"- {clean_text(item)}" for item in state.remote_actions)
|
||||
lines.extend(
|
||||
[
|
||||
"",
|
||||
"## Exact next action",
|
||||
f"- {clean_text(state.next_action, 'Define the next action.')}",
|
||||
]
|
||||
)
|
||||
return lines
|
||||
|
||||
|
||||
def compact_state(state: SessionState, limit: int) -> SessionState:
|
||||
"""Discard oldest ledger detail until the state fits its configured budget."""
|
||||
|
||||
compacted = copy.deepcopy(state)
|
||||
collections: list[tuple[list[Any], int]] = [
|
||||
(compacted.gates, 1),
|
||||
(compacted.native_evidence, 0),
|
||||
(compacted.remote_actions, 0),
|
||||
(compacted.decisions, 1),
|
||||
(compacted.deltas, 1),
|
||||
(compacted.files, 1),
|
||||
(compacted.acceptance, 1),
|
||||
]
|
||||
while len(render_lines(compacted)) > limit:
|
||||
for values, keep in collections:
|
||||
if len(values) > keep:
|
||||
values.pop(0)
|
||||
break
|
||||
else:
|
||||
raise StateError(
|
||||
f"required state structure exceeds session.max_state_lines={limit}"
|
||||
)
|
||||
return compacted
|
||||
|
||||
|
||||
def ensure_state_is_ignored(root: Path, path: Path) -> None:
|
||||
relative = path.resolve(strict=False).relative_to(root.resolve(strict=False)).as_posix()
|
||||
result = run_git(root, "check-ignore", "--quiet", "--", relative, check=False)
|
||||
if result.returncode != 0:
|
||||
raise StateError(
|
||||
f"refusing to write tracked session state; add /{relative} or its directory to .gitignore"
|
||||
)
|
||||
|
||||
|
||||
def write_state(root: Path, workflow: dict[str, Any], state: SessionState) -> Path:
|
||||
path = state_path(root, workflow)
|
||||
ensure_state_is_ignored(root, path)
|
||||
state = compact_state(state, max_state_lines(workflow))
|
||||
text = "\n".join(render_lines(state)) + "\n"
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
temporary: Path | None = None
|
||||
try:
|
||||
with tempfile.NamedTemporaryFile(
|
||||
"w",
|
||||
encoding="utf-8",
|
||||
dir=path.parent,
|
||||
prefix=f".{path.name}.",
|
||||
suffix=".tmp",
|
||||
delete=False,
|
||||
) as handle:
|
||||
handle.write(text)
|
||||
handle.flush()
|
||||
os.fsync(handle.fileno())
|
||||
temporary = Path(handle.name)
|
||||
os.replace(temporary, path)
|
||||
finally:
|
||||
if temporary is not None and temporary.exists():
|
||||
temporary.unlink()
|
||||
return path
|
||||
|
||||
|
||||
def read_state(root: Path, workflow: dict[str, Any]) -> SessionState:
|
||||
path = state_path(root, workflow)
|
||||
try:
|
||||
return parse_state(path.read_text(encoding="utf-8"))
|
||||
except FileNotFoundError as error:
|
||||
raise StateError(f"no session state exists at {path}; run state.py init") from error
|
||||
except OSError as error:
|
||||
raise StateError(f"cannot read session state {path}: {error}") from error
|
||||
|
||||
|
||||
def refresh_repository(root: Path, state: SessionState) -> list[str]:
|
||||
previous = state.repository
|
||||
current = repository_snapshot(root, previous.active_processes)
|
||||
changes: list[str] = []
|
||||
for label, before, after in (
|
||||
("real path", previous.real_path, current.real_path),
|
||||
("branch", previous.branch, current.branch),
|
||||
("HEAD", previous.head, current.head),
|
||||
):
|
||||
if before not in {"None.", after}:
|
||||
changes.append(f"{label}: {before} -> {after}")
|
||||
state.repository = current
|
||||
return changes
|
||||
|
||||
|
||||
def normalize_repo_file(root: Path, raw: str) -> str:
|
||||
candidate = Path(raw).expanduser()
|
||||
if not candidate.is_absolute():
|
||||
candidate = root / candidate
|
||||
candidate = candidate.resolve(strict=False)
|
||||
repository = root.resolve(strict=False)
|
||||
try:
|
||||
return candidate.relative_to(repository).as_posix()
|
||||
except ValueError as error:
|
||||
raise StateError(f"intentional file must be inside the repository: {candidate}") from error
|
||||
|
||||
|
||||
def replace_or_append_file(state: SessionState, path: str, reason: str) -> None:
|
||||
state.files = [item for item in state.files if item.path != path]
|
||||
state.files.append(IntentionalFile(path, clean_text(reason, "Reason not recorded.")))
|
||||
|
||||
|
||||
def replace_or_append_gate(state: SessionState, record: GateRecord) -> None:
|
||||
state.gates = [item for item in state.gates if item.gate != record.gate]
|
||||
state.gates.append(record)
|
||||
|
||||
|
||||
def candidate_commit(root: Path, revision: str) -> str:
|
||||
result = run_git(root, "rev-parse", "--verify", f"{revision}^{{commit}}", check=False)
|
||||
if result.returncode != 0:
|
||||
raise StateError(f"candidate revision is not a commit: {revision}")
|
||||
return result.stdout.strip()
|
||||
|
||||
|
||||
def git_bytes(root: Path, *arguments: str) -> bytes:
|
||||
try:
|
||||
result = subprocess.run(
|
||||
["git", "-C", str(root), *arguments],
|
||||
check=False,
|
||||
stdout=subprocess.PIPE,
|
||||
stderr=subprocess.PIPE,
|
||||
)
|
||||
except OSError as error:
|
||||
raise StateError(f"cannot execute git: {error}") from error
|
||||
if result.returncode != 0:
|
||||
detail = clean_text(result.stderr.decode("utf-8", "replace"), "git command failed")
|
||||
raise StateError(detail)
|
||||
return result.stdout
|
||||
|
||||
|
||||
def _dirty_tree_digest_once(root: Path) -> str:
|
||||
status_arguments = ("status", "--porcelain=v1", "-z", "--untracked-files=all")
|
||||
status_before = git_bytes(root, *status_arguments)
|
||||
if not status_before:
|
||||
raise StateError("--dirty-tree requires a dirty worktree")
|
||||
|
||||
digest = hashlib.sha256()
|
||||
digest.update(b"blacksite-dirty-tree-v1\0")
|
||||
digest.update(git_bytes(root, "rev-parse", "HEAD"))
|
||||
digest.update(b"\0status\0")
|
||||
digest.update(status_before)
|
||||
digest.update(b"\0tracked-diff\0")
|
||||
digest.update(
|
||||
git_bytes(
|
||||
root,
|
||||
"diff",
|
||||
"--binary",
|
||||
"--no-ext-diff",
|
||||
"--submodule=diff",
|
||||
"HEAD",
|
||||
"--",
|
||||
)
|
||||
)
|
||||
|
||||
untracked = git_bytes(root, "ls-files", "--others", "--exclude-standard", "-z")
|
||||
repository = root.resolve(strict=False)
|
||||
for encoded in sorted(path for path in untracked.split(b"\0") if path):
|
||||
relative = os.fsdecode(encoded)
|
||||
relative_path = Path(relative)
|
||||
if relative_path.is_absolute() or ".." in relative_path.parts:
|
||||
raise StateError(f"untracked candidate path escapes the repository: {relative}")
|
||||
path = repository / relative_path
|
||||
digest.update(b"\0untracked\0")
|
||||
digest.update(encoded)
|
||||
if path.is_symlink():
|
||||
digest.update(b"\0symlink\0")
|
||||
digest.update(os.fsencode(os.readlink(path)))
|
||||
elif path.is_file():
|
||||
digest.update(b"\0file\0")
|
||||
digest.update(str(path.stat().st_mode & 0o777).encode("ascii"))
|
||||
with path.open("rb") as handle:
|
||||
while chunk := handle.read(1024 * 1024):
|
||||
digest.update(chunk)
|
||||
else:
|
||||
digest.update(b"\0special\0")
|
||||
|
||||
if git_bytes(root, *status_arguments) != status_before:
|
||||
raise StateError("worktree changed while computing the candidate digest; nominate again")
|
||||
return digest.hexdigest()
|
||||
|
||||
|
||||
def dirty_tree_digest(root: Path) -> str:
|
||||
"""Hash an exact stable base commit, tracked diff, and untracked source set."""
|
||||
|
||||
first = _dirty_tree_digest_once(root)
|
||||
second = _dirty_tree_digest_once(root)
|
||||
if first != second:
|
||||
raise StateError("worktree changed while computing the candidate digest; nominate again")
|
||||
return first
|
||||
|
||||
|
||||
def build_parser() -> argparse.ArgumentParser:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
subparsers = parser.add_subparsers(dest="operation", required=True)
|
||||
|
||||
init = subparsers.add_parser("init", help="create a new compact session state")
|
||||
init.add_argument("--goal", required=True)
|
||||
init.add_argument("--accept", action="append", required=True, help="acceptance criterion; repeat as needed")
|
||||
init.add_argument("--slice", dest="active_slice", required=True)
|
||||
init.add_argument("--next", dest="next_action", required=True)
|
||||
init.add_argument("--non-goals", default="None.")
|
||||
init.add_argument("--issues", default="None.")
|
||||
init.add_argument("--milestone", default="None.")
|
||||
init.add_argument("--active-processes", default="None recorded.")
|
||||
init.add_argument("--force", action="store_true", help="replace an existing state")
|
||||
|
||||
show = subparsers.add_parser("show", help="print the current state")
|
||||
show.add_argument("--path", action="store_true", help="print only the state path")
|
||||
|
||||
subparsers.add_parser("resume", help="refresh repository identity and show the exact next action")
|
||||
|
||||
update = subparsers.add_parser("set", help="update active task fields")
|
||||
update.add_argument("--goal")
|
||||
update.add_argument("--state", choices=VALID_STATES)
|
||||
update.add_argument("--issues")
|
||||
update.add_argument("--milestone")
|
||||
update.add_argument("--slice", dest="active_slice")
|
||||
update.add_argument("--non-goals")
|
||||
update.add_argument("--next", dest="next_action")
|
||||
update.add_argument("--active-processes")
|
||||
update.add_argument("--accept", action="append", help="replace acceptance criteria; repeat as needed")
|
||||
update.add_argument("--decision", action="append", help="append a concise decision")
|
||||
|
||||
delta = subparsers.add_parser("scope-delta", help="record authoritative user steering")
|
||||
delta.add_argument("--title", required=True)
|
||||
delta.add_argument("--source", required=True)
|
||||
delta.add_argument("--classification", required=True)
|
||||
delta.add_argument("--requirement", required=True)
|
||||
delta.add_argument("--evidence-valid", required=True)
|
||||
delta.add_argument("--invalidated-gates", required=True)
|
||||
delta.add_argument("--tracker-sync", choices=("yes", "no"), required=True)
|
||||
delta.add_argument("--next", dest="next_action")
|
||||
|
||||
record_file = subparsers.add_parser("record-file", help="record an intentionally changed file")
|
||||
record_file.add_argument("path")
|
||||
record_file.add_argument("--reason", required=True)
|
||||
|
||||
record_gate = subparsers.add_parser("record-gate", help="record one compact verification result")
|
||||
record_gate.add_argument("--gate", required=True)
|
||||
record_gate.add_argument("--status", type=str.upper, choices=("PASS", "FAIL"), required=True)
|
||||
record_gate.add_argument("--digest", required=True)
|
||||
record_gate.add_argument("--command", required=True)
|
||||
record_gate.add_argument("--date", default=None)
|
||||
record_gate.add_argument("--next", dest="next_action")
|
||||
|
||||
nominate = subparsers.add_parser("nominate", help="nominate an exact candidate commit or tree digest")
|
||||
candidate = nominate.add_mutually_exclusive_group()
|
||||
candidate.add_argument("--commit", default="HEAD")
|
||||
candidate.add_argument(
|
||||
"--dirty-tree",
|
||||
action="store_true",
|
||||
help="explicitly nominate the current dirty tree by a reproducible digest",
|
||||
)
|
||||
nominate.add_argument("--next", dest="next_action")
|
||||
return parser
|
||||
|
||||
|
||||
def perform_operation(root: Path, workflow: dict[str, Any], args: argparse.Namespace) -> int:
|
||||
path = state_path(root, workflow)
|
||||
if args.operation == "init":
|
||||
if path.exists() and not args.force:
|
||||
raise StateError(f"session state already exists at {path}; use init --force to replace it")
|
||||
state = SessionState(
|
||||
repository=repository_snapshot(root, args.active_processes),
|
||||
goal=clean_text(args.goal),
|
||||
issues=clean_text(args.issues),
|
||||
milestone=clean_text(args.milestone),
|
||||
active_slice=clean_text(args.active_slice),
|
||||
non_goals=clean_text(args.non_goals),
|
||||
acceptance=[AcceptanceCriterion(clean_text(value)) for value in args.accept],
|
||||
next_action=clean_text(args.next_action),
|
||||
)
|
||||
write_state(root, workflow, state)
|
||||
print(f"PASS state-init — {path.relative_to(root.resolve(strict=False))}")
|
||||
print(f"NEXT {state.next_action}")
|
||||
return 0
|
||||
|
||||
if args.operation == "show":
|
||||
# Loading the file validates that it remains template-compatible.
|
||||
read_state(root, workflow)
|
||||
if args.path:
|
||||
print(path)
|
||||
else:
|
||||
print(path.read_text(encoding="utf-8"), end="")
|
||||
return 0
|
||||
|
||||
state = read_state(root, workflow)
|
||||
repository_changes = refresh_repository(root, state)
|
||||
|
||||
if args.operation == "resume":
|
||||
write_state(root, workflow, state)
|
||||
print(
|
||||
f"RESUME {state.current_state} — {state.repository.branch}@{state.repository.head[:12]} — "
|
||||
f"{state.goal}"
|
||||
)
|
||||
for change in repository_changes:
|
||||
print(f"REPOSITORY CHANGED {change}")
|
||||
print(f"NEXT {state.next_action}")
|
||||
return 0
|
||||
|
||||
if args.operation == "set":
|
||||
changed = False
|
||||
for argument, attribute in (
|
||||
("goal", "goal"),
|
||||
("state", "current_state"),
|
||||
("issues", "issues"),
|
||||
("milestone", "milestone"),
|
||||
("active_slice", "active_slice"),
|
||||
("non_goals", "non_goals"),
|
||||
("next_action", "next_action"),
|
||||
):
|
||||
value = getattr(args, argument)
|
||||
if value is not None:
|
||||
setattr(state, attribute, clean_text(value))
|
||||
changed = True
|
||||
if args.active_processes is not None:
|
||||
state.repository.active_processes = clean_text(args.active_processes, "None recorded.")
|
||||
changed = True
|
||||
if args.accept is not None:
|
||||
state.acceptance = [AcceptanceCriterion(clean_text(value)) for value in args.accept]
|
||||
changed = True
|
||||
if args.decision:
|
||||
state.decisions.extend(clean_text(value) for value in args.decision)
|
||||
changed = True
|
||||
if not changed:
|
||||
raise StateError("state.py set requires at least one field to update")
|
||||
|
||||
elif args.operation == "scope-delta":
|
||||
classification_key = clean_text(args.classification).lower()
|
||||
classification = CLASSIFICATIONS.get(classification_key)
|
||||
if classification is None:
|
||||
allowed = ", ".join(sorted(key for key in CLASSIFICATIONS if "-" in key))
|
||||
raise StateError(f"unknown scope-delta classification; use one of: {allowed}")
|
||||
state.deltas.append(
|
||||
ScopeDelta(
|
||||
title=clean_text(args.title),
|
||||
source=clean_text(args.source),
|
||||
classification=classification,
|
||||
requirement=clean_text(args.requirement),
|
||||
evidence_valid=clean_text(args.evidence_valid),
|
||||
invalidated_gates=clean_text(args.invalidated_gates),
|
||||
tracker_sync=args.tracker_sync,
|
||||
)
|
||||
)
|
||||
if classification == "added acceptance criterion":
|
||||
state.acceptance.append(AcceptanceCriterion(clean_text(args.requirement)))
|
||||
if args.next_action:
|
||||
state.next_action = clean_text(args.next_action)
|
||||
|
||||
elif args.operation == "record-file":
|
||||
relative = normalize_repo_file(root, args.path)
|
||||
replace_or_append_file(state, relative, args.reason)
|
||||
|
||||
elif args.operation == "record-gate":
|
||||
replace_or_append_gate(
|
||||
state,
|
||||
GateRecord(
|
||||
gate=clean_text(args.gate),
|
||||
status=args.status,
|
||||
digest=clean_text(args.digest),
|
||||
command=clean_text(args.command),
|
||||
date=clean_text(args.date or utc_now()),
|
||||
),
|
||||
)
|
||||
if args.next_action:
|
||||
state.next_action = clean_text(args.next_action)
|
||||
|
||||
elif args.operation == "nominate":
|
||||
if args.dirty_tree:
|
||||
digest = dirty_tree_digest(root)
|
||||
candidate_label = f"dirty-tree sha256:{digest} based on {state.repository.head}"
|
||||
else:
|
||||
if state.repository.worktree != "clean":
|
||||
raise StateError(
|
||||
"candidate nomination requires a clean worktree; use --dirty-tree to nominate an exact dirty-tree digest"
|
||||
)
|
||||
commit = candidate_commit(root, args.commit)
|
||||
candidate_label = f"commit {commit}"
|
||||
state.current_state = "Candidate-ready"
|
||||
state.decisions = [
|
||||
item for item in state.decisions if not item.startswith("Candidate nominated:")
|
||||
]
|
||||
state.decisions.append(f"Candidate nominated: {candidate_label} at {utc_now()}.")
|
||||
state.next_action = clean_text(
|
||||
args.next_action,
|
||||
f"Run candidate verification for {candidate_label}.",
|
||||
)
|
||||
else: # pragma: no cover - argparse prevents this
|
||||
raise StateError(f"unknown operation: {args.operation}")
|
||||
|
||||
write_state(root, workflow, state)
|
||||
relative = path.resolve(strict=False).relative_to(root.resolve(strict=False))
|
||||
print(f"PASS state-{args.operation} — {relative}")
|
||||
print(f"NEXT {state.next_action}")
|
||||
return 0
|
||||
|
||||
|
||||
def _git_fixture(root: Path) -> None:
|
||||
(root / ".codex").mkdir(parents=True)
|
||||
(root / ".codex/workflow.toml").write_text(
|
||||
"""version = 1
|
||||
[session]
|
||||
state_file = ".codex/session/STATE.md"
|
||||
max_state_lines = 70
|
||||
""",
|
||||
encoding="utf-8",
|
||||
)
|
||||
(root / ".gitignore").write_text("/.codex/session/\n", encoding="utf-8")
|
||||
(root / "tracked.txt").write_text("fixture\n", encoding="utf-8")
|
||||
env = dict(os.environ)
|
||||
env.update(
|
||||
{
|
||||
"GIT_AUTHOR_NAME": "Blacksite self-test",
|
||||
"GIT_AUTHOR_EMAIL": "self-test@example.invalid",
|
||||
"GIT_COMMITTER_NAME": "Blacksite self-test",
|
||||
"GIT_COMMITTER_EMAIL": "self-test@example.invalid",
|
||||
}
|
||||
)
|
||||
for command in (
|
||||
["git", "init", "--quiet", str(root)],
|
||||
["git", "-C", str(root), "add", "."],
|
||||
["git", "-C", str(root), "commit", "--quiet", "-m", "fixture"],
|
||||
):
|
||||
subprocess.run(command, check=True, env=env, stdout=subprocess.PIPE, stderr=subprocess.PIPE)
|
||||
|
||||
|
||||
def self_test() -> int:
|
||||
with tempfile.TemporaryDirectory(prefix="blacksite-state-self-test-") as temporary:
|
||||
root = Path(temporary)
|
||||
_git_fixture(root)
|
||||
found = find_repository(root / "nested")
|
||||
if found.resolve() != root.resolve():
|
||||
raise AssertionError("repository locator did not find the temporary workflow")
|
||||
workflow = load_workflow(found)
|
||||
parser = build_parser()
|
||||
|
||||
operations = [
|
||||
[
|
||||
"init",
|
||||
"--goal",
|
||||
"Exercise resumable state",
|
||||
"--accept",
|
||||
"State stays concise",
|
||||
"--slice",
|
||||
"Workflow helpers",
|
||||
"--next",
|
||||
"Update the fixture state.",
|
||||
],
|
||||
["set", "--state", "Engineering-complete", "--next", "Record steering."],
|
||||
[
|
||||
"scope-delta",
|
||||
"--title",
|
||||
"Self-test steering",
|
||||
"--source",
|
||||
"self-test",
|
||||
"--classification",
|
||||
"active-slice-refinement",
|
||||
"--requirement",
|
||||
"Keep the newest exact action",
|
||||
"--evidence-valid",
|
||||
"Earlier fixture setup remains valid",
|
||||
"--invalidated-gates",
|
||||
"None",
|
||||
"--tracker-sync",
|
||||
"no",
|
||||
"--next",
|
||||
"Record the intentional file.",
|
||||
],
|
||||
[
|
||||
"record-file",
|
||||
"scripts/codex/state.py",
|
||||
"--reason",
|
||||
"exercise file recording",
|
||||
],
|
||||
[
|
||||
"record-gate",
|
||||
"--gate",
|
||||
"state-fixture",
|
||||
"--status",
|
||||
"PASS",
|
||||
"--digest",
|
||||
"digest-fixture",
|
||||
"--command",
|
||||
"python state.py --self-test",
|
||||
"--next",
|
||||
"Resume the fixture.",
|
||||
],
|
||||
["resume"],
|
||||
["nominate", "--next", "Run the candidate fixture gate."],
|
||||
]
|
||||
for operation in operations:
|
||||
with contextlib.redirect_stdout(io.StringIO()):
|
||||
result = perform_operation(root, workflow, parser.parse_args(operation))
|
||||
if result != 0:
|
||||
raise AssertionError(f"state operation failed: {operation[0]}")
|
||||
|
||||
state = read_state(root, workflow)
|
||||
if state.current_state != "Candidate-ready":
|
||||
raise AssertionError("nominate did not enter Candidate-ready state")
|
||||
for index in range(12):
|
||||
state.gates.append(
|
||||
GateRecord(
|
||||
gate=f"gate-{index}",
|
||||
status="PASS",
|
||||
digest=f"digest-{index}",
|
||||
command=f"fixture {index}",
|
||||
date=utc_now(),
|
||||
)
|
||||
)
|
||||
state.next_action = "Nominate the fixture commit."
|
||||
path = write_state(root, workflow, state)
|
||||
lines = path.read_text(encoding="utf-8").splitlines()
|
||||
if len(lines) > max_state_lines(workflow):
|
||||
raise AssertionError("state exceeded configured line budget")
|
||||
resumed = read_state(root, workflow)
|
||||
if resumed.next_action != "Nominate the fixture commit.":
|
||||
raise AssertionError("state round-trip lost the exact next action")
|
||||
if resumed.repository.real_path != str(root.resolve()):
|
||||
raise AssertionError("state did not record the canonical repository path")
|
||||
commit = candidate_commit(root, "HEAD")
|
||||
if len(commit) != 40:
|
||||
raise AssertionError("candidate nomination did not resolve a commit")
|
||||
tracked = root / "tracked.txt"
|
||||
tracked.write_text("changed\n", encoding="utf-8")
|
||||
dirty_digest = dirty_tree_digest(root)
|
||||
if dirty_digest != dirty_tree_digest(root):
|
||||
raise AssertionError("dirty candidate digest is not deterministic")
|
||||
tracked.write_text("changed again\n", encoding="utf-8")
|
||||
if dirty_digest == dirty_tree_digest(root):
|
||||
raise AssertionError("dirty candidate digest ignored changed source bytes")
|
||||
tracked.write_text("fixture\n", encoding="utf-8")
|
||||
if worktree_summary(root) != "clean":
|
||||
raise AssertionError("ignored state unexpectedly dirtied the fixture repository")
|
||||
print("PASS state-self-test — temp repository lifecycle and line budget")
|
||||
return 0
|
||||
|
||||
|
||||
def main(argv: Sequence[str] | None = None) -> int:
|
||||
arguments = list(sys.argv[1:] if argv is None else argv)
|
||||
if arguments in (["--self-test"], ["self-test"]):
|
||||
try:
|
||||
return self_test()
|
||||
except (AssertionError, OSError, StateError, subprocess.SubprocessError) as error:
|
||||
print(f"FAIL state-self-test — {error}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
parser = build_parser()
|
||||
args = parser.parse_args(arguments)
|
||||
try:
|
||||
root = find_repository()
|
||||
workflow = load_workflow(root)
|
||||
return perform_operation(root, workflow, args)
|
||||
except StateError as error:
|
||||
print(f"FAIL state-{args.operation} — {error}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Executable
+469
@@ -0,0 +1,469 @@
|
||||
#!/usr/bin/env python3
|
||||
"""Run one command, retain its complete log, and print only a bounded result."""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import argparse
|
||||
import contextlib
|
||||
import io
|
||||
import json
|
||||
import os
|
||||
import re
|
||||
import shlex
|
||||
import subprocess
|
||||
import sys
|
||||
import tempfile
|
||||
import time
|
||||
import tomllib
|
||||
from collections import deque
|
||||
from datetime import datetime, timezone
|
||||
from pathlib import Path
|
||||
from typing import Any, Iterable, Sequence
|
||||
|
||||
|
||||
WORKFLOW_PATH = Path(".codex/workflow.toml")
|
||||
ANSI_RE = re.compile(r"\x1b\[[0-?]*[ -/]*[@-~]")
|
||||
ACTIONABLE_PATTERNS = (
|
||||
re.compile(r"^\s*error(?:\[[A-Z0-9]+\])?:", re.IGNORECASE),
|
||||
re.compile(r"^\s*error\b", re.IGNORECASE),
|
||||
re.compile(r"\bpanicked at\b", re.IGNORECASE),
|
||||
re.compile(r"^\s*thread .+ panicked", re.IGNORECASE),
|
||||
re.compile(r"^\s*Traceback \(most recent call last\):"),
|
||||
re.compile(r"^\s*(?:AssertionError|RuntimeError|ValueError|TypeError):"),
|
||||
re.compile(r"^\s*failures:\s*$", re.IGNORECASE),
|
||||
re.compile(r"^\s*test result: FAILED", re.IGNORECASE),
|
||||
re.compile(r"^\s*FAILED(?:\s|$)", re.IGNORECASE),
|
||||
re.compile(r"^\s*FAIL(?:\s|$)", re.IGNORECASE),
|
||||
re.compile(r"^\s*Caused by:\s*\S", re.IGNORECASE),
|
||||
)
|
||||
TEST_RESULT_RE = re.compile(
|
||||
r"test result: ok\.\s*(\d+) passed;\s*(\d+) failed;\s*(\d+) ignored",
|
||||
re.IGNORECASE,
|
||||
)
|
||||
SAFE_NAME_RE = re.compile(r"[^a-zA-Z0-9_.-]+")
|
||||
|
||||
|
||||
class SummaryError(RuntimeError):
|
||||
"""The wrapper cannot locate its configuration or output paths."""
|
||||
|
||||
|
||||
def find_repository(start: Path | None = None) -> Path:
|
||||
override = os.environ.get("BLACKSITE_WORKSPACE_ROOT")
|
||||
configured = None
|
||||
config_path = (start or Path.cwd()) / ".codex/config.toml"
|
||||
if not override and config_path.is_file():
|
||||
with config_path.open("rb") as handle:
|
||||
configured = tomllib.load(handle).get("workspace_root")
|
||||
candidates = [Path(override or configured)] if (override or configured) else [start or Path.cwd()]
|
||||
if start is None and not override:
|
||||
candidates.append(Path(__file__).parent)
|
||||
visited: set[Path] = set()
|
||||
for candidate in candidates:
|
||||
candidate = candidate.expanduser().absolute()
|
||||
for current in (candidate, *candidate.parents):
|
||||
canonical = current.resolve(strict=False)
|
||||
if canonical in visited:
|
||||
continue
|
||||
visited.add(canonical)
|
||||
if (current / WORKFLOW_PATH).is_file():
|
||||
return current
|
||||
searched = ", ".join(str(path) for path in candidates)
|
||||
raise SummaryError(f"could not locate {WORKFLOW_PATH} from {searched}")
|
||||
|
||||
|
||||
def load_workflow(root: Path) -> dict[str, Any]:
|
||||
path = root / WORKFLOW_PATH
|
||||
try:
|
||||
with path.open("rb") as handle:
|
||||
workflow = tomllib.load(handle)
|
||||
except OSError as error:
|
||||
raise SummaryError(f"cannot read workflow configuration {path}: {error}") from error
|
||||
except tomllib.TOMLDecodeError as error:
|
||||
raise SummaryError(f"invalid workflow configuration {path}: {error}") from error
|
||||
if workflow.get("version") != 1:
|
||||
raise SummaryError(f"unsupported or missing workflow version in {path}")
|
||||
return workflow
|
||||
|
||||
|
||||
def output_settings(workflow: dict[str, Any]) -> tuple[str, int]:
|
||||
output = workflow.get("output", {})
|
||||
if not isinstance(output, dict):
|
||||
raise SummaryError("[output] must be a TOML table")
|
||||
log_dir = output.get("log_dir", ".codex/logs")
|
||||
max_lines = output.get("max_failure_lines", 120)
|
||||
if not isinstance(log_dir, str) or not log_dir:
|
||||
raise SummaryError("output.log_dir must be a non-empty path string")
|
||||
if not isinstance(max_lines, int) or not 1 <= max_lines <= 1000:
|
||||
raise SummaryError("output.max_failure_lines must be an integer from 1 to 1000")
|
||||
return log_dir, max_lines
|
||||
|
||||
|
||||
def resolve_path(root: Path, raw: str) -> Path:
|
||||
path = Path(os.path.expandvars(os.path.expanduser(raw)))
|
||||
if not path.is_absolute():
|
||||
path = root / path
|
||||
return path.absolute()
|
||||
|
||||
|
||||
def relative_display(root: Path, path: Path) -> str:
|
||||
try:
|
||||
return path.relative_to(root.resolve(strict=False)).as_posix()
|
||||
except ValueError:
|
||||
return str(path)
|
||||
|
||||
|
||||
def safe_name(value: str) -> str:
|
||||
cleaned = SAFE_NAME_RE.sub("-", value.strip()).strip("-._")
|
||||
return cleaned[:80] or "command"
|
||||
|
||||
|
||||
def default_log_path(root: Path, log_dir: str, gate: str) -> Path:
|
||||
timestamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%S.%fZ")
|
||||
return resolve_path(root, str(Path(log_dir) / f"{timestamp}-{safe_name(gate)}.log"))
|
||||
|
||||
|
||||
def strip_ansi(value: str) -> str:
|
||||
return ANSI_RE.sub("", value).rstrip("\r\n")
|
||||
|
||||
|
||||
def duration_text(seconds: float) -> str:
|
||||
if seconds < 10:
|
||||
return f"{seconds:.2f}s"
|
||||
if seconds < 60:
|
||||
return f"{seconds:.1f}s"
|
||||
minutes, remainder = divmod(seconds, 60)
|
||||
return f"{int(minutes)}m {remainder:.0f}s"
|
||||
|
||||
|
||||
def is_actionable(line: str) -> bool:
|
||||
plain = strip_ansi(line)
|
||||
return any(pattern.search(plain) for pattern in ACTIONABLE_PATTERNS)
|
||||
|
||||
|
||||
def failure_excerpt(path: Path, limit: int) -> tuple[list[str], str | None]:
|
||||
"""Return bounded context around the first actionable failure.
|
||||
|
||||
The log is streamed rather than loaded wholesale, keeping the wrapper useful
|
||||
for very large compiler output.
|
||||
"""
|
||||
|
||||
before_count = min(12, max(0, limit // 4))
|
||||
before: deque[str] = deque(maxlen=before_count)
|
||||
excerpt: list[str] = []
|
||||
first_actionable: str | None = None
|
||||
matched = False
|
||||
|
||||
with path.open("r", encoding="utf-8", errors="replace") as handle:
|
||||
for raw_line in handle:
|
||||
line = strip_ansi(raw_line)
|
||||
if not matched:
|
||||
if is_actionable(line):
|
||||
matched = True
|
||||
first_actionable = line.strip() or None
|
||||
excerpt.extend(before)
|
||||
excerpt.append(line)
|
||||
else:
|
||||
before.append(line)
|
||||
elif len(excerpt) < limit:
|
||||
excerpt.append(line)
|
||||
else:
|
||||
break
|
||||
|
||||
if not matched:
|
||||
# With no recognizable error, the command's tail is normally the most
|
||||
# useful bounded evidence (signal termination, tool-specific errors).
|
||||
tail: deque[str] = deque(maxlen=limit)
|
||||
with path.open("r", encoding="utf-8", errors="replace") as handle:
|
||||
for raw_line in handle:
|
||||
tail.append(strip_ansi(raw_line))
|
||||
excerpt = list(tail)
|
||||
first_actionable = next((line.strip() for line in excerpt if line.strip()), None)
|
||||
|
||||
while excerpt and not excerpt[0].strip():
|
||||
excerpt.pop(0)
|
||||
while excerpt and not excerpt[-1].strip():
|
||||
excerpt.pop()
|
||||
return excerpt[:limit], first_actionable
|
||||
|
||||
|
||||
def success_summary(path: Path) -> str:
|
||||
last_nonempty = ""
|
||||
test_result: tuple[str, str, str] | None = None
|
||||
explicit_pass = ""
|
||||
with path.open("r", encoding="utf-8", errors="replace") as handle:
|
||||
for raw_line in handle:
|
||||
line = strip_ansi(raw_line).strip()
|
||||
if not line:
|
||||
continue
|
||||
last_nonempty = line
|
||||
match = TEST_RESULT_RE.search(line)
|
||||
if match:
|
||||
test_result = match.groups()
|
||||
if line.startswith("PASS "):
|
||||
explicit_pass = line
|
||||
if test_result is not None:
|
||||
passed, failed, ignored = test_result
|
||||
return f"{passed} passed, {failed} failed, {ignored} ignored"
|
||||
if explicit_pass:
|
||||
return explicit_pass[:240]
|
||||
if last_nonempty.startswith("Finished "):
|
||||
return last_nonempty[:240]
|
||||
return "exit 0"
|
||||
|
||||
|
||||
def write_result(path: Path, result: dict[str, Any]) -> None:
|
||||
path.parent.mkdir(parents=True, exist_ok=True)
|
||||
temporary: Path | None = None
|
||||
try:
|
||||
with tempfile.NamedTemporaryFile(
|
||||
"w",
|
||||
encoding="utf-8",
|
||||
dir=path.parent,
|
||||
prefix=f".{path.name}.",
|
||||
suffix=".tmp",
|
||||
delete=False,
|
||||
) as handle:
|
||||
json.dump(result, handle, indent=2, sort_keys=True)
|
||||
handle.write("\n")
|
||||
handle.flush()
|
||||
os.fsync(handle.fileno())
|
||||
temporary = Path(handle.name)
|
||||
os.replace(temporary, path)
|
||||
finally:
|
||||
if temporary is not None and temporary.exists():
|
||||
temporary.unlink()
|
||||
|
||||
|
||||
def normalized_exit_code(returncode: int) -> int:
|
||||
return 128 + abs(returncode) if returncode < 0 else returncode
|
||||
|
||||
|
||||
def execute(
|
||||
*,
|
||||
root: Path,
|
||||
workflow: dict[str, Any],
|
||||
gate: str,
|
||||
command: Sequence[str],
|
||||
log: Path | None = None,
|
||||
json_result: Path | None = None,
|
||||
cwd: Path | None = None,
|
||||
) -> int:
|
||||
if not command:
|
||||
raise SummaryError("a command is required after --")
|
||||
configured_log_dir, max_lines = output_settings(workflow)
|
||||
log_path = log or default_log_path(root, configured_log_dir, gate)
|
||||
result_path = json_result or log_path.with_suffix(log_path.suffix + ".json")
|
||||
if result_path == log_path:
|
||||
raise SummaryError("the JSON result path must differ from the full log path")
|
||||
command_cwd = cwd or Path.cwd()
|
||||
if not command_cwd.is_dir():
|
||||
raise SummaryError(f"command working directory does not exist: {command_cwd}")
|
||||
log_path.parent.mkdir(parents=True, exist_ok=True)
|
||||
|
||||
started_wall = datetime.now(timezone.utc)
|
||||
started = time.monotonic()
|
||||
returncode = 127
|
||||
launch_error: str | None = None
|
||||
interrupted = False
|
||||
with log_path.open("wb") as log_handle:
|
||||
try:
|
||||
process = subprocess.Popen(
|
||||
list(command),
|
||||
cwd=command_cwd,
|
||||
stdout=log_handle,
|
||||
stderr=subprocess.STDOUT,
|
||||
shell=False,
|
||||
)
|
||||
except OSError as error:
|
||||
launch_error = f"error: unable to execute {command[0]!r}: {error}"
|
||||
log_handle.write((launch_error + "\n").encode("utf-8", errors="replace"))
|
||||
else:
|
||||
try:
|
||||
returncode = normalized_exit_code(process.wait())
|
||||
except KeyboardInterrupt:
|
||||
interrupted = True
|
||||
process.terminate()
|
||||
try:
|
||||
process.wait(timeout=5)
|
||||
except subprocess.TimeoutExpired:
|
||||
process.kill()
|
||||
process.wait()
|
||||
returncode = 130
|
||||
log_handle.write(b"\nerror: command interrupted by user\n")
|
||||
|
||||
duration = time.monotonic() - started
|
||||
status = "PASS" if returncode == 0 else "FAIL"
|
||||
summary = success_summary(log_path) if returncode == 0 else "command failed"
|
||||
excerpt: list[str] = []
|
||||
actionable: str | None = launch_error
|
||||
if returncode != 0:
|
||||
excerpt, detected = failure_excerpt(log_path, max_lines)
|
||||
actionable = actionable or detected
|
||||
|
||||
result = {
|
||||
"schema_version": 1,
|
||||
"gate": gate,
|
||||
"status": status,
|
||||
"exit_code": returncode,
|
||||
"duration_seconds": round(duration, 6),
|
||||
"log": relative_display(root, log_path),
|
||||
"result": relative_display(root, result_path),
|
||||
"command": list(command),
|
||||
"command_display": shlex.join(command),
|
||||
"cwd": str(command_cwd.resolve(strict=False)),
|
||||
"started_at": started_wall.isoformat(timespec="seconds"),
|
||||
"finished_at": datetime.now(timezone.utc).isoformat(timespec="seconds"),
|
||||
"summary": summary,
|
||||
"first_actionable_failure": actionable,
|
||||
"interrupted": interrupted,
|
||||
}
|
||||
write_result(result_path, result)
|
||||
|
||||
if returncode == 0:
|
||||
print(f"PASS {gate} — {duration_text(duration)} — {summary}")
|
||||
else:
|
||||
print(f"FAIL {gate} — {duration_text(duration)}")
|
||||
for line in excerpt:
|
||||
print(line)
|
||||
print(f"Full log: {relative_display(root, log_path)}")
|
||||
return returncode
|
||||
|
||||
|
||||
def parse_arguments(argv: Sequence[str]) -> argparse.Namespace:
|
||||
parser = argparse.ArgumentParser(description=__doc__)
|
||||
parser.add_argument("--gate", required=True, help="short verification gate name")
|
||||
parser.add_argument("--json-result", help="machine-readable result path")
|
||||
parser.add_argument("--log", help="complete combined-output log path")
|
||||
parser.add_argument("--cwd", help="command working directory; defaults to the invocation directory")
|
||||
parser.add_argument("command", nargs=argparse.REMAINDER)
|
||||
args = parser.parse_args(argv)
|
||||
if args.command and args.command[0] == "--":
|
||||
args.command = args.command[1:]
|
||||
if not args.command:
|
||||
parser.error("a command is required after --")
|
||||
return args
|
||||
|
||||
|
||||
def self_test() -> int:
|
||||
with tempfile.TemporaryDirectory(prefix="blacksite-summary-self-test-") as temporary:
|
||||
root = Path(temporary)
|
||||
(root / ".codex").mkdir()
|
||||
(root / ".codex/workflow.toml").write_text(
|
||||
"""version = 1
|
||||
[output]
|
||||
log_dir = ".codex/logs"
|
||||
max_failure_lines = 4
|
||||
""",
|
||||
encoding="utf-8",
|
||||
)
|
||||
nested = root / "nested"
|
||||
nested.mkdir()
|
||||
found = find_repository(nested)
|
||||
workflow = load_workflow(found)
|
||||
parsed = parse_arguments(
|
||||
[
|
||||
"--gate",
|
||||
"parser-fixture",
|
||||
"--json-result",
|
||||
".codex/logs/parser.json",
|
||||
"--",
|
||||
sys.executable,
|
||||
"--version",
|
||||
]
|
||||
)
|
||||
if parsed.command != [sys.executable, "--version"]:
|
||||
raise AssertionError("command arguments after -- were not preserved")
|
||||
|
||||
success_log = root / ".codex/logs/success.log"
|
||||
success_json = root / ".codex/logs/success.json"
|
||||
captured = io.StringIO()
|
||||
with contextlib.redirect_stdout(captured):
|
||||
success = execute(
|
||||
root=root,
|
||||
workflow=workflow,
|
||||
gate="self-test-pass",
|
||||
command=[
|
||||
sys.executable,
|
||||
"-c",
|
||||
"print('test result: ok. 3 passed; 0 failed; 1 ignored')",
|
||||
],
|
||||
log=success_log,
|
||||
json_result=success_json,
|
||||
cwd=root,
|
||||
)
|
||||
if success != 0:
|
||||
raise AssertionError("successful fixture returned a failure")
|
||||
if not captured.getvalue().startswith("PASS self-test-pass"):
|
||||
raise AssertionError("successful fixture did not emit a compact PASS summary")
|
||||
success_data = json.loads(success_json.read_text(encoding="utf-8"))
|
||||
for key in ("status", "exit_code", "duration_seconds", "log"):
|
||||
if key not in success_data:
|
||||
raise AssertionError(f"result JSON omitted required key {key}")
|
||||
if success_data["status"] != "PASS" or success_data["exit_code"] != 0:
|
||||
raise AssertionError("successful result JSON is incorrect")
|
||||
|
||||
failure_log = root / ".codex/logs/failure.log"
|
||||
failure_json = root / ".codex/logs/failure.json"
|
||||
captured = io.StringIO()
|
||||
with contextlib.redirect_stdout(captured):
|
||||
failure = execute(
|
||||
root=root,
|
||||
workflow=workflow,
|
||||
gate="self-test-fail",
|
||||
command=[
|
||||
sys.executable,
|
||||
"-c",
|
||||
"print('noise'); print('error[E0001]: actionable'); print('detail'); raise SystemExit(7)",
|
||||
],
|
||||
log=failure_log,
|
||||
json_result=failure_json,
|
||||
cwd=root,
|
||||
)
|
||||
if failure != 7:
|
||||
raise AssertionError("failing fixture did not preserve exit code 7")
|
||||
visible_lines = captured.getvalue().splitlines()
|
||||
if not visible_lines or not visible_lines[0].startswith("FAIL self-test-fail"):
|
||||
raise AssertionError("failing fixture did not emit a compact FAIL summary")
|
||||
if len(visible_lines[1:-1]) > 4:
|
||||
raise AssertionError("failure excerpt exceeded output.max_failure_lines")
|
||||
failure_data = json.loads(failure_json.read_text(encoding="utf-8"))
|
||||
if failure_data["status"] != "FAIL" or failure_data["exit_code"] != 7:
|
||||
raise AssertionError("failure result JSON is incorrect")
|
||||
if "error[E0001]" not in failure_log.read_text(encoding="utf-8"):
|
||||
raise AssertionError("full failure output was not captured")
|
||||
print("PASS summarize-command-self-test — logs, bounded failure, JSON, exit preservation")
|
||||
return 0
|
||||
|
||||
|
||||
def main(argv: Sequence[str] | None = None) -> int:
|
||||
arguments = list(sys.argv[1:] if argv is None else argv)
|
||||
if arguments in (["--self-test"], ["self-test"]):
|
||||
try:
|
||||
return self_test()
|
||||
except (AssertionError, OSError, SummaryError, subprocess.SubprocessError, json.JSONDecodeError) as error:
|
||||
print(f"FAIL summarize-command-self-test — {error}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
try:
|
||||
args = parse_arguments(arguments)
|
||||
root = find_repository()
|
||||
workflow = load_workflow(root)
|
||||
log = resolve_path(root, args.log) if args.log else None
|
||||
result = resolve_path(root, args.json_result) if args.json_result else None
|
||||
cwd = resolve_path(root, args.cwd) if args.cwd else Path.cwd()
|
||||
return execute(
|
||||
root=root,
|
||||
workflow=workflow,
|
||||
gate=args.gate,
|
||||
command=args.command,
|
||||
log=log,
|
||||
json_result=result,
|
||||
cwd=cwd,
|
||||
)
|
||||
except (OSError, SummaryError) as error:
|
||||
print(f"FAIL summarize-command — {error}", file=sys.stderr)
|
||||
return 2
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
raise SystemExit(main())
|
||||
Executable
+1167
File diff suppressed because it is too large.
Load diff
Reference in new issue
Block a user