Feature: zizmor explain FOO for showing audit documentation in the CLI

[Julian]

Pre-submission checks

• I am not a bug (crash, false positive/negative, etc). These must be filed via the bug report template.
• I have looked through the open issues for a duplicate request.

What's the problem this feature will solve?

When an audit is emitted, there's no in-CLI immediate way to expand on why it's an issue.

Describe the solution you'd like

A nice thing about ruff CLI is that when it emits errors, one can run ruff rule foo to see an explanation of what the issue is as well as why someone thought it was stylistically wrong.

E.g. one can run:

⊙  ruff rule PERF203                                                                                                                                                                                                                                                                                                julian@Airm
# try-except-in-loop (PERF203)

Derived from the **Perflint** linter.
...

and learn what the issue is about, and/or perhaps decide whether they agree with the reasoning for their specific case.

All of this information is clearly on the audit page but I'd propose it's nice to have it immediately accessible in the same place as where one has ran the CLI.

Additional context

No response

[woodruffw]

Thanks for the feature request @Julian!

I agree this would be great to have. I think the only constraint here would be ensuring that we don't end up duplicating rule documentation too much -- ideally a zizmor rule <ID> or zizmor --explain <ID> command could pull from the same data source as the website.

All of this information is clearly on the audit page but I'd propose it's nice to have it immediately accessible in the same place as where one has ran the CLI.

It's not 100% the same, but in case you missed if: if you terminal supports OSC 8, the IDs themselves in zizmor's output are clickable and will take you directly to each rule's online docs. That's not quite the same as having it baked directly into the tool, but I figured I'd call it out in case you hadn't noticed 🙂

[Julian]

Whoa! I did not notice that at all (well I noticed it was link text but didn't try clicking on it because I'd never heard of that standard!) and that is great!