docs: sharpen README first screen — lightweight policy engine framing - #418
docs: sharpen README first screen — lightweight policy engine framing#418shenxianpeng merged 1 commit into
Conversation
Sorry, something went wrong.
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. |
Sorry, something went wrong.
📝 Walkthrough
WalkthroughThe 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 cchk.toml policy file, and summarizes integration points (CLI, pre-commit, CI/GitHub Actions, AI automation) and output formats (JSON, Python API). ChangesDocumentation: Product-Oriented README Overview
Estimated code review effort🎯 1 (Trivial) | ⏱️ ~2 minutes Possibly related PRs
Suggested labelsdocumentation 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
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. ❤️ ShareComment @coderabbitai help to get the list of available commands and usage tips. |
Sorry, something went wrong.
|
Sorry, something went wrong.
There was a problem hiding this comment.
Actionable comments posted: 2
🤖 Prompt for all review comments with AI agentsVerify 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.
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
Run ID: a6e20c59-7ebf-4e10-af68-34c311778680
📥 CommitsReviewing files that changed from the base of the PR and between f5525d9 and afa8597.
📒 Files selected for processing (1)- README.rst
Sorry, something went wrong.
| 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.
⚠️ Potential issue | 🟡 Minor | ⚡ Quick win
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``)‼️ 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``) |
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.
Sorry, something went wrong.
| - **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.
⚠️ Potential issue | 🟡 Minor | ⚡ Quick win
🧩 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.toml exists at repo root.
- “CI / GitHub Actions”: no action.yml / action.yaml exists at repo root.
- JSON output: implemented via --format choices ["text","json"] and a output_format == "json" branch that emits machine-readable results.
- Python API: commit_check/api.py defines validate_message, validate_branch, validate_push, validate_author, and validate_all.
- Pre-commit: .pre-commit-hooks.yaml exists (can’t confirm the “5 hooks” count from the current evidence).
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.
Sorry, something went wrong.
Summary by CodeRabbit