commit-check · shenxianpeng · Apr 9, 2026 · Apr 9, 2026 · Apr 9, 2026 · Apr 9, 2026
@@ -21,7 +21,7 @@ repos:
         args: [ --fix ]
     -   id: ruff-format
 -   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: v1.20.0
+    rev: v1.19.1
     hooks:
     -   id: mypy
         additional_dependencies: [types-PyYAML]

@@ -31,6 +31,11 @@ Commit Check
 
 |ci-badge| |sonar-badge| |pypi-version| |pypi-downloads| |python-versions| |commit-check-badge| |codecov-badge|
 
+.. contents:: Table of Contents
+   :depth: 2
+   :local:
+   :backlinks: none
+
 Overview
 --------
 
@@ -39,89 +44,11 @@ Overview
 As a lightweight, free alternative to GitHub Enterprise `Metadata restrictions <https://docs.github.com/en/enterprise-server@3.11/repositories/configuring-branches-and-merges-in-your-repository/managing-rulesets/available-rules-for-rulesets#metadata-restrictions>`_
 and Bitbucket's paid `Yet Another Commit Checker <https://marketplace.atlassian.com/apps/1211854/yet-another-commit-checker?tab=overview&hosting=datacenter>`_ plugin, Commit Check integrates DevOps principles and Infrastructure as Code (IaC) practices for a modern workflow.
 
-**Why Commit Check?**
-
-The table below compares common approaches to commit policy enforcement.
-``commitlint`` is a specialized commit-message linter. Custom Git hooks and
-the ``pre-commit`` framework are integration mechanisms, so the last column
-reflects a DIY approach rather than built-in product features.
-
-.. list-table::
-   :header-rows: 1
-   :widths: 36 18 18 28
-
-   * - Feature
-     - Commit Check ✅
-     - commitlint
-     - Custom hooks
-   * - Conventional Commits enforcement
-     - ✅
-     - ✅
-     - DIY
-   * - Branch naming validation
-     - ✅
-     - ❌
-     - DIY
-   * - Author name / email validation
-     - ✅
-     - ❌
-     - DIY
-   * - Signed-off-by trailer enforcement
-     - ✅
-     - ✅
-     - DIY
-   * - Co-author ignore list
-     - ✅
-     - ❌
-     - DIY
-   * - Organization-level shared config
-     - ✅
-     - ✅
-     - DIY
-   * - Zero-config defaults
-     - ✅
-     - ❌
-     - ❌
-   * - Works without Node.js
-     - ✅
-     - ❌
-     - Depends
-   * - Native TOML configuration
-     - ✅
-     - ❌
-     - Depends
-   * - Git hook / pre-commit integration
-     - ✅
-     - Partial
-     - ✅
-   * - CI/CD-friendly configuration
-     - ✅
-     - Partial
-     - DIY
-
-For ``commitlint``, organization-level shared config is typically delivered via
-shareable config packages or local files. ``DIY`` means you can implement a
-capability with custom Git hooks or ``pre-commit`` scripts, but it is not
-provided as a turnkey policy layer.
-
-Installation
-------------
-
-To install Commit Check, you can use pip:
-
-.. code-block:: bash
-
-    pip install commit-check
-
-Or install directly from the GitHub repository:
-
-.. code-block:: bash
-
-    pip install git+https://github.com/commit-check/commit-check.git@main
-
-Then, run ``commit-check --help`` or ``cchk --help`` (alias for ``commit-check``) from the command line.
-For more information, see the `docs <https://commit-check.github.io/commit-check/cli_args.html>`_.
+.. image:: https://github.com/commit-check/commit-check/raw/main/docs/demo.gif
+    :alt: commit-check demo
+    :align: center
 
+|
 
 Quick Start
 -----------
@@ -150,6 +77,24 @@ Quick Start
 
     [![commit-check](https://img.shields.io/badge/commit--check-enabled-brightgreen?logo=Git&logoColor=white&color=%232c9ccd)](https://github.com/commit-check/commit-check)
 
+Installation
+------------
+
+To install Commit Check, you can use pip:
+
+.. code-block:: bash
+
+    pip install commit-check
+
+Or install directly from the GitHub repository:
+
+.. code-block:: bash
+
+    pip install git+https://github.com/commit-check/commit-check.git@main
+
+Then, run ``commit-check --help`` or ``cchk --help`` (alias for ``commit-check``) from the command line.
+For more information, see the `docs <https://commit-check.github.io/commit-check/cli_args.html>`_.
+
 
 Configuration
 -------------
@@ -242,20 +187,125 @@ For one-off checks or CI/CD pipelines, you can configure via CLI arguments or en
 
 See the `Configuration documentation <https://commit-check.github.io/commit-check/configuration.html>`_ for all available options.
 
-Usage
------
+AI-Native Usage
+---------------
+
+Commit Check is designed to be consumed by AI agents, LLM toolchains, and
+automation scripts — not just by humans reading terminal output.
+
+Machine-Readable JSON Output (``--format json``)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pass ``--format json`` to any CLI invocation to receive structured JSON instead
+of human-readable ASCII art.  The exit code is unchanged (``0`` = pass, ``1`` = fail),
+so existing CI scripts continue to work:
+
+.. code-block:: bash
+
+    echo "feat: add streaming support" | commit-check -m --format json
+
+.. code-block:: json
+
+    {
+      "status": "pass",
+      "checks": [
+        { "check": "message",           "status": "pass", "value": "", "error": "", "suggest": "" },
+        { "check": "subject_imperative", "status": "pass", "value": "", "error": "", "suggest": "" }
+      ]
+    }
+
+On failure the failing checks carry the full ``error`` and ``suggest`` fields
+an agent needs to self-correct:
+
+.. code-block:: bash
+
+    echo "wip bad commit" | commit-check -m --format json
+
+.. code-block:: json
+
+    {
+      "status": "fail",
+      "checks": [
+        {
+          "check":   "message",
+          "status":  "fail",
+          "value":   "wip bad commit",
+          "error":   "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, ..."
+        }
+      ]
+    }
+
+Python API (no subprocess required)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The ``commit_check.api`` module exposes a lightweight, import-friendly interface
+so AI agents, tools, and scripts can validate commits **without spawning a
+subprocess**.  All functions return plain dicts that are easy to serialise,
+forward to an LLM, or chain into larger workflows:
+
+.. code-block:: python
+
+    from commit_check.api import validate_message, validate_branch, validate_all
+
+    # --- validate a single commit message ---
+    result = validate_message("feat: add streaming support")
+    print(result["status"])          # "pass"
+
+    # --- validate a branch name ---
+    result = validate_branch("feature/add-streaming")
+    print(result["status"])          # "pass"
+
+    # --- run multiple checks at once ---
+    result = validate_all(
+        message="feat: implement new feature",
+        branch="feature/new-feature",
+        author_name="Ada Lovelace",
+        author_email="ada@example.com",
+    )
+    if result["status"] == "fail":
+        for check in result["checks"]:
+            if check["status"] == "fail":
+                print(f"[{check['check']}] {check['error']}")
+                print(f"  suggestion: {check['suggest']}")
+
+    # --- supply a custom config to restrict allowed types ---
+    result = validate_message(
+        "docs: update readme",
+        config={"commit": {"allow_commit_types": ["feat", "fix"]}},
+    )
+    print(result["status"])          # "fail" — 'docs' not in allowed types
+
+**Return-value schema** (all API functions):
+
+.. code-block:: python
+
+    {
+        "status": "pass" | "fail",
+        "checks": [
+            {
+                "check":   "<rule name>",
+                "status":  "pass" | "fail",
+                "value":   "<actual value that was checked>",
+                "error":   "<human-readable error description>",
+                "suggest": "<how to fix>",
+            },
+            # ... one entry per active rule
+        ]
+    }
+
+Available API functions:
+
+* ``validate_message(message, *, config=None)`` — validate a commit message string
+* ``validate_branch(branch=None, *, config=None)`` — validate a branch name (defaults to current git branch)
+* ``validate_author(name=None, email=None, *, config=None)`` — validate author name/email
+* ``validate_all(message, branch, author_name, author_email, *, config=None)`` — run all checks at once
 
 For detailed usage instructions including pre-commit hooks, CLI commands, and STDIN examples, see the `Usage Examples documentation <https://commit-check.github.io/commit-check/example.html>`_.
 
 Examples
 --------
 
-.. image:: https://github.com/commit-check/commit-check/raw/main/docs/demo.gif
-    :alt: commit-check demo
-    :align: center
-
-|
-
 Check Commit Message Failed
 
 .. code-block:: text
@@ -325,6 +375,73 @@ reStructuredText
         :alt: commit-check
 
 
+Why Commit Check?
+-----------------
+
+The table below compares common approaches to commit policy enforcement.
+``commitlint`` is a specialized commit-message linter. Custom Git hooks and
+the ``pre-commit`` framework are integration mechanisms, so the last column
+reflects a DIY approach rather than built-in product features.
+
+.. list-table::
+   :header-rows: 1
+   :widths: 36 18 18 28
+
+   * - Feature
+     - Commit Check ✅
+     - commitlint
+     - Custom hooks
+   * - Conventional Commits enforcement
+     - ✅
+     - ✅
+     - DIY
+   * - Branch naming validation
+     - ✅
+     - ❌
+     - DIY
+   * - Author name / email validation
+     - ✅
+     - ❌
+     - DIY
+   * - Signed-off-by trailer enforcement
+     - ✅
+     - ✅
+     - DIY
+   * - Co-author ignore list
+     - ✅
+     - ❌
+     - DIY
+   * - Organization-level shared config
+     - ✅
+     - ✅
+     - DIY
+   * - Zero-config defaults
+     - ✅
+     - ❌
+     - ❌
+   * - Works without Node.js
+     - ✅
+     - ❌
+     - Depends
+   * - Native TOML configuration
+     - ✅
+     - ❌
+     - Depends
+   * - Git hook / pre-commit integration
+     - ✅
+     - Partial
+     - ✅
+   * - CI/CD-friendly configuration
+     - ✅
+     - Partial
+     - DIY
+
+For ``commitlint``, organization-level shared config is typically delivered via
+shareable config packages or local files. ``DIY`` means you can implement a
+capability with custom Git hooks or ``pre-commit`` scripts, but it is not
+provided as a turnkey policy layer.
+
+
 Versioning
 ----------