From e7bb17b09ff20619807128a16ebe4b2ef8631fe5 Mon Sep 17 00:00:00 2001 From: Jaro-c <75870284+Jaro-c@users.noreply.github.com> Date: Tue, 25 Aug 2026 13:22:04 -0500 Subject: [PATCH] docs: repair docstrings in pin-policy tests and script Three defects misled readers without touching any logic: - An `import pytest` line was wedged into the module docstring of tests/test_pin_policy.py, mid-sentence. The file uses no pytest API (fixtures live in conftest.py), so the stray line had to go and nothing else had to be added. - tests/test_pin_policy.py cited `auditoria-tests-canales.md` three times. That document does not exist in any public Glyndor repo, so the link promised a source no reader could open. The four gaps are already enumerated below each reference, so removing the link leaves the substance intact. - scripts/pin-policy.py: `call_failure`'s docstring said `git api`, which does not exist; the script invokes the `gh` CLI instead. Signed-off-by: Jaro-c <75870284+Jaro-c@users.noreply.github.com> --- scripts/pin-policy.py | 2 +- tests/test_pin_policy.py | 8 +++----- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/scripts/pin-policy.py b/scripts/pin-policy.py index 1240f82..5dd5ac9 100644 --- a/scripts/pin-policy.py +++ b/scripts/pin-policy.py @@ -108,7 +108,7 @@ def gh_api_json(path): def call_failure(exc): - """Return the reason a `git api` call failed, for an operator to act on. + """Return the reason a `gh api` call failed, for an operator to act on. The first version of this script formatted the CalledProcessError itself, which prints the argv and the exit status and drops stderr — so the run diff --git a/tests/test_pin_policy.py b/tests/test_pin_policy.py index a80250d..c3304f4 100644 --- a/tests/test_pin_policy.py +++ b/tests/test_pin_policy.py @@ -1,6 +1,6 @@ """Tests for scripts/pin-policy.py. -The four gaps the audit (`auditoria-tests-canales.md`) called out for action +The four gaps the audit called out for action all live in this script: 1. The `NONE` message for zero pins (line 290-294) — historical guard for @@ -15,7 +15,6 @@ These tests exercise the real `pin-policy.py` binary as a subprocess (the script's hyphenated name prevents direct import without renaming, which -import pytest would break the four consumers). `tests/conftest.py` installs a `gh` stub on PATH so no network or secret is involved; tests assert on stdout, stderr, and exit code. @@ -203,8 +202,7 @@ def test_run_pin_policy_zero_pins_emits_none_message( NOTE: this test pins the *message*, not the exit code. As of the current `scripts/pin-policy.py`, `NONE` is printed but the script - still exits 0 — which is the original fail-open the audit - (`auditoria-tests-canales.md`) flagged. Closing the fail-open + still exits 0 — which is the original fail-open the audit flagged. Closing the fail-open (changing `if unreadable or stale: sys.exit(1)` to also trigger on `pins == 0`) is a separate, smaller PR that lands in the same series; this test catches both the regression of the message and @@ -286,7 +284,7 @@ def test_run_pin_policy_helper_diff_emits_diff_and_exits_one( """A consumer whose pin's reusable bundles a helper that diverges between the pinned SHA and the latest tag must emit `DIFF`. - The audit (`auditoria-tests-canales.md`) flagged that + The audit flagged that `fetch_reusable_surface` only compared the workflow file, leaving the bundled script (`scripts/pin-policy.py`) unchecked. Today's pin-policy-reusable bundles exactly that helper, so without this