docs: sharpen README first screen — lightweight policy engine framing#418
Conversation
Replace the 'most comprehensive' claim with a more credible, professional positioning: Commit Check as a lightweight policy engine for Git commit metadata. Add three core differentiators directly on the first screen: - One policy file (cchk.toml) - Multiple enforcement points (CLI, pre-commit, CI / GitHub Actions) - Machine-readable output (JSON + Python API) All claims verified against the current codebase: - 5 validation categories and 18+ rules (rules_catalog.py) - --format json (main.py:157) - commit_check.api with validate_message/branch/author/push/all (api.py) - 5 pre-commit hooks (.pre-commit-hooks.yaml)
✅ Deploy Preview for commit-check ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
📝 WalkthroughWalkthroughThe README's "Overview" section for Commit Check was rewritten to be more concise and product-focused. The updated text explicitly states what is validated (commit messages, branch names, author identity, signoff trailers, push safety), highlights the single versioned ChangesDocumentation: Product-Oriented README Overview
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Possibly related PRs
Suggested labels
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
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. Comment |
|
There was a problem hiding this comment.
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 `@README.rst`:
- Line 48: Update the README sentence that currently says "One policy file:
cchk.toml" to mention both supported filenames so readers aren't misled; change
it to something like "One policy file: cchk.toml (or commit-check.toml)" or add
a footnote explaining that the tool accepts either cchk.toml or
commit-check.toml while still enforcing a single policy file; ensure references
to the filenames cchk.toml and commit-check.toml in the README are consistent.
- Around line 48-50: Update the README wording to accurately reflect available
differentiators: state that a policy file cchk.toml exists at the repository
root; describe machine-readable output as supported via the CLI --format option
(["text","json"]) and the output_format == "json" branch that emits JSON;
reference the Python API by naming the functions in commit_check/api.py
(validate_message, validate_branch, validate_push, validate_author,
validate_all); note that pre-commit integration is present via
.pre-commit-hooks.yaml but do not assert a specific hook count; and tighten the
CI/GitHub Actions claim to indicate CI integrations are supported but no
action.yml/action.yaml is present at the repo root.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
| and push safety — using one versioned TOML policy across local hooks, CI, | ||
| GitHub Actions, and AI automation. | ||
|
|
||
| - **One policy file:** ``cchk.toml`` |
There was a problem hiding this comment.
Clarify "one policy file" when two filenames are supported.
Line 48 states "One policy file: cchk.toml", but lines 111 and 123 in the README mention both cchk.toml and commit-check.toml as supported configuration filenames. This could confuse readers who might think only cchk.toml works.
Consider revising to acknowledge both filenames while emphasizing the single-policy-file concept, e.g., "One policy file: cchk.toml (or commit-check.toml)" or "One policy file: cchk.toml*" with a footnote.
📝 Proposed clarification
-**One policy file:** ``cchk.toml``
+**One policy file:** ``cchk.toml`` (or ``commit-check.toml``)📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - **One policy file:** ``cchk.toml`` | |
| - **One policy file:** ``cchk.toml`` (or ``commit-check.toml``) |
🤖 Prompt for 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.
In `@README.rst` at line 48, Update the README sentence that currently says "One
policy file: cchk.toml" to mention both supported filenames so readers aren't
misled; change it to something like "One policy file: cchk.toml (or
commit-check.toml)" or add a footnote explaining that the tool accepts either
cchk.toml or commit-check.toml while still enforcing a single policy file;
ensure references to the filenames cchk.toml and commit-check.toml in the README
are consistent.
| - **One policy file:** ``cchk.toml`` | ||
| - **Multiple enforcement points:** CLI, pre-commit, CI / GitHub Actions | ||
| - **Machine-readable output:** JSON + Python API for automation and AI agents |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Verify core differentiators are implemented
# 1. Check for policy file at root
echo "=== 1. Policy file at root ==="
fd -t f "^(cchk|commit-check)\.toml$" --max-depth 1
# 2. Verify no action.yml exists (confirming "CI / GitHub Actions" vs "GitHub Action")
echo -e "\n=== 2. Check for action.yml (should NOT exist) ==="
fd -t f "^action\.ya?ml$" --max-depth 1
if [ $? -ne 0 ]; then
echo "✓ No action.yml found (confirms 'CI / GitHub Actions' wording)"
fi
# 3. Check for --format json implementation
echo -e "\n=== 3. JSON output implementation ==="
rg -n "format.*json|--format|argparse.*format" commit_check/main.py -C3 | head -30
# 4. Verify Python API functions
echo -e "\n=== 4. Python API functions ==="
rg -n "^def (validate_message|validate_branch|validate_author|validate_push|validate_all)" commit_check/api.py -A 1
# 5. Check for pre-commit hooks file
echo -e "\n=== 5. Pre-commit hooks file ==="
fd -t f "pre-commit-hooks\.ya?ml$"
if [ -f .pre-commit-hooks.yaml ]; then
echo "Found .pre-commit-hooks.yaml"
rg "^\s+- id:" .pre-commit-hooks.yaml
fiRepository: commit-check/commit-check
Length of output: 1262
Confirm differentiators (policy file, JSON output, Python API, pre-commit hooks) and tighten CI/GitHub Actions wording
- Policy file:
cchk.tomlexists at repo root. - “CI / GitHub Actions”: no
action.yml/action.yamlexists at repo root. - JSON output: implemented via
--formatchoices["text","json"]and aoutput_format == "json"branch that emits machine-readable results. - Python API:
commit_check/api.pydefinesvalidate_message,validate_branch,validate_push,validate_author, andvalidate_all. - Pre-commit:
.pre-commit-hooks.yamlexists (can’t confirm the “5 hooks” count from the current evidence).
🤖 Prompt for 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.
In `@README.rst` around lines 48 - 50, Update the README wording to accurately
reflect available differentiators: state that a policy file cchk.toml exists at
the repository root; describe machine-readable output as supported via the CLI
--format option (["text","json"]) and the output_format == "json" branch that
emits JSON; reference the Python API by naming the functions in
commit_check/api.py (validate_message, validate_branch, validate_push,
validate_author, validate_all); note that pre-commit integration is present via
.pre-commit-hooks.yaml but do not assert a specific hook count; and tighten the
CI/GitHub Actions claim to indicate CI integrations are supported but no
action.yml/action.yaml is present at the repo root.
Summary by CodeRabbit