feat: add stable rule IDs and a rules reference by shenxianpeng · Pull Request #512 · commit-check/commit-check

shenxianpeng · 2026-08-03T10:12:19Z

Summary

Every check that can report a failure now has a stable rule ID (CC001, CC003, …) and a link to its documentation. Rule IDs give users a durable handle to reference in code review, docs, and tooling — the same way ESLint, ruff, and SonarQube do.

ID ranges

Range	Category	Examples
`CC0xx`	Commit message	`CC001` message, `CC003` subject-imperative, `CC012` require-signed-off-by, `CC013` ai-attribution
`CC1xx`	Author	`CC101` author-name, `CC102` author-email
`CC2xx`	Branch	`CC201` branch, `CC202` merge-base
`CC3xx`	Push	`CC301` no-force-push

Internal bookkeeping entries that never produce a diagnostic (ignore_authors) intentionally carry no ID.

Output

Default:

CC003 subject_imperative check failed ==> docs: revamped the profile
Commit message should use imperative mood (e.g., 'fix bug' not 'fixed bug', ...)
Suggest: Change the first verb to imperative form, e.g., 'fix' instead of 'fixed'/'fixes'/'fixing'
Docs: https://docs.commit-check.com/rules.html#cc003

Compact:

[FAIL] CC003 subject_imperative: docs: revamped the profile

JSON (--format json) gains rule_id and docs_url per check.

The redundant Type prefix was dropped now that the rule ID leads the line.

Implementation notes

IDs live in rules_catalog.py. ValidationRule exposes rule_id / docs_url as properties that look the check up in the catalog, so no per-rule copying happens at build time and the ~10 ValidationRule construction sites stay untouched. New rules inherit their identity automatically, so this can't drift.
docs_url is derived from the ID, so there is a single source of truth.
Rule construction stays allocation-free: build_all_rules() benchmarks flat against main.

Documentation

Adds docs/rules.rst — a rules reference with a summary table and a section per rule (anchored as #cc001, #cc003, …), wired into the toctree.

Testing

New tests/rules_catalog_test.py: ID uniqueness, format, propagation into built rules and to_dict(), docs_url derivation, and that internal entries have no ID.
Anti-drift guard: a test fails if any rule ships without a corresponding anchor in docs/rules.rst.
Full suite passes (454 passed); docs build verified to emit all 18 rule anchors.

Follow-ups this unlocks

Rule IDs are the prerequisite for SARIF output (ruleId), per-rule suppression (e.g. # cchk-disable CC003), and linking each finding to its docs from the GitHub Action's PR comment.

netlify · 2026-08-03T10:12:25Z

✅ Deploy Preview for commit-check ready!

Name	Link
🔨 Latest commit	`3f4f6ee`
🔍 Latest deploy log	https://app.netlify.com/projects/commit-check/deploys/6a708459600a37000853d5a4
😎 Deploy Preview	https://deploy-preview-512--commit-check.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

coderabbitai · 2026-08-03T10:12:38Z

📝 Walkthrough

Walkthrough

The change adds stable rule identifiers and documentation URLs to catalog entries, generated rules, validation outcomes, and failure output. It adds a complete rules reference and tests metadata propagation, formatting, catalog filtering, and documentation anchors.

Changes

Rule metadata flow

Layer / File(s)	Summary
Catalog identifiers and documentation URLs `commit_check/rules_catalog.py`	The catalog assigns stable IDs to user-facing rules, exposes rule names and documentation URLs, and collects identified entries in `ALL_RULES`.
Generated rule metadata `commit_check/rule_builder.py`	`ValidationRule` stores and serializes optional metadata. `RuleBuilder` attaches catalog metadata to commit, branch, and push rules.
Validation outcomes and failure output `commit_check/engine.py`, `commit_check/util.py`	Detailed outcomes include rule IDs and documentation URLs. Failure output displays rule IDs and optional documentation links.
Rule reference and catalog drift checks `docs/index.md`, `docs/rules.rst`, `tests/rules_catalog_test.py`	The documentation reference describes all supported rules. Tests verify catalog IDs, metadata propagation, serialization, and documentation anchors.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant RulesCatalog
  participant RuleBuilder
  participant ValidationEngine
  participant FailureReporter
  RulesCatalog->>RuleBuilder: provide rule_id and docs_url
  RuleBuilder->>ValidationEngine: build metadata-bearing ValidationRule
  ValidationEngine->>FailureReporter: pass metadata in CheckOutcome
  FailureReporter-->>ValidationEngine: render identified failure output

Possibly related PRs

commit-check/commit-check#383: Both changes modify print_error_message and failure output formatting.
commit-check/commit-check#456: Both changes modify the rule catalog, RuleBuilder, and validation metadata propagation.

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 50.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main changes: stable rule IDs and a rules reference.

✨ Finishing Touches 💡 1

📝 Generate docstrings 💡

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feature/rule-ids

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

codecov · 2026-08-03T10:14:36Z

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 97.43%. Comparing base (c8303f5) to head (3f4f6ee).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #512      +/-   ##
==========================================
+ Coverage   97.27%   97.43%   +0.15%     
==========================================
  Files          12       12              
  Lines        1175     1207      +32     
==========================================
+ Hits         1143     1176      +33     
+ Misses         32       31       -1

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

coderabbitai

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/rules.rst`:
- Around line 8-12: Update the rules output example to include the Docs:
<rule-url> line after the failure message and suggestion, or show separate
examples distinguishing output modes where the documentation link is omitted in
compact output.

In `@tests/rules_catalog_test.py`:
- Around line 81-86: Update test_internal_entries_have_no_id to assert that the
ignore_authors catalog entry exists and has rule_id set to None, removing the
conditional if rule is not None guard so omission cannot satisfy the test.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

Push a commit to this branch (recommended)
Create a new PR with the fixes

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: c8b4550e-9d1a-4f80-ade4-54f64ff5212b

📥 Commits

Reviewing files that changed from the base of the PR and between 4922fec and 400f5af.

📒 Files selected for processing (7)

commit_check/engine.py
commit_check/rule_builder.py
commit_check/rules_catalog.py
commit_check/util.py
docs/index.md
docs/rules.rst
tests/rules_catalog_test.py

codspeed-hq · 2026-08-03T10:25:42Z

Merging this PR will regress 1 benchmark

⚠️

Different runtime environments detected

Some benchmarks with significant performance changes were compared across different runtime environments,
which may affect the accuracy of the results.

Open the report in CodSpeed to investigate

⚡ 1 improved benchmark
❌ 1 regressed benchmark
✅ 391 untouched benchmarks
🆕 11 new benchmarks
⏩ 115 skipped benchmarks¹

Warning

Please fix the performance issues or acknowledge them on CodSpeed.

Performance Changes

	Benchmark	`BASE`	`HEAD`	Efficiency
❌	`test_signoff_validator_missing_signoff`	410.5 µs	461.6 µs	-11.08%
⚡	`test_empty_message_passes`	2.9 ms	2.3 ms	+27.52%
🆕	`test_built_rule_has_id_and_docs_url`	N/A	607.2 µs	N/A
🆕	`test_internal_entries_have_no_id`	N/A	631.3 µs	N/A
🆕	`test_to_dict_includes_id_and_docs_url`	N/A	625.8 µs	N/A
🆕	`test_diagnostic_rules_all_have_ids`	N/A	264.4 µs	N/A
🆕	`test_docs_url_derives_from_id`	N/A	279.2 µs	N/A
🆕	`test_name_is_kebab_case`	N/A	277.1 µs	N/A
🆕	`test_no_docs_url_without_id`	N/A	271.3 µs	N/A
🆕	`test_rule_ids_are_unique`	N/A	281 µs	N/A
🆕	`test_rule_ids_are_well_formed`	N/A	464 µs	N/A
🆕	`test_every_rule_is_documented`	N/A	931.5 µs	N/A
🆕	`test_identified_checks_are_unique`	N/A	270.8 µs	N/A

Tip

Investigate this regression by commenting @codspeedbot fix this regression on this PR, or directly use the CodSpeed MCP with your agent.

_{Comparing feature/rule-ids (3f4f6ee) with main (c8303f5)}

115 benchmarks were skipped, so the baseline results were used instead. If they were deleted from the codebase, click here and archive them to remove them from the performance reports. ↩

Every check that can report a failure now has a stable rule ID (CC001, CC003, ...) plus a link to its documentation. IDs are assigned in the catalog and attached centrally when rules are built, so new rules inherit their identity automatically. Rule IDs and docs links now appear in the default, compact, and JSON output, giving users a durable handle to reference and look up. Add docs/rules.rst documenting every rule, and a test that fails if a rule ships without a corresponding entry in that page.

Assert unconditionally that the ignore_authors catalog entry and its built rule carry no rule ID; the previous conditional guard let the test pass vacuously if the rule were never built. Show the complete default output in the rules reference, including the Docs link, and document the compact form alongside it.

Attaching the rule ID with dataclasses.replace() rebuilt every rule on each build_all_rules() call, roughly doubling its cost (19us -> 41us) and showing up as a broad benchmark regression. Expose rule_id and docs_url as properties backed by a check-name lookup into the catalog. Identity still lives in one place, so rules cannot carry a stale copy, and building them no longer does extra work. Add a test asserting the lookup's key assumption that identified check names are unique.

Rule IDs print a link to their reference section, and that link ships in terminal output and JSON results. Settle it on the project's own domain before the first release that carries it, so the URLs do not need redirecting later.

sonarqubecloud · 2026-08-03T12:11:12Z

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud

shenxianpeng requested a review from a team as a code owner August 3, 2026 10:12

github-actions Bot added documentation Improvements or additions to documentation enhancement New feature or request tests Add test related changes labels Aug 3, 2026

coderabbitai Bot reviewed Aug 3, 2026

View reviewed changes

Comment thread docs/rules.rst Outdated

Comment thread tests/rules_catalog_test.py Outdated

shenxianpeng mentioned this pull request Aug 3, 2026

ci: treat 95% or higher project coverage as passing #513

Merged

shenxianpeng force-pushed the feature/rule-ids branch from f682b70 to d7c519b Compare August 3, 2026 10:45

shenxianpeng mentioned this pull request Aug 3, 2026

docs: move documentation links to the project domain #514

Merged

shenxianpeng and others added 5 commits August 3, 2026 15:06

ci: auto fixes from pre-commit.com hooks

72be1c2

docs: point rule links at the documentation domain

3f4f6ee

Rule IDs print a link to their reference section, and that link ships in terminal output and JSON results. Settle it on the project's own domain before the first release that carries it, so the URLs do not need redirecting later.

shenxianpeng force-pushed the feature/rule-ids branch from effdf71 to 3f4f6ee Compare August 3, 2026 12:06

shenxianpeng removed documentation Improvements or additions to documentation tests Add test related changes labels Aug 3, 2026

github-actions Bot added documentation Improvements or additions to documentation tests Add test related changes labels Aug 3, 2026

shenxianpeng added minor A minor version bump and removed documentation Improvements or additions to documentation tests Add test related changes labels Aug 3, 2026

shenxianpeng merged commit bfb5eb1 into main Aug 3, 2026
32 checks passed

shenxianpeng deleted the feature/rule-ids branch August 3, 2026 12:13

This was referenced Aug 3, 2026

docs: rebuild the documentation site as a product surface #515

Merged

docs: update documentation links to commit-check.com #518

Merged

This was referenced Aug 4, 2026

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

Merged

feat: report checked value in JSON output for passing checks #522

Merged

ci: run commit-check on every PR, and check the title as it will land #531

Merged

Navigation Menu

Uh oh!

Uh oh!

feat: add stable rule IDs and a rules reference - #512

feat: add stable rule IDs and a rules reference#512
shenxianpeng merged 5 commits into
mainfrom
feature/rule-ids

shenxianpeng commented Aug 3, 2026 •

edited

Loading

Uh oh!

netlify Bot commented Aug 3, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Aug 3, 2026 •

edited

Loading

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

codecov Bot commented Aug 3, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot left a comment

Uh oh!

Uh oh!

Uh oh!

codspeed-hq Bot commented Aug 3, 2026 •

edited

Loading

Uh oh!

sonarqubecloud Bot commented Aug 3, 2026

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Uh oh!

Conversation

shenxianpeng commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

ID ranges

Output

Implementation notes

Documentation

Testing

Follow-ups this unlocks

Uh oh!

netlify Bot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for commit-check ready!

Uh oh!

coderabbitai Bot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Sequence Diagram(s)

❌ Failed checks (1 warning)

Uh oh!

codecov Bot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

coderabbitai Bot left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

codspeed-hq Bot commented Aug 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Merging this PR will regress 1 benchmark

Performance Changes

Footnotes

Uh oh!

sonarqubecloud Bot commented Aug 3, 2026

Quality Gate passed

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

shenxianpeng commented Aug 3, 2026 •

edited

Loading

netlify Bot commented Aug 3, 2026 •

edited

Loading

coderabbitai Bot commented Aug 3, 2026 •

edited

Loading

codecov Bot commented Aug 3, 2026 •

edited

Loading

codspeed-hq Bot commented Aug 3, 2026 •

edited

Loading