Introduce a rule which suggests that permissions are documented

[johnbillion]

Fixes #1127

This introduces a pedantic undocumented-permissions rule which suggests that all the permissions directives at the root level and the job level are documented with a trailing comment. The contents: read permission is excluded because it's self-explanatory and very common. I don't think it makes sense to require that be documented everywhere.

I've added full test coverage and updated the docs.

AI disclaimer: I've never written a line of Rust in my life. This was almost entirely produced by an AI-powered coding agent following my guidance. I'd love to know whether the code that it produced for the new rule is any good.

[kusari-inspector]

Kusari Analysis Results:

✅ No Flagged Issues Detected
All values appear to be within acceptable risk parameters.

No pinned version dependency changes, code issues or exposed secrets detected!

Note

View full detailed analysis result for more information on the output and the checks that were run.

---

@kusari-inspector rerun - Trigger a re-analysis of this PR
@kusari-inspector feedback [your message] - Send feedback to our AI and team
See Kusari's documentation for setup and configuration.
Commit: 6814672, performed at: 2025-09-12T01:37:08Z

Found this helpful? Give it a 👍 or 👎 reaction!

[woodruffw]

Thanks @johnbillion! I'll do a review pass now.

AI disclaimer: I've never written a line of Rust in my life. This was almost entirely produced by an AI-powered coding agent following my guidance. I'd love to know whether the code that it produced for the new rule is any good.

Thanks for disclaiming this 🙂

[kusari-inspector]

Kusari PR Analysis rerun based on - 9cdce29 performed at: 2025-09-02T01:32:18Z - link to updated analysis

[kusari-inspector]

Kusari PR Analysis rerun based on - 01dd6ca performed at: 2025-09-02T02:15:59Z - link to updated analysis

[kusari-inspector]

Kusari PR Analysis rerun based on - 266c299 performed at: 2025-09-02T02:18:28Z - link to updated analysis

[kusari-inspector]

Kusari PR Analysis rerun based on - ed74cd1 performed at: 2025-09-02T12:08:33Z - link to updated analysis

[woodruffw]

Thanks @johnbillion! This looks great to me overall, feel free to mark it as ready for review when you feel it's ready for a final pass 🙂

[johnbillion]

@woodruffw I was waiting for you to approve the GitHub Actions workflows so they ran :D

[woodruffw]

@woodruffw I was waiting for you to approve the GitHub Actions workflows so they ran :D

Oops, I forgot they don't auto-run 🤦

[kusari-inspector]

Kusari PR Analysis rerun based on - c1c0334 performed at: 2025-09-04T22:19:02Z - link to updated analysis

[kusari-inspector]

Kusari PR Analysis rerun based on - bc43186 performed at: 2025-09-04T22:23:13Z - link to updated analysis

[kusari-inspector]

Kusari PR Analysis rerun based on - af512a8 performed at: 2025-09-05T17:00:13Z - link to updated analysis

[johnbillion]

@woodruffw I can't figure out what the failing snapshot is telling me. Locally everything passes, so I presume there's something different about the way the tests run on CI (maybe due to a difference with and without TTY) but I'm not sure. Any pointers?

[woodruffw]

@woodruffw I can't figure out what the failing snapshot is telling me. Locally everything passes, so I presume there's something different about the way the tests run on CI (maybe due to a difference with and without TTY) but I'm not sure. Any pointers?

I can take a look tonight! Sorry, I've been very busy.

[kusari-inspector]

Kusari PR Analysis rerun based on - dda98e5 performed at: 2025-09-12T01:37:22Z - link to updated analysis

[kusari-inspector]

Kusari PR Analysis rerun based on - 7384c05 performed at: 2025-09-12T01:39:08Z - link to updated analysis

[kusari-inspector]

Kusari PR Analysis rerun based on - a4bd5c0 performed at: 2025-09-12T01:44:11Z - link to updated analysis

[kusari-inspector]

Kusari PR Analysis rerun based on - 3f9d22a performed at: 2025-09-12T01:47:29Z - link to updated analysis

[kusari-inspector]

Kusari PR Analysis rerun based on - 1076016 performed at: 2025-09-12T01:48:02Z - link to updated analysis

[kusari-inspector]

Kusari PR Analysis rerun based on - 6814672 performed at: 2025-09-12T01:48:45Z - link to updated analysis

[woodruffw]

Thanks a ton @johnbillion!