Skip to content

OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security

refactor: clarify Python contracts and simplify scan recovery and reporting (#2340)

Michael D'Angelo5c0be2444b47
diff --git a/.github/scripts/require_native_python_report.py b/.github/scripts/require_native_python_report.py
index 54e04ff40..69fab17fc 100644
--- a/.github/scripts/require_native_python_report.py
+++ b/.github/scripts/require_native_python_report.py
@@ -1,3 +1,5 @@
+"""Require at least one test case and zero skipped cases in reports/python.xml."""
+
from xml.etree import ElementTree
report = ElementTree.parse("reports/python.xml")
diff --git a/.github/scripts/test_require_native_python_report.py b/.github/scripts/test_require_native_python_report.py
index 2b1e3b0ff..62757ef3a 100644
--- a/.github/scripts/test_require_native_python_report.py
+++ b/.github/scripts/test_require_native_python_report.py
@@ -1,3 +1,5 @@
+"""Exercise the native-test CI gate with missing, malformed, skipped, and passing reports."""
+
from contextlib import nullcontext
from pathlib import Path
from runpy import run_path
diff --git a/docker/wolfi/payload/stage.py b/docker/wolfi/payload/stage.py
index c8ed6f8da..3b632eb28 100644
--- a/docker/wolfi/payload/stage.py
+++ b/docker/wolfi/payload/stage.py
@@ -47,6 +47,7 @@ def read_json(path):
def matches_target(package):
+ """Return whether the npm package permits the target OS, CPU, and libc."""
for key, target in TARGET.items():
values = package.get(key, [])
allowed = [v for v in values if not v.startswith("!")]
@@ -56,6 +57,7 @@ def matches_target(package):
def source_url(pkg):
+ """Return the canonical HTTPS GitHub repository URL, raising ValueError on unfamiliar metadata."""
repo = pkg.get("repository")
raw = repo.get("url") if isinstance(repo, dict) else repo
# npm accepts both GitHub shorthand and conventional git URLs. Do not
@@ -67,6 +69,7 @@ def source_url(pkg):
def select_scanner_payload(app):
+ """Prune voice assets and off-target MCP binaries in place, checking the remaining Codex files."""
# Voice belongs to the interactive client, not repository scanning. The
# MCP server uses Node's target (Linux x64 glibc), while the Codex executable
# itself is the upstream static musl build.
@@ -86,6 +89,16 @@ def select_scanner_payload(app):
def write_attributions(root, app, wanted):
+ """Write upstream notices and the source inventory into the staged license directory.
+
+ Args:
+ root (Path): Staged filesystem containing the license directory.
+ app (Path): Directory containing the installed npm packages.
+ wanted (dict): Target-specific lock records keyed by installed package path.
+
+ Raises:
+ ValueError: A notice, declared license, or source falls outside the reviewed set.
+ """
license_dir = root / LICENSE_DIR
notices = read_json(HERE / "notices/sources.json")
for name, item in notices.items():
@@ -137,6 +150,15 @@ def write_attributions(root, app, wanted):
def stage_root(root):
+ """Stage the locked scanner runtime and return its count of target npm packages.
+
+ Args:
+ root (Path): Scratch filesystem root with space for a new runtime tree.
+ A failed installation or verification can leave partial files here.
+
+ SCANNER_RUNTIME_LOCK selects an alternate lock, and SCANNER_TARBALL supplies
+ a local release archive in place of the registry's scanner package.
+ """
app = root / INSTALL
app.mkdir(parents=True)
lock_path = Path(os.environ.get("SCANNER_RUNTIME_LOCK") or HERE / "package-lock.json")
@@ -204,6 +226,7 @@ def stage_root(root):
def normalize(entry):
+ """Set reproducible ownership, timestamp, and mode on a tar member and return it to tarfile."""
if not (entry.isdir() or entry.isreg() or entry.issym()):
raise ValueError(f"Unexpected file type: {entry.name}")
entry.uid = entry.gid = entry.mtime = 0
@@ -213,6 +236,7 @@ def normalize(entry):
def main():
+ """Publish payload.tar.gz and print its package count and the digest of the uncompressed tar."""
args = argparse.ArgumentParser(description=__doc__)
args.add_argument("stage", type=Path, help="melange --source-dir (only payload.tar.gz will be written)")
output = args.parse_args().stage.resolve()
diff --git a/docker/wolfi/release-sbom.py b/docker/wolfi/release-sbom.py
index 3130a7585..548f7652d 100644
--- a/docker/wolfi/release-sbom.py
+++ b/docker/wolfi/release-sbom.py
@@ -9,6 +9,18 @@ from urllib.parse import quote
def enrich(sbom, components):
+ """Add installed npm packages, bundled tokenizer libraries, and native files to an SPDX document.
+
+ Args:
+ sbom (dict): apko's single-image SPDX document, updated in place.
+ components (dict): public-components.json inventory produced for the same image.
+
+ Returns:
+ dict: The input document with containment relationships and a new document namespace.
+
+ Raises:
+ ValueError: The image manifest in the inventory differs from the one in the SBOM.
+ """
packages = sbom["packages"]
image, = (p for p in packages if p["SPDXID"] in sbom["documentDescribes"])
if image["name"] != components["image_manifest"]:
diff --git a/docker/wolfi/snapshot-builder.py b/docker/wolfi/snapshot-builder.py
index 601c77a61..4481c3c98 100644
--- a/docker/wolfi/snapshot-builder.py
+++ b/docker/wolfi/snapshot-builder.py
@@ -14,11 +14,23 @@ REPO = "https://packages.wolfi.dev/os/" + ARCH
class NoRedirect(HTTPRedirectHandler):
+ """Keep the APK downloader on the exact URLs recorded in the builder lock."""
+
def redirect_request(self, *args):
return None # Only fetch the exact URLs in the lock.
def stage_package(pkg, directory, fetch):
+ """Write one APK into the staging directory, checking each locked byte range.
+
+ Args:
+ pkg (dict): Package record from the apko lock, including component checksums.
+ directory (Path): Existing staging directory for x86_64 APKs.
+ fetch (callable): Open the package URL with a timeout and return a binary stream.
+
+ Raises:
+ ValueError: The source, architecture, byte ranges, or digests differ from the lock.
+ """
name, version = pkg["name"], pkg["version"]
filename = f"{name}-{version}.apk"
if not all(re.fullmatch(r"[a-zA-Z0-9][a-zA-Z0-9.+_~-]*", s) for s in (name, version)):
@@ -47,6 +59,16 @@ def stage_package(pkg, directory, fetch):
def snapshot(lock, output, fetch):
+ """Publish the locked APKs under output/x86_64 after every package verifies.
+
+ Args:
+ lock (dict): Nonempty apko v1 builder lock.
+ output (Path): New or empty repository directory.
+ fetch (callable): URL opener passed to stage_package for each locked package.
+
+ Raises:
+ ValueError: The lock or destination is invalid, or a package fails verification.
+ """
if lock["version"] != "v1" or not lock["contents"]["packages"]:
raise ValueError("Expected a nonempty apko v1 builder lock")
output.mkdir(parents=True, exist_ok=True)
diff --git a/docker/wolfi/tests/test_snapshot_builder.py b/docker/wolfi/tests/test_snapshot_builder.py
index 84bb3acf7..79a6260eb 100644
--- a/docker/wolfi/tests/test_snapshot_builder.py
+++ b/docker/wolfi/tests/test_snapshot_builder.py
@@ -1,3 +1,5 @@
+"""Exercise snapshot publication against signed, unsigned, and corrupted APK byte streams."""
+
import base64
import gzip
import hashlib
@@ -11,6 +13,7 @@ snapshot = runpy.run_path(str(Path(__file__).resolve().parents[1] / "snapshot-bu
def fixture(name, signed):
+ """Return an apko lock record and the matching gzip members for one synthetic APK."""
# APK v2 stores consecutive, independently compressed gzip members.
url = f"https://packages.wolfi.dev/os/x86_64/{name}-1-r0.apk"
pkg = {"name": name, "version": "1-r0", "url": url, "architecture": "x86_64"}
@@ -28,6 +31,8 @@ def fixture(name, signed):
class SnapshotTest(unittest.TestCase):
+ """Stage packages in a temporary directory using an in-memory URL opener."""
+
def setUp(self):
self.first, self.a = fixture("first", signed=False)
self.second, self.b = fixture("second", signed=True)
diff --git a/docker/wolfi/tests/test_tokenizer_inventory.py b/docker/wolfi/tests/test_tokenizer_inventory.py
index ff769926b..81c91802c 100644
--- a/docker/wolfi/tests/test_tokenizer_inventory.py
+++ b/docker/wolfi/tests/test_tokenizer_inventory.py
@@ -1,3 +1,5 @@
+"""Check bundled tokenizer component identities and the legacy npm dependency fallback."""
+
import json
import runpy
import unittest
diff --git a/docker/wolfi/to-oci.py b/docker/wolfi/to-oci.py
index 1d7ad00ba..7fa08cabb 100644
--- a/docker/wolfi/to-oci.py
+++ b/docker/wolfi/to-oci.py
@@ -15,6 +15,19 @@ from pathlib import Path
def convert(archive, verification, destination):
+ """Verify each image blob before publishing a new OCI layout.
+
+ Args:
+ archive (Path): Uncompressed, single-platform apko image tar.
+ verification (Path): Matching verification.json from the verified release.
+ destination (Path): New layout directory under an existing parent.
+
+ Returns:
+ str: OCI manifest digest, including the sha256 prefix.
+
+ Raises:
+ ValueError: The destination exists or an archive verification check fails.
+ """
if destination.exists() or destination.is_symlink():
raise ValueError(f"Destination already exists: {destination}")
expected = json.loads(verification.read_bytes())
@@ -34,6 +47,7 @@ def convert(archive, verification, destination):
return m
def copy_blob(name, desc):
+ """Write a blob into the layout, verify its size and SHA-256, and return its staged path."""
digest = desc["digest"]
if not re.fullmatch(r"sha256:[0-9a-f]{64}", digest):
raise ValueError(f"Invalid blob digest: {digest}")
diff --git a/docker/wolfi/verify-public.py b/docker/wolfi/verify-public.py
index bd50cb2aa..74802e224 100644
--- a/docker/wolfi/verify-public.py
+++ b/docker/wolfi/verify-public.py
@@ -25,10 +25,12 @@ GPL-2.0-only GPL-2.0-or-later GPL-3.0-or-later LGPL-2.0-or-later LGPL-2.1 LGPL-2
LGPL-2.1-or-later LGPL-3.0-or-later GCC-exception-3.1 libselinux-1.0 blessing CC-PDDC AND OR WITH""".split())
def check(ok, message):
+ """Exit with the supplied verification message when a release invariant fails."""
if not ok:
raise SystemExit(message)
def check_license(name, expression):
+ """Exit if the declared expression is empty or contains an unreviewed license term."""
terms = set(re.findall(r"[\w.+-]+", expression or ""))
check(terms and not (terms - LICENSES), f"Unreviewed license for {name}: {expression}")
@@ -46,10 +48,12 @@ class HashingReader:
@property
def digest(self):
+ """Return the OCI-style SHA-256 digest of the bytes read so far."""
return "sha256:" + self.hash.hexdigest()
def read_blob(tar, descriptor):
+ """Return a parsed OCI JSON blob after checking its byte length and SHA-256."""
data = tar.extractfile(descriptor["digest"]).read()
check(len(data) == descriptor["size"] and "sha256:" + hashlib.sha256(data).hexdigest() == descriptor["digest"],
f"OCI blob does not match descriptor: {descriptor['digest']}")
@@ -57,6 +61,19 @@ def read_blob(tar, descriptor):
def inspect_layer(fs):
+ """Collect release evidence in one pass through the root filesystem.
+
+ Args:
+ fs (tarfile.TarFile): Open layer tar positioned for streaming reads.
+
+ Returns:
+ tuple: Raw package metadata by image path, npm manifests by install path,
+ public APK keys by filename, and native file SHA-256 hashes by image path.
+
+ Raises:
+ SystemExit: The layer contains a melange.rsa file name or a non-file APK key,
+ or lacks a regular entrypoint executable by the configured runtime user.
+ """
raw, manifests, keys, native = {}, {}, {}, {}
executable = False
for ent in fs:
@@ -84,6 +101,7 @@ def inspect_layer(fs):
def inventory_apks(database, packages):
+ """Return installed APK records sorted by name after checking them against the lock."""
apks = []
lock = {p["name"]:p for p in packages}
for record in database.decode().strip().split("\n\n"):
@@ -102,6 +120,7 @@ def inventory_apks(database, packages):
def inventory_npm(manifests, packages, sources):
+ """Match manifests to lockfile and attribution entries by install path and return the npm inventory."""
paths = {p["path"] for p in sources}
check(len(paths) == len(sources) and paths == manifests.keys(),
"Installed npm package paths differ from SOURCES.json")
@@ -125,6 +144,12 @@ def inventory_npm(manifests, packages, sources):
def inventory_tokenizer(manifests, bom):
+ """Return the bundled tokenizer's verified CycloneDX components.
+
+ When a legacy image has no tokenizer BOM, verify that the installed
+ js-tiktoken package matches the SDK dependency pin. Return an empty list
+ because the npm inventory already includes that installation.
+ """
scanner = manifests[SCANNER]
if bom is None:
# Older releases installed the pinned tokenizer as an ordinary npm dependency.
@@ -151,6 +176,18 @@ def inventory_tokenizer(manifests, bom):
def verify(archive, lock):
+ """Verify a local Linux/amd64 image and assemble its two release reports.
+
+ Args:
+ archive (Path): The apko image tar containing Docker and OCI manifests.
+ lock (dict): The apko lock contents with the expected packages and keyring.
+
+ Returns:
+ dict: Report payloads keyed by verification.json and public-components.json.
+
+ Raises:
+ SystemExit: An explicit image, package, or source verification check fails.
+ """
with tarfile.open(archive) as tar:
manifest, = json.load(tar.extractfile("manifest.json"))
index, = json.load(tar.extractfile("index.json"))["manifests"]
diff --git a/plugins/codex-security/mcp-app/tests/clock_workbench.py b/plugins/codex-security/mcp-app/tests/clock_workbench.py
index 5225c226d..b306e0d42 100644
--- a/plugins/codex-security/mcp-app/tests/clock_workbench.py
+++ b/plugins/codex-security/mcp-app/tests/clock_workbench.py
@@ -1,4 +1,8 @@
-"""Control the workbench clock while retaining its real commands and database writes."""
+"""Run a workbench command at TEST_WORKBENCH_NOW against its real database.
+
+The first argument selects the workbench script. When TEST_WORKBENCH_RECEIPT_IO_FAILURE
+is set, replacing an acceptance receipt raises ENOSPC so tests can observe recovery.
+"""
import errno
import os
diff --git a/plugins/codex-security/scripts/deep_scan_config.py b/plugins/codex-security/scripts/deep_scan_config.py
index a0e200ac5..3ee192f54 100644
--- a/plugins/codex-security/scripts/deep_scan_config.py
+++ b/plugins/codex-security/scripts/deep_scan_config.py
@@ -34,12 +34,14 @@ CONFIG_KEYS = set(CONFIG_FIELDS.values())
def codex_home() -> Path:
+ """Expand CODEX_HOME, falling back to ~/.codex when the setting is empty or whitespace."""
return Path(
os.environ["CODEX_HOME"] if os.environ.get("CODEX_HOME", "").strip() else "~/.codex"
).expanduser()
def config_path() -> Path:
+ """Return the configured TOML path or the per-user config.toml under the Codex home."""
configured = os.environ.get("CODEX_SECURITY_DEEP_SCAN_CONFIG_PATH", "").strip()
if configured:
return Path(configured).expanduser()
@@ -47,12 +49,28 @@ def config_path() -> Path:
def resolve_deep_scan_config(available_parallelism: int) -> dict[str, int | float]:
+ """Return the numeric deep scan settings for a launch with no project overrides."""
return resolve_deep_scan_setup(available_parallelism)["settings"]
def resolve_deep_scan_setup(
available_parallelism: int, project_json: str | None = None
) -> dict[str, Any]:
+ """Resolve project overrides, per-user TOML settings, and bundled defaults in that order.
+
+ Args:
+ available_parallelism (int): Positive parallelism reported by the caller.
+ The configured worker count is independent of this value.
+ project_json (str | None): Serialized project configuration with path and settings keys.
+
+ Returns:
+ dict: Numeric settings and a source label for each, plus the paths of the
+ supplied project configuration and any existing per-user configuration.
+
+ Raises:
+ SystemExit: A selected setting is invalid or a required TOML file cannot be read.
+ json.JSONDecodeError: The supplied project JSON cannot be parsed.
+ """
project = json.loads(project_json) if project_json is not None else None
overrides = project["settings"] if project is not None else {}
unknown = sorted(set(overrides) - set(CONFIG_FIELDS))
@@ -106,6 +124,7 @@ def resolve_deep_scan_setup(
def require_integer(value: object, label: str, *, minimum: int) -> int:
+ """Return an integer at least minimum, accepting integral floats and raising SystemExit for invalid counts."""
if isinstance(value, float) and value.is_integer():
value = int(value)
if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
@@ -121,6 +140,7 @@ def require_integer(value: object, label: str, *, minimum: int) -> int:
def require_positive_number(value: object, label: str) -> int | float:
+ """Return a duration in hours, raising SystemExit unless it falls in (0, 96]."""
if isinstance(value, bool) or not isinstance(value, (int, float)):
raise SystemExit(f"{label} must be a positive finite number no greater than 96.")
if not 0 < value <= MAX_TIME_HOURS:
diff --git a/plugins/codex-security/scripts/deep_scan_workbench.py b/plugins/codex-security/scripts/deep_scan_workbench.py
index e2fb2e18d..635963ca3 100644
--- a/plugins/codex-security/scripts/deep_scan_workbench.py
+++ b/plugins/codex-security/scripts/deep_scan_workbench.py
@@ -42,6 +42,7 @@ def dependencies() -> Any:
def deep_scan_error(run: sqlite3.Row) -> str | None:
+ """Return recorded error messages, publication error first, or None if both are absent."""
original = run["error_message"]
publication = run["publication_error_message"]
if not isinstance(publication, str):
@@ -68,6 +69,7 @@ def require_deep_scan_run(connection: sqlite3.Connection, scan_id: str) -> sqlit
def deep_scan_deadline_reached(run: sqlite3.Row) -> bool:
+ """Return whether the time since run creation has reached its configured limit in hours."""
elapsed = _parse_timestamp(dependencies().now()) - _parse_timestamp(str(run["created_at"]))
return elapsed.total_seconds() / 3600 >= run["max_time_hours"]
@@ -75,6 +77,11 @@ def deep_scan_deadline_reached(run: sqlite3.Row) -> bool:
def require_deep_scan_ready_for_parent_completion(
connection: sqlite3.Connection, scan: sqlite3.Row
) -> None:
+ """Require a succeeded discovery run with a saved manifest before a Deep Scan completes.
+
+ For a capped run, also verify its workers have finished. Raise SystemExit
+ when a completion requirement fails. Other scan modes can complete directly.
+ """
if scan["mode"] != "deep":
return
run = connection.execute(
@@ -169,6 +176,7 @@ def require_deep_scan_workers_finished(
def require_owned_scan(
connection: sqlite3.Connection, scan_id: str, thread_id: str
) -> tuple[sqlite3.Row, sqlite3.Row]:
+ """Return the scan and workspace rows or raise SystemExit unless thread_id matches the recorded owner."""
scan = dependencies().require_scan(connection, scan_id)
workspace = dependencies().require_workspace(connection, scan["workspace_id"])
owner = optional_text(thread_id, maximum=512)
@@ -187,6 +195,7 @@ def deep_scan_path(
*,
kind: str,
) -> str:
+ """Return the canonical absolute path to an existing scan-local file or directory of the requested kind."""
supplied = Path(value).expanduser()
if not supplied.is_absolute():
raise SystemExit(f"{label} must be an absolute path inside the scan directory.")
@@ -206,6 +215,7 @@ def deep_scan_path(
def deep_scan_output_path(scan: sqlite3.Row, value: str, label: str) -> str:
+ """Validate an absolute output path under the scan directory, allowing a new file under an existing parent."""
supplied = Path(value).expanduser()
if not supplied.is_absolute():
raise SystemExit(f"{label} must be an absolute path inside the scan directory.")
@@ -219,6 +229,7 @@ def deep_scan_output_path(scan: sqlite3.Row, value: str, label: str) -> str:
def promote_staged_file(staged_path: str, output_path: str) -> tuple[Path, Path, Path | None]:
+ """Publish the staged file and return the paths needed to finalize or undo the move."""
staged = Path(staged_path)
output = Path(output_path)
if staged == output:
@@ -236,6 +247,7 @@ def promote_staged_file(staged_path: str, output_path: str) -> tuple[Path, Path,
def rollback_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:
+ """Move the published file back to staging and restore the previous output if present."""
staged, output, backup = promotion
if output.exists():
os.replace(output, staged)
@@ -244,12 +256,14 @@ def rollback_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:
def finish_staged_file(promotion: tuple[Path, Path, Path | None]) -> None:
+ """Remove the previous output saved during promotion."""
backup = promotion[2]
if backup is not None:
backup.unlink(missing_ok=True)
def publication_matches_snapshot(publication: Path, snapshot: Path) -> bool:
+ """Return whether the publication and snapshot identify the same file or contain identical bytes."""
try:
if publication.samefile(snapshot):
return True
@@ -279,6 +293,11 @@ def canonical_discovery_artifacts(scan: sqlite3.Row) -> dict[str, str]:
def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, Any]:
+ """Return persisted orchestration state including settings, workers, artifacts, and deduplication inputs.
+
+ Order workers by creation time and ID. Retain the recorded order of each
+ deduplication worker’s discovery inputs.
+ """
run = require_deep_scan_run(connection, scan_id)
scan = dependencies().require_scan(connection, run["scan_id"])
worker_rows = saved_deep_workers(connection, scan)
@@ -372,6 +391,7 @@ def deep_scan_state(connection: sqlite3.Connection, scan_id: str) -> dict[str, A
def independent_review_progress(
connection: sqlite3.Connection, scan_id: str
) -> dict[str, int | str] | None:
+ """Return completed and allowed review counts and the consolidation state, or None for a missing run."""
run = connection.execute(
"""
SELECT completion_sequence, phase, updated_at, max_discovery_runs
@@ -435,6 +455,7 @@ def deep_scan_result(
def effective_deep_scan_config(
args: argparse.Namespace, workspace: sqlite3.Row | None = None
) -> dict[str, Any]:
+ """Use persisted workspace settings when available, otherwise resolve the current launch configuration."""
if workspace is not None and workspace["deep_scan_config_json"] is not None:
return json.loads(workspace["deep_scan_config_json"])
available_parallelism = args.available_parallelism or os.cpu_count() or 1
@@ -451,6 +472,7 @@ def ensure_deep_scan_run(
service_tier: str | None,
pending_target_project_path: str | None = None,
) -> sqlite3.Row:
+ """Return the existing orchestration row or initialize one for a running Deep Scan with the supplied settings."""
existing = connection.execute(
"SELECT * FROM deep_scan_runs WHERE scan_id = ?", (scan["id"],)
).fetchone()
@@ -819,6 +841,7 @@ def begin_deep_scan_for_target(
def begin_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
+ """Begin orchestration for a registered scan or a target, returning the scan state and its start disposition."""
thread_id = optional_text(args.thread_id, maximum=512)
if thread_id is None:
raise SystemExit("thread-id is required.")
@@ -832,6 +855,7 @@ def begin_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) ->
def get_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -> dict[str, Any]:
+ """Return the persisted orchestration result to the thread that owns the scan."""
scan, _ = require_owned_scan(connection, args.scan_id, args.thread_id)
return deep_scan_result(connection, scan["id"])
@@ -860,6 +884,7 @@ def coordinator_lease_is_live(
scan: sqlite3.Row,
timestamp: str,
) -> bool:
+ """Check coordinator freshness using the lease generation and its applicable activity timestamps."""
if run["coordinator_generation"] == 1:
active_worker = connection.execute(
"""
@@ -923,7 +948,8 @@ def claim_deep_scan_coordinator_locked(
args.claim_token,
error_message="Deep Scan orchestration is owned by another continuation.",
)
- run, _ = require_running_deep_scan(connection, scan_id)
+ run = require_deep_scan_run(connection, scan_id)
+ require_running_deep_scan(run, scan)
timestamp = dependencies().now()
if args.coordinator_generation is not None:
require_current_coordinator(run, args)
@@ -957,6 +983,7 @@ def claim_deep_scan_coordinator_locked(
def recover_expired_coordinator(
connection: sqlite3.Connection, run: sqlite3.Row, timestamp: str
) -> None:
+ """Recover interrupted publications and reset active work so a replacement coordinator can resume."""
scan_id = run["scan_id"]
recover_candidate_ledger_publication(connection, scan_id)
legacy_generation = int(run["coordinator_generation"] == 1)
@@ -1032,6 +1059,7 @@ def recover_expired_coordinator(
def recover_candidate_ledger_publication(connection: sqlite3.Connection, scan_id: str) -> None:
+ """Reconcile ledger backups with reducer snapshots after an interrupted publication."""
scan = dependencies().require_scan(connection, scan_id)
ledger = Path(scan["scan_dir"]) / "artifacts" / "02_discovery" / "candidate_ledger.jsonl"
backups = sorted(
@@ -1069,26 +1097,11 @@ def recover_candidate_ledger_publication(connection: sqlite3.Connection, scan_id
return
-def require_deep_scan_worker(connection: sqlite3.Connection, worker_id: str) -> sqlite3.Row:
- worker_id = require_uuid(worker_id, "worker-id")
- row = connection.execute(
- "SELECT * FROM deep_scan_workers WHERE id = ?", (worker_id,)
- ).fetchone()
- if row is None:
- raise SystemExit("Codex Security Deep Scan worker not found.")
- return row
-
-
-def require_running_deep_scan(
- connection: sqlite3.Connection, scan_id: str
-) -> tuple[sqlite3.Row, sqlite3.Row]:
- run = require_deep_scan_run(connection, scan_id)
- scan = dependencies().require_scan(connection, run["scan_id"])
+def require_running_deep_scan(run: sqlite3.Row, scan: sqlite3.Row) -> None:
if run["status"] != "running" or run["cancel_requested"]:
raise SystemExit("Only a running Deep Scan can update orchestration state.")
if scan["status"] != "running" or scan["canceled_at"] is not None:
raise SystemExit("Only a running scan can update Deep Scan orchestration state.")
- return run, scan
def require_worker_transition(current: str, requested: str) -> None:
@@ -1146,7 +1159,7 @@ def upsert_deep_scan_worker(
and args.status in {"succeeded", "failed", "canceled"}
)
if not cleanup_update and not terminal_repeat:
- require_running_deep_scan(connection, scan_id)
+ require_running_deep_scan(run, scan)
prompt_path = deep_scan_path(scan, args.prompt_path, "Worker prompt path", kind="file")
artifact_dir = deep_scan_path(
scan, args.artifact_dir, "Worker artifact directory", kind="directory"
@@ -1351,13 +1364,19 @@ def upsert_deep_scan_worker(
def record_deep_scan_iteration(
connection: sqlite3.Connection, args: argparse.Namespace
) -> dict[str, Any]:
- """Commit the host-computed union and its Standard scans in one transaction."""
+ """Commit the checkpoint and its input workers in one transaction, then return deep scan state.
+
+ Repeating the same iteration and inputs replays the saved result. Conflicting
+ checkpoint or input-worker IDs raise SystemExit.
+ """
scan_id = require_uuid(args.scan_id, "scan-id")
checkpoint_id = require_uuid(args.worker_id, "worker-id")
input_ids = [require_uuid(value, "input-worker-id") for value in args.input_worker_id]
connection.execute("BEGIN IMMEDIATE")
with connection:
- run, scan = require_running_deep_scan(connection, scan_id)
+ run = require_deep_scan_run(connection, scan_id)
+ scan = dependencies().require_scan(connection, scan_id)
+ require_running_deep_scan(run, scan)
require_current_coordinator(run, args)
result = deep_scan_path(scan, args.result_manifest_path, "Iteration result", kind="file")
existing = connection.execute(
@@ -1419,10 +1438,10 @@ def finish_deep_scan(connection: sqlite3.Connection, args: argparse.Namespace) -
def finish_deep_scan_locked(
connection: sqlite3.Connection, args: argparse.Namespace, scan_id: str
) -> dict[str, Any]:
- omitted_worker_ids = [
+ omitted_worker_ids = {
require_uuid(value, "omitted-worker-id") for value in args.omitted_worker_id
- ]
- if len(set(omitted_worker_ids)) != len(omitted_worker_ids):
+ }
+ if len(omitted_worker_ids) != len(args.omitted_worker_id):
raise SystemExit("Omitted Deep Scan worker IDs must be unique.")
promotion: tuple[Path, Path, Path | None] | None = None
deadline_publication: (
@@ -1442,24 +1461,19 @@ def finish_deep_scan_locked(
)
standard_scan_manifest = manifest_path == str(Path(scan["scan_dir"]) / "scan-manifest.json")
- buffered_worker_ids = [
+ buffered_worker_ids = {
row["id"]
for row in connection.execute(
"""
SELECT id
FROM deep_scan_workers
WHERE scan_id = ? AND kind = 'discovery' AND merge_state = 'buffered'
- ORDER BY completion_sequence, id
""",
(scan_id,),
)
- ]
+ }
# Historical succeeded runs retain their exact omitted-worker replay contract.
- omissions_match = (
- set(omitted_worker_ids) == set(buffered_worker_ids)
- if args.terminal_reason == "saturated" or run["status"] == "succeeded"
- else not omitted_worker_ids and not buffered_worker_ids
- )
+ omissions_match = omitted_worker_ids == buffered_worker_ids
if run["status"] == "succeeded":
if (
run["terminal_reason"] != args.terminal_reason
@@ -1478,7 +1492,7 @@ def finish_deep_scan_locked(
)
connection.commit()
return deep_scan_result(connection, scan_id)
- require_running_deep_scan(connection, scan_id)
+ require_running_deep_scan(run, scan)
if run["error_message"] is not None:
raise SystemExit(run["error_message"])
if (
@@ -1795,6 +1809,7 @@ def cancel_active_workers(connection: sqlite3.Connection, scan_id: str, timestam
def other_running_deep_scans(
connection: sqlite3.Connection, current_scan_id: str
) -> list[dict[str, str]]:
+ """List other running Deep Scans ordered by most recent update, with target paths and phases."""
rows = connection.execute(
"""
SELECT id, target_path, phase, started_at, updated_at
diff --git a/plugins/codex-security/scripts/filesystem_identity.py b/plugins/codex-security/scripts/filesystem_identity.py
index 91d6c5346..541c84a72 100644
--- a/plugins/codex-security/scripts/filesystem_identity.py
+++ b/plugins/codex-security/scripts/filesystem_identity.py
@@ -19,6 +19,7 @@ def serialize_filesystem_identity(value: int) -> int | str:
def stored_filesystem_identity_matches(stored: object, current: int) -> bool:
+ """Compare a stored SQLite value with the platform file ID in its database representation."""
return stored == serialize_filesystem_identity(current)
diff --git a/plugins/codex-security/scripts/finalize_scan_contract.py b/plugins/codex-security/scripts/finalize_scan_contract.py
index 705238561..a10e49efb 100644
--- a/plugins/codex-security/scripts/finalize_scan_contract.py
+++ b/plugins/codex-security/scripts/finalize_scan_contract.py
@@ -862,6 +862,11 @@ def stage_scan_local_bytes(
owner_read_write: bool = False,
replace_existing: bool = False,
) -> Iterator[Callable[..., tuple[os.stat_result, int]]]:
+ """Stage payload under the scan directory and yield a callback that publishes it.
+
+ Call the callback inside the context to get file metadata and a platform-specific
+ change-time token. Leaving without publishing discards the staged write.
+ """
scan_dir, relative_path = _scan_local_write_path(scan_dir, relative_path, external_name)
if not _descriptor_relative_writes_available():
if not _is_windows():
@@ -2780,6 +2785,7 @@ def _read_sealed_scan(
def build_sarif_projection(
scan_dir: Path, source_root: Path | None = None, schema_dir: Path | None = None
) -> dict[str, Any]:
+ """Build SARIF for a sealed scan, using the optional source directory to resolve locations."""
if source_root is not None:
try:
source_root = source_root.resolve(strict=True)
@@ -2892,6 +2898,7 @@ def finding_csv_columns(deep_scan: bool) -> tuple[str, ...]:
def build_csv_projection(findings: dict[str, Any], coverage: dict[str, Any]) -> bytes:
+ """Encode findings in input order as UTF-8 CSV using the columns selected by coverage and findings."""
output = io.StringIO(newline="")
writer = csv.writer(output)
deep_scan = report_projection.uses_deep_presentation(coverage, findings["findings"])
@@ -2935,6 +2942,11 @@ def build_findings_export(
schema_dir: Path | None = None,
avit_template: Path | None = None,
) -> bytes:
+ """Return bytes for the requested export of a sealed scan.
+
+ JSON preserves the sealed findings bytes. SARIF can use source_root to resolve
+ locations. ServiceNow AVIT requires an application template.
+ """
if export_format not in EXPORT_PATHS:
raise ContractError(f"unsupported export format: {export_format}")
if export_format == "sarif":
@@ -3058,6 +3070,8 @@ def _write_sarif_projection_if_possible(
class PreparedScanFinalization(NamedTuple):
+ """Validated in-memory scan documents, rendered report bytes, and warnings awaiting publication."""
+
scan_dir: Path
schema_dir: Path
manifest: dict[str, Any]
@@ -3069,6 +3083,7 @@ class PreparedScanFinalization(NamedTuple):
def manifest_is_sealed(scan: dict[str, Any]) -> bool:
+ """Return whether the manifest records a seal time or sealed artifacts."""
return scan.get("sealedAt") is not None or scan.get("artifacts") not in (None, [])
diff --git a/plugins/codex-security/scripts/finding_preview.py b/plugins/codex-security/scripts/finding_preview.py
index d943a9cbe..7754d155e 100644
--- a/plugins/codex-security/scripts/finding_preview.py
+++ b/plugins/codex-security/scripts/finding_preview.py
@@ -27,6 +27,11 @@ from workbench_constants import (
def bounded_finding_details(value: Any) -> dict[str, Any]:
+ """Build the workbench preview of a stored finding, returning an empty dict for non-object input.
+
+ Budget for writeup text, diagnostics, and guidance alongside code evidence so a
+ large snippet cannot consume the whole preview.
+ """
if not isinstance(value, dict):
return {}
prepared: dict[str, Any] = {}
@@ -251,6 +256,7 @@ def bounded_finding_section(
priority_keys: tuple[str, ...],
reserved_fields: tuple[tuple[tuple[str, ...], int], ...],
) -> Any:
+ """Apply each field group’s size cap before selecting fields in priority order under the section cap."""
if not isinstance(value, dict):
return bounded_json_value(value, [maximum_bytes])
ordered: dict[str, Any] = {}
@@ -270,6 +276,12 @@ def bounded_finding_section(
def merged_bounded_code_evidence(value: dict[str, Any]) -> tuple[str | None, Any]:
+ """Return the preferred evidence key and the preview data to store under it.
+
+ Merge camelCase and snake_case catalogs by evidence ID, keeping the first
+ eligible snippet per ID. Return (None, None) if both keys are absent.
+ If neither value is a list, preserve the first supplied value.
+ """
evidence_keys = [key for key in ("codeEvidence", "code_evidence") if key in value]
if not evidence_keys:
return None, None
@@ -315,6 +327,7 @@ def merged_bounded_code_evidence(value: dict[str, Any]) -> tuple[str | None, Any
def json_size(value: Any) -> int:
+ """Return the byte count of the compact, ASCII-escaped JSON representation."""
# ASCII output gives byte length; strings can use the cached default encoder.
return len(json.dumps(value, separators=None if isinstance(value, str) else (",", ":")))
@@ -326,6 +339,7 @@ def bounded_json_value(
depth: int = 0,
max_depth: int = 4,
) -> Any:
+ """Build a depth-limited preview while charging its JSON representation to the shared byte budget."""
if budget[0] <= 0:
return None
if depth >= max_depth:
@@ -415,6 +429,7 @@ def bounded_json_value(
def consume_json_budget(budget: list[int], size: int) -> bool:
+ """Deduct the requested size and return whether it fit, exhausting the budget on failure."""
if budget[0] < size:
budget[0] = 0
return False
@@ -423,6 +438,11 @@ def consume_json_budget(budget: list[int], size: int) -> bool:
def bounded_json_text(value: str, maximum_bytes: int) -> tuple[str, int]:
+ """Return a string prefix and its ASCII-escaped JSON size in bytes.
+
+ Count the surrounding quotes and escape sequences toward maximum_bytes.
+ If even the empty string exceeds the budget, return the empty string and 2.
+ """
length = bisect_right(
range(min(len(value), maximum_bytes) + 1), maximum_bytes, key=lambda n: json_size(value[:n])
)
diff --git a/plugins/codex-security/scripts/posix_scan_local_files.py b/plugins/codex-security/scripts/posix_scan_local_files.py
index 021eaa2a4..5df348ab1 100644
--- a/plugins/codex-security/scripts/posix_scan_local_files.py
+++ b/plugins/codex-security/scripts/posix_scan_local_files.py
@@ -14,6 +14,7 @@ from pathlib import Path, PurePosixPath
def descriptor_relative_writes_available() -> bool:
+ """Return whether the platform supports the descriptor-relative operations used for writes."""
# os.replace accepts src_dir_fd/dst_dir_fd wherever descriptor-relative
# os.rename is supported, but Python lists only os.rename in supports_dir_fd.
required_operations = (os.mkdir, os.open, os.rename, os.stat, os.unlink)
@@ -24,6 +25,7 @@ def descriptor_relative_writes_available() -> bool:
@contextmanager
def managed_fd(descriptor: int) -> Iterator[int]:
+ """Yield the descriptor and close it when the context exits, including on error."""
try:
yield descriptor
finally:
@@ -34,6 +36,7 @@ def managed_fd(descriptor: int) -> Iterator[int]:
def stage_file(
parent_fd: int, filename: str, payload: bytes, owner_read_write: bool
) -> Iterator[int]:
+ """Yield a synced file descriptor for a new staging entry, removing the entry on exit if it still matches."""
descriptor = os.open(filename, os.O_WRONLY | os.O_CREAT | os.O_EXCL, 0o600, dir_fd=parent_fd)
try:
with os.fdopen(descriptor, "wb", closefd=False) as handle:
@@ -56,6 +59,7 @@ def stage_file(
def _rename_exclusive(parent_fd: int, source: str, destination: str) -> None:
+ """Rename a directory entry atomically while requiring the destination to be absent."""
import ctypes
libc = ctypes.CDLL(None, use_errno=True)
@@ -87,6 +91,7 @@ def _rename_exclusive(parent_fd: int, source: str, destination: str) -> None:
def publish_new_file(parent_fd: int, source: str, destination: str) -> None:
+ """Publish the staged name without overwriting the destination, using an exclusive rename if linking is unavailable."""
try:
os.link(
source, destination, src_dir_fd=parent_fd, dst_dir_fd=parent_fd, follow_symlinks=False
@@ -118,6 +123,12 @@ def stage_write(
check_parent: Callable[[Path], None],
contract_error: type[ValueError],
) -> Iterator[Callable[..., tuple[os.stat_result, int]]]:
+ """Stage payload under the open parent directory and yield a callable that publishes it.
+
+ Call the publisher inside the context. It returns file metadata and the
+ change time in nanoseconds. With compare_existing, matching bytes can
+ reuse an existing file when replacements are allowed.
+ """
name = PurePosixPath(relative_path).name
# Stage through the held parent so a replacement path cannot redirect the write.
try:
diff --git a/plugins/codex-security/scripts/report_projection.py b/plugins/codex-security/scripts/report_projection.py
index 56cb6e809..b6a0a329b 100644
--- a/plugins/codex-security/scripts/report_projection.py
+++ b/plugins/codex-security/scripts/report_projection.py
@@ -14,6 +14,13 @@ from typing import Any
SEVERITY_ORDER = {"critical": 0, "high": 1, "medium": 2, "low": 3, "informational": 4}
CONFIDENCE_ORDER = {"high": 0, "medium": 1, "low": 2}
REPORTABLE_SEVERITIES = {"critical", "high", "medium", "low"}
+THREAT_MODEL_SECTIONS = (
+ ("Assets", "assets"),
+ ("Trust Boundaries", "trustBoundaries"),
+ ("Attacker Capabilities", "attackerCapabilities"),
+ ("Security Objectives", "securityObjectives"),
+ ("Assumptions", "assumptions"),
+)
DISPOSITION_LABELS = {
"reported": "Reported",
"no_issue_found": "No issue found",
@@ -31,6 +38,14 @@ class ReportProjectionError(ValueError):
"""Raised when a canonical scan cannot be projected into a valid report."""
+def markdown_threat_model_content(model: dict[str, Any]) -> str | None:
+ """Return nonblank authored content for a Markdown model, otherwise None."""
+ content = model.get("content")
+ if model.get("format") == "markdown" and isinstance(content, str) and content.strip():
+ return content
+ return None
+
+
def _escape_markdown(value: str) -> str:
# Locate whole URLs before matching code spans: a URL can contain backticks.
urls = [match.span() for match in re.finditer(WWW_LINK_RE, value)]
@@ -135,6 +150,7 @@ def _has_deep_child_metadata(finding: dict[str, Any]) -> bool:
def uses_deep_presentation(coverage: dict[str, Any], findings: list[dict[str, Any]]) -> bool:
+ """Select deep-report formatting for repository scans in deep mode and scoped scans with deep-child metadata."""
if coverage.get("mode") == "deep_repository":
return True
if coverage.get("mode") != "scoped_path":
@@ -167,15 +183,6 @@ def _deep_title_parts(finding: dict[str, Any], report_id: str) -> tuple[str, str
return normalized, None
-def _deep_finding_groups(
- findings: list[dict[str, Any]], writeup_paths: list[str | None]
-) -> list[list[tuple[int, dict[str, Any], str | None]]]:
- groups: dict[str, list[tuple[int, dict[str, Any], str | None]]] = {}
- for number, (finding, report_path) in enumerate(zip(findings, writeup_paths, strict=True), 1):
- groups.setdefault(_deep_candidate_id(finding), []).append((number, finding, report_path))
- return list(groups.values())
-
-
def _deep_group_levels(
group: list[tuple[int, dict[str, Any], str | None]],
field: str,
@@ -242,6 +249,7 @@ def _bullet_section(heading: str, items: list[str]) -> list[str]:
def code_evidence_rows(*catalogs: Any) -> Iterator[dict[str, Any]]:
+ """Yield evidence objects with nonblank code in their original order."""
for items in catalogs:
if isinstance(items, list):
yield from (
@@ -254,6 +262,7 @@ def code_evidence_rows(*catalogs: Any) -> Iterator[dict[str, Any]]:
def embedded_code_evidence(section: dict[str, Any]) -> Iterator[dict[str, Any]]:
+ """Collect code evidence from both supported field spellings."""
return code_evidence_rows(section.get("codeEvidence"), section.get("code_evidence"))
@@ -282,6 +291,7 @@ def _section_code_evidence(
def merged_root_cause(value: dict[str, Any]) -> tuple[str | None, Any]:
+ """Return the first recorded root-cause field name and its merged detail, or (None, None) if absent."""
keys = [key for key in ("rootCause", "root_cause") if key in value]
if not keys:
return None, None
@@ -743,6 +753,16 @@ def _linked_finding_section(number: int, finding: dict[str, Any], report_path: s
def build_report_markdown(
manifest: dict[str, Any], findings_document: dict[str, Any], coverage: dict[str, Any]
) -> str:
+ """Render findings and review coverage as a Markdown report ending in a newline.
+
+ Args:
+ manifest: Scan metadata, target, and scope.
+ findings_document: Canonical findings for the scan.
+ coverage: Review coverage for older manifests. Newer scans supply review state inline.
+
+ Raises:
+ ReportProjectionError: Reportable findings share a writeup path.
+ """
scan = manifest["scan"]
if "review" in scan and "coverageRef" not in scan:
from review_state import review_state
@@ -759,19 +779,23 @@ def build_report_markdown(
),
key=_finding_sort_key,
)
- writeup_paths = [_writeup_report_path(finding) for finding in findings]
- duplicate_writeup_paths = sorted(
- path
- for path, count in Counter(path for path in writeup_paths if path is not None).items()
- if count > 1
- )
+ numbered_findings = [
+ (number, finding, _writeup_report_path(finding))
+ for number, finding in enumerate(findings, 1)
+ ]
+ writeup_counts = Counter(path for _, _, path in numbered_findings if path is not None)
+ duplicate_writeup_paths = sorted(path for path, count in writeup_counts.items() if count > 1)
if duplicate_writeup_paths:
raise ReportProjectionError(
"reportable findings have duplicate writeup reportPath values: "
+ ", ".join(duplicate_writeup_paths)
)
deep_presentation = uses_deep_presentation(coverage, findings)
- deep_finding_groups = _deep_finding_groups(findings, writeup_paths) if deep_presentation else []
+ deep_finding_groups: dict[str, list[tuple[int, dict[str, Any], str | None]]] = {}
+ if deep_presentation:
+ for entry in numbered_findings:
+ _, finding, _ = entry
+ deep_finding_groups.setdefault(_deep_candidate_id(finding), []).append(entry)
hardening_portfolio_path = _hardening_portfolio_path(scan)
include_paths = [
_path_text(path) for path in coverage.get("includePaths", scope.get("includePaths", []))
@@ -840,8 +864,8 @@ def build_report_markdown(
"",
]
)
- content = threat_model.get("content")
- if threat_model.get("format") == "markdown" and isinstance(content, str) and content.strip():
+ content = markdown_threat_model_content(threat_model)
+ if content is not None:
lines.append(content)
else:
lines.append(
@@ -850,13 +874,7 @@ def build_report_markdown(
"No explicit canonical threat-model summary was recorded.",
)
)
- for heading, key in (
- ("Assets", "assets"),
- ("Trust Boundaries", "trustBoundaries"),
- ("Attacker Capabilities", "attackerCapabilities"),
- ("Security Objectives", "securityObjectives"),
- ("Assumptions", "assumptions"),
- ):
+ for heading, key in THREAT_MODEL_SECTIONS:
values = _strings(threat_model.get(key))
if values:
lines.extend(["", f"### {heading}", "", *(f"- {value}" for value in values)])
@@ -881,7 +899,7 @@ def build_report_markdown(
"| --- | --- | --- | --- | --- |",
]
)
- lines.extend(_deep_group_row(group) for group in deep_finding_groups)
+ lines.extend(_deep_group_row(group) for group in deep_finding_groups.values())
else:
lines.extend(
[
@@ -889,9 +907,7 @@ def build_report_markdown(
"| --- | --- | --- | --- |",
]
)
- for number, (finding, report_path) in enumerate(
- zip(findings, writeup_paths, strict=True), 1
- ):
+ for number, finding, report_path in numbered_findings:
title = _cell(finding["title"])
finding_link = f"[{title}](#finding-{number})"
writeup_link = f"[Open report]({report_path})" if report_path else "inline below"
@@ -911,9 +927,7 @@ def build_report_markdown(
"| low | Evidence is incomplete and the item is retained only for explicit follow-up. |",
]
)
- for number, (finding, report_path) in enumerate(
- zip(findings, writeup_paths, strict=True), 1
- ):
+ for number, finding, report_path in numbered_findings:
if report_path is not None:
lines.extend(["", *_linked_finding_section(number, finding, report_path)])
else:
@@ -1018,6 +1032,7 @@ def generate_report_markdown(
findings: dict[str, Any],
coverage: dict[str, Any],
) -> bytes:
+ """Return the Markdown report for the scan as UTF-8 bytes ready to write."""
return build_report_markdown(manifest, findings, coverage).encode("utf-8")
diff --git a/plugins/codex-security/scripts/review_state.py b/plugins/codex-security/scripts/review_state.py
index 17554e6c9..cdfd6bcbd 100644
--- a/plugins/codex-security/scripts/review_state.py
+++ b/plugins/codex-security/scripts/review_state.py
@@ -8,17 +8,23 @@ from typing import Any
def uses_legacy_review(scan: dict[str, Any]) -> bool:
+ """Return whether the manifest points to separate coverage or predates inline review metadata."""
return "coverageRef" in scan or ("reviewState" not in scan and "review" not in scan)
def review_summary(state: dict[str, Any]) -> dict[str, Any]:
+ """Return the excluded path patterns in the compact form stored on the scan manifest."""
return {
"excludedPaths": [item["pattern"] for item in state.get("explicitExclusions", [])],
}
def review_state(scan: dict[str, Any]) -> dict[str, Any]:
- """Read new manifest metadata using the recovery code's existing representation."""
+ """Build the recovery coverage record from inline manifest metadata.
+
+ Copy the saved review state, deriving exclusions from the summary when needed,
+ and attach the inventory strategy and scope for this scan.
+ """
summary = scan.get("review", {})
state = copy.deepcopy(scan.get("reviewState", {}))
mode = scan.get("mode", "repository")
@@ -48,7 +54,7 @@ def review_state(scan: dict[str, Any]) -> dict[str, Any]:
def checkpoint_review_state(state: dict[str, Any]) -> dict[str, Any]:
- """Retain unfinished work and candidate outcomes, without a coverage report."""
+ """Copy the review data needed for recovery, omitting per-surface risk areas and report metadata."""
return {
"surfaces": [
{key: copy.deepcopy(value) for key, value in item.items() if key != "riskArea"}
diff --git a/plugins/codex-security/scripts/servicenow_avit.py b/plugins/codex-security/scripts/servicenow_avit.py
index 3e9710926..04a33c5db 100644
--- a/plugins/codex-security/scripts/servicenow_avit.py
+++ b/plugins/codex-security/scripts/servicenow_avit.py
@@ -32,6 +32,16 @@ AVIT_FINDING_FIELDS = (
def read_template(path: Path) -> tuple[list[str], dict[str, str]]:
+ """Read the application defaults for a ServiceNow AVIT export from a UTF-8 CSV.
+
+ Returns:
+ tuple: The original column headings and a mapping of stripped, case-folded
+ headings to values from the single application row.
+
+ Raises:
+ ValueError: The file is unreadable, required columns are missing or
+ duplicated, or application values are empty or too long.
+ """
try:
with path.open(encoding="utf-8-sig", newline="") as source:
rows = (row for row in csv.reader(source, strict=True) if row)
@@ -62,6 +72,11 @@ def _narrative(text: str) -> str:
def finding_fields(finding: dict[str, Any], location: dict[str, Any], steps: str) -> dict[str, str]:
+ """Return AVIT columns for a finding at the selected location with the recorded steps.
+
+ Use the first recognized CWE as the category, or the finding ID as the
+ vulnerability ID when no CWE qualifies. Both narrative fields fit in 1,000 characters.
+ """
details = (
f"{finding['findingId']} | {location['path']}:{location['startLine']}\n"
f"{finding['title']}\n{finding['summary']}\n{finding['remediation']}"
@@ -85,6 +100,11 @@ def finding_fields(finding: dict[str, Any], location: dict[str, Any], steps: str
def render(template: Path, rows: Iterable[dict[str, str]]) -> bytes:
+ """Return UTF-8 CSV bytes with the template's header and one row per finding.
+
+ The template supplies application fields and column order. For nonempty input,
+ write the count of findings missing reproduction steps to stderr.
+ """
headers, row = read_template(template)
output = io.StringIO(newline="")
writer = csv.writer(output)
diff --git a/plugins/codex-security/scripts/snapshot_sqlite.py b/plugins/codex-security/scripts/snapshot_sqlite.py
index e91d81a75..4d8f7a3dc 100644
--- a/plugins/codex-security/scripts/snapshot_sqlite.py
+++ b/plugins/codex-security/scripts/snapshot_sqlite.py
@@ -10,6 +10,7 @@ from urllib.parse import quote
def main() -> None:
+ """Back up the read-only source database into a separate destination using SQLite’s backup API."""
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("source", type=Path)
parser.add_argument("destination", type=Path)
diff --git a/plugins/codex-security/scripts/threat_model_projection.py b/plugins/codex-security/scripts/threat_model_projection.py
index ff17b7334..30e06043b 100644
--- a/plugins/codex-security/scripts/threat_model_projection.py
+++ b/plugins/codex-security/scripts/threat_model_projection.py
@@ -6,7 +6,6 @@ from __future__ import annotations
import argparse
import json
import sys
-from collections.abc import Callable
from pathlib import Path
from typing import Any
@@ -14,14 +13,6 @@ from typing import Any
sys.path.insert(0, str(Path(__file__).resolve().parent))
import report_projection as report
-_STRUCTURED_SECTIONS = (
- ("Assets", "assets"),
- ("Trust Boundaries", "trustBoundaries"),
- ("Attacker Capabilities", "attackerCapabilities"),
- ("Security Objectives", "securityObjectives"),
- ("Assumptions", "assumptions"),
-)
-
def _is_structured_model(model: dict[str, Any]) -> bool:
summary = model.get("summary")
@@ -31,21 +22,18 @@ def _is_structured_model(model: dict[str, Any]) -> bool:
and all(
isinstance(values := model.get(key, []), list)
and all(isinstance(value, str) and value for value in values)
- for _, key in _STRUCTURED_SECTIONS
+ for _, key in report.THREAT_MODEL_SECTIONS
)
)
-def _markdown_content(model: dict[str, Any]) -> str | None:
- content = model.get("content")
- if model.get("format") == "markdown" and isinstance(content, str) and content.strip():
- return content
- return None
-
-
def threat_model_body(model: dict[str, Any]) -> str:
- """Keep authored Markdown intact, including summaries from older scans."""
- content = _markdown_content(model)
+ """Return the authored Markdown body verbatim or render a legacy summary and its sections.
+
+ Raises:
+ ValueError: Required content is absent or the saved model has invalid metadata or sections.
+ """
+ content = report.markdown_threat_model_content(model)
if content is not None:
# The structured schema permits legacy metadata as extension fields.
if _is_structured_model(model):
@@ -82,7 +70,7 @@ def threat_model_body(model: dict[str, Any]) -> str:
sections = [
summary if summary.strip() else "No explicit canonical threat-model summary was recorded."
]
- for heading, key in _STRUCTURED_SECTIONS:
+ for heading, key in report.THREAT_MODEL_SECTIONS:
values = model.get(key, [])
if not isinstance(values, list):
raise ValueError(f"threatModel.{key}: expected an array")
@@ -96,7 +84,7 @@ def threat_model_body(model: dict[str, Any]) -> str:
return "\n\n".join(sections)
-def _scope_lines(scope: Any, label: str, text: Callable[[Any, str], str]) -> list[str]:
+def _scope_lines(scope: Any, label: str) -> list[str]:
# Older structured models may use these extension names for unrelated data.
included = scope.get("includePaths") if isinstance(scope, dict) else None
if not isinstance(included, list) or not all(isinstance(path, str) for path in included):
@@ -109,14 +97,19 @@ def _scope_lines(scope: Any, label: str, text: Callable[[Any, str], str]) -> lis
lines.append(f"- {label} exclusions: {excluded_text or 'none'}")
summary = scope.get("summary")
if isinstance(summary, str) and summary:
- lines.append(f"- {label} description: {text(summary, 'not recorded')}")
+ lines.append(f"- {label} description: {report._text(summary, 'not recorded')}")
return lines
def render_threat_model(model: dict[str, Any], provenance: dict[str, Any] | None = None) -> bytes:
- """Render a portable document with authored content and recorded provenance."""
+ """Return the saved threat model as UTF-8 Markdown, including its provenance footer.
+
+ Args:
+ model (dict): Authored Markdown or a legacy structured model from a scan.
+ provenance (dict | None): Optional saved scan identifiers, scope, and provisional status.
+ """
body = threat_model_body(model)
- if _markdown_content(model) is None:
+ if report.markdown_threat_model_content(model) is None:
body = "# Threat Model\n\n" + body
text = report._text
provenance = provenance or {}
@@ -132,10 +125,10 @@ def render_threat_model(model: dict[str, Any], provenance: dict[str, Any] | None
if provenance.get(key):
footer.append(f"- {label}: {text(str(provenance[key]), 'not recorded')}")
footer.append(f"- Model origin: {text(model.get('origin'), 'not recorded')}")
- footer.extend(_scope_lines(model.get("scope"), "Model scope", text))
+ footer.extend(_scope_lines(model.get("scope"), "Model scope"))
scan_scope = provenance.get("scanScope")
if isinstance(scan_scope, dict):
- footer.extend(_scope_lines(scan_scope, "Scan scope", text))
+ footer.extend(_scope_lines(scan_scope, "Scan scope"))
if provenance.get("provisional"):
footer.extend(["", "This is a provisional model saved before successful completion."])
return (body + ("\n" if body.endswith("\n") else "\n\n") + "\n".join(footer) + "\n").encode(
@@ -144,6 +137,7 @@ def render_threat_model(model: dict[str, Any], provenance: dict[str, Any] | None
def main() -> int:
+ """Render a JSON payload from stdin to UTF-8 Markdown on stdout and return zero on success."""
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--input-json-stdin", action="store_true", required=True)
parser.parse_args()
diff --git a/plugins/codex-security/scripts/validate_scan_contract.py b/plugins/codex-security/scripts/validate_scan_contract.py
index 3e1849386..b8e9d0a6f 100644
--- a/plugins/codex-security/scripts/validate_scan_contract.py
+++ b/plugins/codex-security/scripts/validate_scan_contract.py
@@ -15,7 +15,11 @@ import finalize_scan_contract as FINALIZER
def validate_contract(scan_dir: Path) -> dict[str, Any]:
- """Return validated canonical documents for one sealed scan."""
+ """Validate the sealed artifacts and return the manifest, original findings, and review summary.
+
+ Legacy finding records are adapted for validation only. ContractError propagates
+ when a required artifact, digest, schema, or evidence check fails.
+ """
scan_dir = FINALIZER._require_scan_directory(scan_dir.expanduser().resolve(strict=True))
schema_dir = Path(__file__).resolve().parents[1] / "schemas"
@@ -46,6 +50,7 @@ def validate_contract(scan_dir: Path) -> dict[str, Any]:
def receipt(validated: dict[str, Any]) -> dict[str, Any]:
+ """Return the CLI success payload with paths to the validated manifest, findings, and report."""
scan_dir = Path(validated["scanDir"])
scan = validated["manifest"]["scan"]
return {
@@ -58,6 +63,7 @@ def receipt(validated: dict[str, Any]) -> dict[str, Any]:
def main(argv: list[str] | None = None) -> int:
+ """Print the validation receipt on success or report a validation error to stderr and return 2."""
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("--scan-dir", required=True, type=Path)
args = parser.parse_args(argv)
diff --git a/plugins/codex-security/scripts/windows_scan_local_files.py b/plugins/codex-security/scripts/windows_scan_local_files.py
index 800c45442..a23cf8db0 100644
--- a/plugins/codex-security/scripts/windows_scan_local_files.py
+++ b/plugins/codex-security/scripts/windows_scan_local_files.py
@@ -587,7 +587,11 @@ def open_read_fd(scan_dir: Path, relative_path: str, context: str) -> int:
def open_read_fd_with_path(scan_dir: Path, relative_path: str, context: str) -> tuple[int, str]:
- """Return the descriptor and its filename while the verified parents are held."""
+ """Return an owned read descriptor and the scan-relative path with the file's actual leaf name.
+
+ Verify the regular file while holding its parent directories. The caller must
+ close the returned descriptor.
+ """
try:
with _locked_parent(scan_dir, relative_path, create=False, missing_is_path_error=False) as (
@@ -636,6 +640,7 @@ def file_change_time(descriptor: int) -> int:
def stream_matches_payload(stream: BinaryIO, payload: bytes) -> bool:
+ """Compare bytes from the current stream position to payload, requiring EOF after the final byte."""
offset = 0
while offset < len(payload):
chunk = stream.read(min(_MAX_COMPARE_CHUNK, len(payload) - offset))
diff --git a/plugins/codex-security/scripts/workbench/__init__.py b/plugins/codex-security/scripts/workbench/__init__.py
index 660a264fe..450800ad1 100644
--- a/plugins/codex-security/scripts/workbench/__init__.py
+++ b/plugins/codex-security/scripts/workbench/__init__.py
@@ -1 +1 @@
-"""Focused Codex Security workbench operation modules."""
+"""Persist workbench state, transfer scan ownership, and recover results from saved artifacts."""
diff --git a/plugins/codex-security/scripts/workbench/handoff.py b/plugins/codex-security/scripts/workbench/handoff.py
index fa21ec8d5..1d64d8854 100644
--- a/plugins/codex-security/scripts/workbench/handoff.py
+++ b/plugins/codex-security/scripts/workbench/handoff.py
@@ -12,6 +12,7 @@ RECOVERY_HANDOFF_TOKEN_PREFIX = "recovery_"
def require_handoff_claim_token(value: str) -> str:
+ """Normalize the claim UUID, retaining the prefix that marks a recovery handoff."""
recovery_token = value.startswith(RECOVERY_HANDOFF_TOKEN_PREFIX)
token = value.removeprefix(RECOVERY_HANDOFF_TOKEN_PREFIX) if recovery_token else value
normalized = require_uuid(token, "claim-token")
@@ -24,6 +25,7 @@ def require_current_continuation(
*,
error_message: str,
) -> None:
+ """Require the current claim token, allowing a tokenless continuation for legacy delivered scans."""
if (
scan["handoff_status"] == "delivered"
and scan["handoff_claim_token"] is None
@@ -41,6 +43,7 @@ def validate_handoff_delivery_thread(
requesting_thread_id: str,
claim_token: str,
) -> None:
+ """Require the owning thread for delivery unless the caller presents a recovery claim token."""
if owning_thread_id != requesting_thread_id and not claim_token.startswith(
RECOVERY_HANDOFF_TOKEN_PREFIX
):
@@ -54,6 +57,12 @@ def claim_handoff_delivery(
connection: sqlite3.Connection,
args: argparse.Namespace,
) -> dict[str, Any]:
+ """Claim a pending handoff and return the current workspace state.
+
+ The first claim wins. When take_over_stale is requested, replacing an expired
+ claim also clears the continuation and deep scan owner. Retrying the same claim
+ or losing a competing claim returns the workspace state without changing ownership.
+ """
scan_id = require_uuid(args.scan_id, "scan-id")
claim_token = require_handoff_claim_token(args.claim_token)
timestamp = wb.now()
@@ -102,6 +111,7 @@ def release_handoff_delivery(
connection: sqlite3.Connection,
args: argparse.Namespace,
) -> dict[str, Any]:
+ """Release a matching pending claim, detach its continuation, and return the workspace state."""
scan_id = require_uuid(args.scan_id, "scan-id")
claim_token = require_handoff_claim_token(args.claim_token)
timestamp = wb.now()
@@ -126,6 +136,11 @@ def attach_scan_continuation_thread(
connection: sqlite3.Connection,
args: argparse.Namespace,
) -> dict[str, Any]:
+ """Bind the claimed scan to a continuation and return its workspace state.
+
+ An immediate transaction serializes ownership changes. Reattaching the same
+ thread is idempotent. A different thread or mismatched claim token raises SystemExit.
+ """
scan_id = require_uuid(args.scan_id, "scan-id")
claim_token = require_handoff_claim_token(args.claim_token)
thread_id = optional_text(args.thread_id, maximum=512)
@@ -165,6 +180,11 @@ def mark_handoff_delivered(
connection: sqlite3.Connection,
args: argparse.Namespace,
) -> dict[str, Any]:
+ """Record delivery for the pending claim and return the workspace state.
+
+ For standard scans this resets preflight progress. The same claim can confirm
+ delivery again. A conflicting claim or invalid requesting thread raises SystemExit.
+ """
scan_id = require_uuid(args.scan_id, "scan-id")
claim_token = require_handoff_claim_token(args.claim_token)
thread_id = optional_text(args.thread_id, maximum=512)
diff --git a/plugins/codex-security/scripts/workbench/retained_coverage.py b/plugins/codex-security/scripts/workbench/retained_coverage.py
index b4e394d3b..7329c0e0d 100644
--- a/plugins/codex-security/scripts/workbench/retained_coverage.py
+++ b/plugins/codex-security/scripts/workbench/retained_coverage.py
@@ -116,7 +116,13 @@ def merge_saved_results(
current_contract: bool = False,
recovery_snapshot_error: _CheckpointSnapshotError | None = None,
) -> tuple[dict[str, Any], dict[str, Any], dict[str, Any]] | None:
- """Read only bound parent/worker files; return an unsealed loss-preserving union."""
+ """Reconcile the bound parent and worker checkpoints into an unsealed scan draft.
+
+ Return the manifest, findings document, and coverage document, or None when there
+ is no saved input or the sealed parent already reflects the selected checkpoints.
+ Frozen digests and heads identify the inputs selected when the scan stopped.
+ Recovery appends diagnostics to the caller's warnings list.
+ """
initial_warnings = set(warnings)
if frozen_source_digests is None:
checkpoint_heads = {}
@@ -621,18 +627,16 @@ def merge_saved_results(
if previous is not None and isinstance(previous.get("id"), str):
result["id"] = previous["id"]
else:
- surfaces = coverage.get("surfaces", [])
if any(
isinstance(row, dict) and row.get("id") == result["id"]
- for row in (surfaces if isinstance(surfaces, list) else [])
+ for row in _coverage_rows(coverage, "surfaces")
):
result["id"] = f"{result['id']}-{_digest(result)[:16]}"
elif field == "deferred":
result["id"] = f"{prefix}-deferred-{index}"
if isinstance(item.get("surfaceIds"), list):
surface_ids: dict[str, str] = {}
- surfaces = projected_coverage.get("surfaces", [])
- for surface in surfaces if isinstance(surfaces, list) else []:
+ for surface in _coverage_rows(projected_coverage, "surfaces"):
if not isinstance(surface, dict) or not isinstance(surface.get("id"), str):
continue
provenance = surface.get("provenance", {})
@@ -643,9 +647,8 @@ def merge_saved_results(
and isinstance(provenance.get("sourceId"), str)
):
surface_ids.setdefault(provenance["sourceId"], surface["id"])
- surfaces = source.get("surfaces", [])
source_surface_ids: dict[str, tuple[int, dict[str, Any]]] = {}
- for offset, surface in enumerate(surfaces if isinstance(surfaces, list) else [], 1):
+ for offset, surface in enumerate(_coverage_rows(source, "surfaces"), 1):
if isinstance(surface, dict) and isinstance(surface.get("id"), str):
source_surface_ids.setdefault(surface["id"], (offset, surface))
for (owner, source_id), accepted in accepted_surfaces.items():
@@ -771,8 +774,7 @@ def merge_saved_results(
for relative, draft, worker_id in sources:
if relative not in accepted_sources:
continue
- surfaces = draft["reviewState"].get("surfaces", [])
- for index, surface in enumerate(surfaces if isinstance(surfaces, list) else [], 1):
+ for index, surface in enumerate(_coverage_rows(draft["reviewState"], "surfaces"), 1):
if isinstance(surface, dict) and isinstance(surface.get("id"), str):
accepted_surfaces.setdefault((worker_id, surface["id"]), []).append(
(index, surface)
@@ -893,11 +895,7 @@ def merge_saved_results(
surface_ids_by_source: dict[tuple[str, str], list[str]] = {
(relative, row["id"]): []
for relative, draft, _ in all_sources
- for row in (
- draft["reviewState"].get("surfaces", [])
- if isinstance(draft["reviewState"].get("surfaces"), list)
- else []
- )
+ for row in _coverage_rows(draft["reviewState"], "surfaces")
if isinstance(row, dict) and isinstance(row.get("id"), str)
}
discarded_coverage_sources: set[str] = set()
@@ -1155,8 +1153,7 @@ def merge_saved_results(
retained_surface_rows: set[int] = set()
for relative, draft, _ in all_sources:
for field in ("surfaces", "deferred"):
- rows = draft["reviewState"].get(field)
- for row in rows if isinstance(rows, list) else []:
+ for row in _coverage_rows(draft["reviewState"], field):
if isinstance(row, dict):
paths_for_row = coverage_sources.setdefault(id(row), (row, []))[1]
if relative not in paths_for_row:
@@ -1316,8 +1313,7 @@ def merge_saved_results(
if isinstance(finding, dict) and valid_finding(finding)
}
for field in ("surfaces", "deferred", "explicitExclusions"):
- rows = draft["reviewState"].get(field, [])
- for index, row in enumerate(rows if isinstance(rows, list) else [], 1):
+ for index, row in enumerate(_coverage_rows(draft["reviewState"], field), 1):
if not isinstance(row, dict):
continue
if (
@@ -1439,8 +1435,7 @@ def merge_saved_results(
pending_surface_orders: dict[tuple[str | None, str], tuple[int, int]] = {}
for relative, draft, owner in all_sources:
- surfaces = draft["reviewState"].get("surfaces", [])
- for surface in surfaces if isinstance(surfaces, list) else []:
+ for surface in _coverage_rows(draft["reviewState"], "surfaces"):
if (
isinstance(surface, dict)
and surface.get("disposition") == "needs_follow_up"
@@ -3174,8 +3169,7 @@ def merge_saved_results(
item = {"id": "scan-stopped", "reason": reason}
if item not in coverage["deferred"]:
coverage["deferred"].append(item)
- surfaces = coverage.get("surfaces", [])
- for surface in surfaces if isinstance(surfaces, list) else []:
+ for surface in _coverage_rows(coverage, "surfaces"):
if isinstance(surface, dict) and isinstance(surface.get("provenance"), dict):
surface["provenance"].pop("scanReceiptRefs", None)
if (
diff --git a/plugins/codex-security/scripts/workbench/retained_records.py b/plugins/codex-security/scripts/workbench/retained_records.py
index 4e84a755b..5b808dcf1 100644
--- a/plugins/codex-security/scripts/workbench/retained_records.py
+++ b/plugins/codex-security/scripts/workbench/retained_records.py
@@ -20,6 +20,7 @@ from finalize_scan_contract import (
_validate_schema_node,
finding_candidate_id,
)
+from finalize_scan_contract import _schema_values_equal as same_raw_value
from workbench.saved_coverage import _coverage_rows, _saved_coverage_id
from workbench.saved_sources import _digest, _encoded
from workbench_coverage_receipts import resolve_coverage_receipts
@@ -242,6 +243,7 @@ def _append_previous_finding(
def _recover_preserved_worker_source(
scan_dir, relative, scan_id, binding, worker_id, worker, draft, warnings
):
+ """Normalize findings and receipt references in the draft and return diagnostics for discarded findings."""
discarded_findings = []
# Recover imported records without relaxing canonical parent validation.
if "complete" in draft and not isinstance(draft["complete"], bool):
@@ -320,10 +322,10 @@ def _recover_preserved_worker_source(
def _recover_preserved_worker_coverage(
scan_dir, relative, worker_id, draft, discarded_findings, warnings
):
+ """Repair coverage in the draft, append source warnings, and return whether coverage was discarded."""
discarded_coverage = False
for field in ("surfaces", "explicitExclusions", "deferred"):
- rows = draft["reviewState"].get(field)
- for row in rows if isinstance(rows, list) else []:
+ for row in _coverage_rows(draft["reviewState"], field):
if isinstance(row, dict):
row.setdefault("id", _saved_coverage_id(row))
if field == "surfaces":
@@ -352,6 +354,7 @@ def _recover_preserved_worker_coverage(
def identifiers(value: dict[str, Any]) -> tuple[Any, Any]:
+ """Return the report ID and ledger row ID from extensions, using None for missing or blank IDs."""
extensions = value.get("extensions")
return tuple(
identifier if _has_identity_text(identifier) else None
@@ -363,6 +366,7 @@ def identifiers(value: dict[str, Any]) -> tuple[Any, Any]:
def distinct_reports(left: dict[str, Any] | None, right: dict[str, Any] | None) -> bool:
+ """Check the latest observations for conflicting report IDs or ledger row IDs."""
return (
left is not None
and right is not None
@@ -374,6 +378,7 @@ def distinct_reports(left: dict[str, Any] | None, right: dict[str, Any] | None)
def raw_owner(value: dict[str, Any], source_owner: str | None) -> str | None:
+ """Return the source owner, falling back to the worker ID recorded in finding provenance."""
if source_owner is not None:
return source_owner
provenance = value.get("provenance", {})
@@ -382,6 +387,7 @@ def raw_owner(value: dict[str, Any], source_owner: str | None) -> str | None:
def raw_scope(value: dict[str, Any]) -> tuple[Any, ...]:
+ """Return the rule, path, and line range of the first location used to match anonymous reports."""
# Match scanFindingIdentity's primary location for anonymous reports.
location = value["locations"][0]
return (
@@ -393,6 +399,7 @@ def raw_scope(value: dict[str, Any]) -> tuple[Any, ...]:
def same_raw_finding(left: dict[str, Any], right: dict[str, Any]) -> bool:
+ """Check whether semantic identities match or, in their absence, whether candidate and report IDs are compatible."""
if isinstance(left.get("identity"), dict) and isinstance(right.get("identity"), dict):
return _semantic_identity_key(left, _finding_identity(left)) == _semantic_identity_key(
right, _finding_identity(right)
@@ -409,24 +416,9 @@ def same_raw_finding(left: dict[str, Any], right: dict[str, Any]) -> bool:
return True
-def same_raw_value(left: Any, right: Any) -> bool:
- if isinstance(left, dict):
- return (
- isinstance(right, dict)
- and left.keys() == right.keys()
- and all(same_raw_value(value, right[key]) for key, value in left.items())
- )
- if isinstance(left, list):
- return (
- isinstance(right, list)
- and len(left) == len(right)
- and all(same_raw_value(a, b) for a, b in zip(left, right, strict=True))
- )
- # JSON numbers compare by value, but booleans are a distinct scalar type.
- return isinstance(left, bool) == isinstance(right, bool) and left == right
-
-
def same_raw_content(left: dict[str, Any], right: dict[str, Any]) -> bool:
+ """Compare substantive finding fields while ignoring identity, provenance, and report-tracking IDs."""
+
def content(value: dict[str, Any]) -> dict[str, Any]:
result = _finding_content(value)
if isinstance(result.get("extensions"), dict):
@@ -443,6 +435,10 @@ def same_raw_content(left: dict[str, Any], right: dict[str, Any]) -> bool:
def contains_raw_value(current: Any, previous: Any) -> bool:
+ """Check whether the current JSON value retains every part of the previous value.
+
+ Match dictionary values by key and list elements by content, regardless of order.
+ """
if isinstance(previous, dict):
return isinstance(current, dict) and all(
key in current and contains_raw_value(current[key], value)
@@ -521,6 +517,7 @@ def _saved_candidate_outcomes(
workers_by_id,
coverage_schema,
):
+ """Return saved candidate outcomes with their evidence and the ordering of pending candidates by owner."""
pending_candidate_orders: dict[tuple[str | None, str], tuple[int, int]] = {}
outcomes = []
for relative, draft, owner in current_drafts:
@@ -531,8 +528,7 @@ def _saved_candidate_outcomes(
}
pending_candidates = set()
for field in ("deferred", "surfaces"):
- items = draft["reviewState"].get(field, [])
- for item in items if isinstance(items, list) else []:
+ for item in _coverage_rows(draft["reviewState"], field):
if isinstance(item, dict) and (
field == "deferred" or item.get("disposition") == "needs_follow_up"
):
diff --git a/plugins/codex-security/scripts/workbench/runtime_toml.py b/plugins/codex-security/scripts/workbench/runtime_toml.py
index 8c8af28b9..beae50248 100644
--- a/plugins/codex-security/scripts/workbench/runtime_toml.py
+++ b/plugins/codex-security/scripts/workbench/runtime_toml.py
@@ -1,4 +1,7 @@
-"""Load TOML using the supported Python runtime."""
+"""Expose tomllib to workbench callers, using tomli on Python 3.10.
+
+Import exits with setup guidance when the runtime is too old or the backport is missing.
+"""
import sys
diff --git a/plugins/codex-security/scripts/workbench/saved_coverage.py b/plugins/codex-security/scripts/workbench/saved_coverage.py
index 7b37c19a2..d57e8e59e 100644
--- a/plugins/codex-security/scripts/workbench/saved_coverage.py
+++ b/plugins/codex-security/scripts/workbench/saved_coverage.py
@@ -250,7 +250,7 @@ def prepare_saved_coverage_projection(
class SavedCoverageProjection:
- """Keep worker source links stable while legacy and accepted rows converge."""
+ """Track which worker supplied a coverage row so reconstructed links can resolve to the retained surface."""
def __init__(self, project_worker_coverage, legacy_surface_links, projection_origins):
self.project_worker_coverage = project_worker_coverage
@@ -293,8 +293,7 @@ class SavedCoverageProjection:
if field == "surfaces":
# Canonical IDs can change while source content and ownership stay the same.
item = {key: value for key, value in item.items() if key != "id"}
- records = coverage.get(field, [])
- for record in records if isinstance(records, list) else []:
+ for record in _coverage_rows(coverage, field):
if not isinstance(record, dict):
continue
original = dict(canonical_record(field, record))
@@ -329,12 +328,11 @@ class SavedCoverageProjection:
or worker["merge_state"] != "merged"
):
return False
- reviews = canonical.get("reviews", [])
return any(
isinstance(review, dict)
and review.get("workerId") == worker["id"]
and review.get("attempt") == worker["attempt"]
- for review in (reviews if isinstance(reviews, list) else [])
+ for review in _coverage_rows(canonical, "reviews")
)
def repair_reviewed_surface(self, coverage, canonical, worker, source, surface):
@@ -446,11 +444,8 @@ class SavedCoverageProjection:
retained_legacy_surface_links: dict[
int, tuple[dict[str, Any], dict[str, dict[str, Any]]]
] = {}
- output_tasks = coverage.get("deferred", [])
- task_candidates = [
- (self.worker_row_owners.get(id(row)), row)
- for row in (output_tasks if isinstance(output_tasks, list) else [])
- ]
+ output_tasks = _coverage_rows(coverage, "deferred")
+ task_candidates = [(self.worker_row_owners.get(id(row)), row) for row in output_tasks]
for task, published_id, surface, _ in self.task_surface_links(task_candidates):
retained_surface = self.linked_surface(
surface,
@@ -481,8 +476,7 @@ class SavedCoverageProjection:
named_surface_outputs = {
identity for outputs in self.worker_surface_outputs.values() for identity in outputs
}
- surfaces = coverage.get("surfaces", [])
- for surface in surfaces if isinstance(surfaces, list) else []:
+ for surface in _coverage_rows(coverage, "surfaces"):
if not isinstance(surface, dict):
continue
owner, identity = self.worker_row_owners.get(id(surface)), surface.get("id")
@@ -496,7 +490,7 @@ class SavedCoverageProjection:
and id(existing) not in named_surface_outputs
):
worker_surfaces[key] = surface
- for task in output_tasks if isinstance(output_tasks, list) else []:
+ for task in output_tasks:
if (
not isinstance(task, dict)
or (owner := self.worker_row_owners.get(id(task))) is None
@@ -610,8 +604,7 @@ class SavedCoverageProjection:
# tasks. Preserve their original links, even when the outcome changes ID
# or a distinct retained surface shares the old source-local ID.
for relative, draft, owner in all_sources:
- originals = draft["reviewState"].get("surfaces", [])
- for original in originals if isinstance(originals, list) else []:
+ for original in _coverage_rows(draft["reviewState"], "surfaces"):
if (
not isinstance(original, dict)
or id(original) in retained_surface_rows
@@ -652,8 +645,7 @@ class SavedCoverageProjection:
prospective_surfaces = {}
prospective_named = {}
for relative, draft, owner in all_sources:
- rows = draft["reviewState"].get("surfaces", [])
- for row in rows if isinstance(rows, list) else []:
+ for row in _coverage_rows(draft["reviewState"], "surfaces"):
if owner is None or not isinstance(row, dict):
continue
emitted = surface_is_retained(relative, owner, row)
diff --git a/plugins/codex-security/scripts/workbench/saved_outputs.py b/plugins/codex-security/scripts/workbench/saved_outputs.py
index bb9910a9a..b438ac23d 100644
--- a/plugins/codex-security/scripts/workbench/saved_outputs.py
+++ b/plugins/codex-security/scripts/workbench/saved_outputs.py
@@ -26,6 +26,11 @@ _PUBLISHED_OUTPUTS = (
def _snapshot_published_outputs(
scan_dir: Path, relative_paths: tuple[str, ...] = _PUBLISHED_OUTPUTS
) -> dict[str, tuple[bytes, os.stat_result] | None]:
+ """Capture each artifact's bytes and stat metadata before publication.
+
+ A None entry records an absent artifact. An unsafe optional threatmodel.md is
+ omitted so rollback leaves it alone. Other unreadable existing outputs raise ContractError.
+ """
snapshots: dict[str, tuple[bytes, os.stat_result] | None] = {}
for relative in relative_paths:
descriptor = -1
@@ -56,6 +61,10 @@ def _restore_published_outputs(
snapshots: dict[str, tuple[bytes, os.stat_result] | None],
created_paths: set[str] | None = None,
) -> None:
+ """Restore the captured bytes and timestamps after a publication failure.
+
+ Remove outputs that were originally absent and paths journaled as newly created by the caller.
+ """
for relative, snapshot in snapshots.items():
if snapshot is None:
path = scan_dir / relative
diff --git a/plugins/codex-security/scripts/workbench/saved_sources.py b/plugins/codex-security/scripts/workbench/saved_sources.py
index 55caff0a6..d8c018a1e 100644
--- a/plugins/codex-security/scripts/workbench/saved_sources.py
+++ b/plugins/codex-security/scripts/workbench/saved_sources.py
@@ -57,6 +57,11 @@ def _source_digests(value: Any, error: str) -> dict[str, str]:
def _retained_source_state(value: Any) -> tuple[dict[str, str], str | None]:
+ """Return the saved source digests and the optional path supplying the threat model.
+
+ Accept both a legacy path-to-digest map and an envelope containing sources.
+ Raise ContractError if the model points outside that envelope's source set.
+ """
if isinstance(value, dict) and isinstance(value.get("sources"), dict):
sources = _source_digests(
value["sources"], "Saved stopped-scan source digests are malformed."
@@ -73,6 +78,11 @@ def _retained_source_state(value: Any) -> tuple[dict[str, str], str | None]:
def _retained_checkpoint_state(
scan: Any,
) -> tuple[dict[str, str | None] | None, dict[str, Any] | None]:
+ """Return selected checkpoint heads and any pending recovery record.
+
+ Older scans can store the head map directly. Recovery records also bind
+ the selection to a sealed manifest digest. A conflicting digest raises ContractError.
+ """
raw = scan["retained_checkpoint_heads_json"]
if raw is None:
return None, None
@@ -125,6 +135,7 @@ def _checkpoint_paths(scan_dir: Path, directory: str) -> list[str]:
def _checkpoint_head_directory(relative: str) -> Path | None:
+ """Return the owner directory of a current or archived checkpoint head path, or None for another file."""
path = Path(relative)
if path.name == "checkpoint-head.json":
return path.parent
@@ -162,6 +173,7 @@ def _capture_saved_source(
checkpoint_heads: dict[str, str | None] | None = None,
expected_digest: str | None = None,
) -> dict[str, tuple[str, int]]:
+ """Capture digests and observation times for a saved source and its selected checkpoint or receipt inputs."""
if not snapshot_head or Path(relative).name != "checkpoint-head.json":
_, digest, observed = _read_saved_result(scan_dir, relative, scan_id, kind=kind)
return capture_receipt_checkpoints(
@@ -392,6 +404,7 @@ def _restore_checkpoint_head(
sources: dict[str, str],
relative: str,
) -> None:
+ """Restore the prior selection for a checkpoint directory, allowing legacy evidence with no selected head."""
path = Path(relative)
if path.name != "checkpoint-head.json":
return
diff --git a/plugins/codex-security/scripts/workbench/storage.py b/plugins/codex-security/scripts/workbench/storage.py
index 2a303cfa4..90abe5cd3 100644
--- a/plugins/codex-security/scripts/workbench/storage.py
+++ b/plugins/codex-security/scripts/workbench/storage.py
@@ -9,6 +9,7 @@ from typing import Any
def state_dir(*, canonical: bool = True) -> Path:
+ """Return the workbench state path, resolving symlinks unless canonical is false."""
configured = os.environ.get("CODEX_SECURITY_STATE_DIR")
if configured:
path = Path(configured).expanduser()
@@ -21,6 +22,7 @@ def state_dir(*, canonical: bool = True) -> Path:
def resolve_scan_root(scan_root: str | None) -> Path:
+ """Resolve an explicit scan output root, defaulting to the scans directory under workbench state."""
return Path(scan_root).expanduser().resolve() if scan_root else state_dir() / "scans"
diff --git a/plugins/codex-security/scripts/workbench_cli.py b/plugins/codex-security/scripts/workbench_cli.py
index e2d2cf10c..acd772c35 100644
--- a/plugins/codex-security/scripts/workbench_cli.py
+++ b/plugins/codex-security/scripts/workbench_cli.py
@@ -37,6 +37,11 @@ def add_user_context(parser: argparse.ArgumentParser, *, required: bool = False)
def parse_args(description: str, *, inspection_only: bool = False) -> argparse.Namespace:
+ """Parse the workbench command line into the namespace consumed by its dispatcher.
+
+ For a full command, read UTF-8 user context from stdin when requested. In
+ inspection mode, recognized inspection arguments return before that read.
+ """
parser = argparse.ArgumentParser(description=description)
subparsers = parser.add_subparsers(dest="command", required=True)
diff --git a/plugins/codex-security/scripts/workbench_constants.py b/plugins/codex-security/scripts/workbench_constants.py
index a5441e42c..cc1452c6e 100644
--- a/plugins/codex-security/scripts/workbench_constants.py
+++ b/plugins/codex-security/scripts/workbench_constants.py
@@ -63,6 +63,7 @@ EMPTY_GIT_TREES = {
def optional_text(value: str | None, *, maximum: int | None = None) -> str | None:
+ """Strip surrounding whitespace, return None for blank text, and enforce the character limit."""
if value is None:
return None
normalized = value.strip()
@@ -72,6 +73,7 @@ def optional_text(value: str | None, *, maximum: int | None = None) -> str | Non
def positive_int(value: str) -> int:
+ """Parse a CLI count and reject values below one with an argparse validation error."""
parsed = int(value)
if parsed < 1:
raise argparse.ArgumentTypeError("expected a positive integer")
diff --git a/plugins/codex-security/scripts/workbench_coverage_receipts.py b/plugins/codex-security/scripts/workbench_coverage_receipts.py
index 8bdde383e..4b27b3997 100644
--- a/plugins/codex-security/scripts/workbench_coverage_receipts.py
+++ b/plugins/codex-security/scripts/workbench_coverage_receipts.py
@@ -108,6 +108,7 @@ def retain_recorded_receipt_ownership(
def resolve_coverage_receipts(
scan_dir: Path, item: dict[str, Any], worker: Any, relative: str
) -> Any:
+ """Qualify worker receipt references relative to their source checkpoint for use in parent coverage."""
refs = item.get("receiptRefs", [])
if not isinstance(refs, list):
return refs
diff --git a/plugins/codex-security/scripts/workbench_db.py b/plugins/codex-security/scripts/workbench_db.py
index aec50dbb6..e1661a406 100644
--- a/plugins/codex-security/scripts/workbench_db.py
+++ b/plugins/codex-security/scripts/workbench_db.py
@@ -175,6 +175,7 @@ def database_path() -> Path:
@contextmanager
def scan_completion_lock(scan_id: str) -> Any:
+ """Hold the cross-process lock for a scan ID until the context exits."""
lock_dir = state_dir() / "completion-locks"
create_private_directory(lock_dir)
lock_path = lock_dir / f"{require_uuid(scan_id, 'scan-id')}.lock"
@@ -238,6 +239,20 @@ def release_completion_file_lock(descriptor: int) -> None:
def connect(*, deferred: bool = False) -> sqlite3.Connection:
+ """Open the workbench SQLite database and bring its schema up to date.
+
+ Args:
+ deferred (bool): Let the first migration attempt defer its write lock.
+ Retries after lock contention use an immediate transaction.
+
+ Returns:
+ sqlite3.Connection: A caller-owned connection with named rows, foreign
+ keys enabled, and write-ahead logging.
+
+ Raises:
+ sqlite3.OperationalError: Opening or configuring the database fails, or
+ lock contention persists after retries.
+ """
path = database_path()
guidance = (
f"Workbench database: {path}. Ensure the state directory and SQLite journal files "
@@ -289,11 +304,13 @@ def requested_scan_file_paths(scan: sqlite3.Row) -> list[str]:
def requested_finding_scope(scan: sqlite3.Row) -> list[tuple[str, bool]]:
+ """Return requested paths paired with whether the stored recipe identified each one as a file."""
files = {PurePosixPath(path) for path in requested_scan_file_paths(scan)}
return [(path, PurePosixPath(path) in files) for path in requested_scan_paths(scan)]
def scan_contract(scan: sqlite3.Row) -> dict[str, Any]:
+ """Return the target identity, scope requirements, and diff target recorded for this scan."""
target = Path(scan["target_path"])
target_contract = {
"allowedKinds": expected_target_kinds(scan),
@@ -326,6 +343,7 @@ def scan_contract(scan: sqlite3.Row) -> dict[str, Any]:
def expected_coverage_mode(scan: sqlite3.Row) -> str:
+ """Return the coverage mode implied by the recorded scope, scan mode, and diff target kind."""
if scan["mode"] == "diff":
mode = {
"commit": "commit",
@@ -347,6 +365,7 @@ def expected_coverage_mode(scan: sqlite3.Row) -> str:
def workbench_completion_binding(
scan: sqlite3.Row, completed_at: str, manifest: dict[str, Any] | None = None
) -> dict[str, Any]:
+ """Build the scan ID, timestamps, producer, target, and scope used to bind output artifacts at completion."""
contract = scan_contract(scan)
target_contract = contract["target"]
plugin_version = loaded_plugin_version()
@@ -384,6 +403,7 @@ def workbench_completion_binding(
def verify_manifest_binding(scan: sqlite3.Row, manifest: dict[str, Any]) -> None:
+ """Raise SystemExit if the supplied manifest does not match the registered scan, target, or scope."""
manifest_scan = manifest.get("scan")
if not isinstance(manifest_scan, dict):
raise SystemExit("scan-manifest.json scan must be an object.")
@@ -471,6 +491,10 @@ def require_scan(connection: sqlite3.Connection, scan_id: str) -> sqlite3.Row:
def resolve_scan_id(connection: sqlite3.Connection, scan_id: str) -> str:
+ """Return a canonical UUID or resolve a unique scan ID prefix of at least eight characters.
+
+ Raise SystemExit for a prefix that is too short, ambiguous, or absent from the database.
+ """
try:
return str(uuid.UUID(scan_id))
except ValueError:
@@ -942,6 +966,7 @@ def _start_prompt_driven_scan(
def scan_local_file_digest(scan_dir: Path, relative_path: str) -> str:
+ """Return the SHA-256 of the scan-local file contents, prefixed with sha256:."""
digest = hashlib.sha256()
with open_scan_local_file(scan_dir, relative_path) as source:
for chunk in iter(lambda: source.read(1024 * 1024), b""):
@@ -950,6 +975,7 @@ def scan_local_file_digest(scan_dir: Path, relative_path: str) -> str:
def published_manifest_digest(scan_dir: Path, manifest: dict[str, Any]) -> str:
+ """Return the canonical manifest digest or raise SystemExit if the published bytes differ."""
canonical = (json.dumps(manifest, allow_nan=False, indent=2, sort_keys=True) + "\n").encode()
expected = f"sha256:{hashlib.sha256(canonical).hexdigest()}"
actual = scan_local_file_digest(scan_dir, ARTIFACTS["manifest"])
@@ -959,6 +985,7 @@ def published_manifest_digest(scan_dir: Path, manifest: dict[str, Any]) -> str:
def require_recorded_manifest_digest(scan: sqlite3.Row, scan_dir: Path) -> None:
+ """Raise SystemExit if the saved manifest differs from the digest recorded when the scan was sealed."""
expected = scan["seal_manifest_digest"]
if expected is None:
return
@@ -969,6 +996,7 @@ def require_recorded_manifest_digest(scan: sqlite3.Row, scan_dir: Path) -> None:
def pin_legacy_manifest_digest(
connection: sqlite3.Connection, scan_id: str, manifest_digest: str
) -> None:
+ """Record a previously missing digest in a write transaction, rejecting a conflict with an existing digest."""
connection.execute("BEGIN IMMEDIATE")
with connection:
scan = require_scan(connection, scan_id)
@@ -1044,6 +1072,7 @@ def finalize_scan_usage(connection: sqlite3.Connection, args: argparse.Namespace
def complete_budget_exhausted_scan(
connection: sqlite3.Connection, args: argparse.Namespace
) -> dict[str, Any]:
+ """Complete a running CLI Deep Scan using the measured cost and saved results after its budget is exhausted."""
scan_id = require_uuid(args.scan_id, "scan-id")
cost_json = parse_scan_cost(args.cost_json)
if cost_json is None:
@@ -1440,6 +1469,12 @@ def register_cli_scan(
*,
before_archive: Callable[[], None] | None = None,
) -> dict[str, Any]:
+ """Register a CLI scan and its selected target before execution begins.
+
+ Record the launch recipe and target identity with the new scan. When reusing
+ an output directory, coordinate archiving with registration so previous results
+ can still be located. Return the scan ID, contract, and target metadata.
+ """
repository = require_target(args.repository)
require_scannable_target(repository)
scan_dir = None
@@ -2583,6 +2618,11 @@ def scan_result(
*,
occurrence_id: str | None = None,
) -> dict[str, Any]:
+ """Assemble the workbench view of a saved scan, backfilling older finding details as needed.
+
+ An occurrence ID selects one finding from that scan. An occurrence belonging
+ to a different scan raises SystemExit.
+ """
backfill_legacy_finding_details(connection, scan)
scan = scan_history.scan_with_progress(connection, scan["id"])
artifact_rows = connection.execute(
@@ -2612,9 +2652,6 @@ def scan_result(
raise SystemExit("This finding does not belong to the selected scan.")
if all(row["id"] != occurrence["id"] for row in occurrence_rows):
occurrence_rows.append(occurrence)
- finding_count = connection.execute(
- "SELECT COUNT(*) FROM finding_occurrences WHERE scan_id = ?", (scan["id"],)
- ).fetchone()[0]
severity_counts = {
row["severity"]: row["count"]
for row in connection.execute(
@@ -2627,6 +2664,7 @@ def scan_result(
(scan["id"],),
)
}
+ finding_count = sum(severity_counts.values())
remediation_available, remediation_unavailable_reason = remediation_availability(scan)
progress_result, review_updated_at = scan_progress_result(connection, scan)
relations = scan_history.finding_relations(
diff --git a/plugins/codex-security/scripts/workbench_feedback.py b/plugins/codex-security/scripts/workbench_feedback.py
index 3f9201a25..605a8a792 100644
--- a/plugins/codex-security/scripts/workbench_feedback.py
+++ b/plugins/codex-security/scripts/workbench_feedback.py
@@ -20,6 +20,11 @@ from workbench_validation import bounded_output_text
def get_scan_feedback(connection: sqlite3.Connection, scan: sqlite3.Row) -> dict[str, Any]:
+ """Return reviewed false-positive decisions from other completed scans of the same target.
+
+ For each finding, include the latest decision only if it closes the finding as a
+ false positive with a nonblank reason. Prefer the root-control location in its preview.
+ """
rows = connection.execute(
"""
WITH ranked_decisions AS (
diff --git a/plugins/codex-security/scripts/workbench_finding_index.py b/plugins/codex-security/scripts/workbench_finding_index.py
index 0fecd9320..1e7969fa0 100644
--- a/plugins/codex-security/scripts/workbench_finding_index.py
+++ b/plugins/codex-security/scripts/workbench_finding_index.py
@@ -70,6 +70,7 @@ def index_findings(
document: dict[str, Any],
timestamp: str,
) -> None:
+ """Index findings for this scan and write occurrence and ordered location rows in the caller’s transaction."""
repository_id = connection.execute(
"SELECT target_id FROM scans WHERE id = ?", (scan_id,)
).fetchone()["target_id"]
diff --git a/plugins/codex-security/scripts/workbench_finding_workflows.py b/plugins/codex-security/scripts/workbench_finding_workflows.py
index ffa541b7d..18f9c0752 100644
--- a/plugins/codex-security/scripts/workbench_finding_workflows.py
+++ b/plugins/codex-security/scripts/workbench_finding_workflows.py
@@ -95,6 +95,7 @@ def _recorded_cost(value: str | None) -> dict[str, Any] | None:
def read_workflow(connection: sqlite3.Connection, workflow_id: str) -> dict[str, Any] | None:
+ """Return the stored stages, scope, and available scan cost, or None if the workflow ID is unknown."""
row = connection.execute(
"""SELECT w.*, s.cost_json FROM finding_workflows AS w
LEFT JOIN scans AS s ON s.id = w.scan_id AND s.scan_dir = w.scan_dir
@@ -128,6 +129,7 @@ def read_workflow(connection: sqlite3.Connection, workflow_id: str) -> dict[str,
def save_workflow(connection: sqlite3.Connection, state: dict[str, Any], timestamp: str) -> None:
+ """Insert or update the workflow bindings, scope, stage statuses, and saved results in the caller’s connection."""
values = {"id": state["id"]}
values.update({column: state.get(field) for field, column in WORKFLOW_BINDINGS.items()})
scope = state.get("scope", {})
@@ -160,6 +162,7 @@ def save_workflow(connection: sqlite3.Connection, state: dict[str, Any], timesta
def bind_workflow(state: dict[str, Any], binding: dict[str, Any]) -> None:
+ """Add bindings to the supplied state in place, raising SystemExit for unknown or conflicting fields."""
for field, value in binding.items():
if field not in WORKFLOW_BINDINGS and field != "scope":
raise SystemExit("Unknown workflow binding.")
@@ -206,6 +209,7 @@ def register_workflow_scan(
def finding_workflow(
connection: sqlite3.Connection, payload: dict[str, Any], timestamp: str
) -> dict[str, Any]:
+ """Dispatch a workflow request by ID and return its state, source snapshot, or review as the action specifies."""
workflow_id = payload["id"]
if not isinstance(workflow_id, str) or not workflow_id.strip():
raise SystemExit("workflowId must be a nonempty string.")
diff --git a/plugins/codex-security/scripts/workbench_native_indexes.py b/plugins/codex-security/scripts/workbench_native_indexes.py
index 1f64c5030..20b1e60d2 100644
--- a/plugins/codex-security/scripts/workbench_native_indexes.py
+++ b/plugins/codex-security/scripts/workbench_native_indexes.py
@@ -20,6 +20,7 @@ def list_global_findings(
connection: sqlite3.Connection,
args: argparse.Namespace,
) -> dict[str, Any]:
+ """Return a page of indexed findings after applying the requested filters, with nextOffset for continuation."""
limit = min(args.limit, FINDINGS_PAGE_MAX)
query = args.query.strip().casefold() if args.query else ""
findings = (
@@ -203,6 +204,7 @@ def list_repositories(
connection: sqlite3.Connection,
args: argparse.Namespace | None = None,
) -> dict[str, Any]:
+ """Return tracked targets with scan summaries, finding counts, and current checkout availability."""
by_target: dict[str, dict[str, Any]] = {}
for row in connection.execute(
f"""
diff --git a/plugins/codex-security/scripts/workbench_progress.py b/plugins/codex-security/scripts/workbench_progress.py
index 50a3b1d3d..7727bb8d3 100644
--- a/plugins/codex-security/scripts/workbench_progress.py
+++ b/plugins/codex-security/scripts/workbench_progress.py
@@ -16,6 +16,7 @@ from workbench_validation import optional_text, require_uuid, user_context_argum
def reportable_count(
current_phase: str, requested_phase: str | None, count: int | None
) -> int | None:
+ """Default a missing count to zero on entering validation or a later phase from an earlier phase."""
if count is None and requested_phase in PHASES[3:] and current_phase in PHASES[:3]:
return 0
return count
@@ -26,6 +27,7 @@ def update_context(
connection: sqlite3.Connection,
args: argparse.Namespace,
) -> dict[str, Any]:
+ """Update user context on a running scan and return the refreshed scan context in the same workbench."""
scan_id = require_uuid(args.scan_id, "scan-id")
context = user_context_argument(args)
connection.execute("BEGIN IMMEDIATE")
@@ -72,6 +74,12 @@ def update_progress(
connection: sqlite3.Connection,
args: argparse.Namespace,
) -> dict[str, Any]:
+ """Record phase and review counters for a running scan and return its updated context.
+
+ Check continuation and coordinator ownership where applicable. A new phase
+ starts with fresh phase counters. A new Deep Scan review pass must start
+ with zero completed items. Invalid progress raises SystemExit.
+ """
scan_id = require_uuid(args.scan_id, "scan-id")
model = optional_text(args.model, maximum=200)
reasoning_effort = optional_text(args.reasoning_effort, maximum=32)
diff --git a/plugins/codex-security/scripts/workbench_publication.py b/plugins/codex-security/scripts/workbench_publication.py
index d649fa693..b87630493 100644
--- a/plugins/codex-security/scripts/workbench_publication.py
+++ b/plugins/codex-security/scripts/workbench_publication.py
@@ -31,6 +31,7 @@ from validate_scan_contract import validate_contract
def destination_key(destination: Any) -> str:
+ """Encode exact provider-specific destination IDs into a stable key for matching issue receipts."""
if not isinstance(destination, dict):
raise SystemExit("Finding issues require an exact tracker destination.")
kind = destination.get("type")
@@ -59,6 +60,12 @@ def verify_publication_history(
scan_directory: str,
findings: list[dict[str, Any]],
) -> None:
+ """Require publication input to match the completed scan in local history.
+
+ Check the exact scan ID, directory, pinned manifest digest when present,
+ and the complete set of occurrence-to-finding associations. Raise
+ SystemExit if any of these disagree.
+ """
try:
scan = db.require_scan(connection, scan_id)
except SystemExit as exc:
@@ -109,6 +116,7 @@ def inspect_issue_receipts(
key: str,
finding_ids: list[str],
) -> list[dict[str, Any]]:
+ """Return receipts for the selected findings and destination, including receipts from older Linear tables."""
tables = {
row[0] for row in connection.execute("SELECT name FROM sqlite_master WHERE type = 'table'")
}
@@ -132,6 +140,7 @@ def inspect_issue_receipts(
def validate_issue_receipts(receipts: Any, selected: dict[str, str]) -> list[dict[str, Any]]:
+ """Return receipts bound to the selected finding occurrences or raise SystemExit on invalid receipt data."""
if not isinstance(receipts, list):
raise SystemExit("Finding issue receipts must be an array.")
for receipt in receipts:
@@ -367,6 +376,7 @@ def write_csv_export(
scan: sqlite3.Row,
findings_document: dict[str, Any],
) -> Path:
+ """Write indexed findings to exports/findings.csv, adding candidate IDs for Deep Scans, and return its path."""
scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
output = io.StringIO(newline="")
writer = csv.writer(output)
diff --git a/plugins/codex-security/scripts/workbench_remediation.py b/plugins/codex-security/scripts/workbench_remediation.py
index 6792bfa79..a0848f8e2 100644
--- a/plugins/codex-security/scripts/workbench_remediation.py
+++ b/plugins/codex-security/scripts/workbench_remediation.py
@@ -47,6 +47,7 @@ SCAN_STATUS_ERROR = "Remediation is available only for successfully completed sc
def require_available(connection: sqlite3.Connection, args: Any, require_scan: Any) -> None:
+ """Require a successfully completed scan for commands that act on a remediation request."""
if args.command not in COMMANDS:
return
occurrence = require_occurrence(connection, args.occurrence_id)
@@ -57,6 +58,7 @@ def require_available(connection: sqlite3.Connection, args: Any, require_scan: A
def require_request(
connection: sqlite3.Connection, request_id: str, occurrence: sqlite3.Row
) -> sqlite3.Row:
+ """Return the request row or raise SystemExit if the request is missing or belongs to a different occurrence."""
current = connection.execute(
"SELECT * FROM finding_remediation_attempts WHERE request_id = ?",
(request_id,),
@@ -67,6 +69,7 @@ def require_request(
def latest_attempt(connection: sqlite3.Connection, occurrence_id: str) -> sqlite3.Row | None:
+ """Return the newest remediation attempt for the occurrence, breaking timestamp ties by insertion order."""
return connection.execute(
"""
SELECT * FROM finding_remediation_attempts
@@ -344,6 +347,12 @@ def patch_metadata(
patch: bytes | None,
resolve_path: Callable[[str], str],
) -> tuple[str | None, str | None]:
+ """Resolve a remediation attempt’s patch path and SHA-256 digest.
+
+ For newly generated bytes, compute the digest and use the existing or
+ request-specific path. For a referenced patch, validate the supplied path
+ and digest. Raise SystemExit if either conflicts with a previously reviewed value.
+ """
path = args.patch_path
digest = args.patch_digest
if patch is not None:
@@ -371,6 +380,7 @@ def patch_metadata(
def same_file_version(
original: tuple[os.stat_result, int], current: tuple[os.stat_result, int]
) -> bool:
+ """Compare file identity, size, modification time, and the platform-specific change-time token."""
before, before_change = original
after, after_change = current
return (
@@ -382,6 +392,7 @@ def same_file_version(
def file_digest_and_version(source: BinaryIO, label: str) -> tuple[str, tuple[os.stat_result, int]]:
+ """Hash the remaining stream bytes and return their digest and file version, raising SystemExit if the file changes."""
before = scan_local_file_version(source.fileno())
digest = hashlib.sha256()
for chunk in iter(lambda: source.read(1024 * 1024), b""):
@@ -393,6 +404,7 @@ def file_digest_and_version(source: BinaryIO, label: str) -> tuple[str, tuple[os
def matching_patch_metadata(source: BinaryIO, expected_digest: str) -> tuple[os.stat_result, int]:
+ """Return the stable patch version or raise SystemExit if its bytes differ from expected_digest."""
digest, version = file_digest_and_version(source, "scan-local patch")
if digest != expected_digest:
raise SystemExit("Patch digest does not match the scan-local patch file.")
@@ -402,6 +414,7 @@ def matching_patch_metadata(source: BinaryIO, expected_digest: str) -> tuple[os.
def patch_manifest_version(
db: Any, scan: sqlite3.Row, scan_dir: Path
) -> tuple[str, tuple[os.stat_result, int]]:
+ """Verify the sealed scan manifest and return its byte digest and file version, including for legacy scans."""
manifest_path = db.ARTIFACTS["manifest"]
expected = scan["seal_manifest_digest"]
if expected is None:
diff --git a/plugins/codex-security/scripts/workbench_saved_results.py b/plugins/codex-security/scripts/workbench_saved_results.py
index f9ac96ee2..466d9f680 100644
--- a/plugins/codex-security/scripts/workbench_saved_results.py
+++ b/plugins/codex-security/scripts/workbench_saved_results.py
@@ -85,6 +85,7 @@ _RESERVED_ARTIFACT_PATHS = json.loads(
def threat_model_fields(db: Any, scan: sqlite3.Row) -> dict[str, Any]:
+ """Return availability and provenance for a saved threat model, reporting it as unavailable when verification fails."""
scan_dir = Path(scan["scan_dir"])
fields: dict[str, Any] = {"threatModelAvailable": False}
try:
@@ -352,6 +353,7 @@ def _recovery_source_digests(
def scan_results_recovery_needed(db: Any, connection: Any, scan: Any) -> bool:
+ """Return whether a failed, uncanceled scan has a publication error or saved evidence to recover."""
if scan["status"] != "failed" or scan["canceled_at"] is not None:
return False
warnings = json.loads(scan["completion_warnings_json"])
@@ -409,6 +411,7 @@ def preserve_parent_head_on_error(scan_dir: Path) -> Iterator[None]:
def coverage_for_comparison(db: Any, scan: Any) -> dict[str, Any]:
+ """Return coverage from the verified, sealed scan or raise SystemExit if the stored scan cannot be matched."""
if scan["seal_manifest_digest"] is None:
raise SystemExit("Only sealed scans can be compared.")
scan_dir = db.require_canonical_scan_directory(Path(scan["scan_dir"]))
@@ -894,6 +897,7 @@ def preserve_scan_results_locked(
def recover_scan_results(db: Any, connection: Any, args: Any) -> dict[str, Any]:
+ """Recover terminal results from saved checkpoints under the completion lock for a failed, uncanceled scan."""
scan_id = db.require_uuid(args.scan_id, "scan-id")
with db.scan_completion_lock(scan_id):
scan = db.require_scan(connection, scan_id)
@@ -926,6 +930,7 @@ def recover_scan_results(db: Any, connection: Any, args: Any) -> dict[str, Any]:
def preserve_scan_results(db: Any, connection: Any, args: Any) -> dict[str, Any]:
+ """Publish results for a stopped scan under its completion lock and return the updated scan context."""
scan_id = db.require_uuid(args.scan_id, "scan-id")
with db.scan_completion_lock(scan_id):
scan = db.require_scan(connection, scan_id)
@@ -1003,6 +1008,12 @@ def save_scan_artifact(db: Any, connection: Any, args: Any) -> dict[str, Any]:
def write_scan_draft(db: Any, connection: Any, args: Any) -> dict[str, Any]:
+ """Publish a staged draft for the current continuation of a running, unsealed scan.
+
+ Read the draft from its registered scan directory and bind it to the scan
+ before publishing it under the completion lock. Return the scan ID, the
+ draft_written status, and any warning about the optional threat model.
+ """
scan_id = db.require_uuid(args.scan_id, "scan-id")
with db.scan_completion_lock(scan_id):
scan = db.require_scan(connection, scan_id)
@@ -1320,6 +1331,7 @@ def cancel_scan_locked(db: Any, connection: Any, args: Any) -> dict[str, Any]:
def preserve_stopped_results_after_transition(db: Any, connection: Any, scan_id: str) -> None:
+ """Try to publish saved evidence after stopping a scan and record a warning if publication fails."""
try:
published = preserve_scan_results_locked(db, connection, scan_id)
except (ContractError, OSError, SystemExit, ValueError) as exc:
diff --git a/plugins/codex-security/scripts/workbench_scan_history.py b/plugins/codex-security/scripts/workbench_scan_history.py
index f6719df2e..76f8e3d09 100644
--- a/plugins/codex-security/scripts/workbench_scan_history.py
+++ b/plugins/codex-security/scripts/workbench_scan_history.py
@@ -43,6 +43,7 @@ def rename_scan(connection: sqlite3.Connection, scan: sqlite3.Row, name: str) ->
def scan_recipe(scan: sqlite3.Row) -> dict[str, Any]:
+ """Return the public launch recipe with its scan and parent IDs, raising SystemExit if the recipe was never saved."""
if scan["recipe_json"] is None:
raise SystemExit("This scan does not have a saved launch recipe.")
return {
@@ -55,6 +56,7 @@ def scan_recipe(scan: sqlite3.Row) -> dict[str, Any]:
def preserve_sealed_completion(
binding: dict[str, Any], manifest: dict[str, Any] | None
) -> dict[str, Any]:
+ """Copy the original timestamps and producer version from a sealed manifest into binding, then return it."""
manifest_scan = manifest.get("scan") if manifest is not None else None
if isinstance(manifest_scan, dict) and manifest_scan.get("sealedAt") is not None:
# Keep the original producer; finalization still validates schema, seal and owner.
@@ -147,6 +149,7 @@ def cli_scan_resume(
def coverage_summary_for_history(
wb: Any, scan: sqlite3.Row, canonical_scan_directory: Callable[[Path], Path]
) -> dict[str, Any]:
+ """Return the coverage mode and path filters for history after verifying the sealed scan data."""
scan_dir = canonical_scan_directory(Path(scan["scan_dir"]))
coverage_ref = "coverage.json"
try:
@@ -655,6 +658,7 @@ def compare_scans(
include_matching_inputs: bool = False,
require_matches: bool = False,
) -> dict[str, Any]:
+ """Compare completed scans of the same repository, returning finding groups and any inputs needed for matching."""
before = require_scan(connection, args.before_scan_id)
after = require_scan(connection, args.after_scan_id)
if before["id"] == after["id"]:
@@ -688,9 +692,7 @@ def compare_scans(
after_findings = _scan_findings(connection, after["id"])
matches = json.loads(cached["result_json"]) if cached is not None else None
saved_matches = matches["matches"] if matches is not None else []
- occurrences = {
- row["id"]: row for row in chain(before_findings.values(), after_findings.values())
- }
+ occurrences = before_findings | after_findings
aliases = _confirmed_finding_aliases(connection, occurrences)
groups = _finding_groups(before_findings, after_findings, saved_matches, aliases)
uncertain = (
@@ -709,17 +711,8 @@ def compare_scans(
}
for previous_rows, current_rows, match_reason in groups:
- previous = (
- min(previous_rows, key=lambda row: SEVERITY_ORDER[row["severity"]])
- if previous_rows
- else None
- )
- current = (
- min(current_rows, key=lambda row: SEVERITY_ORDER[row["severity"]])
- if current_rows
- else None
- )
- selected = current if current is not None else previous
+ selected_rows = current_rows or previous_rows
+ selected = min(selected_rows, key=lambda row: SEVERITY_ORDER[row["severity"]])
item = {
"findingId": selected["finding_id"],
"path": selected["relative_path"],
@@ -730,18 +723,12 @@ def compare_scans(
uncertain_reason = next(
(
uncertain[(side, row["id"])]
- for row in current_rows or previous_rows
+ for row in selected_rows
if (side, row["id"]) in uncertain
),
None,
)
- if previous is None:
- if uncertain_reason is None:
- status = "new"
- else:
- status = "unknown"
- item["reason"] = uncertain_reason
- elif current is not None:
+ if previous_rows and current_rows:
status = (
"reopened"
if any(
@@ -756,6 +743,8 @@ def compare_scans(
elif uncertain_reason is not None:
status = "unknown"
item["reason"] = uncertain_reason
+ elif current_rows:
+ status = "new"
elif not all(
scan_covers_path(
after,
@@ -776,17 +765,17 @@ def compare_scans(
status = "not_observed"
item["reason"] = "Not observed in the later scan; remediation has not been verified."
if len(previous_rows) == 1:
- item["beforeOccurrenceId"] = previous["id"]
+ item["beforeOccurrenceId"] = previous_rows[0]["id"]
elif previous_rows:
item["beforeOccurrenceIds"] = [row["id"] for row in previous_rows]
if len(current_rows) == 1:
- item["afterOccurrenceId"] = current["id"]
+ item["afterOccurrenceId"] = current_rows[0]["id"]
elif current_rows:
item["afterOccurrenceIds"] = [row["id"] for row in current_rows]
- if current is not None:
+ if current_rows:
item["triage"] = {
- "closeReason": current["close_reason"],
- "status": current["triage_status"],
+ "closeReason": selected["close_reason"],
+ "status": selected["triage_status"],
}
item["status"] = status
findings.append(item)
@@ -860,8 +849,10 @@ def save_scan_comparison(
if not _same_repository(before, after):
raise SystemExit("Semantic scan comparisons require the same repository target.")
read_coverage(after)
- before_findings = _scan_findings(connection, before["id"])
- after_findings = _scan_findings(connection, after["id"])
+ allowed = {
+ "before": set(_scan_findings(connection, before["id"])),
+ "after": set(_scan_findings(connection, after["id"])),
+ }
matches_json = (
sys.stdin.read() if getattr(args, "matches_json_stdin", False) else args.matches_json
)
@@ -879,10 +870,6 @@ def save_scan_comparison(
not isinstance(payload.get(key, []), list) for key in ("matches", "uncertain", "related")
):
raise SystemExit("Scan comparison matches must contain matches and uncertain arrays.")
- allowed = {
- "before": {row["id"] for row in before_findings.values()},
- "after": {row["id"] for row in after_findings.values()},
- }
consumed: dict[str, dict[str, int]] = {"before": {}, "after": {}}
for group, match in enumerate(payload["matches"]):
if (
@@ -1177,10 +1164,7 @@ def _finding_groups(
matches: list[dict[str, Any]],
aliases: dict[str, str],
) -> list[tuple[list[sqlite3.Row], list[sqlite3.Row], str | None]]:
- rows = {
- side: {row["id"]: row for row in findings.values()}
- for side, findings in (("before", before_findings), ("after", after_findings))
- }
+ rows = {"before": before_findings, "after": after_findings}
groups: dict[str, tuple[list[sqlite3.Row], list[sqlite3.Row], list[str]]] = {}
def group(row: sqlite3.Row) -> tuple[list[sqlite3.Row], list[sqlite3.Row], list[str]]:
@@ -1308,6 +1292,7 @@ def finding_occurrence_conditions(
def _scan_findings(connection: sqlite3.Connection, scan_id: str) -> dict[str, sqlite3.Row]:
+ """Index one scan's finding rows by the occurrence IDs used in comparisons."""
rows = connection.execute(
"""
SELECT occurrences.*,
@@ -1326,7 +1311,7 @@ def _scan_findings(connection: sqlite3.Connection, scan_id: str) -> dict[str, sq
""",
(scan_id,),
)
- return {row["finding_id"]: row for row in rows}
+ return {row["id"]: row for row in rows}
def scan_covers_path(
@@ -1336,6 +1321,7 @@ def scan_covers_path(
path: str | None,
coverage: dict[str, Any],
) -> bool:
+ """Check whether a completed scan of this target included the path after applying all recorded exclusions."""
if scan["status"] != "complete" or scan["target_id"] != target_id:
return False
if not isinstance(path, str) or not path:
diff --git a/plugins/codex-security/scripts/workbench_scan_start.py b/plugins/codex-security/scripts/workbench_scan_start.py
index 03b09a41d..8a93b69cf 100644
--- a/plugins/codex-security/scripts/workbench_scan_start.py
+++ b/plugins/codex-security/scripts/workbench_scan_start.py
@@ -30,6 +30,7 @@ from workbench_validation import optional_text, read_json_object
def safe_segment(value: str) -> str:
+ """Normalize a filename segment, falling back to ``scan`` for an empty result."""
segment = re.sub(r"[^\w.-]", "-", value)
if segment != value:
segment = segment.strip("-")
@@ -37,10 +38,12 @@ def safe_segment(value: str) -> str:
def compact_timestamp() -> str:
+ """Return the current UTC time in YYYYMMDDTHHMMSSZ format."""
return datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
def loaded_plugin_version() -> str:
+ """Read the required version string from the loaded plugin's manifest."""
manifest = read_json_object(
Path(__file__).resolve().parents[1] / ".codex-plugin" / "plugin.json"
)
@@ -56,6 +59,11 @@ def scan_target_identity(
*,
metadata: os.stat_result | None = None,
) -> tuple[str, str | None, int | str, int | str]:
+ """Return revision, content digest, device ID, and inode for scan registration.
+
+ An explicit diff uses its head revision and a None digest. Other targets use
+ the worktree or directory digest. Device and inode use the SQLite-safe representation.
+ """
if metadata is None:
metadata = target.stat()
revision = diff_target["headRevision"] if diff_target else git_revision(target)
@@ -77,6 +85,7 @@ def scan_target_identity(
def scan_diff_identity(
diff_target: dict[str, str] | None,
) -> tuple[str | None, str | None, str | None, str | None]:
+ """Return kind, base, head, and optional digest in database order, or four nulls."""
if diff_target is None:
return (None, None, None, None)
return (
@@ -88,6 +97,7 @@ def scan_diff_identity(
def stored_diff_target(row: sqlite3.Row) -> dict[str, str] | None:
+ """Rebuild the diff target from a scan row, or return None for a full scan."""
if not row["diff_target_kind"]:
return None
target = {
@@ -110,6 +120,7 @@ def archive_scan(
*,
before_archive: Callable[[], None] | None = None,
) -> Iterator[Path | None]:
+ """Yield the archive directory while preparing the original scan path for reuse."""
archived_scan_dir = (
canonical_directory(Path(args.archived_scan_dir).expanduser())
if args.archived_scan_dir is not None
diff --git a/plugins/codex-security/scripts/workbench_scan_usage.py b/plugins/codex-security/scripts/workbench_scan_usage.py
index a0cb5b902..01b4d6e64 100644
--- a/plugins/codex-security/scripts/workbench_scan_usage.py
+++ b/plugins/codex-security/scripts/workbench_scan_usage.py
@@ -30,6 +30,8 @@ STATE_DATABASE_TIMEOUT_SECONDS = 1.0
@dataclass(frozen=True)
class RolloutSession:
+ """Associate a thread and its optional parent with the path of the rollout used for usage accounting."""
+
thread_id: str
parent_thread_id: str | None
path: Path
@@ -37,6 +39,8 @@ class RolloutSession:
@dataclass
class RolloutUsage:
+ """Collect token counts, their update time, warnings, and account rate-limit observations for a rollout."""
+
tokens: dict[str, int]
warnings: set[str]
tokens_updated_at: datetime | None
@@ -89,7 +93,12 @@ def collect_scan_usage(
completed_at: str | None = None,
completed_turn_id: str | None = None,
) -> dict[str, Any]:
- """Count attributable receipts and flag observable gaps inside the scan window."""
+ """Count attributable session receipts during the scan window and report missing coverage.
+
+ The optional thread and completion arguments identify the finishing turn when
+ the scan record alone is insufficient. Return an unavailable usage record when
+ the window, Codex state, or relevant threads cannot be established.
+ """
roots = _scan_root_thread_ids(connection, scan, thread_id)
parent_ids = set(_scan_root_thread_ids(connection, scan, thread_id, include_workers=False))
diff --git a/plugins/codex-security/scripts/workbench_schema.py b/plugins/codex-security/scripts/workbench_schema.py
index 526fb38f5..990829735 100644
--- a/plugins/codex-security/scripts/workbench_schema.py
+++ b/plugins/codex-security/scripts/workbench_schema.py
@@ -52,6 +52,12 @@ def apply_migrations(
*,
immediate: bool = False,
) -> None:
+ """Apply missing schema versions and repair supported historical migrations.
+
+ Commit pending work on the connection before starting the migration transaction.
+ Set immediate to acquire the SQLite write lock up front. The backfill callback
+ links older scans and workspaces to stable targets when required.
+ """
connection.commit()
connection.execute("BEGIN IMMEDIATE" if immediate else "BEGIN")
with connection:
@@ -178,6 +184,11 @@ def repair_thread_scoped_workspaces_migration(connection: sqlite3.Connection) ->
def repair_stable_targets_migration(connection: sqlite3.Connection) -> bool:
+ """Repair a partial target-ID migration and return whether the schema required repair.
+
+ Create missing target tables, columns, and indexes. Clear scan references
+ to missing target records so they can be backfilled.
+ """
workspace_columns = {row["name"] for row in connection.execute("PRAGMA table_info(workspaces)")}
scan_columns = {row["name"] for row in connection.execute("PRAGMA table_info(scans)")}
existing_objects = {
@@ -215,6 +226,7 @@ def repair_stable_targets_migration(connection: sqlite3.Connection) -> bool:
def repair_additive_migration(connection: sqlite3.Connection, version: int) -> None:
+ """Replay the column additions from one historical migration, skipping columns already present."""
sql = next(sql for migration_version, _, sql in MIGRATIONS if migration_version == version)
for statement in sql_statements(sql):
add_migration_column(connection, statement)
diff --git a/plugins/codex-security/scripts/workbench_setup.py b/plugins/codex-security/scripts/workbench_setup.py
index 6fa406952..fcfeafede 100644
--- a/plugins/codex-security/scripts/workbench_setup.py
+++ b/plugins/codex-security/scripts/workbench_setup.py
@@ -22,6 +22,7 @@ from workbench_target import (
def require_target(value: str) -> Path:
+ """Return the resolved local directory or raise SystemExit if the supplied path is relative or missing."""
expanded = Path(value).expanduser()
if not expanded.is_absolute():
raise SystemExit("Scan target must be an absolute local directory path.")
@@ -32,6 +33,7 @@ def require_target(value: str) -> Path:
def inspect_target(target: Path) -> dict[str, Any]:
+ """Return the target path, display name, and local Git metadata used by setup."""
return {
"displayName": target.name,
"targetMetadata": git_target_metadata(target),
@@ -40,6 +42,7 @@ def inspect_target(target: Path) -> dict[str, Any]:
def resolve_git_commit(target: Path, revision: str, label: str) -> str:
+ """Resolve a revision to a local commit ID or raise SystemExit with the caller’s label."""
value = optional_text(revision, maximum=512)
if not value:
raise SystemExit(f"{label} is required.")
@@ -62,6 +65,11 @@ def require_diff_target(
head_revision: str | None,
content_digest: str | None,
) -> dict[str, str]:
+ """Resolve the selected Git change to its base and head commits.
+
+ For a working-tree selection, also return the current content digest and reject
+ changes since selection. Invalid or stale selections raise SystemExit.
+ """
current_head = require_review_changes_target(target)
if kind not in DIFF_TARGET_KINDS:
raise SystemExit("Choose which Git changes to review before starting a diff scan.")
@@ -131,6 +139,7 @@ def inspect_setup_values(
diff_head_revision: str | None,
diff_content_digest: str | None,
) -> dict[str, Any]:
+ """Validate the target, scope, and scan mode and return their normalized values and resolved diff target."""
target = require_target(target_path)
inspected = require_scannable_target(target)
normalized_scope = require_scope(scope, mode, target)
@@ -165,6 +174,7 @@ def inspect_setup_values(
def require_review_changes_target(target: Path) -> str:
+ """Return the checked-out revision or raise SystemExit if target is not the worktree root."""
revision = require_git_worktree_head(target)
repository_root = git_output(target, "rev-parse", "--show-toplevel")
if repository_root is None or not Path(repository_root).samefile(target):
@@ -175,6 +185,7 @@ def require_review_changes_target(target: Path) -> str:
def require_scannable_target(target: Path) -> dict[str, Any]:
+ """Return the inspected target metadata, rejecting a Git repository that has no checked-out worktree."""
inspected = inspect_target(target)
metadata = inspected["targetMetadata"]
if metadata["isGit"] and not metadata["isWorktree"]:
@@ -185,6 +196,7 @@ def require_scannable_target(target: Path) -> dict[str, Any]:
def require_scope(scope: str, mode: str, target: Path) -> str:
+ """Return the existing scan directory relative to the target, requiring the whole repository for deep mode."""
value = scope if scope.strip() else "."
requested_scope = Path(value)
if "\\" in value and (os.name != "nt" or not requested_scope.is_absolute()):
diff --git a/plugins/codex-security/scripts/workbench_source_excerpt.py b/plugins/codex-security/scripts/workbench_source_excerpt.py
index 6faaccf28..5efcb3430 100644
--- a/plugins/codex-security/scripts/workbench_source_excerpt.py
+++ b/plugins/codex-security/scripts/workbench_source_excerpt.py
@@ -30,6 +30,18 @@ def finding_source_excerpt(
locations: list[dict[str, Any]],
scopes: list[str],
) -> str | None:
+ """Return numbered context from a finding location at the scanned Git revision.
+
+ Args:
+ scan: Saved scan row with its revision, snapshot digest, and scope metadata.
+ target: Local target directory in which to resolve the recorded Git objects.
+ locations: Displayed finding locations, using one-based line numbers.
+ scopes: Selected paths used to interpret saved source scopes.
+
+ Returns:
+ A bounded excerpt, or None when a location, scope, or local blob cannot
+ supply it. Root-control locations have priority.
+ """
if target is None or not locations or scan["target_revision"] == "unversioned":
return None
snapshot = scan["target_snapshot_digest"]
@@ -116,6 +128,7 @@ def finding_source_excerpt(
def scanned_source_text(repository: Path, object_id: str) -> str | None:
+ """Decode the locally available Git blob as UTF-8 with replacement, or return None on lookup failure."""
try:
content = offline_git_bytes(repository, "cat-file", "blob", object_id)
except (OSError, RuntimeError, SystemExit):
diff --git a/plugins/codex-security/scripts/workbench_source_scopes.py b/plugins/codex-security/scripts/workbench_source_scopes.py
index 88198e0c4..bb0060b32 100644
--- a/plugins/codex-security/scripts/workbench_source_scopes.py
+++ b/plugins/codex-security/scripts/workbench_source_scopes.py
@@ -26,6 +26,7 @@ OBJECT_ID = re.compile(r"(?:[0-9a-f]{40}|[0-9a-f]{64})\Z")
def expected_target_kinds(scan: sqlite3.Row) -> list[str]:
+ """Return the manifest target kinds compatible with the stored scan mode, revision, and snapshot digest."""
if scan["mode"] == "diff":
return ["git_diff"]
if scan["target_revision"] == "unversioned":
@@ -38,6 +39,7 @@ def expected_target_kinds(scan: sqlite3.Row) -> list[str]:
def requested_scan_paths(scan: sqlite3.Row) -> list[str]:
+ """Return the explicit paths in the saved launch recipe, falling back to the scan’s original scope."""
if "recipe_json" in scan.keys() and scan["recipe_json"] is not None:
recipe = json.loads(scan["recipe_json"], parse_constant=reject_non_finite_json)
target = recipe["target"]
@@ -47,6 +49,7 @@ def requested_scan_paths(scan: sqlite3.Row) -> list[str]:
def public_scan_recipe(scan: sqlite3.Row) -> dict[str, Any]:
+ """Return the decoded launch recipe with the internal file-scope metadata removed."""
recipe = json.loads(scan["recipe_json"], parse_constant=reject_non_finite_json)
recipe.pop("_codexSecurityFileScopes", None)
return recipe
@@ -62,6 +65,7 @@ def relative_path(value: str) -> PurePosixPath | None:
def safe_source_path(target: Path, value: str) -> Path | None:
+ """Resolve a repository-relative POSIX path and return None if it is invalid or resolves outside the target."""
parsed = relative_path(value)
if parsed is None:
return None
@@ -74,6 +78,7 @@ def safe_source_path(target: Path, value: str) -> Path | None:
def offline_git_bytes(repository: Path, *arguments: str) -> bytes | None:
+ """Return raw stdout for a successful offline Git command with replacement objects disabled, otherwise None."""
result = git_command(
repository,
*arguments,
@@ -86,6 +91,7 @@ def offline_git_bytes(repository: Path, *arguments: str) -> bytes | None:
@cache
def tree_entries(repository: Path, tree: str) -> dict[str, tuple[tuple[str, str, str], ...]] | None:
+ """Index a Git tree by normalized name, retaining every original name, entry kind, and object ID in each group."""
content = offline_git_bytes(repository, "ls-tree", "-z", tree)
if content is None:
return None
@@ -217,6 +223,12 @@ def capture_source_scopes(
*,
diff_target_kind: str | None = None,
) -> dict[str, Any]:
+ """Bind requested paths to the local Git objects that may supply excerpts later.
+
+ Return the revision and the file or tree IDs that can be verified locally.
+ A working-tree diff, dirty snapshot, or replacement ref leaves the scope list
+ empty. A path that cannot be bound adds no authority to read other paths.
+ """
revision, snapshot = target_identity[:2]
result: dict[str, Any] = {"version": 1, "revision": revision, "scopes": []}
# HEAD cannot represent the uncommitted bytes reviewed by a working-tree scan.
@@ -267,6 +279,11 @@ def capture_source_scopes(
def load_source_scopes(
scan: sqlite3.Row, target: Path, requested: list[str]
) -> tuple[Path, str, list[dict[str, str]]] | None:
+ """Return the repository, tree ID, and valid source scopes, or None when none can be established.
+
+ Use saved object IDs for current records. For a legacy scan, reconstruct only
+ unambiguous entries from its original revision and respect any recorded file kinds.
+ """
kind = scan["diff_target_kind"] if "diff_target_kind" in scan.keys() else None
if kind == "working_tree" or (
"mode" in scan.keys() and scan["mode"] == "diff" and kind not in ("commit", "range")
@@ -343,6 +360,7 @@ def load_source_scopes(
def source_object_for_path(
repository: Path, tree: str, target: Path, value: str, scope: dict[str, str]
) -> str | None:
+ """Return the Git blob ID for a file covered by the recorded scope, or None if the path cannot be verified."""
path = relative_path(value)
if path is None or safe_source_path(target, value) is None:
return None
diff --git a/plugins/codex-security/scripts/workbench_target.py b/plugins/codex-security/scripts/workbench_target.py
index 74b98e9fe..55ce17a60 100644
--- a/plugins/codex-security/scripts/workbench_target.py
+++ b/plugins/codex-security/scripts/workbench_target.py
@@ -44,6 +44,11 @@ def committed_diff_snapshot_digest(kind: str, base_revision: str, head_revision:
def diff_snapshot_digest(scan: sqlite3.Row, manifest: dict[str, Any] | None) -> str | None:
+ """Return the content identity used for a stored diff, or None when unavailable.
+
+ Working-tree scans use their recorded content digest. Commit and range scans
+ reuse the sealed manifest value during recovery or derive a digest from both revisions.
+ """
if scan["diff_target_kind"] == "working_tree":
return scan["diff_content_digest"]
if scan["diff_target_kind"] in {"commit", "range"}:
@@ -67,6 +72,7 @@ def git_output(
work_tree: Path | None = None,
offline: bool = False,
) -> str | None:
+ """Return decoded Git stdout with one trailing newline removed, or None on failure or empty output."""
completed = git_command(
target, *args, text=False, git_dir=git_dir, work_tree=work_tree, offline=offline
)
@@ -275,6 +281,12 @@ def git_command(
environment_overrides: dict[str, str] | None = None,
offline: bool = False,
) -> subprocess.CompletedProcess[str] | subprocess.CompletedProcess[bytes]:
+ """Run Git against target and return the completed process with its exit status.
+
+ Pass git_dir and work_tree together to select an explicit checkout. Set
+ offline to disable transports and lazy fetches. The text flag selects
+ decoded or binary output, and stdout_file can redirect it to a file.
+ """
if (git_dir is None) != (work_tree is None):
raise ValueError("git_dir and work_tree must be provided together")
environment = os.environ.copy()
@@ -527,6 +539,19 @@ def update_digest_field(digest: Any, label: bytes, value: bytes) -> None:
digest.update(value)
+def _update_regular_file_digest(digest: Any, path: Path, prefix: bytes = b"") -> None:
+ """Record the file kind, byte count, and SHA-256 in the snapshot digest."""
+ content = hashlib.sha256()
+ size = 0
+ with path.open("rb") as handle:
+ for chunk in iter(lambda: handle.read(1024 * 1024), b""):
+ content.update(chunk)
+ size += len(chunk)
+ update_digest_field(digest, prefix + b"kind", b"file")
+ update_digest_field(digest, prefix + b"size", str(size).encode())
+ update_digest_field(digest, prefix + b"content-sha256", content.digest())
+
+
def _visible_git_character(char: str) -> str:
if char in "\n\t" or unicodedata.category(char) not in {"Cc", "Cf"}:
return char
@@ -569,6 +594,7 @@ def _update_digest_field_from_git(
def worktree_content_digest(target: Path) -> str:
+ """Return the worktree digest for the selected path after checking the state of its submodules."""
require_clean_submodule_worktrees(target)
repository, pathspec = git_worktree_context(target)
return worktree_content_digest_for_context(repository, pathspec)
@@ -582,6 +608,7 @@ def remediation_checkout_snapshot(
"Repository HEAD changed. Regenerate the remediation patch against the current checkout."
),
) -> tuple[str, str | None]:
+ """Return the current revision and content digest after verifying the recorded checkout identity and required revision."""
target = require_scan_target_identity(scan)
revision = git_revision(target)
required_revision = expected_revision or scan["target_revision"]
@@ -706,26 +733,10 @@ def worktree_content_digest_for_context(
directory_content_digest(path.resolve()).encode(),
)
elif stat.S_ISREG(metadata.st_mode):
- content_digest = hashlib.sha256()
- content_size = 0
try:
- with path.open("rb") as handle:
- for chunk in iter(lambda: handle.read(1024 * 1024), b""):
- content_digest.update(chunk)
- content_size += len(chunk)
+ _update_regular_file_digest(digest, path, prefix=b"untracked-")
except OSError as exc:
raise SystemExit(f"Could not read untracked file: {relative_path}") from exc
- update_digest_field(digest, b"untracked-kind", b"file")
- update_digest_field(
- digest,
- b"untracked-size",
- str(content_size).encode(),
- )
- update_digest_field(
- digest,
- b"untracked-content-sha256",
- content_digest.digest(),
- )
else:
raise SystemExit(f"Unsupported untracked file type: {relative_path}")
return f"codex-security-snapshot/v1:sha256:{digest.hexdigest()}"
@@ -1084,18 +1095,10 @@ def directory_content_digest(
elif stat.S_ISDIR(mode):
update_digest_field(digest, b"kind", b"directory")
elif stat.S_ISREG(mode):
- content_digest = hashlib.sha256()
- content_size = 0
try:
- with path.open("rb") as handle:
- for chunk in iter(lambda: handle.read(1024 * 1024), b""):
- content_digest.update(chunk)
- content_size += len(chunk)
+ _update_regular_file_digest(digest, path)
except OSError as exc:
raise UnreadableLocalFile(f"Could not read local file: {relative_path}") from exc
- update_digest_field(digest, b"kind", b"file")
- update_digest_field(digest, b"size", str(content_size).encode())
- update_digest_field(digest, b"content-sha256", content_digest.digest())
else:
raise UnsupportedLocalFileType(f"Unsupported local file type: {relative_path}")
return f"codex-security-snapshot/v1:sha256:{digest.hexdigest()}"
@@ -1311,6 +1314,7 @@ def require_remediation_target(value: str) -> Path:
def require_scan_target_identity(scan: sqlite3.Row) -> Path:
+ """Return the recorded checkout path or raise SystemExit if it no longer identifies the original directory."""
target = require_remediation_target(scan["target_path"])
expected_inode = scan["target_inode"]
if expected_inode is None:
diff --git a/plugins/codex-security/scripts/workbench_target_state.py b/plugins/codex-security/scripts/workbench_target_state.py
index 7d24a5f20..23daebb95 100644
--- a/plugins/codex-security/scripts/workbench_target_state.py
+++ b/plugins/codex-security/scripts/workbench_target_state.py
@@ -10,11 +10,13 @@ from pathlib import Path
def stable_target_id(target: Path) -> str:
+ """Hash the supplied path spelling into the workbench ID for a local workspace."""
digest = hashlib.sha256(f"local-workspace\0{target}".encode()).hexdigest()
return f"target_sha256_{digest}"
def backfill_security_targets(connection: sqlite3.Connection) -> None:
+ """Fill missing target IDs on scans and workspaces in the caller’s transaction."""
rows = connection.execute(
"""
SELECT target_path FROM workspaces WHERE target_path IS NOT NULL
@@ -36,6 +38,7 @@ def backfill_security_targets(connection: sqlite3.Connection) -> None:
def ensure_security_target(connection: sqlite3.Connection, target_path: str) -> str:
+ """Return the ID already associated with the path or insert a deterministic ID for it."""
existing = connection.execute(
"SELECT id FROM security_targets WHERE current_path = ?",
(target_path,),
diff --git a/plugins/codex-security/scripts/workbench_validation.py b/plugins/codex-security/scripts/workbench_validation.py
index cc9f51cf5..df5b1e6db 100644
--- a/plugins/codex-security/scripts/workbench_validation.py
+++ b/plugins/codex-security/scripts/workbench_validation.py
@@ -27,6 +27,7 @@ reject_non_finite_json = finalizer._reject_non_finite_json
def read_json_object(path: Path) -> dict[str, Any]:
+ """Read a UTF-8 JSON object from path, raising SystemExit on read errors, malformed JSON, or another top-level type."""
try:
payload = json.loads(
path.read_text(encoding="utf-8"),
@@ -53,6 +54,7 @@ def timestamp_key(value: str) -> datetime:
def require_uuid(value: str, label: str) -> str:
+ """Return the standard hyphenated UUID text or raise SystemExit using label to identify the invalid argument."""
try:
return str(uuid.UUID(value))
except ValueError as exc:
@@ -67,6 +69,7 @@ path_within_scope = finalizer.path_within_scope
def require_close_note(close_reason: str | None, note: str | None) -> None:
+ """Require a note when closing a finding as a false positive or when declining a fix."""
if note is None and close_reason == "false_positive":
raise SystemExit("Explain why this finding is a false positive.")
if note is None and close_reason == "wont_fix":
@@ -201,6 +204,11 @@ def _valid_measured_scan_usage(usage: object) -> bool:
def parse_scan_cost(value: str | None) -> str | None:
+ """Return compact JSON for valid measured usage or a legacy cost estimate.
+
+ None means cost data was omitted. Invalid JSON, nonfinite numbers, or an
+ unsupported cost record raise SystemExit.
+ """
if value is None:
return None
try:
@@ -223,11 +231,13 @@ def parse_scan_cost(value: str | None) -> str | None:
def bounded_output_text(value: Any, maximum_bytes: int) -> str:
+ """Return the prefix of the stringified value that fits in maximum_bytes of UTF-8 without splitting a character."""
encoded = str(value).encode("utf-8")[:maximum_bytes]
return encoded.decode("utf-8", errors="ignore")
def require_occurrence(connection: sqlite3.Connection, occurrence_id: str) -> sqlite3.Row:
+ """Return the finding occurrence row or raise SystemExit if its ID is missing or unknown."""
occurrence_id = optional_text(occurrence_id, maximum=256)
if occurrence_id is None:
raise SystemExit("occurrence-id is required.")
diff --git a/plugins/codex-security/skills/threat-model-visualize/scripts/build_explorer.py b/plugins/codex-security/skills/threat-model-visualize/scripts/build_explorer.py
index 666474c7c..94aaeeb42 100644
--- a/plugins/codex-security/skills/threat-model-visualize/scripts/build_explorer.py
+++ b/plugins/codex-security/skills/threat-model-visualize/scripts/build_explorer.py
@@ -16,7 +16,20 @@ def require(condition, message):
def validate(model, assessment_bytes: bytes):
+ """Check the explorer graph and its citations against the assessment before rendering.
+
+ Args:
+ model (dict): Parsed explorer JSON containing the graph, scenarios, and evidence.
+ assessment_bytes (bytes): Original UTF-8 bytes used to match quotations, line ranges,
+ and the optional assessment digest. Preserve the original line endings.
+
+ Raises:
+ ValueError: A graph relationship, layout value, or evidence check fails.
+ KeyError: A required field is missing when accessed by name.
+ """
+
def indexed(key, default=None):
+ """Index a model collection by its unique, nonempty string IDs."""
items = model.get(key, default)
require(isinstance(items, list), f"{key} must be a list")
ids = [item.get("id") for item in items]
@@ -148,6 +161,7 @@ def validate(model, assessment_bytes: bytes):
source_roles(model.get("participants", []), "participants", participant=True)
def chain(item, scenario_id, route_id):
+ """Return the edge IDs of a connected route after checking its assessment references."""
ids = item.get("edges", [])
require(
isinstance(ids, list) and ids and all(i in edges for i in ids),
@@ -163,6 +177,7 @@ def validate(model, assessment_bytes: bytes):
return ids
def applicable_routes(control, routes, sources):
+ """Return the routes selected by both the control and any sources it targets."""
return [
route
for route in routes
@@ -482,6 +497,7 @@ def validate(model, assessment_bytes: bytes):
def embedded(value):
+ """Encode a value as JSON for an HTML script element, escaping HTML delimiters."""
return (
json.dumps(value, ensure_ascii=False, allow_nan=False)
.replace("<", "\\u003c")
@@ -491,7 +507,10 @@ def embedded(value):
def enters_node(start, end, node):
- """Intersect the segment's parameter interval with the open box on each axis."""
+ """Return whether the segment between two (x, y) points enters the open node rectangle.
+
+ Contact with an edge or corner alone is allowed when routing a connector.
+ """
enter, leave = 0, 1
for a, b, low, size in zip(start, end, (node["x"], node["y"]), (node["w"], node["h"])):
high = low + size
@@ -505,6 +524,7 @@ def enters_node(start, end, node):
def connector_warnings(model):
+ """Yield layout warnings for diagonal end bends and connectors that enter node interiors."""
for edge in model["edges"]:
segments = [(a, b) for a, b in pairwise(edge["points"]) if a != b]
diagonal = [a[0] != b[0] and a[1] != b[1] for a, b in segments]
@@ -518,6 +538,7 @@ def connector_warnings(model):
def main():
+ """Validate the assessment and model, write a self-contained HTML file, and print layout warnings."""
parser = argparse.ArgumentParser(description=__doc__)
parser.add_argument("model", type=Path)
parser.add_argument("--assessment", required=True, type=Path)
diff --git a/plugins/codex-security/tests/conftest.py b/plugins/codex-security/tests/conftest.py
index c7b038c7d..1b9736de1 100644
--- a/plugins/codex-security/tests/conftest.py
+++ b/plugins/codex-security/tests/conftest.py
@@ -1,3 +1,5 @@
+"""Provide an isolated in-memory workbench database for each test using a shared migrated schema."""
+
from __future__ import annotations
import runpy
@@ -18,6 +20,7 @@ from publication_fixtures import ( # noqa: F401 -- pytest discovers these share
@pytest.fixture(scope="session")
def workbench_api():
+ """Return the script globals used to exercise the workbench directly without starting its CLI."""
script = Path(__file__).resolve().parents[1] / "scripts" / "workbench_db.py"
return runpy.run_path(str(script), run_name="codex_security_test_workbench")
@@ -34,6 +37,7 @@ def workbench_schema(workbench_api):
@pytest.fixture
def workbench_db(workbench_schema):
+ """Yield a fresh in-memory copy of the migrated schema with foreign keys enabled and named rows."""
with closing(sqlite3.connect(":memory:")) as connection:
connection.row_factory = sqlite3.Row
connection.execute("PRAGMA foreign_keys = ON")
diff --git a/plugins/codex-security/tests/deep_deadline_crash.py b/plugins/codex-security/tests/deep_deadline_crash.py
index c5dda0a3b..e2a6fbdf7 100644
--- a/plugins/codex-security/tests/deep_deadline_crash.py
+++ b/plugins/codex-security/tests/deep_deadline_crash.py
@@ -12,11 +12,14 @@ COMMIT_EXIT = 23
class CrashBeforeCommit(sqlite3.Connection):
+ """Terminate the child at its commit call so the parent can test recovery with unpublished database state."""
+
def commit(self):
os._exit(COMMIT_EXIT)
def interrupt_finish_before_commit(database, scan, hash_seed):
+ """Run deadline completion in a child with the requested hash seed and require the simulated crash exit code."""
result = subprocess.run(
[
sys.executable,
diff --git a/plugins/codex-security/tests/finalize_sarif_cases.py b/plugins/codex-security/tests/finalize_sarif_cases.py
index 0cc1e31e6..e33b9a637 100644
--- a/plugins/codex-security/tests/finalize_sarif_cases.py
+++ b/plugins/codex-security/tests/finalize_sarif_cases.py
@@ -1,3 +1,5 @@
+"""Exercise SARIF source locations, URI encoding, and fingerprints against the scan's captured source."""
+
from __future__ import annotations
import io
diff --git a/plugins/codex-security/tests/publication_fixtures.py b/plugins/codex-security/tests/publication_fixtures.py
index 9a768e71b..ae7fff403 100644
--- a/plugins/codex-security/tests/publication_fixtures.py
+++ b/plugins/codex-security/tests/publication_fixtures.py
@@ -1,3 +1,5 @@
+"""Build recorded workbench scans and worker artifacts for publication and crash-recovery tests."""
+
from __future__ import annotations
import copy
@@ -14,7 +16,19 @@ from workbench_test_support import read_review_state, write_completed_contract
class PublicationScan(SimpleNamespace):
+ """Drive publication and recovery against one test scan and its persisted worker records."""
+
+ def worker_draft(self, findings=(), **coverage_updates):
+ """Build a completed worker result using this scan's coverage as the starting point."""
+ return {
+ "scanId": self.scan_id,
+ "complete": True,
+ "findings": list(findings),
+ "coverage": {**self.coverage, **coverage_updates},
+ }
+
def add_worker(self, connection=None, *, status="succeeded") -> Path:
+ """Register a discovery worker and return the path where the test can write its result manifest."""
worker_id = str(uuid.uuid4())
output = self.scan_dir / "workers" / worker_id
output.mkdir(parents=True)
@@ -221,16 +235,7 @@ def publication_scan(workbench_api, workbench_db, tmp_path, monkeypatch):
def saturated_scan(publication_scan):
scan = publication_scan()
completed_result = scan.add_worker()
- completed_result.write_text(
- json.dumps(
- {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": scan.findings,
- "coverage": scan.coverage,
- }
- )
- )
+ completed_result.write_text(json.dumps(scan.worker_draft(scan.findings)))
reducer_result = scan.add_worker()
reducer_result.write_bytes(completed_result.read_bytes())
with scan.connection:
diff --git a/plugins/codex-security/tests/source_cases.py b/plugins/codex-security/tests/source_cases.py
index fbbfc0219..caaf6ad7d 100644
--- a/plugins/codex-security/tests/source_cases.py
+++ b/plugins/codex-security/tests/source_cases.py
@@ -11,6 +11,8 @@ from typing import NamedTuple
class SourceCase(NamedTuple):
+ """Pair the original and modified contents of one repository-relative file for inventory and ranking tests."""
+
path: str
before: str
after: str
diff --git a/plugins/codex-security/tests/test_checkpoint_publication_authority.py b/plugins/codex-security/tests/test_checkpoint_publication_authority.py
index 63ea81688..9237bd49a 100644
--- a/plugins/codex-security/tests/test_checkpoint_publication_authority.py
+++ b/plugins/codex-security/tests/test_checkpoint_publication_authority.py
@@ -1,3 +1,5 @@
+"""Test which saved parent and worker checkpoints may supply findings after publication or a stop."""
+
from __future__ import annotations
import copy
@@ -47,16 +49,7 @@ def test_flat_retained_source_name_replays(workbench_db, publication_scan, sourc
(scan.scan_dir / "findings.json").write_text(json.dumps({"findings": []}))
scan.add_worker(status="canceled")
source = scan.scan_dir / source_name
- source.write_text(
- json.dumps(
- {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": scan.findings,
- "coverage": scan.coverage,
- }
- )
- )
+ source.write_text(json.dumps(scan.worker_draft(scan.findings)))
with workbench_db:
workbench_db.execute(
"UPDATE deep_scan_workers SET result_manifest_path = ? WHERE scan_id = ?",
@@ -206,12 +199,7 @@ def test_recovery_honors_rejection_committed_before_result_replacement(
if archived:
result_path = result_path.parent / "attempts" / "attempt-1" / "result.json"
result_path.parent.mkdir(parents=True)
- previous = {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [provisional, retained],
- "coverage": scan.coverage,
- }
+ previous = scan.worker_draft([provisional, retained])
result_path.write_text(json.dumps(previous))
old_checkpoint = write_checkpoint(result_path.parent / "checkpoints", previous)
rejected = {
@@ -258,22 +246,17 @@ def save_disposition(scan, directory, disposition):
directory.mkdir(parents=True, exist_ok=True)
finding = copy.deepcopy(scan.findings[0])
finding["extensions"] = {"candidateId": "candidate-disposition"}
- draft = {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [finding] if disposition == "reported" else [],
- "coverage": {
- **scan.coverage,
- "surfaces": [
- {
- "candidateId": "candidate-disposition",
- "label": "Validated candidate disposition",
- "disposition": disposition,
- "receiptRefs": [],
- }
- ],
- },
- }
+ draft = scan.worker_draft(
+ [finding] if disposition == "reported" else [],
+ surfaces=[
+ {
+ "candidateId": "candidate-disposition",
+ "label": "Validated candidate disposition",
+ "disposition": disposition,
+ "receiptRefs": [],
+ }
+ ],
+ )
checkpoint = write_checkpoint(directory / "checkpoints", draft)
head = select_checkpoint(directory, checkpoint)
result = directory / "result.json"
diff --git a/plugins/codex-security/tests/test_checkpoint_recovery_fallbacks.py b/plugins/codex-security/tests/test_checkpoint_recovery_fallbacks.py
index b6dcb5aba..a0dd1e709 100644
--- a/plugins/codex-security/tests/test_checkpoint_recovery_fallbacks.py
+++ b/plugins/codex-security/tests/test_checkpoint_recovery_fallbacks.py
@@ -1,3 +1,5 @@
+"""Recover selected checkpoint records when sibling captures fail or a previous recovery was interrupted."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_checkpoint_schema.py b/plugins/codex-security/tests/test_checkpoint_schema.py
index bd2e1e97a..5d9121c61 100644
--- a/plugins/codex-security/tests/test_checkpoint_schema.py
+++ b/plugins/codex-security/tests/test_checkpoint_schema.py
@@ -1,3 +1,5 @@
+"""Check that upgrading the checkpoint-head schema preserves scans and lets current readers proceed during a write."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_cli_dry_runs.py b/plugins/codex-security/tests/test_cli_dry_runs.py
index 624902f16..d6400ccd7 100644
--- a/plugins/codex-security/tests/test_cli_dry_runs.py
+++ b/plugins/codex-security/tests/test_cli_dry_runs.py
@@ -1,3 +1,5 @@
+"""Exercise isolated script imports, CLI help, and finalization of the checked-in example bundle."""
+
from __future__ import annotations
import shutil
diff --git a/plugins/codex-security/tests/test_collect_checkmarx.py b/plugins/codex-security/tests/test_collect_checkmarx.py
index d848342e8..b2943dc03 100644
--- a/plugins/codex-security/tests/test_collect_checkmarx.py
+++ b/plugins/codex-security/tests/test_collect_checkmarx.py
@@ -1,3 +1,5 @@
+"""Exercise selected Checkmarx One and CxSAST report collection with isolated vendor tools."""
+
import io
import json
import os
diff --git a/plugins/codex-security/tests/test_deep_coverage_recovery.py b/plugins/codex-security/tests/test_deep_coverage_recovery.py
index 016eb0761..cec9ce4d7 100644
--- a/plugins/codex-security/tests/test_deep_coverage_recovery.py
+++ b/plugins/codex-security/tests/test_deep_coverage_recovery.py
@@ -1,3 +1,5 @@
+"""Reconcile worker coverage with parent findings, deferred tasks, and their supporting receipts on replay."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_deep_deadline_recovery_edges.py b/plugins/codex-security/tests/test_deep_deadline_recovery_edges.py
index 80df432dd..8f032273a 100644
--- a/plugins/codex-security/tests/test_deep_deadline_recovery_edges.py
+++ b/plugins/codex-security/tests/test_deep_deadline_recovery_edges.py
@@ -1,3 +1,5 @@
+"""Preserve usable worker checkpoints and earlier recovery files when deadline publication fails."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_deep_deadline_rollback.py b/plugins/codex-security/tests/test_deep_deadline_rollback.py
index 3d1caf1a4..d9c8bc9d4 100644
--- a/plugins/codex-security/tests/test_deep_deadline_rollback.py
+++ b/plugins/codex-security/tests/test_deep_deadline_rollback.py
@@ -1,3 +1,5 @@
+"""Check which parent observations and worker evidence survive rollback of a deadline publication."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_deep_scan_deadline_contracts.py b/plugins/codex-security/tests/test_deep_scan_deadline_contracts.py
index 3e8da2ed8..a1b653c86 100644
--- a/plugins/codex-security/tests/test_deep_scan_deadline_contracts.py
+++ b/plugins/codex-security/tests/test_deep_scan_deadline_contracts.py
@@ -1,3 +1,5 @@
+"""Require recovered deadline findings and worker closeouts to satisfy the completed scan contract."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_deep_scan_deadline_recovery.py b/plugins/codex-security/tests/test_deep_scan_deadline_recovery.py
index 8d268684c..9c4bf68c6 100644
--- a/plugins/codex-security/tests/test_deep_scan_deadline_recovery.py
+++ b/plugins/codex-security/tests/test_deep_scan_deadline_recovery.py
@@ -1,3 +1,5 @@
+"""Replay deadline completion across crashes while preserving pending work and prior rejection decisions."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_deep_scan_deadline_surface_links.py b/plugins/codex-security/tests/test_deep_scan_deadline_surface_links.py
index ae439b21d..81e419dc5 100644
--- a/plugins/codex-security/tests/test_deep_scan_deadline_surface_links.py
+++ b/plugins/codex-security/tests/test_deep_scan_deadline_surface_links.py
@@ -1,3 +1,5 @@
+"""Track source-to-surface links through deadline recovery, reused IDs, and repeated crashes."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_deep_scan_project_config.py b/plugins/codex-security/tests/test_deep_scan_project_config.py
index 74e610cb5..e6cff3af1 100644
--- a/plugins/codex-security/tests/test_deep_scan_project_config.py
+++ b/plugins/codex-security/tests/test_deep_scan_project_config.py
@@ -1,3 +1,5 @@
+"""Check when project limits are captured and how simultaneous deep scans keep their settings separate."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_deep_scan_publication.py b/plugins/codex-security/tests/test_deep_scan_publication.py
index d57a306be..0bb692e73 100644
--- a/plugins/codex-security/tests/test_deep_scan_publication.py
+++ b/plugins/codex-security/tests/test_deep_scan_publication.py
@@ -1,3 +1,5 @@
+"""Compare an archived deep scan publication with the snapshot used to produce it."""
+
from __future__ import annotations
import importlib
diff --git a/plugins/codex-security/tests/test_deep_scan_publication_authority.py b/plugins/codex-security/tests/test_deep_scan_publication_authority.py
index d5aab2a1b..a2404ea73 100644
--- a/plugins/codex-security/tests/test_deep_scan_publication_authority.py
+++ b/plugins/codex-security/tests/test_deep_scan_publication_authority.py
@@ -1,3 +1,5 @@
+"""Check coordinator ownership and receipt validation when publishing or replaying a deep scan."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_deep_scan_publication_replay.py b/plugins/codex-security/tests/test_deep_scan_publication_replay.py
index 34871113b..a59c048b5 100644
--- a/plugins/codex-security/tests/test_deep_scan_publication_replay.py
+++ b/plugins/codex-security/tests/test_deep_scan_publication_replay.py
@@ -1,3 +1,5 @@
+"""Replay the inputs selected before a publication crash while protecting newer canonical output."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_deep_scan_request_identity.py b/plugins/codex-security/tests/test_deep_scan_request_identity.py
index edda16ae6..a17e768fe 100644
--- a/plugins/codex-security/tests/test_deep_scan_request_identity.py
+++ b/plugins/codex-security/tests/test_deep_scan_request_identity.py
@@ -1,3 +1,5 @@
+"""Match resumable deep scans to their original target and discovery context, including older records."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_deep_scan_stop_conditions.py b/plugins/codex-security/tests/test_deep_scan_stop_conditions.py
index 0d9a54024..c35644499 100644
--- a/plugins/codex-security/tests/test_deep_scan_stop_conditions.py
+++ b/plugins/codex-security/tests/test_deep_scan_stop_conditions.py
@@ -1,3 +1,5 @@
+"""Recover findings and checkpoint evidence when deep scans hit a stop condition."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_deep_scan_successful_publication.py b/plugins/codex-security/tests/test_deep_scan_successful_publication.py
index 19d2ad175..3a899ce76 100644
--- a/plugins/codex-security/tests/test_deep_scan_successful_publication.py
+++ b/plugins/codex-security/tests/test_deep_scan_successful_publication.py
@@ -1,3 +1,5 @@
+"""Check how final deep scan reports preserve remediation, selected paths, and worker evidence."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_deep_security_scan_concurrency_guard.py b/plugins/codex-security/tests/test_deep_security_scan_concurrency_guard.py
index 84093455e..89beb9f4a 100644
--- a/plugins/codex-security/tests/test_deep_security_scan_concurrency_guard.py
+++ b/plugins/codex-security/tests/test_deep_security_scan_concurrency_guard.py
@@ -1,3 +1,5 @@
+"""Check that scan context counts concurrent deep scans while excluding the current run."""
+
from __future__ import annotations
import uuid
diff --git a/plugins/codex-security/tests/test_finalize_scan_contract.py b/plugins/codex-security/tests/test_finalize_scan_contract.py
index 799910775..1e1fb6083 100644
--- a/plugins/codex-security/tests/test_finalize_scan_contract.py
+++ b/plugins/codex-security/tests/test_finalize_scan_contract.py
@@ -1,3 +1,5 @@
+"""Exercise sealing and recovery of scan bundles, including inputs that change during finalization."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_finalize_scan_timestamps.py b/plugins/codex-security/tests/test_finalize_scan_timestamps.py
index dcc50a2a3..91967c98e 100644
--- a/plugins/codex-security/tests/test_finalize_scan_timestamps.py
+++ b/plugins/codex-security/tests/test_finalize_scan_timestamps.py
@@ -1,3 +1,5 @@
+"""Distinguish workbench timestamps from model-supplied times when sealing and exporting a scan."""
+
from __future__ import annotations
import os
diff --git a/plugins/codex-security/tests/test_finalize_schema_validation.py b/plugins/codex-security/tests/test_finalize_schema_validation.py
index f1fe9c2a9..6bd98de96 100644
--- a/plugins/codex-security/tests/test_finalize_schema_validation.py
+++ b/plugins/codex-security/tests/test_finalize_schema_validation.py
@@ -1,3 +1,5 @@
+"""Exercise numeric types and constraints on referenced nodes in the finalizer's schema checker."""
+
from __future__ import annotations
import pytest
diff --git a/plugins/codex-security/tests/test_finalize_writeup_recovery.py b/plugins/codex-security/tests/test_finalize_writeup_recovery.py
index e2f23a8a8..0640623c7 100644
--- a/plugins/codex-security/tests/test_finalize_writeup_recovery.py
+++ b/plugins/codex-security/tests/test_finalize_writeup_recovery.py
@@ -1,3 +1,5 @@
+"""Distinguish a missing optional writeup from other read failures during scan recovery."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_finding_issue_receipts.py b/plugins/codex-security/tests/test_finding_issue_receipts.py
index 1b690ded0..81244f719 100644
--- a/plugins/codex-security/tests/test_finding_issue_receipts.py
+++ b/plugins/codex-security/tests/test_finding_issue_receipts.py
@@ -1,3 +1,5 @@
+"""Verify that issue receipts stay bound to their finding and that inspection preserves local state."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_finding_preview.py b/plugins/codex-security/tests/test_finding_preview.py
index 1bfcf4c5c..0d1226cf7 100644
--- a/plugins/codex-security/tests/test_finding_preview.py
+++ b/plugins/codex-security/tests/test_finding_preview.py
@@ -1,3 +1,5 @@
+"""Check how finding previews fit a size budget while retaining report text and diagnostics."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_git_inventory_regressions.py b/plugins/codex-security/tests/test_git_inventory_regressions.py
index 20e7c9fb6..86f84e877 100644
--- a/plugins/codex-security/tests/test_git_inventory_regressions.py
+++ b/plugins/codex-security/tests/test_git_inventory_regressions.py
@@ -1,3 +1,5 @@
+"""Exercise local Git inventories for root commits, worktree changes, submodules, and optional snapshots."""
+
from __future__ import annotations
import hashlib
diff --git a/plugins/codex-security/tests/test_partial_coverage_projection.py b/plugins/codex-security/tests/test_partial_coverage_projection.py
index a0d2020cc..745e8b521 100644
--- a/plugins/codex-security/tests/test_partial_coverage_projection.py
+++ b/plugins/codex-security/tests/test_partial_coverage_projection.py
@@ -1,3 +1,5 @@
+"""Preserve source-specific receipts, surface links, and pending work when projecting partial coverage."""
+
from __future__ import annotations
import copy
@@ -62,17 +64,7 @@ def test_parent_candidate_outcome_compares_headless_worker_chronology(
"receiptRefs": [],
}
task = {"id": "worker-task", "candidateId": candidate, "reason": "Validate worker evidence."}
- draft = {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {
- **scan.coverage,
- "completeness": "partial",
- "surfaces": [surface],
- "deferred": [task],
- },
- }
+ draft = scan.worker_draft(completeness="partial", surfaces=[surface], deferred=[task])
write_result_draft(result, draft, mtime_ns=300)
originals = {result: result.read_bytes()}
if has_head:
@@ -154,17 +146,7 @@ def test_missing_deferred_projection_links_first_duplicate_surface(
}
result.write_text(
json.dumps(
- {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {
- **scan.coverage,
- "completeness": "partial",
- "surfaces": surfaces,
- "deferred": [deferred],
- },
- }
+ scan.worker_draft(completeness="partial", surfaces=surfaces, deferred=[deferred])
)
)
original = result.read_bytes()
@@ -503,17 +485,9 @@ def test_missing_projection_keeps_surface_links_and_independent_reviews(
)
result.write_text(
json.dumps(
- {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {
- **scan.coverage,
- "completeness": "partial",
- "surfaces": worker_surfaces,
- "deferred": [deferred],
- },
- }
+ scan.worker_draft(
+ completeness="partial", surfaces=worker_surfaces, deferred=[deferred]
+ )
)
)
originals[result] = result.read_bytes()
@@ -567,16 +541,7 @@ def test_previous_attempt_resolution_does_not_clear_current_gap(
result = scan.add_worker()
worker_id = result.parent.name
deferred = {"candidateId": "candidate-1", "reason": "Validate the current attempt."}
- result.write_text(
- json.dumps(
- {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {**scan.coverage, "completeness": "partial", "deferred": [deferred]},
- }
- )
- )
+ result.write_text(json.dumps(scan.worker_draft(completeness="partial", deferred=[deferred])))
original = result.read_bytes()
with workbench_db:
workbench_db.execute(
@@ -630,16 +595,7 @@ def test_recovery_compares_open_questions_using_canonical_normalization(
" Which deployment controls apply? ",
{"question": " Which runtime settings apply? ", "followUpPrompt": " \t"},
]
- result.write_text(
- json.dumps(
- {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {**scan.coverage, "openQuestions": questions},
- }
- )
- )
+ result.write_text(json.dumps(scan.worker_draft(openQuestions=questions)))
original = result.read_bytes()
if selected_checkpoint:
checkpoint = write_checkpoint(result.parent / "checkpoints", json.loads(result.read_text()))
@@ -697,16 +653,7 @@ def test_rejected_retry_preserves_original_finding_history(
"disposition": "rejected",
"receiptRefs": [],
}
- result.write_text(
- json.dumps(
- {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {**scan.coverage, "surfaces": [surface]},
- }
- )
- )
+ result.write_text(json.dumps(scan.worker_draft(surfaces=[surface])))
with workbench_db:
workbench_db.execute("UPDATE deep_scan_workers SET attempt = 2 WHERE id = ?", (worker_id,))
other_result = scan.add_worker()
@@ -781,16 +728,7 @@ def test_stopped_recovery_keeps_current_parent_projection(
result = scan.add_worker()
worker_id = result.parent.name
deferred = {"candidateId": "candidate-1", "reason": "The current review remains unresolved."}
- result.write_text(
- json.dumps(
- {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {**scan.coverage, "completeness": "partial", "deferred": [deferred]},
- }
- )
- )
+ result.write_text(json.dumps(scan.worker_draft(completeness="partial", deferred=[deferred])))
reducer = scan.add_worker()
reducer.write_text(json.dumps({"scanId": scan.scan_id, "findings": []}))
reducer_checkpoint = write_checkpoint(
@@ -934,24 +872,18 @@ def test_matching_accepted_checkpoint_preserves_receipt_path(
receipt = result.parent / "artifacts" / "evidence.txt"
receipt.parent.mkdir(parents=True, exist_ok=True)
receipt.write_text("Synthetic source-review evidence.")
- draft = {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {
- **scan.coverage,
- "completeness": "complete",
- "deferred": [],
- "surfaces": [
- {
- "id": "source-review",
- "label": "Accepted source review",
- "disposition": "no_issue_found",
- "receiptRefs": ["artifacts/evidence.txt"],
- }
- ],
- },
- }
+ draft = scan.worker_draft(
+ completeness="complete",
+ deferred=[],
+ surfaces=[
+ {
+ "id": "source-review",
+ "label": "Accepted source review",
+ "disposition": "no_issue_found",
+ "receiptRefs": ["artifacts/evidence.txt"],
+ }
+ ],
+ )
result.write_text(json.dumps(draft))
checkpoint = write_checkpoint(result.parent / "checkpoints", draft)
os.utime(result, ns=(100, 100))
@@ -1018,12 +950,7 @@ def test_idless_accepted_surface_matches_projection_after_checkpoint_id_inferenc
"disposition": "no_issue_found",
"receiptRefs": [],
}
- draft = {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {**scan.coverage, "surfaces": [surface]},
- }
+ draft = scan.worker_draft(surfaces=[surface])
result.write_text(json.dumps(draft))
checkpoint = write_checkpoint(
result.parent / "checkpoints",
@@ -1077,16 +1004,7 @@ def test_parent_candidate_provenance_cannot_override_accepted_worker_evidence(
finding = copy.deepcopy(scan.findings[0])
finding["provenance"]["candidateId"] = "source-candidate"
finding["summary"] = "Accepted independent source evidence."
- result.write_text(
- json.dumps(
- {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [finding],
- "coverage": scan.coverage,
- }
- )
- )
+ result.write_text(json.dumps(scan.worker_draft([finding])))
originals = {result: result.read_bytes()}
if selected_checkpoint:
checkpoint = write_checkpoint(result.parent / "checkpoints", json.loads(result.read_text()))
@@ -1158,17 +1076,7 @@ def test_projected_generic_closure_updates_parent_copy_in_its_worker_namespace(
"reason": "Complete source follow-up.",
"surfaceIds": [surface["id"]],
}
- draft = {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {
- **scan.coverage,
- "completeness": "partial",
- "surfaces": [surface],
- "deferred": [task],
- },
- }
+ draft = scan.worker_draft(completeness="partial", surfaces=[surface], deferred=[task])
result.write_text(json.dumps(draft))
projected_surface = {
**surface,
@@ -1259,17 +1167,7 @@ def test_selected_candidate_outcome_removes_its_projected_parent_pending_rows(
"candidateId": candidate,
"reason": "Complete candidate follow-up.",
}
- draft = {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {
- **scan.coverage,
- "completeness": "partial",
- "surfaces": [surface],
- "deferred": [task],
- },
- }
+ draft = scan.worker_draft(completeness="partial", surfaces=[surface], deferred=[task])
result.write_text(json.dumps(draft))
projected_candidate = (
f"{worker_id}-attempt-1-candidate-{hashlib.sha256(candidate.encode()).hexdigest()}"
@@ -1410,17 +1308,7 @@ def test_selected_worker_projection_keeps_links_and_pending_authority(
receipt = result.parent / "artifacts" / f"{name}.txt"
receipt.parent.mkdir(exist_ok=True)
receipt.write_text(f"Synthetic {name} receipt.\n")
- draft = {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {
- **scan.coverage,
- "completeness": "partial",
- "surfaces": surfaces,
- "deferred": deferred,
- },
- }
+ draft = scan.worker_draft(completeness="partial", surfaces=surfaces, deferred=deferred)
if change == "reopened mixed receipts":
draft["coverage"]["resolvedDeferred"] = [
{"id": task["id"], "reason": "Earlier source follow-up completed."}
@@ -1644,17 +1532,7 @@ def test_linked_archived_receipts_preserve_accepted_surface_links(
"disposition": "needs_follow_up",
"receiptRefs": ["artifacts/review.txt"],
}
- draft = {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {
- **scan.coverage,
- "completeness": "partial",
- "surfaces": [surface],
- "deferred": [],
- },
- }
+ draft = scan.worker_draft(completeness="partial", surfaces=[surface], deferred=[])
result.write_text(json.dumps(draft))
projected = {
**surface,
@@ -1822,17 +1700,7 @@ def test_deferred_projection_preserves_each_referenced_source_surface(
{"id": f"task-{index}", "reason": f"Verify source {index}.", "surfaceIds": [surface["id"]]}
for index, surface in enumerate(surfaces)
]
- draft = {
- "scanId": scan.scan_id,
- "complete": True,
- "findings": [],
- "coverage": {
- **scan.coverage,
- "completeness": "partial",
- "surfaces": surfaces,
- "deferred": deferred,
- },
- }
+ draft = scan.worker_draft(completeness="partial", surfaces=surfaces, deferred=deferred)
result.write_text(json.dumps(draft))
original = result.read_bytes()
for name in ("scan-manifest.json", "findings.json", "coverage.json"):
diff --git a/plugins/codex-security/tests/test_plugin_contract.py b/plugins/codex-security/tests/test_plugin_contract.py
index 63c2c2730..e1e0469c5 100644
--- a/plugins/codex-security/tests/test_plugin_contract.py
+++ b/plugins/codex-security/tests/test_plugin_contract.py
@@ -1,3 +1,5 @@
+"""Check the plugin manifest, skill interfaces, declared app connections, and referenced assets."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_portable_artifact_paths.py b/plugins/codex-security/tests/test_portable_artifact_paths.py
index 85278b9f8..16ed6fbee 100644
--- a/plugins/codex-security/tests/test_portable_artifact_paths.py
+++ b/plugins/codex-security/tests/test_portable_artifact_paths.py
@@ -1,3 +1,5 @@
+"""Distinguish portable sealed-artifact names from the source paths a finding may cite."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_recovered_worker_closeouts.py b/plugins/codex-security/tests/test_recovered_worker_closeouts.py
index 29f7f5938..8ac615a24 100644
--- a/plugins/codex-security/tests/test_recovered_worker_closeouts.py
+++ b/plugins/codex-security/tests/test_recovered_worker_closeouts.py
@@ -1,3 +1,5 @@
+"""Track worker closeouts through parent copies, reopened work, and archived attempts."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_report_projection.py b/plugins/codex-security/tests/test_report_projection.py
index 0b7ded5e4..09c12b9bf 100644
--- a/plugins/codex-security/tests/test_report_projection.py
+++ b/plugins/codex-security/tests/test_report_projection.py
@@ -1,3 +1,5 @@
+"""Check how structured scan records and legacy evidence become readable Markdown reports."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_resolved_deferred_finalization.py b/plugins/codex-security/tests/test_resolved_deferred_finalization.py
index 26d850775..f9c96073d 100644
--- a/plugins/codex-security/tests/test_resolved_deferred_finalization.py
+++ b/plugins/codex-security/tests/test_resolved_deferred_finalization.py
@@ -1,3 +1,5 @@
+"""Check how finalization reconciles completed deferred work with the remaining coverage record."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_review_state.py b/plugins/codex-security/tests/test_review_state.py
index b03a02bad..7aa0804fa 100644
--- a/plugins/codex-security/tests/test_review_state.py
+++ b/plugins/codex-security/tests/test_review_state.py
@@ -1,3 +1,5 @@
+"""Reconstruct coverage from results that contain review state but have no separate coverage file."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_root_candidate_authority.py b/plugins/codex-security/tests/test_root_candidate_authority.py
index b9ed0e7b0..5d0741df3 100644
--- a/plugins/codex-security/tests/test_root_candidate_authority.py
+++ b/plugins/codex-security/tests/test_root_candidate_authority.py
@@ -1,3 +1,5 @@
+"""Resolve competing root candidate outcomes from canonical, pending, and legacy checkpoint evidence."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_runtime_settings.py b/plugins/codex-security/tests/test_runtime_settings.py
index bf078ec05..bd8ccd928 100644
--- a/plugins/codex-security/tests/test_runtime_settings.py
+++ b/plugins/codex-security/tests/test_runtime_settings.py
@@ -1,3 +1,5 @@
+"""Check Python settings against SDK conventions for home paths, TOML numbers, and parser availability."""
+
from __future__ import annotations
import runpy
diff --git a/plugins/codex-security/tests/test_sarif_projection.py b/plugins/codex-security/tests/test_sarif_projection.py
index 02dc7fa02..2a36a40ac 100644
--- a/plugins/codex-security/tests/test_sarif_projection.py
+++ b/plugins/codex-security/tests/test_sarif_projection.py
@@ -1,3 +1,5 @@
+"""Project sealed findings into SARIF while preserving alert identity, rule metadata, and run warnings."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_saved_deferred_identity.py b/plugins/codex-security/tests/test_saved_deferred_identity.py
index 4d538a8d2..d3aadd92e 100644
--- a/plugins/codex-security/tests/test_saved_deferred_identity.py
+++ b/plugins/codex-security/tests/test_saved_deferred_identity.py
@@ -1,3 +1,5 @@
+"""Track deferred observations through ID collisions, worker revisions, and frozen source order."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_saved_deferred_unicode.py b/plugins/codex-security/tests/test_saved_deferred_unicode.py
index 41062d488..5ecec879a 100644
--- a/plugins/codex-security/tests/test_saved_deferred_unicode.py
+++ b/plugins/codex-security/tests/test_saved_deferred_unicode.py
@@ -1,3 +1,5 @@
+"""Recover and publish scans whose earlier writers stored Unicode review identifiers."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_saved_threat_model_recovery.py b/plugins/codex-security/tests/test_saved_threat_model_recovery.py
index 477c1e8b2..ebd8c611a 100644
--- a/plugins/codex-security/tests/test_saved_threat_model_recovery.py
+++ b/plugins/codex-security/tests/test_saved_threat_model_recovery.py
@@ -1,3 +1,5 @@
+"""Recover findings and replay the frozen result when optional threat-model context is invalid."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_scan_contract_examples.py b/plugins/codex-security/tests/test_scan_contract_examples.py
index 0871e54ae..5cb65d02d 100644
--- a/plugins/codex-security/tests/test_scan_contract_examples.py
+++ b/plugins/codex-security/tests/test_scan_contract_examples.py
@@ -1,3 +1,5 @@
+"""Validate the checked-in scan examples and exercise schema boundaries for evidence and coverage."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_scan_local_write_cleanup.py b/plugins/codex-security/tests/test_scan_local_write_cleanup.py
index 35ebb5434..efc54e40f 100644
--- a/plugins/codex-security/tests/test_scan_local_write_cleanup.py
+++ b/plugins/codex-security/tests/test_scan_local_write_cleanup.py
@@ -1,3 +1,5 @@
+"""Exercise cleanup and file-identity checks when scan-local writes race or fail partway."""
+
from __future__ import annotations
import ctypes
diff --git a/plugins/codex-security/tests/test_threat_model_projection.py b/plugins/codex-security/tests/test_threat_model_projection.py
index 6a13d17ac..a86845698 100644
--- a/plugins/codex-security/tests/test_threat_model_projection.py
+++ b/plugins/codex-security/tests/test_threat_model_projection.py
@@ -1,3 +1,5 @@
+"""Check how authored Markdown and older threat models are sealed, recovered, and exported."""
+
from __future__ import annotations
import io
diff --git a/plugins/codex-security/tests/test_threat_model_visualize.py b/plugins/codex-security/tests/test_threat_model_visualize.py
index 8fd49d248..69b270e29 100644
--- a/plugins/codex-security/tests/test_threat_model_visualize.py
+++ b/plugins/codex-security/tests/test_threat_model_visualize.py
@@ -1,4 +1,4 @@
-"""Semantic guard checks for control effects. Python 3.12+."""
+"""Test explorer validation against assessment bytes and inspect the resulting self-contained HTML."""
import copy
import hashlib
@@ -19,6 +19,7 @@ spec.loader.exec_module(builder)
def run_builder(model_file, source, output):
+ """Run the explorer CLI on the supplied paths and return its exit status, stdout, and stderr."""
return subprocess.run(
[
sys.executable,
@@ -59,6 +60,8 @@ class EmbeddedHtml(HTMLParser):
class ControlValidation(unittest.TestCase):
+ """Vary a three-node scenario to test route, control, evidence, and rendering contracts."""
+
def setUp(self):
self.model = {
"brand": "Synthetic assessment",
@@ -135,6 +138,17 @@ class ControlValidation(unittest.TestCase):
def build_html(
self, assessment_bytes, *, error=None, existing_html=None, model_encoding="utf-8"
):
+ """Run the builder with temporary inputs and check the outcome.
+
+ Args:
+ assessment_bytes (bytes): Exact assessment content used to validate the model.
+ error (str | None): Expected stderr substring for a build that exits with status 2.
+ existing_html (str | None): Prior output to seed and check after a failed build.
+ model_encoding (str): Encoding used to write the model fixture.
+
+ Returns:
+ str | None: The generated HTML on success, or None after the expected failure.
+ """
with tempfile.TemporaryDirectory() as folder:
folder = Path(folder)
model_file, source, output = (
@@ -162,6 +176,7 @@ class ControlValidation(unittest.TestCase):
return output.read_text(encoding="utf-8")
def embedded_data(self, html, element_id):
+ """Decode the single application/json script with element_id from the generated HTML."""
values = [
code
for tag, attrs, code in EmbeddedHtml(html).elements
diff --git a/plugins/codex-security/tests/test_track_findings_skill.py b/plugins/codex-security/tests/test_track_findings_skill.py
index 36918bc93..9eb9b9c75 100644
--- a/plugins/codex-security/tests/test_track_findings_skill.py
+++ b/plugins/codex-security/tests/test_track_findings_skill.py
@@ -1,3 +1,5 @@
+"""Check provider app declarations and the instructions for reading back a published finding."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_validate_scan_contract.py b/plugins/codex-security/tests/test_validate_scan_contract.py
index ce96d3d04..fb41ec7fb 100644
--- a/plugins/codex-security/tests/test_validate_scan_contract.py
+++ b/plugins/codex-security/tests/test_validate_scan_contract.py
@@ -1,3 +1,5 @@
+"""Exercise read-only validation of sealed bundles, including legacy evidence and unsealed inputs."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_windows_report_e2e.py b/plugins/codex-security/tests/test_windows_report_e2e.py
index 6bdb8a6a3..61d934ba2 100644
--- a/plugins/codex-security/tests/test_windows_report_e2e.py
+++ b/plugins/codex-security/tests/test_windows_report_e2e.py
@@ -1,3 +1,5 @@
+"""Complete and export a scan through the native Windows filesystem backend."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_windows_scan_local_files.py b/plugins/codex-security/tests/test_windows_scan_local_files.py
index 9dc5f1889..1b55b9a60 100644
--- a/plugins/codex-security/tests/test_windows_scan_local_files.py
+++ b/plugins/codex-security/tests/test_windows_scan_local_files.py
@@ -1,3 +1,5 @@
+"""Exercise Windows scan-local path handling across aliases, junctions, and replacement races."""
+
from __future__ import annotations
import argparse
diff --git a/plugins/codex-security/tests/test_workbench_archive.py b/plugins/codex-security/tests/test_workbench_archive.py
index 43614e831..e094dd883 100644
--- a/plugins/codex-security/tests/test_workbench_archive.py
+++ b/plugins/codex-security/tests/test_workbench_archive.py
@@ -1,3 +1,5 @@
+"""Exercise output archiving when registrations race, fail, or encounter aliases to active state."""
+
from __future__ import annotations
import argparse
diff --git a/plugins/codex-security/tests/test_workbench_cancellation.py b/plugins/codex-security/tests/test_workbench_cancellation.py
index cae122b3e..2d40c6db5 100644
--- a/plugins/codex-security/tests/test_workbench_cancellation.py
+++ b/plugins/codex-security/tests/test_workbench_cancellation.py
@@ -1,3 +1,5 @@
+"""Test scan ownership and coherent workbench responses when cancellation or replacement races a request."""
+
from __future__ import annotations
import argparse
diff --git a/plugins/codex-security/tests/test_workbench_checkpoint_heads.py b/plugins/codex-security/tests/test_workbench_checkpoint_heads.py
index e2ccfb6da..a4d8c6780 100644
--- a/plugins/codex-security/tests/test_workbench_checkpoint_heads.py
+++ b/plugins/codex-security/tests/test_workbench_checkpoint_heads.py
@@ -1,3 +1,5 @@
+"""Replay frozen checkpoint selections across late changes, tied timestamps, and explicit recovery."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_workbench_cli.py b/plugins/codex-security/tests/test_workbench_cli.py
index c43958a69..a332ad6d7 100644
--- a/plugins/codex-security/tests/test_workbench_cli.py
+++ b/plugins/codex-security/tests/test_workbench_cli.py
@@ -1,3 +1,5 @@
+"""Check how workbench commands read context from stdin and handle conflicting inputs."""
+
from __future__ import annotations
import os
diff --git a/plugins/codex-security/tests/test_workbench_completion_binding.py b/plugins/codex-security/tests/test_workbench_completion_binding.py
index 7646cfd9a..331cdd7be 100644
--- a/plugins/codex-security/tests/test_workbench_completion_binding.py
+++ b/plugins/codex-security/tests/test_workbench_completion_binding.py
@@ -1,3 +1,5 @@
+"""Bind CLI scan counts, final artifacts, and recovered coverage to the registered target."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_workbench_db.py b/plugins/codex-security/tests/test_workbench_db.py
index a07d015be..b24b0b68e 100644
--- a/plugins/codex-security/tests/test_workbench_db.py
+++ b/plugins/codex-security/tests/test_workbench_db.py
@@ -1,3 +1,5 @@
+"""Exercise persisted workbench operations, including scan budgets, finding state, and patch identity."""
+
from __future__ import annotations
import hashlib
diff --git a/plugins/codex-security/tests/test_workbench_db_exports.py b/plugins/codex-security/tests/test_workbench_db_exports.py
index f98b9cc66..293f33702 100644
--- a/plugins/codex-security/tests/test_workbench_db_exports.py
+++ b/plugins/codex-security/tests/test_workbench_db_exports.py
@@ -1,3 +1,5 @@
+"""Export saved findings from stopped scans while retaining newer drafts across recovery."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_workbench_deep_scan.py b/plugins/codex-security/tests/test_workbench_deep_scan.py
index 9d87ab61c..7b44c6bd3 100644
--- a/plugins/codex-security/tests/test_workbench_deep_scan.py
+++ b/plugins/codex-security/tests/test_workbench_deep_scan.py
@@ -1,3 +1,5 @@
+"""Exercise deep scan registration, coordinator claims, iteration ordering, and terminal state transitions."""
+
from __future__ import annotations
import hashlib
@@ -191,6 +193,8 @@ def write_canonical_artifacts(scan_dir: Path) -> dict[str, Path]:
@dataclass(frozen=True)
class DeepScan:
+ """Keep a test scan ID, state directory, and Codex home together when issuing worker and coordinator commands."""
+
state_dir: Path
codex_home: Path
id: str
diff --git a/plugins/codex-security/tests/test_workbench_diagnostics.py b/plugins/codex-security/tests/test_workbench_diagnostics.py
index 33339db0a..dc3eb321c 100644
--- a/plugins/codex-security/tests/test_workbench_diagnostics.py
+++ b/plugins/codex-security/tests/test_workbench_diagnostics.py
@@ -1,3 +1,5 @@
+"""Check that workbench failures retain their full diagnostics through terminal updates and replay."""
+
from __future__ import annotations
import sqlite3
diff --git a/plugins/codex-security/tests/test_workbench_draft_publication.py b/plugins/codex-security/tests/test_workbench_draft_publication.py
index 0c3da7d10..3b70729a3 100644
--- a/plugins/codex-security/tests/test_workbench_draft_publication.py
+++ b/plugins/codex-security/tests/test_workbench_draft_publication.py
@@ -1,3 +1,5 @@
+"""Exercise deep scan drafts before orchestration and after the run has reached a terminal state."""
+
from __future__ import annotations
import hashlib
diff --git a/plugins/codex-security/tests/test_workbench_feedback.py b/plugins/codex-security/tests/test_workbench_feedback.py
index d4098a3aa..1f468187b 100644
--- a/plugins/codex-security/tests/test_workbench_feedback.py
+++ b/plugins/codex-security/tests/test_workbench_feedback.py
@@ -1,3 +1,5 @@
+"""Project false-positive decisions into later scans and preserve the reasons behind triage changes."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_workbench_finding_workflows.py b/plugins/codex-security/tests/test_workbench_finding_workflows.py
index 3f274a7b3..407c2e298 100644
--- a/plugins/codex-security/tests/test_workbench_finding_workflows.py
+++ b/plugins/codex-security/tests/test_workbench_finding_workflows.py
@@ -1,3 +1,5 @@
+"""Exercise competing finding workflow registrations and the scope of their optional evidence snapshots."""
+
from __future__ import annotations
import hashlib
diff --git a/plugins/codex-security/tests/test_workbench_handoff.py b/plugins/codex-security/tests/test_workbench_handoff.py
index cc45ac7fb..7c1c8526b 100644
--- a/plugins/codex-security/tests/test_workbench_handoff.py
+++ b/plugins/codex-security/tests/test_workbench_handoff.py
@@ -1,3 +1,5 @@
+"""Check handoff claims, releases, and continuation ownership across concurrent workbench requests."""
+
from __future__ import annotations
import sqlite3
diff --git a/plugins/codex-security/tests/test_workbench_local_dedupe.py b/plugins/codex-security/tests/test_workbench_local_dedupe.py
index b09236365..d850158f7 100644
--- a/plugins/codex-security/tests/test_workbench_local_dedupe.py
+++ b/plugins/codex-security/tests/test_workbench_local_dedupe.py
@@ -1,3 +1,5 @@
+"""Check that embedding cache migrations preserve vectors and distinguish local and service records."""
+
from __future__ import annotations
import sqlite3
diff --git a/plugins/codex-security/tests/test_workbench_native_index_queries.py b/plugins/codex-security/tests/test_workbench_native_index_queries.py
index 01a780079..27e1933b6 100644
--- a/plugins/codex-security/tests/test_workbench_native_index_queries.py
+++ b/plugins/codex-security/tests/test_workbench_native_index_queries.py
@@ -1,3 +1,5 @@
+"""Exercise filtering, pagination, and latest-scan selection in finding and repository indexes."""
+
from __future__ import annotations
import ntpath
diff --git a/plugins/codex-security/tests/test_workbench_native_indexes.py b/plugins/codex-security/tests/test_workbench_native_indexes.py
index 6e8d34f74..80b3649fe 100644
--- a/plugins/codex-security/tests/test_workbench_native_indexes.py
+++ b/plugins/codex-security/tests/test_workbench_native_indexes.py
@@ -1,3 +1,5 @@
+"""Check cross-scan finding identity, repository counts, and Unicode search in the workbench indexes."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_workbench_output_permissions.py b/plugins/codex-security/tests/test_workbench_output_permissions.py
index 8613231cc..add821b1e 100644
--- a/plugins/codex-security/tests/test_workbench_output_permissions.py
+++ b/plugins/codex-security/tests/test_workbench_output_permissions.py
@@ -1,3 +1,5 @@
+"""Check private output creation under permissive umasks and reuse of existing directories."""
+
from __future__ import annotations
import os
diff --git a/plugins/codex-security/tests/test_workbench_progress.py b/plugins/codex-security/tests/test_workbench_progress.py
index aa44a2898..86871e003 100644
--- a/plugins/codex-security/tests/test_workbench_progress.py
+++ b/plugins/codex-security/tests/test_workbench_progress.py
@@ -1,3 +1,5 @@
+"""Carry phase receipts and historical preflight diagnostics through workbench progress updates."""
+
import json
import sqlite3
from pathlib import Path
diff --git a/plugins/codex-security/tests/test_workbench_prompt_only_scan.py b/plugins/codex-security/tests/test_workbench_prompt_only_scan.py
index 2f2eca21a..25c24b3bd 100644
--- a/plugins/codex-security/tests/test_workbench_prompt_only_scan.py
+++ b/plugins/codex-security/tests/test_workbench_prompt_only_scan.py
@@ -1,3 +1,5 @@
+"""Check ownership, target identity, and backwards compatibility when starting scans without setup."""
+
from __future__ import annotations
import argparse
diff --git a/plugins/codex-security/tests/test_workbench_recovery_outcome_validation.py b/plugins/codex-security/tests/test_workbench_recovery_outcome_validation.py
index 833492b52..071baa6be 100644
--- a/plugins/codex-security/tests/test_workbench_recovery_outcome_validation.py
+++ b/plugins/codex-security/tests/test_workbench_recovery_outcome_validation.py
@@ -1,3 +1,5 @@
+"""Require evidence for rejection and closure decisions before recovered scans can be sealed."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_workbench_remediation_cancellation.py b/plugins/codex-security/tests/test_workbench_remediation_cancellation.py
index 4ef1c6d64..921bc4196 100644
--- a/plugins/codex-security/tests/test_workbench_remediation_cancellation.py
+++ b/plugins/codex-security/tests/test_workbench_remediation_cancellation.py
@@ -1,3 +1,5 @@
+"""Check that canceling a remediation request restores the finding's prior state."""
+
from __future__ import annotations
import subprocess
diff --git a/plugins/codex-security/tests/test_workbench_remediation_retry.py b/plugins/codex-security/tests/test_workbench_remediation_retry.py
index 4bb0e9b14..915867479 100644
--- a/plugins/codex-security/tests/test_workbench_remediation_retry.py
+++ b/plugins/codex-security/tests/test_workbench_remediation_retry.py
@@ -1,3 +1,5 @@
+"""Exercise patch verification and retries after failed remediation steps, including offline Git reads."""
+
from __future__ import annotations
import argparse
diff --git a/plugins/codex-security/tests/test_workbench_saved_source_order.py b/plugins/codex-security/tests/test_workbench_saved_source_order.py
index f8867b4f1..e0294e18d 100644
--- a/plugins/codex-security/tests/test_workbench_saved_source_order.py
+++ b/plugins/codex-security/tests/test_workbench_saved_source_order.py
@@ -1,3 +1,5 @@
+"""Check which saved sources a stopped scan selects when timestamps tie or publication is retried."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_workbench_scan_archive.py b/plugins/codex-security/tests/test_workbench_scan_archive.py
index 41a78042c..bc6cd3fd7 100644
--- a/plugins/codex-security/tests/test_workbench_scan_archive.py
+++ b/plugins/codex-security/tests/test_workbench_scan_archive.py
@@ -1,3 +1,5 @@
+"""Exercise scan directory reuse and protect the active database while archiving or rolling back."""
+
from __future__ import annotations
import argparse
diff --git a/plugins/codex-security/tests/test_workbench_scan_history.py b/plugins/codex-security/tests/test_workbench_scan_history.py
index d05b02615..3ecf51637 100644
--- a/plugins/codex-security/tests/test_workbench_scan_history.py
+++ b/plugins/codex-security/tests/test_workbench_scan_history.py
@@ -1,3 +1,5 @@
+"""Exercise history updates and reruns against the original checkout, scope, and revisions."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_workbench_scan_history_queries.py b/plugins/codex-security/tests/test_workbench_scan_history_queries.py
index f0d0925c5..b6f421b75 100644
--- a/plugins/codex-security/tests/test_workbench_scan_history_queries.py
+++ b/plugins/codex-security/tests/test_workbench_scan_history_queries.py
@@ -1,3 +1,5 @@
+"""Check repository matching and finding relationships across legacy, linked, and unlinked scan records."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_workbench_scan_usage.py b/plugins/codex-security/tests/test_workbench_scan_usage.py
index 87cc68523..22343b250 100644
--- a/plugins/codex-security/tests/test_workbench_scan_usage.py
+++ b/plugins/codex-security/tests/test_workbench_scan_usage.py
@@ -1,3 +1,5 @@
+"""Compute scan usage from session events and receipts, accounting for legacy duplicates and partial turns."""
+
from __future__ import annotations
import json
@@ -33,6 +35,8 @@ def scan_usage(workbench_api):
@dataclass(frozen=True)
class ScanFixture:
+ """Hold the CLI environment, scan identity, and launch time for replaying rollout events in usage tests."""
+
state_dir: Path
target: Path
scan_id: str
@@ -45,6 +49,7 @@ class ScanFixture:
def write_parent_rollout(
self, events: list[dict[str, Any]], *, originator: str | None = None
) -> Path:
+ """Write a parent rollout, register it in the fixture state graph, and return its path."""
rollout = _rollout(self.target.parent, "scan-parent", events, originator=originator)
_state_graph(self.environment, {"scan-parent": rollout}, [])
return rollout
diff --git a/plugins/codex-security/tests/test_workbench_scan_validation.py b/plugins/codex-security/tests/test_workbench_scan_validation.py
index aadf0152e..877a9f0f8 100644
--- a/plugins/codex-security/tests/test_workbench_scan_validation.py
+++ b/plugins/codex-security/tests/test_workbench_scan_validation.py
@@ -1,3 +1,5 @@
+"""Check saved target snapshots against current contents and earlier revision-only scan records."""
+
from __future__ import annotations
import os
diff --git a/plugins/codex-security/tests/test_workbench_setup_and_migrations.py b/plugins/codex-security/tests/test_workbench_setup_and_migrations.py
index 162258b23..69566b80a 100644
--- a/plugins/codex-security/tests/test_workbench_setup_and_migrations.py
+++ b/plugins/codex-security/tests/test_workbench_setup_and_migrations.py
@@ -1,3 +1,5 @@
+"""Exercise workbench state setup and migration across historical schemas and conflicting histories."""
+
from __future__ import annotations
import argparse
diff --git a/plugins/codex-security/tests/test_workbench_standard_deep_results.py b/plugins/codex-security/tests/test_workbench_standard_deep_results.py
index 2c6e759bf..d96cba887 100644
--- a/plugins/codex-security/tests/test_workbench_standard_deep_results.py
+++ b/plugins/codex-security/tests/test_workbench_standard_deep_results.py
@@ -1,3 +1,5 @@
+"""Reconcile saved parent and worker results across stops, reopened findings, and publication retries."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/test_workbench_stopped_worker_coverage.py b/plugins/codex-security/tests/test_workbench_stopped_worker_coverage.py
index 35fe9205e..99fc2c057 100644
--- a/plugins/codex-security/tests/test_workbench_stopped_worker_coverage.py
+++ b/plugins/codex-security/tests/test_workbench_stopped_worker_coverage.py
@@ -1,3 +1,5 @@
+"""Rebuild stopped scan coverage from worker surfaces, deferred links, and matching artifact receipts."""
+
from __future__ import annotations
import json
diff --git a/plugins/codex-security/tests/test_workbench_target.py b/plugins/codex-security/tests/test_workbench_target.py
index d2f83096d..e766e4af1 100644
--- a/plugins/codex-security/tests/test_workbench_target.py
+++ b/plugins/codex-security/tests/test_workbench_target.py
@@ -1,3 +1,5 @@
+"""Exercise Git discovery, snapshot identity, scoped inventory, and patch handling across filesystem aliases."""
+
from __future__ import annotations
import difflib
diff --git a/plugins/codex-security/tests/test_workbench_timestamps.py b/plugins/codex-security/tests/test_workbench_timestamps.py
index 5bd9097b6..4c58aa341 100644
--- a/plugins/codex-security/tests/test_workbench_timestamps.py
+++ b/plugins/codex-security/tests/test_workbench_timestamps.py
@@ -1,3 +1,5 @@
+"""Exercise UTC timestamps for workbench leases and deadlines with Python 3.10 semantics."""
+
from __future__ import annotations
import importlib
@@ -13,6 +15,8 @@ pytestmark = pytest.mark.cross_platform
class Python310DateTime(datetime):
+ """Freeze the clock and reproduce Python 3.10's handling of Z-suffixed timestamps for lease tests."""
+
@classmethod
def fromisoformat(cls, value: str) -> datetime:
if isinstance(value, str) and value.endswith(("Z", "z")):
diff --git a/plugins/codex-security/tests/test_worker_receipt_admission.py b/plugins/codex-security/tests/test_worker_receipt_admission.py
index b90bdaa24..f6917a7ca 100644
--- a/plugins/codex-security/tests/test_worker_receipt_admission.py
+++ b/plugins/codex-security/tests/test_worker_receipt_admission.py
@@ -1,3 +1,5 @@
+"""Check which worker receipts and surface links a stopped scan may retain from saved checkpoints."""
+
from __future__ import annotations
import copy
diff --git a/plugins/codex-security/tests/workbench_test_support.py b/plugins/codex-security/tests/workbench_test_support.py
index 273ead7a0..c576e7f97 100644
--- a/plugins/codex-security/tests/workbench_test_support.py
+++ b/plugins/codex-security/tests/workbench_test_support.py
@@ -1,3 +1,5 @@
+"""Build temporary workbench targets, scan artifacts, and database state for integration tests."""
+
from __future__ import annotations
import hashlib
@@ -34,6 +36,7 @@ PLUGIN_MANIFEST = Path(__file__).resolve().parents[1] / ".codex-plugin" / "plugi
def load_script(name: str, *, module_name: str | None = None) -> ModuleType:
+ """Load a fresh module from the plugin scripts directory, optionally overriding its import name."""
script = SCRIPT.parent / f"{name}.py"
spec = importlib.util.spec_from_file_location(module_name or name, script)
if spec is None or spec.loader is None:
@@ -120,6 +123,7 @@ def source_plugin_version() -> str:
def write_checkpoint(checkpoint_dir: Path, payload: Any, *, mtime_ns: int | None = None) -> Path:
+ """Write the serialized payload as a SHA-256-named checkpoint and optionally set its timestamp for ordering tests."""
encoded = json.dumps(payload).encode()
checkpoint_dir.mkdir(parents=True, exist_ok=True)
checkpoint_path = checkpoint_dir / f"{hashlib.sha256(encoded).hexdigest()}.json"
@@ -130,6 +134,7 @@ def write_checkpoint(checkpoint_dir: Path, payload: Any, *, mtime_ns: int | None
def select_checkpoint(output: Path, checkpoint: Path, *, mtime_ns: int | None = None) -> Path:
+ """Write a head pointing to the checkpoint filename and return the head path for further fixture changes."""
head = output / "checkpoint-head.json"
head.write_text(json.dumps({"checkpoint": checkpoint.name}))
if mtime_ns is not None:
@@ -143,6 +148,7 @@ def write_result_draft(path: Path, draft: dict, *, mtime_ns: int) -> None:
def sort_checkpoint_entries(monkeypatch, *, key=None, reverse=False):
+ """Control checkpoint enumeration order so a test can distinguish filesystem order from source precedence."""
from workbench import saved_sources
children = saved_sources._children
@@ -210,6 +216,7 @@ def saved_discovery_worker(output: Path, worker_id: str = "worker", attempt: int
def replay_saved_results(
module, documents, scan_dir, scan_id, binding, workers=(), *, stopped=True
):
+ """Rebuild the interrupted result using the source digests frozen in the supplied manifest."""
return module.merge_saved_results(
scan_dir,
scan_id,
@@ -235,6 +242,7 @@ def update_digest_field(digest: Any, label: bytes, value: bytes) -> None:
def directory_snapshot_digest(target: Path, *, excluded: tuple[Path, ...] = ()) -> str:
+ """Compute the expected snapshot digest from fixture paths, entry modes, link targets, and file contents."""
excluded_relative = []
for path in excluded:
try:
@@ -278,6 +286,12 @@ def run_workbench(
input_text: str | None = None,
umask: int = -1,
) -> dict[str, object]:
+ """Run the workbench CLI with a fixture state directory and capture its output.
+
+ By default, decode JSON from stdout and raise CalledProcessError on failure.
+ With check=False, return the exit code and stderr for diagnostic assertions.
+ Entries in environment override the inherited environment and state setting.
+ """
completed = subprocess.run(
[sys.executable, str(SCRIPT), *args],
check=check,
@@ -535,6 +549,8 @@ def write_remediation_patch(patch_path: Path, **text_options: Any) -> None:
@dataclass(frozen=True)
class RemediationRequest:
+ """Run remediation commands for one occurrence using the same request ID across retries and state changes."""
+
state_dir: Path
occurrence_id: str
id: str = field(default_factory=lambda: str(uuid.uuid4()))
@@ -997,6 +1013,8 @@ def windows_file_backend() -> mock.Mock:
class ScanFixtureTestCase(TestCase):
+ """Copy the example scan into a fresh temporary directory and rebuild its report for each test."""
+
def setUp(self) -> None:
self.temp_dir = tempfile.TemporaryDirectory()
self.scan_dir = Path(self.temp_dir.name) / "scan"
@@ -1019,6 +1037,7 @@ class ScanFixtureTestCase(TestCase):
path.write_text(json.dumps(payload, indent=2) + "\n", encoding="utf-8")
def rewrite_sealed_artifact(self, relative_path: str, payload: object) -> None:
+ """Rewrite the JSON artifact and update its hash in the fixture manifest so the seal matches the new bytes."""
self.write_json(relative_path, payload)
manifest = self.read_json("scan-manifest.json")
for artifact in manifest["scan"]["artifacts"]:
diff --git a/sdk/typescript/tests-ts/fixtures/source_scopes.py b/sdk/typescript/tests-ts/fixtures/source_scopes.py
index ddf66cebc..d70952144 100644
--- a/sdk/typescript/tests-ts/fixtures/source_scopes.py
+++ b/sdk/typescript/tests-ts/fixtures/source_scopes.py
@@ -1,4 +1,8 @@
-"""Synthetic Git fixtures for finding-source authorization tests."""
+"""Run one source-scope scenario in a temporary Git repository and print its JSON result.
+
+The SDK test passes the workbench scripts directory and scenario name on the command line.
+Scenarios exercise saved scan permissions against Git objects and the host filesystem.
+"""
from __future__ import annotations
@@ -28,6 +32,7 @@ from workbench_target import clean_worktree_content_digest
def git(repository: Path, *arguments: str, input_data: bytes | None = None) -> str:
+ """Run Git with fixture-local author details and return stripped stdout on success."""
environment = dict(
os.environ, GIT_CONFIG_GLOBAL=os.devnull, GIT_CONFIG_NOSYSTEM="1"
)
@@ -60,12 +65,14 @@ def write(repository: Path, name: str, content: str) -> None:
def commit(repository: Path) -> str:
+ """Stage all fixture changes, commit them, and return the resulting revision."""
git(repository, "add", "--all")
git(repository, "commit", "--quiet", "-m", "Synthetic fixture")
return git(repository, "rev-parse", "HEAD")
def scan(repository: Path, revision: str, paths: list[str]) -> dict:
+ """Build a saved scan record for a clean revision using the requested relative paths."""
identity = (revision, clean_worktree_content_digest(), 0, 0)
return {
"target_revision": revision,
@@ -80,6 +87,7 @@ def scan(repository: Path, revision: str, paths: list[str]) -> dict:
def excerpt(
record: dict, repository: Path, path: str, selected: list[str]
) -> str | None:
+ """Return the numbered excerpt for the first line at path, or None when it is unavailable."""
return excerpts.finding_source_excerpt(
record, repository, [{"path": path, "startLine": 1}], selected
)
@@ -88,6 +96,16 @@ def excerpt(
def register_recipe(
repository: Path, recipe: dict, environment: dict[str, str] | None = None
) -> tuple[dict, dict]:
+ """Register a real CLI scan in fixture state and read it back from SQLite.
+
+ Args:
+ repository (Path): Synthetic target with a writable parent for state and scan files.
+ recipe (dict): Launch recipe serialized for the register-cli-scan command.
+ environment (dict | None): Extra environment variables for the workbench subprocess.
+
+ Returns:
+ tuple: The JSON reply used by CLI callers and the complete persisted scan row.
+ """
state = repository.parent / "state"
scan_dir = Path(tempfile.mkdtemp(prefix="cli-scan-", dir=repository.parent))
result = subprocess.run(
@@ -125,6 +143,7 @@ def register_recipe(
def directory_link(target: Path, link: Path) -> None:
+ """Create a directory junction on Windows or a directory symlink on POSIX."""
if os.name == "nt":
subprocess.run(
[
@@ -142,6 +161,7 @@ def directory_link(target: Path, link: Path) -> None:
def replacements(repository: Path) -> None:
+ """Check that saved excerpts use original Git objects and active replacements block new scopes."""
write(repository, "selected.py", "selected source\n")
write(repository, "private.py", "private source\n")
write(repository, "selected/public.py", "selected directory\n")
@@ -170,6 +190,7 @@ def replacements(repository: Path) -> None:
def replacement_filters(repository: Path) -> None:
+ """Check that registering a revision with replacement refs never invokes the worktree clean filter."""
write(repository, "tracked.py", "synthetic source\n")
write(repository, ".gitattributes", "tracked.py filter=scope_probe\n")
revision = commit(repository)
@@ -217,6 +238,7 @@ def replacement_filters(repository: Path) -> None:
def replacement_snapshot(repository: Path) -> None:
+ """Exercise saved and legacy scopes when replacements make a different tree appear clean."""
from workbench_scan_start import scan_target_identity
write(repository, "src/public.py", "historical source\n")
@@ -259,6 +281,7 @@ def replacement_snapshot(repository: Path) -> None:
def indexed_scopes(repository: Path) -> int:
+ """Return the number of selected files after checking that path normalization scales linearly."""
selected = [f"source-{index}.py" for index in range(256)]
for name in selected:
write(repository, name, "synthetic source\n")
@@ -280,6 +303,7 @@ def indexed_scopes(repository: Path) -> int:
def display_locations(repository: Path) -> int:
+ """Return the displayed location count after checking the excerpt uses a visible location."""
import workbench_db as db
from filesystem_identity import serialize_filesystem_identity
@@ -341,6 +365,7 @@ def display_locations(repository: Path) -> int:
def selected_redirects(repository: Path) -> None:
+ """Verify requested paths stay in the recipe even when directory links prevent excerpt access."""
write(repository, ".gitignore", "/selected/link\n")
write(repository, "selected/public.py", "selected source\n")
write(repository, "private/secret.py", "private source\n")
@@ -374,6 +399,7 @@ def selected_redirects(repository: Path) -> None:
def working_tree_excerpt(repository: Path) -> dict:
+ """Report excerpt availability for dirty working-tree scans and explicit commit-range scans."""
write(repository, "source.py", "old committed source\n")
revision = commit(repository)
write(repository, "source.py", "new working-tree source\n")
@@ -415,6 +441,7 @@ def working_tree_excerpt(repository: Path) -> dict:
def unsafe_locations(repository: Path) -> None:
+ """Check that malformed line numbers and paths outside the repository are rejected before Git lookup."""
write(repository, "source.py", "selected source\n")
record = scan(repository, commit(repository), ["."])
outside = repository.parent / "outside"
@@ -442,6 +469,7 @@ def unsafe_locations(repository: Path) -> None:
def boundaries(repository: Path) -> dict:
+ """Return excerpt results for saved and legacy scopes, including removed paths and offline reads."""
for name, content in {
"src/public.py": "public source\n",
"src/support.py": "support source\n",
@@ -583,6 +611,7 @@ def boundaries(repository: Path) -> dict:
def aliases(repository: Path) -> dict:
+ """Return the case and Unicode aliases supported by the fixture filesystem after checking excerpt lookup."""
composed = unicodedata.normalize("NFC", "café")
decomposed = unicodedata.normalize("NFD", composed)
write(repository, "src/nested/public.py", "historical source\n")
@@ -666,6 +695,7 @@ def aliases(repository: Path) -> dict:
def descendant_aliases(repository: Path) -> None:
+ """Exercise case collisions below a saved directory before and after deleting its worktree copy."""
pairs = [("foo.py", "FOO.py"), ("nested/public.py", "NESTED/public.py")]
for lower, _ in pairs:
write(repository, f"selected/{lower}", "lower source\n")
@@ -703,6 +733,7 @@ def descendant_aliases(repository: Path) -> None:
def alias_evidence(_: Path) -> dict:
+ """Return alias decisions for simulated regular files, hard links, symlinks, and reparse points."""
selected, candidate = Path("/synthetic/SECRET.py"), Path("/synthetic/secret.py")
result = {}
for kind in ("ordinary", "hardlink", "symlink", "reparse"):
@@ -732,6 +763,7 @@ def alias_evidence(_: Path) -> dict:
def worktrees(repository: Path) -> None:
+ """Check that scopes in a nested scan target retain that boundary in a linked worktree."""
write(repository, "nested/src/public.py", "nested target source\n")
write(repository, "private.py", "outside target source\n")
revision = commit(repository)
@@ -757,6 +789,7 @@ def worktrees(repository: Path) -> None:
def writer(repository: Path, kind: str) -> str:
+ """Exercise the named scan entry point, check persisted scope metadata, and return the entry point name."""
write(repository, "src/public.py", "public source\n")
write(repository, "selected.py", "selected file\n")
revision = commit(repository)
@@ -897,6 +930,7 @@ def writer(repository: Path, kind: str) -> str:
def migration(_: Path) -> None:
+ """Check how source-scope migrations handle preexisting scans and conflicting migration records."""
from workbench_schema import MIGRATIONS, apply_migrations
timestamp = "2026-08-01T00:00:00Z"
diff --git a/sdk/typescript/tests-ts/fixtures/verify_fix_stderr_harness.py b/sdk/typescript/tests-ts/fixtures/verify_fix_stderr_harness.py
index ab8e6a1c8..b44b92323 100644
--- a/sdk/typescript/tests-ts/fixtures/verify_fix_stderr_harness.py
+++ b/sdk/typescript/tests-ts/fixtures/verify_fix_stderr_harness.py
@@ -1,3 +1,9 @@
+"""Run verify-fix fixture processes with broken or congested stderr and emit JSON results.
+
+A separate pipe carries synchronization events so tests can observe worker completion,
+cancellation, and cleanup even when the simulated terminal stops accepting output.
+"""
+
from __future__ import annotations
from contextlib import contextmanager
@@ -21,6 +27,8 @@ NODE, FIXTURE, CWD, STATE_ROOT, SCENARIO_TIMEOUT = sys.argv[1:]
class HarnessTermination(Exception):
+ """Unwind a scenario on SIGTERM so the harness can clean up its process group."""
+
pass
@@ -33,6 +41,7 @@ signal.signal(signal.SIGTERM, terminate_harness)
def wait(process: subprocess.Popen, timeout: float = 10):
+ """Return True if the child is still running after the timeout, in seconds."""
try:
process.wait(timeout=timeout)
return False
@@ -41,6 +50,14 @@ def wait(process: subprocess.Popen, timeout: float = 10):
class RunningProcess:
+ """Own a fixture subprocess, its process group, and the read end of its synchronization pipe.
+
+ The process attribute is the Node child. The state path is where its worker
+ publishes a PID. Use event_until to synchronize with that worker and finish
+ to collect the exit status and output. The running context manager releases
+ the process group and descriptors on exit.
+ """
+
def __init__(self, scenario: str, stderr, label: str):
self.label = label
sync_read, sync_write = os.pipe()
@@ -75,12 +92,14 @@ class RunningProcess:
self.sync_buffer = b""
def send(self, command: str = "continue"):
+ """Write one newline-terminated command to the child and flush it immediately."""
if self.process.stdin is None or self.process.stdin.closed:
raise AssertionError("fixture stdin is closed")
self.process.stdin.write(f"{command}\n".encode())
self.process.stdin.flush()
def _next_event(self, timeout: float = 10):
+ """Decode one newline-delimited JSON event, retaining later events in the read buffer."""
deadline = time.monotonic() + timeout
while b"\n" not in self.sync_buffer:
remaining = deadline - time.monotonic()
@@ -97,6 +116,18 @@ class RunningProcess:
return json.loads(line)
def event_until(self, name: str, worker: int | None = None):
+ """Read synchronization events through the first matching milestone.
+
+ Args:
+ name (str): Event name emitted by the child.
+ worker (int | None): Require a matching worker ID when supplied.
+
+ Returns:
+ list: All events read by this call, including the matching event.
+
+ Raises:
+ AssertionError: The synchronization pipe closes or times out before the milestone.
+ """
events = []
while True:
try:
@@ -127,6 +158,7 @@ class RunningProcess:
pass
def stop(self):
+ """Stop the fixture, escalating to SIGKILL and cleaning up any descendants still in its group."""
if self.process.poll() is None:
self.signal_group(signal.SIGTERM)
if wait(self.process, 1):
@@ -154,6 +186,7 @@ class RunningProcess:
return stream.read().decode(errors="replace")
def collect(self, events, blocked: bool = False):
+ """Drain events into the supplied list and return exit status, captured output, and the blocked flag."""
if self.process.poll() is None:
self.process.wait()
events.extend(self._remaining_events())
@@ -171,6 +204,15 @@ class RunningProcess:
}
def finish(self, events, timeout: float = 10):
+ """Close stdin, then wait for the child before collecting its final state.
+
+ Args:
+ events (list): Previously observed synchronization events, extended in place.
+ timeout (float): Seconds to wait for normal exit before stopping the group.
+
+ Returns:
+ dict: Exit code, timeout flag (blocked), stdout, stderr, and all observed events.
+ """
self.close_stdin()
blocked = wait(self.process, timeout)
if blocked:
@@ -192,6 +234,8 @@ class RunningProcess:
@contextmanager
def running(scenario: str, stderr=subprocess.PIPE, *, label: str | None = None):
+ """Yield an isolated fixture process and clean it up on completion, interruption, or timeout."""
+
def timeout(_signal_number, _frame):
raise TimeoutError(f"Verification fixture timed out: {scenario}")
@@ -206,6 +250,7 @@ def running(scenario: str, stderr=subprocess.PIPE, *, label: str | None = None):
def read_pty(master: int):
+ """Read the master end through EOF or terminal hangup and decode the captured output."""
chunks = []
while True:
try:
@@ -235,12 +280,14 @@ def drain_pty(master: int, stopped: threading.Event):
def open_pty():
+ """Return master and slave descriptors for a terminal with 24 rows and 100 columns."""
master, slave = pty.openpty()
fcntl.ioctl(slave, termios.TIOCSWINSZ, struct.pack("HHHH", 24, 100, 0, 0))
return master, slave
def wait_for_worker(state: Path):
+ """Return the PID written by a worker, raising AssertionError if its state file fails to appear."""
deadline = time.monotonic() + 10
while not state.exists():
if time.monotonic() >= deadline:
@@ -274,6 +321,7 @@ def connected_output(scenario: str, name: str, stderr=subprocess.PIPE):
def fill_output(fd: int):
+ """Fill the descriptor until a single byte would block, then restore blocking mode."""
os.set_blocking(fd, False)
try:
chunk = b"x" * 4096
@@ -324,6 +372,7 @@ def disconnected_pty(scenario: str):
def release_with_full_terminal(fixture: RunningProcess, slave: int):
+ """Fill terminal output before releasing the second worker and return its startup events."""
events = fixture.event_until("worker-started", 2)
# Use a separate file description so the fixture's stderr stays blocking.
with open(os.ttyname(slave), "wb", buffering=0) as filler:
@@ -333,6 +382,7 @@ def release_with_full_terminal(fixture: RunningProcess, slave: int):
def paused_pty(scenario: str, sent_signal: signal.Signals | None):
+ """Return completion and worker-liveness observations while leaving terminal output undrained."""
master, slave = open_pty()
try:
with running(scenario, slave) as fixture:
@@ -395,6 +445,7 @@ def full_terminal(scenario: str):
def mixed_signals(first: signal.Signals, second: signal.Signals):
+ """Send the second signal after the worker observes the first and collect the final worker state."""
scenario = f"pty-backpressure-mixed-{first.name.lower()}-{second.name.lower()}"
master, slave = open_pty()
try:
@@ -431,6 +482,7 @@ def mixed_signals(first: signal.Signals, second: signal.Signals):
def cleanup_sigwinch():
+ """Deliver a resize signal after terminal cleanup and capture the fixture's response."""
master, slave = open_pty()
stop_reader = threading.Event()
reader = threading.Thread(target=drain_pty, args=(master, stop_reader))