[CI] pre-commit: auto create Markdown hook docs with Python

jbampton · jbampton · commit 7bc42d52cefd · 2025-07-27T11:54:35.000+10:00
diff --git a/.github/workflows/scripts/create_pre_commit_docs.py b/.github/workflows/scripts/create_pre_commit_docs.py
@@ -0,0 +1,70 @@
+#!/usr/bin/env python3
+
+import yaml
+
+
+def generate_pre_commit_table(yaml_path):
+    """
+    Generates a Markdown table from a pre-commit-config.yaml file.
+    """
+    try:
+        with open(yaml_path) as f:
+            config = yaml.safe_load(f)
+    except FileNotFoundError:
+        return f"Error: The file '{yaml_path}' was not found."
+    except yaml.YAMLError as e:
+        return f"Error parsing YAML file: {e}"
+
+    table_header = "| Hook ID | Language | Name | Description | Version |\n"
+    table_separator = "|---|---|---|---|---|\n"
+    table_rows = []
+
+    for repo in config.get("repos", []):
+        version = repo.get("rev", "N/A")
+        url = repo.get("repo", "N/A")
+        for hook in repo.get("hooks", []):
+            hook_id = hook.get("id", "N/A")
+            name = hook.get("name", "N/A")
+            description = hook.get("description", "N/A")
+            language = hook.get("language", "N/A")
+            # args = ", ".join(hook.get("args", [])) if hook.get("args") else "N/A"
+            if url not in ["local", "meta"]:
+                entry = f"[{hook_id}]({url})"
+            else:
+                entry = f"{hook_id}"
+
+            table_rows.append(f"| {entry} | {language} | {name} | {description} | {version} |\n")
+
+    return table_header + table_separator + "".join(table_rows)
+
+
+def create_markdown_file(target_file_path, content_to_append):
+    """
+    Creates a Markdown file with the content.
+    """
+    try:
+        with open(target_file_path, "w+") as f:
+            f.seek(0)
+            f.write("# pre-commit hook documentation\n\n")
+            f.write(content_to_append)
+        return f"File content successfully created at '{target_file_path}'."
+    except OSError as e:
+        return f"Error creating file: {e}"
+
+
+if __name__ == "__main__":
+
+    pre_commit_yaml_path = (
+        ".pre-commit-config.yaml"  # Assuming this file is in the same directory
+    )
+    output_markdown_path = "doc/guides/pre-commit-hooks.md"
+
+    # Generate the Markdown table
+    markdown_table = generate_pre_commit_table(pre_commit_yaml_path)
+
+    # Add the table to the target Markdown file
+    if "Error" not in markdown_table:
+        result = create_markdown_file(output_markdown_path, markdown_table)
+        print(result)
+    else:
+        print(markdown_table)
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -19,6 +19,14 @@ repos:
         description: check hooks apply to the repository
   - repo: local
     hooks:
+      - id: create-pre-commit-docs
+        name: create pre-commit docs
+        description: creates a Markdown file with information on the pre-commit hooks
+        entry: .github/workflows/scripts/create_pre_commit_docs.py
+        language: python
+        additional_dependencies:
+          - pyyaml
+        require_serial: true
       - id: prettier
         name: run prettier
         description: format files with prettier
@@ -43,29 +51,67 @@ repos:
     rev: v5.0.0
     hooks:
       - id: check-added-large-files
+        name: check added large files
+        description: Prevent giant files from being committed
       - id: check-case-conflict
+        name: check case conflict
+        description: Check for files with names that would conflict on a case-insensitive filesystem like MacOS HFS+ or Windows FAT
       - id: check-executables-have-shebangs
+        name: check executables have shebangs
+        description: Checks that non-binary executables have a proper shebang
         exclude: ^test/t/lang\.rb$
       - id: check-illegal-windows-names
+        name: check-illegal-windows-names
+        description: Check for files that cannot be created on Windows
       - id: pretty-format-json
+        name: pretty format json
+        description: Checks that all your JSON files are pretty
         args: [--autofix, --no-sort-keys]
       - id: check-json
+        name: check json
+        description: Attempts to load all json files to verify syntax
       - id: check-merge-conflict
+        name: check merge conflict
+        description: Check for files that contain merge conflict strings
       - id: check-shebang-scripts-are-executable
+        name: check shebang scripts are executable
+        description: Checks that scripts with shebangs are executable
       - id: check-vcs-permalinks
+        name: check vcs permalinks
+        description: Ensures that links to vcs websites are permalinks
       - id: check-yaml
+        name: check yaml
+        description: Attempts to load all yaml files to verify syntax
       - id: destroyed-symlinks
+        name: destroyed symlinks
+        description: Check for debugger imports and py37+ breakpoint() calls in python source
       - id: detect-aws-credentials
+        name: detect aws credentials
+        description: Checks for the existence of AWS secrets that you have set up with the AWS CLI
         args: [--allow-missing-credentials]
       - id: detect-private-key
+        name: detect private key
+        description: Checks for the existence of private keys
       - id: end-of-file-fixer
+        name: end of file fixer
+        description: Makes sure files end in a newline and only a newline
       - id: file-contents-sorter
+        name: file contents sorter
+        description: Sort the lines in specified files (defaults to alphabetical)
         args: [--unique]
         files: ^\.github/linters/codespell\.txt$
       - id: fix-byte-order-marker
+        name: fix byte order marker
+        description: Removes UTF-8 byte order marker
       - id: forbid-submodules
+        name: forbid submodules
+        description: Prevent addition of new git submodules
       - id: mixed-line-ending
+        name: mixed line ending
+        description: Replaces or checks mixed line ending
       - id: trailing-whitespace
+        name: trailing whitespace
+        description: Trims trailing whitespace
   - repo: https://github.com/Lucas-C/pre-commit-hooks
     rev: v1.5.5
     hooks:
diff --git a/.prettierignore b/.prettierignore
@@ -1,5 +1,6 @@
 # Ignore artifacts:
 build
 coverage
+doc/guides/pre-commit-hooks.md
 doc/internal/opcode.md
 tools/lrama
diff --git a/doc/guides/pre-commit-hooks.md b/doc/guides/pre-commit-hooks.md
@@ -0,0 +1,38 @@
+# pre-commit hook documentation
+
+| Hook ID | Language | Name | Description | Version |
+|---|---|---|---|---|
+| identity | N/A | run identity | check your identity | N/A |
+| check-hooks-apply | N/A | run check-hooks-apply | check hooks apply to the repository | N/A |
+| create-pre-commit-docs | python | create pre-commit docs | creates a Markdown file with information on the pre-commit hooks | N/A |
+| prettier | node | run prettier | format files with prettier | N/A |
+| [gitleaks](https://github.com/gitleaks/gitleaks) | N/A | run gitleaks | detect hardcoded secrets with gitleaks | v8.27.2 |
+| [oxipng](https://github.com/shssoichiro/oxipng) | N/A | run oxipng | use lossless compression to optimize PNG files | v9.1.5 |
+| [check-added-large-files](https://github.com/pre-commit/pre-commit-hooks) | N/A | check added large files | Prevent giant files from being committed | v5.0.0 |
+| [check-case-conflict](https://github.com/pre-commit/pre-commit-hooks) | N/A | check case conflict | Check for files with names that would conflict on a case-insensitive filesystem like MacOS HFS+ or Windows FAT | v5.0.0 |
+| [check-executables-have-shebangs](https://github.com/pre-commit/pre-commit-hooks) | N/A | check executables have shebangs | Checks that non-binary executables have a proper shebang | v5.0.0 |
+| [check-illegal-windows-names](https://github.com/pre-commit/pre-commit-hooks) | N/A | check-illegal-windows-names | Check for files that cannot be created on Windows | v5.0.0 |
+| [pretty-format-json](https://github.com/pre-commit/pre-commit-hooks) | N/A | pretty format json | Checks that all your JSON files are pretty | v5.0.0 |
+| [check-json](https://github.com/pre-commit/pre-commit-hooks) | N/A | check json | Attempts to load all json files to verify syntax | v5.0.0 |
+| [check-merge-conflict](https://github.com/pre-commit/pre-commit-hooks) | N/A | check merge conflict | Check for files that contain merge conflict strings | v5.0.0 |
+| [check-shebang-scripts-are-executable](https://github.com/pre-commit/pre-commit-hooks) | N/A | check shebang scripts are executable | Checks that scripts with shebangs are executable | v5.0.0 |
+| [check-vcs-permalinks](https://github.com/pre-commit/pre-commit-hooks) | N/A | check vcs permalinks | Ensures that links to vcs websites are permalinks | v5.0.0 |
+| [check-yaml](https://github.com/pre-commit/pre-commit-hooks) | N/A | check yaml | Attempts to load all yaml files to verify syntax | v5.0.0 |
+| [destroyed-symlinks](https://github.com/pre-commit/pre-commit-hooks) | N/A | destroyed symlinks | Check for debugger imports and py37+ breakpoint() calls in python source | v5.0.0 |
+| [detect-aws-credentials](https://github.com/pre-commit/pre-commit-hooks) | N/A | detect aws credentials | Checks for the existence of AWS secrets that you have set up with the AWS CLI | v5.0.0 |
+| [detect-private-key](https://github.com/pre-commit/pre-commit-hooks) | N/A | detect private key | Checks for the existence of private keys | v5.0.0 |
+| [end-of-file-fixer](https://github.com/pre-commit/pre-commit-hooks) | N/A | end of file fixer | Makes sure files end in a newline and only a newline | v5.0.0 |
+| [file-contents-sorter](https://github.com/pre-commit/pre-commit-hooks) | N/A | file contents sorter | Sort the lines in specified files (defaults to alphabetical) | v5.0.0 |
+| [fix-byte-order-marker](https://github.com/pre-commit/pre-commit-hooks) | N/A | fix byte order marker | Removes UTF-8 byte order marker | v5.0.0 |
+| [forbid-submodules](https://github.com/pre-commit/pre-commit-hooks) | N/A | forbid submodules | Prevent addition of new git submodules | v5.0.0 |
+| [mixed-line-ending](https://github.com/pre-commit/pre-commit-hooks) | N/A | mixed line ending | Replaces or checks mixed line ending | v5.0.0 |
+| [trailing-whitespace](https://github.com/pre-commit/pre-commit-hooks) | N/A | trailing whitespace | Trims trailing whitespace | v5.0.0 |
+| [forbid-tabs](https://github.com/Lucas-C/pre-commit-hooks) | N/A | run no-tabs checker | check the codebase for tabs | v1.5.5 |
+| [remove-tabs](https://github.com/Lucas-C/pre-commit-hooks) | N/A | run tabs remover | find and convert tabs to spaces | v1.5.5 |
+| [actionlint](https://github.com/rhysd/actionlint) | N/A | run actionlint | lint GitHub Actions workflow files | v1.7.7 |
+| [codespell](https://github.com/codespell-project/codespell) | N/A | run codespell | check spelling with codespell | v2.4.1 |
+| [markdownlint](https://github.com/igorshubovych/markdownlint-cli) | N/A | run markdownlint | checks the style of Markdown files | v0.45.0 |
+| [markdown-link-check](https://github.com/tcort/markdown-link-check) | N/A | run markdown-link-check | checks hyperlinks in Markdown files | v3.13.7 |
+| [rubocop](https://github.com/rubocop/rubocop) | N/A | run rubocop | RuboCop is a Ruby code style checker (linter) and formatter based on the community-driven Ruby Style Guide | v1.78.0 |
+| [shellcheck](https://github.com/shellcheck-py/shellcheck-py) | N/A | run shellcheck | check shell scripts with a static analysis tool | v0.10.0.1 |
+| [yamllint](https://github.com/adrienverge/yamllint) | N/A | run yamllint | check YAML files with yamllint | v1.37.1 |
diff --git a/requirements.txt b/requirements.txt
@@ -0,0 +1,2 @@
+pre-commit
+pyyaml
