fix: link rule IDs to their documentation in terminal output - #520

The rule ID now carries an OSC 8 hyperlink to its section of the rules reference, so the ID itself is what you click — the same mechanism ruff uses for its codes.

Verified against ruff rather than assumed: under a terminal it advertises support for, it emits

ESC]8;;https://docs.astral.sh/ruff/rules/unused-import ESC\ F401 ESC]8;;ESC\

and prints no separate documentation line, which is why its output stays compact.

The URL still has to survive CI

commit-check runs in a lot of places ruff does not, so dropping the Docs: line outright would lose the address wherever the escape cannot render. The line is kept unless the ID is actually a link:

All four were exercised against a real pty, not just unit-tested.

Three things the output got wrong

Visible in any two-failure run:

The blank line closed the suggestion, not the block. Docs: ended up separated from the rule it belonged to and butted against the next one:

Suggest: Use <type>(<scope>): <description>, ...
                                                  ← separator landed here
Docs: https://commit-check.com/rules/#cc001
CC005 subject_min_length check failed ==> test    ← no separation

The name was the config key, not the documented one. Output said subject_min_length; the rules reference titles that section subject-min-length. Reading a name off the terminal and searching the docs for it found nothing. RuleCatalogEntry.name already existed for this and simply was not being used.

The advice for the length rules named no length. Suggest: Provide a meaningful subject (>= configured min) sat directly under Subject must be at least 5 characters — vaguer than the line above it. Both length suggestions are now templated on the same value as the error, so CC004 and CC005 name the actual limit.

Before / after

$ echo "test" | commit-check -m --no-banner    # piped
CC001 message check failed ==> test
The commit message should follow Conventional Commits. See https://www.conventionalcommits.org
Suggest: Use <type>(<scope>): <description>, where <type> is one of: feat, fix, ...
Docs: https://commit-check.com/rules/#cc001

CC005 subject-min-length check failed ==> test
Subject must be at least 5 characters
Suggest: Write a subject of at least 5 characters
Docs: https://commit-check.com/rules/#cc005

Trailing whitespace on the failure and suggestion lines is gone as a side effect of the rewrite.

Testing

$ pytest tests/ -q
472 passed, 1 failed

The failure is test_load_config_file_permission_error, which uses os.chmod(0o000) and cannot fail as root; it reproduces on main.

TestHyperlinks adds 11 cases: the escape shape, terminal detection across nine environments including a malformed VTE_VERSION, that the ID is linked only when supported, that the Docs: line appears exactly when the ID is not a link, and that the blank line closes the block.

Two existing assertions in test_print_error_message were checking for author_email in the output. They now assert author-email and additionally that no underscore survives into the printed name, so the kebab-case contract is pinned rather than merely accommodated.

Not in this PR

The banner says "Commit rejected by Commit-Check." and then "Commit rejected." on either side of the ASCII art, and there is still no summary count of failures. Both change the shape of the output rather than fix a defect in it, so they belong with the Action output rework on the roadmap.

Summary by CodeRabbit

• Bug Fixes

  • Length-related suggestions now clearly reference the configured minimum or maximum.
  • Error messages consistently display the relevant check name and failure indicator.
  • Improved spacing prevents unnecessary blank lines in suggestions.

• Usability Improvements

  • Rule identifiers can link directly to documentation in supported terminals.
  • Documentation links remain visible as plain URLs when terminal hyperlinks are unavailable.
  • Check names are displayed in a more readable kebab-case format.