Skip to content

feat: update organization files to align with current best practices - #1

Merged
williaby merged 1 commit into
mainfrom
claude/review-org-files
Nov 17, 2025
Merged

williaby merged 1 commit into
mainfrom
claude/review-org-files

Conversation

@williaby

Copy link
Copy Markdown
Collaborator

✨ feat: update organization files to align with current best practices

📊 Change Summary

Metric Value Status
Files Changed 16 ⚠️ Large
Total Lines +404 / -34 ⚠️
Commits 1 ✅
Copilot Compatible 16/28 files ✅
Base Branch main ✅

🎯 Summary

This PR includes:

  • ✨ 1 feat change

📋 Changes

Files Changed: 16

  • Lines Added: +404
  • Lines Removed: -34
  • Net Change: +370 lines

File Types Modified:

  • no extension: 2 files
  • .md: 8 files
  • .yml: 5 files
  • .sh: 1 files

⚠️ PR Size Warning

This PR exceeds recommended size limits for optimal review:

Tool Current Limit Status
GitHub Copilot 16 files 28 files ✅ Compatible
WhatTheDiff ~1752 tokens 2500 tokens ✅ Compatible
Review Size 438 lines 400 lines ⚠️ Large

✅ Review Checklist

  • Code follows project coding standards
  • Changes have been tested locally
  • Documentation has been updated if needed
  • No sensitive information is being committed
  • Breaking changes are documented and justified

🔧 Testing Instructions

  1. Pull this branch: git checkout claude/review-org-files
  2. Review the changes in the affected files
  3. Test the functionality manually or run automated tests
  4. Verify no regressions in existing functionality

📝 Notes for Reviewers

This PR contains 1 commits with changes across 16 files.


Auto-generated with zen PR preparation tool 🤖

- Fix FUNDING.yml syntax by removing invalid YAML separators and format
- Update issue templates (bug.yml, feature.yml) to use textarea for multi-line fields
- Add required validations to issue template fields
- Add pull_request_template.md for standardized PR descriptions
- Add ISSUE_TEMPLATE/config.yml to configure issue template chooser
- Add dependabot.yml for automated dependency updates across ecosystems
- Add LICENSE file (MIT) to formalize licensing
- Add profile/README.md for organization profile page
- Update all file dates from April 30, 2025 to November 16, 2025
- Update README.md to document all new files
- Update sync_org_files.sh to include new files in sync process

These changes bring the organization's community health files in line with
2025 best practices for GitHub organizations, improving contributor experience,
automation, and security.
@williaby
williaby merged commit 5ee6377 into main Nov 17, 2025
@williaby
williaby deleted the claude/review-org-files branch November 19, 2025 04:17
williaby added a commit that referenced this pull request May 26, 2026
… and CI

Critical

- scripts/fleet-audit-sha-pins.sh: the workflows-listing failure path
  emitted a "$full,error" sentinel and continued without setting
  audit_incomplete=true, so STRICT_AUDIT=1 exited 0 even when error
  rows were present. Verified by manual reproduction with a 429-stub
  before the fix. New bats case "exits non-zero on workflows-listing
  failure (Critical #1 regression)" is the regression guard.
- .github/workflows/shell-tests.yml: bats runner only executed
  tests/update-pinned-actions.bats; the 13 cases in
  tests/fleet-audit-sha-pins.bats (including all STRICT_AUDIT and
  REPO_LIMIT tests from PR #176 and the new ones in PR #177) never
  ran in CI. Switched to find + xargs over tests/*.bats, which is
  glob-injection-safe and discovers new test files automatically.
  This is the reason Critical #1 escaped detection until self-review.

Important

- scripts/fleet-audit-sha-pins.sh: mapfile -t repos < <(gh repo list ...)
  discarded the gh exit code via process substitution; auth-loss or
  rate-limit mid-enumeration silently contributed zero rows. Now
  captures stdout to a tmpfile and surfaces the rc, flagging
  audit_incomplete on failure.
- scripts/fleet-audit-sha-pins.sh: REPO_LIMIT validated as positive
  integer at script entry; previously a non-numeric value crashed
  inside [[ -eq ]] under set -euo pipefail. Exits 1 with a clear
  error message instead.
- scripts/update-pinned-actions.sh: null-guard paths in resolve_tag_sha
  now emit a stderr WARN before returning empty so operators can
  distinguish a malformed GitHub API response from a missing tag.
- scripts/fleet-audit-sha-pins.sh: STRICT_AUDIT accepts truthy
  spellings 1, true, yes (case-insensitive). Previously only "1"
  worked and STRICT_AUDIT=true silently degraded to report-only.

Suggested

- scripts/fleet-audit-sha-pins.sh: strip trailing CR from each line
  before regex matching so workflow files with CRLF endings do not
  leak \r into BASH_REMATCH and inflate violation counts.
- tests/fleet-audit-sha-pins.bats: 8 new regression tests covering
  the above paths.
- tests/update-pinned-actions.bats: 1 new test for the first-call
  null guard in resolve_tag_sha (the second-call path was already
  covered); strengthened branch-with-comment assertion to anchor on
  the "WARN: branch ref detected" header; added positive controls
  to the empty-SKIP_OWNERS test.
- scripts/update-pinned-actions.sh: maintenance note that changing
  the sed delimiter requires updating both the replacement-side
  escape set and the pattern-side escape_sed_pat() function.
- .claude/CLAUDE.md: corrected stale statement that bats coverage
  is limited to scripts/update-pinned-actions.sh.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
williaby added a commit that referenced this pull request May 26, 2026
…#177)

* feat(fleet-audit): add STRICT_AUDIT mode and env-overridable REPO_LIMIT

- REPO_LIMIT now reads from environment with default 1000:
  `REPO_LIMIT="${REPO_LIMIT:-1000}"`. Allows tests to exercise the
  saturation WARN with a small stub-friendly value and gives operators
  an escape hatch for fleets that grow beyond the default.
- New STRICT_AUDIT=1 mode: track an audit_incomplete flag during the
  run. When STRICT_AUDIT=1 is set in the environment and any repo
  emitted a `repo,error` row OR REPO_LIMIT saturated, exit 2 with a
  diagnostic stderr line. The default flow remains report-only (exit 0)
  so existing CI consumers do not break; CI gates that need fail-closed
  semantics opt in by setting STRICT_AUDIT=1.
- Header comment updated with both env vars under a new
  "Environment overrides" block.

Addresses Suggested findings S-7 (STRICT_AUDIT fail-closed mode) and
S-1 partial (env override for REPO_LIMIT) from the /pr-review of #176.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(pin-tags): detect missing object fields in resolve_tag_sha

When the GitHub API returns a tag-ref response missing `.object.type` or
`.object.sha`, jq -r emits the literal string "null". The previous code
accepted that as a successful resolution and produced patterns like
`actions/checkout@null` which the caller then wrote into the workflow
file (replacing the original tag-pinned ref with a broken SHA pin).

After both the initial composite fetch and the second annotated-tag
dereferencing call, validate that the returned fields are non-empty and
not the literal "null". Return empty (the existing failure convention)
so the caller marks the action SKIPPED rather than writing junk.

Also clarify the sed-delimiter assumption in the safe_tag escape block:
the comment now explicitly names the three replacement-side specials
(\, &, |) and notes that the | escape is tied to the sed delimiter
choice; if the delimiter ever changes, this set must be updated.

Addresses Suggested findings S-6 (annotated-tag .object.sha guard)
and S-9 (sed-delimiter documentation) from the /pr-review of #176.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* test: cover Suggested-tier regression vectors for sha-pin tooling

Adds nine new bats cases guarding the production fixes in this branch
and the residual coverage gaps the /pr-review of #176 surfaced:

fleet-audit-sha-pins.bats:
- "audit warns when gh repo list saturates REPO_LIMIT": exercises the
  saturation WARN with REPO_LIMIT=3 + a 3-repo stub
- "STRICT_AUDIT=1 exits non-zero on REPO_LIMIT saturation": verifies
  the new fail-closed exit-2 path on saturation
- "STRICT_AUDIT=1 exits non-zero when any repo emits error sentinel":
  verifies fail-closed exit-2 path on per-repo API failure
- "STRICT_AUDIT=1 remains exit 0 on a fully clean run": regression guard
  so STRICT_AUDIT does not break healthy audits
- "--skip-owners with a single owner (no commas)": verifies the case
  framing handles a single-value SKIP_OWNERS (",actions,")
- "--skip-owners with empty string does not skip anything": empty
  SKIP_OWNERS produces "," framing that matches no owner
- "--skip-owners with double internal commas still matches listed
  owners": noisy empty segments do not break the match

update-pinned-actions.bats:
- "--pin-tags reports branch refs that carry an inline comment":
  extract_branch_pins must surface a comment-annotated branch ref
  (previously only the tag-extraction path was tested with comments)
- "--pin-tags --apply on a workflow with no third-party refs succeeds
  without warnings": first-party-only fixture exercises the rc-aware
  extract_*_pins zero-match path under set -euo pipefail
- "--pin-tags --apply skips when annotated-tag dereferencing returns
  missing .object.sha": stubs the second-step call to return an object
  without .sha; asserts the new null guard marks the action SKIPPED
  and never writes "actions/checkout@null" into the workflow file

Addresses Suggested findings S-1 (REPO_LIMIT test), S-2 (branch-pin
inline-comment test), S-3 (zero-match fixture), S-5 (SKIP_OWNERS
edges), S-6 test (annotated-tag null), and S-7 tests (STRICT_AUDIT)
from the /pr-review of #176.

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* docs(changelog): record STRICT_AUDIT mode and resolve_tag_sha null guard

- Add ### Added entry for the new STRICT_AUDIT=1 environment toggle
  and the env-overridable REPO_LIMIT
- Add ### Fixed entry for the resolve_tag_sha guard against jq's
  literal "null" output when a tag-ref response is missing object
  fields
- Add ### Fixed entry summarizing the nine new bats cases added in
  this branch covering Suggested-tier regression vectors

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

* fix(scripts): address /pr-review self-review findings on STRICT_AUDIT and CI

Critical

- scripts/fleet-audit-sha-pins.sh: the workflows-listing failure path
  emitted a "$full,error" sentinel and continued without setting
  audit_incomplete=true, so STRICT_AUDIT=1 exited 0 even when error
  rows were present. Verified by manual reproduction with a 429-stub
  before the fix. New bats case "exits non-zero on workflows-listing
  failure (Critical #1 regression)" is the regression guard.
- .github/workflows/shell-tests.yml: bats runner only executed
  tests/update-pinned-actions.bats; the 13 cases in
  tests/fleet-audit-sha-pins.bats (including all STRICT_AUDIT and
  REPO_LIMIT tests from PR #176 and the new ones in PR #177) never
  ran in CI. Switched to find + xargs over tests/*.bats, which is
  glob-injection-safe and discovers new test files automatically.
  This is the reason Critical #1 escaped detection until self-review.

Important

- scripts/fleet-audit-sha-pins.sh: mapfile -t repos < <(gh repo list ...)
  discarded the gh exit code via process substitution; auth-loss or
  rate-limit mid-enumeration silently contributed zero rows. Now
  captures stdout to a tmpfile and surfaces the rc, flagging
  audit_incomplete on failure.
- scripts/fleet-audit-sha-pins.sh: REPO_LIMIT validated as positive
  integer at script entry; previously a non-numeric value crashed
  inside [[ -eq ]] under set -euo pipefail. Exits 1 with a clear
  error message instead.
- scripts/update-pinned-actions.sh: null-guard paths in resolve_tag_sha
  now emit a stderr WARN before returning empty so operators can
  distinguish a malformed GitHub API response from a missing tag.
- scripts/fleet-audit-sha-pins.sh: STRICT_AUDIT accepts truthy
  spellings 1, true, yes (case-insensitive). Previously only "1"
  worked and STRICT_AUDIT=true silently degraded to report-only.

Suggested

- scripts/fleet-audit-sha-pins.sh: strip trailing CR from each line
  before regex matching so workflow files with CRLF endings do not
  leak \r into BASH_REMATCH and inflate violation counts.
- tests/fleet-audit-sha-pins.bats: 8 new regression tests covering
  the above paths.
- tests/update-pinned-actions.bats: 1 new test for the first-call
  null guard in resolve_tag_sha (the second-call path was already
  covered); strengthened branch-with-comment assertion to anchor on
  the "WARN: branch ref detected" header; added positive controls
  to the empty-SKIP_OWNERS test.
- scripts/update-pinned-actions.sh: maintenance note that changing
  the sed delimiter requires updating both the replacement-side
  escape set and the pattern-side escape_sed_pat() function.
- .claude/CLAUDE.md: corrected stale statement that bats coverage
  is limited to scripts/update-pinned-actions.sh.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.7 <noreply@anthropic.com>
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.

2 participants