Skip to content

ci: make public-hygiene-lint green - #6

Open
MattJackson wants to merge 3 commits into
mainfrom
ci/public-hygiene-green
Open

ci: make public-hygiene-lint green#6
MattJackson wants to merge 3 commits into
mainfrom
ci/public-hygiene-green

Conversation

@MattJackson

Copy link
Copy Markdown
Contributor

public-hygiene-lint was RED on main in this repo. Every hit is fixed by rewriting the text to
state the BEHAVIOUR rather than our internal process. No allow markers were added anywhere in
this change: a blanket allow would turn the gate into decoration.

Hits found on main, and the decision for each

  • .github/scripts/next-version.sh + .github/workflows/release-selftest.yml [internal-issue-id]
    cited an internal guard id. REWRITTEN: id dropped.
  • store-postgres/src/lib.rs [audit-finding-id] carried a bare audit id (L2) on a doc comment.
    REWRITTEN: removed. The sentence describes the function completely without it.
  • store-postgres/src/tests.rs x5 [tdd-narration] narrated how each fix was developed ("reverting
    the fix makes this test fail, confirmed by re-running"). REWRITTEN to state the invariant and why
    the assertion is non-vacuous, which is the durable fact; the development sequence is not.
  • store-postgres/src/tests.rs x2 [mutation-testing, internal-issue-id] named the QA harness and
    its campaign round. REWRITTEN to describe what the tests below pin, and to state the
    unreachable-branch conclusion directly rather than as a coverage-pass scoping decision.
  • store-postgres-plugin/tests/{e2e,admin_api_e2e}.rs [mutation-testing] named the QA harness as a
    build-shape example. REWRITTEN: release-check.sh's phase is the concrete case and it is kept.

Red before green

Same invocation CI uses. Output is ASCII-folded for this description; the runs are verbatim
otherwise.

Before (on main)

$ python3 busbarAI/scripts/public-hygiene-lint.py --root .
== public-hygiene: what a customer reads, in . ==
  scanned 19 file(s) via git ls-files; 11 rules applied

  [audit-finding-id] bare audit finding identifier - 1 hit(s)
      why: a one-or-two-letter-plus-number decision id (`C6`, `S1`, `self-service D2`) is meaningless outside the audit that assigned it, and was shipped in the public API spec
      store-postgres/src/lib.rs:64: /// Extract the PASSWORD from a Postgres DSN (L2). Supports both the URL form

  [internal-issue-id] internal issue / task / audit-round identifier - 3 hit(s)
      why: cites a tracker or audit artifact the reader cannot open; `task #141` and `R27 #8` shipped inside operator-facing API documentation
      .github/scripts/next-version.sh:5: # release automation can't silently rot (guard #135.8). Prints "v<MAJOR>.<MINOR>.<PATCH>" to stdout.
      .github/workflows/release-selftest.yml:1: # CI self-test for the release-on-upstream version-compute logic (guard #135.8).
      store-postgres/src/tests.rs:722: // Mutation-testing gap fixes (cargo-mutants round 1 against this file): each test below is named

  [mutation-testing] mutation-testing workflow leaked into shipped prose - 4 hit(s)
      why: names an internal QA tool and the campaign it was run in; the shipped comment should state the invariant the test protects, not the harness that found the gap
      store-postgres-plugin/tests/admin_api_e2e.rs:84: /// cargo-mutants runs) does NOT uplift the cdylib to the top-level profile dir, only to
      store-postgres-plugin/tests/e2e.rs:78: /// cargo-mutants runs) does NOT uplift the cdylib to the top-level profile dir, only to
      store-postgres/src/tests.rs:722: // Mutation-testing gap fixes (cargo-mutants round 1 against this file): each test below is named
      store-postgres/src/tests.rs:1271: /// out of scope for a mutation-testing coverage pass).

  [tdd-narration] test-driven-development narration - 5 hit(s)
      why: describes how the code was WRITTEN, not what it does; a reader of a shipped file is being shown our process instead of the software
      store-postgres/src/tests.rs:118: /// re-running the suite (or running it twice, as red-before-green proofs do) never sees stale state
      store-postgres/src/tests.rs:217: // RED-BEFORE-GREEN evidence lives in the assertions below: this test only passes if delete_key
      store-postgres/src/tests.rs:251: /// RED-BEFORE-GREEN: reverting the ON CONFLICT UPDATE SET clause to omit `deleted_at=NULL` (its
      store-postgres/src/tests.rs:369: /// RED-BEFORE-GREEN: reverting the fix (VALUES ...,$8,$8,$9,... binding created_at's placeholder
      store-postgres/src/tests.rs:577: /// RED-BEFORE-GREEN: this test is a genuine regression guard rather than a fresh finding (get_usage

== result ==
  19 public file(s) scanned against 11 rules - 13 hit(s), 0 allowed
  public-hygiene-lint FAILED
  These lines describe how the software was BUILT, not what it does, in files a
  customer can read. Rewrite the text to state the behaviour or the invariant; if a
  line is genuinely legitimate, mark it:
    # public-hygiene-lint: allow - <why this text belongs in a public file>

After (this branch)

$ python3 busbarAI/scripts/public-hygiene-lint.py --root .
== public-hygiene: what a customer reads, in . ==
  scanned 19 file(s) via git ls-files; 11 rules applied

== result ==
  19 public file(s) scanned against 11 rules - 0 hit(s), 0 allowed
  public-hygiene-lint passed

Matthew Jackson and others added 3 commits August 8, 2026 16:00
The public-hygiene gate flags text in customer-readable files that
describes how the software was BUILT rather than what it DOES. Every hit
in this repo is rewritten to state the behaviour or the invariant; no
allow markers are added, so the gate keeps its teeth.
busbar resolves `env:` secret references during `--validate` now and exits
non-zero when one cannot resolve, so the file-drop fixture -- which names
`providers.mock.api_key: { env: MOCK_KEY }` and never exported MOCK_KEY --
described a gateway that could not start:

  busbar --validate must succeed with the file-dropped postgres plugin: stdout=
  stderr=[error] providers.mock.api_key: secret env:MOCK_KEY cannot resolve:
  environment variable 'MOCK_KEY' is unset

CI had not surfaced this one yet: the admin-API test failed first for a
different reason and aborted the run before this binary was reached.

The variable names are derived FROM the config files busbar is about to read,
rather than listed at each call site, so the next person to add a secret
reference to one of these fixtures does not also have to remember to export it --
forgetting produces a failure that never names the variable. Reading the files
back (not the strings the test built them from) is what keeps the two from
drifting apart. `tests/common/mod.rs` holds the scan; `tests/config_secrets.rs`
covers it directly.

Red-before-green against a real `busbar` built from the core branch CI tests
against, and a real postgres: before, `load_and_exercise_postgres_plugin_via_file_drop`
FAILED with the error quoted above; after, every test in the crate passes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant