From 9b8f32ab313bc367cb21b5066cbfa2fce62d99ab Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 11 Sep 2026 14:03:40 +0900 Subject: [PATCH 1/2] docs(ci): explain JavaScript materializer trust boundaries --- .../agent-review-runtime-quality-ci.yml | 41 ++++++++++++++++- ...0912-javascript-materializer-docstrings.md | 1 + .../materialize_base_javascript_packages.py | 45 +++++++++++++++---- ...test_javascript_materializer_docstrings.py | 21 +++++++++ 4 files changed, 97 insertions(+), 11 deletions(-) create mode 100644 CHANGELOG.d/20260912-javascript-materializer-docstrings.md create mode 100644 tests/test_javascript_materializer_docstrings.py diff --git a/.github/workflows/agent-review-runtime-quality-ci.yml b/.github/workflows/agent-review-runtime-quality-ci.yml index 3680da8778..4fb32063d5 100644 --- a/.github/workflows/agent-review-runtime-quality-ci.yml +++ b/.github/workflows/agent-review-runtime-quality-ci.yml @@ -16,6 +16,8 @@ on: - ".github/workflows/opencode-review-dispatch.yml" - "scripts/ci/ensure_rust_llvm19.sh" - "tests/test_opencode_rust_coverage_toolchain_contract.py" + - "scripts/ci/materialize_base_javascript_packages.py" + - "tests/test_javascript_materializer_docstrings.py" - "tests/test_pr_review_autofix_nvidia_nim_contract.py" - "docs/doctoring/opencode-rust-coverage-runtime-boundary.md" - ".github/workflows/strix.yml" @@ -90,6 +92,10 @@ on: - "scripts/ci/organization_commercial_readiness_loop.py" - "organization_commercial_readiness_fixtures.py" - "tests/test_organization_commercial_readiness_loop*.py" + - "tests/test_organization_commercial_readiness_docstrings.py" + - "CHANGELOG.d/20260911-commercial-readiness-docstrings.md" + - "tests/test_action_pin_annotation_integrity.py" + - "CHANGELOG.d/20260910-action-pin-annotation-integrity.md" - "docs/doctoring/organization-commercial-readiness-loop.md" - ".github/workflows/exact-artifact-sbom-attestation.yml" - "scripts/ci/verify_exact_artifact_sbom_handoff.py" @@ -97,6 +103,8 @@ on: - "tests/test_exact_artifact_sbom_review_regressions.py" - "tests/test_verify_exact_artifact_sbom_handoff.py" - "tests/test_exact_artifact_quality_single_runner.py" + - ".github/workflows/**" + - ".github/actions/**" - "docs/doctoring/exact-artifact-sbom-attestation.md" - "docs/doctoring/exact-artifact-sbom-quality-runner-consolidation-20260903.md" - "CHANGELOG.d/20260903-exact-artifact-quality-runner-consolidation.md" @@ -153,6 +161,7 @@ jobs: review_repair_suite=false commercial_readiness_suite=false exact_artifact_suite=false + pin_annotation_suite=false while IFS= read -r changed_path; do case "$changed_path" in @@ -164,6 +173,7 @@ jobs: review_repair_suite=true commercial_readiness_suite=true exact_artifact_suite=true + pin_annotation_suite=true ;; tests/test_pr_review_autofix_nvidia_nim_contract.py) opencode_suite=true @@ -185,6 +195,8 @@ jobs: .github/workflows/opencode-review-dispatch.yml|\ scripts/ci/ensure_rust_llvm19.sh|\ tests/test_opencode_rust_coverage_toolchain_contract.py|\ + scripts/ci/materialize_base_javascript_packages.py|\ + tests/test_javascript_materializer_docstrings.py|\ docs/doctoring/opencode-rust-coverage-runtime-boundary.md) opencode_suite=true ;; @@ -271,6 +283,8 @@ jobs: scripts/ci/organization_commercial_readiness_loop.py|\ organization_commercial_readiness_fixtures.py|\ tests/test_organization_commercial_readiness_loop*.py|\ + tests/test_organization_commercial_readiness_docstrings.py|\ + CHANGELOG.d/20260911-commercial-readiness-docstrings.md|\ docs/doctoring/organization-commercial-readiness-loop.md) commercial_readiness_suite=true ;; @@ -286,6 +300,11 @@ jobs: exact_artifact_suite=true ;; esac + case "$changed_path" in + .github/workflows/*|.github/actions/*|tests/test_action_pin_annotation_integrity.py|CHANGELOG.d/20260910-action-pin-annotation-integrity.md) + pin_annotation_suite=true + ;; + esac done < <(git diff --name-only "$BASE_SHA...$HEAD_SHA") { @@ -296,6 +315,7 @@ jobs: echo "review_repair=$review_repair_suite" echo "commercial_readiness=$commercial_readiness_suite" echo "exact_artifact=$exact_artifact_suite" + echo "pin_annotation=$pin_annotation_suite" } >>"$GITHUB_OUTPUT" - name: Install exact hash-verified base dependencies @@ -339,6 +359,13 @@ jobs: tests/test_noema_refreshed_app_identity.py \ tests/test_noema_token_lifetime_stale_run_contract.py + - name: Verify immutable action annotation consistency + if: steps.affected_suites.outputs.pin_annotation == 'true' + run: | + set -euo pipefail + python -m pytest -q tests/test_action_pin_annotation_integrity.py + python -m compileall -q tests/test_action_pin_annotation_integrity.py + - name: Verify OpenCode Rust coverage toolchain contract if: steps.affected_suites.outputs.opencode == 'true' run: | @@ -346,6 +373,13 @@ jobs: python -m pytest -q tests/test_opencode_rust_coverage_toolchain_contract.py python -m compileall -q tests/test_opencode_rust_coverage_toolchain_contract.py + - name: Verify JavaScript materializer documentation contract + if: steps.affected_suites.outputs.opencode == 'true' + run: | + set -euo pipefail + python -m pytest -q tests/test_javascript_materializer_docstrings.py + python -m compileall -q scripts/ci/materialize_base_javascript_packages.py tests/test_javascript_materializer_docstrings.py + - name: Verify exact-head path policy and syntax if: steps.affected_suites.outputs.strix == 'true' env: @@ -425,7 +459,9 @@ jobs: run: | python -m coverage run \ --branch \ - -m pytest --import-mode=importlib tests/test_organization_commercial_readiness_loop*.py -q + -m pytest --import-mode=importlib \ + tests/test_organization_commercial_readiness_loop*.py \ + tests/test_organization_commercial_readiness_docstrings.py -q python -m coverage report \ --include='scripts/ci/organization_commercial_readiness_loop.py' \ --show-missing \ @@ -433,7 +469,8 @@ jobs: python -m compileall -q \ scripts/ci/organization_commercial_readiness_loop.py \ organization_commercial_readiness_fixtures.py \ - tests/test_organization_commercial_readiness_loop*.py + tests/test_organization_commercial_readiness_loop*.py \ + tests/test_organization_commercial_readiness_docstrings.py - name: Set up minimum supported Python for exact-artifact contracts if: steps.affected_suites.outputs.exact_artifact == 'true' diff --git a/CHANGELOG.d/20260912-javascript-materializer-docstrings.md b/CHANGELOG.d/20260912-javascript-materializer-docstrings.md new file mode 100644 index 0000000000..1165181540 --- /dev/null +++ b/CHANGELOG.d/20260912-javascript-materializer-docstrings.md @@ -0,0 +1 @@ +Document trusted JavaScript lock discovery and validation boundaries with explanatory contracts enforced by CI. diff --git a/scripts/ci/materialize_base_javascript_packages.py b/scripts/ci/materialize_base_javascript_packages.py index 489364f92e..5937161896 100644 --- a/scripts/ci/materialize_base_javascript_packages.py +++ b/scripts/ci/materialize_base_javascript_packages.py @@ -58,7 +58,10 @@ def _github_actions_escape(value: object) -> str: def _git(repo_root: pathlib.Path, *args: str) -> bytes: - """Run one read-only git command in the materialized repository.""" + """Run one read-only git command in the materialized repository. + + Git failures remain bounded diagnostics and never become trusted input. + """ completed = subprocess.run( ["git", "-C", str(repo_root), *args], check=False, @@ -72,7 +75,10 @@ def _git(repo_root: pathlib.Path, *args: str) -> bytes: def _regular_base_paths(repo_root: pathlib.Path, base_sha: str) -> set[str]: - """Return regular blob paths from the exact validated base commit.""" + """Return regular blob paths from the exact validated base commit. + + Symlink-like and traversal paths are excluded before content is materialized. + """ entries = _git(repo_root, "ls-tree", "-r", "-z", "--full-tree", base_sha) paths: set[str] = set() for raw_entry in entries.split(b"\0"): @@ -102,7 +108,10 @@ def _regular_base_paths(repo_root: pathlib.Path, base_sha: str) -> set[str]: def base_pnpm_projects( repo_root: pathlib.Path, base_sha: str ) -> list[tuple[str, str, dict[str, bytes]]]: - """Return exact base pnpm inputs grouped by lockfile directory.""" + """Return exact base pnpm inputs grouped by lockfile directory. + + Each project must declare an exact package-manager version and regular inputs. + """ if not SHA_RE.fullmatch(base_sha): raise ValueError("base SHA must be exactly 40 hexadecimal characters") @@ -183,7 +192,10 @@ def base_pnpm_projects( def base_npm_projects( repo_root: pathlib.Path, base_sha: str ) -> list[tuple[str, str, dict[str, bytes]]]: - """Return exact base npm inputs grouped by lockfile directory.""" + """Return exact base npm inputs grouped by lockfile directory. + + Vestigial locks and unsafe workspace paths are excluded from the trusted set. + """ if not SHA_RE.fullmatch(base_sha): raise ValueError("base SHA must be exactly 40 hexadecimal characters") @@ -268,7 +280,10 @@ def base_npm_projects( def _lock_blob_sha(repo_root: pathlib.Path, revision_sha: str, lock_path: str) -> str: - """Return the exact Git blob SHA for one validated revision lockfile.""" + """Return the exact Git blob SHA for one validated revision lockfile. + + The identity binds materialized dependency bytes to the reviewed revision. + """ raw_blob = _git(repo_root, "rev-parse", f"{revision_sha}:{lock_path}") blob_sha = raw_blob.decode("ascii", errors="strict").strip() if not SHA_RE.fullmatch(blob_sha): @@ -279,7 +294,10 @@ def _lock_blob_sha(repo_root: pathlib.Path, revision_sha: str, lock_path: str) - def validate_head_npm_lock(lock_path: str, lock_content: bytes) -> None: - """Fail closed unless a changed HEAD npm lock is registry- and hash-bounded.""" + """Fail closed unless a changed HEAD npm lock is registry- and hash-bounded. + + Registry URLs, workspace links, and integrity values are checked without installation. + """ try: lock_data: Any = json.loads(lock_content.decode("utf-8")) except (UnicodeDecodeError, json.JSONDecodeError) as exc: @@ -372,7 +390,10 @@ def validate_head_npm_lock(lock_path: str, lock_content: bytes) -> None: def _validate_pnpm_tarball_url( lock_path: str, package_key: str, tarball_url: str ) -> None: - """Fail closed unless one pnpm tarball URL is an npm-registry HTTPS URL.""" + """Fail closed unless one pnpm tarball URL is an npm-registry HTTPS URL. + + Userinfo, ports, query strings, fragments, and alternate hosts are rejected. + """ parsed = urllib.parse.urlsplit(tarball_url) try: parsed_port = parsed.port @@ -516,7 +537,10 @@ def materialize( output_dir: pathlib.Path, head_sha: str | None = None, ) -> list[dict[str, str]]: - """Write trusted base and bounded HEAD inputs under Docker-context-safe paths.""" + """Write trusted base and bounded HEAD inputs under Docker-context-safe paths. + + Manifest records retain revision and lock-blob identity for downstream verification. + """ if output_dir.exists() and output_dir.is_symlink(): raise ValueError("output directory must not be a symlink") output_dir.mkdir(parents=True, exist_ok=True) @@ -624,7 +648,10 @@ def materialize( def main(argv: list[str] | None = None) -> int: - """Materialize trusted JavaScript locks and report their exact revisions.""" + """Materialize trusted JavaScript locks and report their exact revisions. + + Invalid or unsafe input returns a bounded non-zero diagnostic for the caller. + """ parser = argparse.ArgumentParser() parser.add_argument("--repo-root", required=True, type=pathlib.Path) parser.add_argument("--base-sha", required=True) diff --git a/tests/test_javascript_materializer_docstrings.py b/tests/test_javascript_materializer_docstrings.py new file mode 100644 index 0000000000..0457332d01 --- /dev/null +++ b/tests/test_javascript_materializer_docstrings.py @@ -0,0 +1,21 @@ +"""Documentation contract for trusted JavaScript lock materialization.""" + +import ast +from pathlib import Path + + +MODULE = Path(__file__).resolve().parents[1] / "scripts/ci/materialize_base_javascript_packages.py" + + +def test_materializer_symbols_have_explanatory_multiline_docstrings() -> None: + """Lock discovery and validation code must explain its trust boundary.""" + tree = ast.parse(MODULE.read_text(encoding="utf-8")) + violations = [] + for node in ast.walk(tree): + if not isinstance(node, (ast.ClassDef, ast.FunctionDef, ast.AsyncFunctionDef)): + continue + docstring = ast.get_docstring(node, clean=False) + if docstring is None or "\n" not in docstring: + violations.append((node.name, node.lineno)) + + assert not violations, f"materializer symbols need explanatory docs: {violations}" From a6160ab6d4a5708781d2d842094de9a7a07d4ace Mon Sep 17 00:00:00 2001 From: Seongho Bae Date: Fri, 11 Sep 2026 14:15:45 +0900 Subject: [PATCH 2/2] fix(ci): keep JavaScript quality lane self-contained --- .../agent-review-runtime-quality-ci.yml | 29 ++----------------- 1 file changed, 2 insertions(+), 27 deletions(-) diff --git a/.github/workflows/agent-review-runtime-quality-ci.yml b/.github/workflows/agent-review-runtime-quality-ci.yml index 4fb32063d5..6c6efc3dd1 100644 --- a/.github/workflows/agent-review-runtime-quality-ci.yml +++ b/.github/workflows/agent-review-runtime-quality-ci.yml @@ -92,10 +92,6 @@ on: - "scripts/ci/organization_commercial_readiness_loop.py" - "organization_commercial_readiness_fixtures.py" - "tests/test_organization_commercial_readiness_loop*.py" - - "tests/test_organization_commercial_readiness_docstrings.py" - - "CHANGELOG.d/20260911-commercial-readiness-docstrings.md" - - "tests/test_action_pin_annotation_integrity.py" - - "CHANGELOG.d/20260910-action-pin-annotation-integrity.md" - "docs/doctoring/organization-commercial-readiness-loop.md" - ".github/workflows/exact-artifact-sbom-attestation.yml" - "scripts/ci/verify_exact_artifact_sbom_handoff.py" @@ -103,8 +99,6 @@ on: - "tests/test_exact_artifact_sbom_review_regressions.py" - "tests/test_verify_exact_artifact_sbom_handoff.py" - "tests/test_exact_artifact_quality_single_runner.py" - - ".github/workflows/**" - - ".github/actions/**" - "docs/doctoring/exact-artifact-sbom-attestation.md" - "docs/doctoring/exact-artifact-sbom-quality-runner-consolidation-20260903.md" - "CHANGELOG.d/20260903-exact-artifact-quality-runner-consolidation.md" @@ -161,7 +155,6 @@ jobs: review_repair_suite=false commercial_readiness_suite=false exact_artifact_suite=false - pin_annotation_suite=false while IFS= read -r changed_path; do case "$changed_path" in @@ -173,7 +166,6 @@ jobs: review_repair_suite=true commercial_readiness_suite=true exact_artifact_suite=true - pin_annotation_suite=true ;; tests/test_pr_review_autofix_nvidia_nim_contract.py) opencode_suite=true @@ -283,8 +275,6 @@ jobs: scripts/ci/organization_commercial_readiness_loop.py|\ organization_commercial_readiness_fixtures.py|\ tests/test_organization_commercial_readiness_loop*.py|\ - tests/test_organization_commercial_readiness_docstrings.py|\ - CHANGELOG.d/20260911-commercial-readiness-docstrings.md|\ docs/doctoring/organization-commercial-readiness-loop.md) commercial_readiness_suite=true ;; @@ -300,11 +290,6 @@ jobs: exact_artifact_suite=true ;; esac - case "$changed_path" in - .github/workflows/*|.github/actions/*|tests/test_action_pin_annotation_integrity.py|CHANGELOG.d/20260910-action-pin-annotation-integrity.md) - pin_annotation_suite=true - ;; - esac done < <(git diff --name-only "$BASE_SHA...$HEAD_SHA") { @@ -315,7 +300,6 @@ jobs: echo "review_repair=$review_repair_suite" echo "commercial_readiness=$commercial_readiness_suite" echo "exact_artifact=$exact_artifact_suite" - echo "pin_annotation=$pin_annotation_suite" } >>"$GITHUB_OUTPUT" - name: Install exact hash-verified base dependencies @@ -359,13 +343,6 @@ jobs: tests/test_noema_refreshed_app_identity.py \ tests/test_noema_token_lifetime_stale_run_contract.py - - name: Verify immutable action annotation consistency - if: steps.affected_suites.outputs.pin_annotation == 'true' - run: | - set -euo pipefail - python -m pytest -q tests/test_action_pin_annotation_integrity.py - python -m compileall -q tests/test_action_pin_annotation_integrity.py - - name: Verify OpenCode Rust coverage toolchain contract if: steps.affected_suites.outputs.opencode == 'true' run: | @@ -460,8 +437,7 @@ jobs: python -m coverage run \ --branch \ -m pytest --import-mode=importlib \ - tests/test_organization_commercial_readiness_loop*.py \ - tests/test_organization_commercial_readiness_docstrings.py -q + tests/test_organization_commercial_readiness_loop*.py -q python -m coverage report \ --include='scripts/ci/organization_commercial_readiness_loop.py' \ --show-missing \ @@ -469,8 +445,7 @@ jobs: python -m compileall -q \ scripts/ci/organization_commercial_readiness_loop.py \ organization_commercial_readiness_fixtures.py \ - tests/test_organization_commercial_readiness_loop*.py \ - tests/test_organization_commercial_readiness_docstrings.py + tests/test_organization_commercial_readiness_loop*.py - name: Set up minimum supported Python for exact-artifact contracts if: steps.affected_suites.outputs.exact_artifact == 'true'