diff --git a/.github/workflows/scripts/create_pre_commit_docs.py b/.github/workflows/scripts/create_pre_commit_docs.py new file mode 100755 index 000000000000..5174fc105551 --- /dev/null +++ b/.github/workflows/scripts/create_pre_commit_docs.py @@ -0,0 +1,112 @@ +#!/usr/bin/env python3 + +# Licensed to the Apache Software Foundation (ASF) under one +# or more contributor license agreements. See the NOTICE file +# distributed with this work for additional information +# regarding copyright ownership. The ASF licenses this file +# to you under the Apache License, Version 2.0 (the +# "License"); you may not use this file except in compliance +# with the License. You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, +# software distributed under the License is distributed on an +# "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY +# KIND, either express or implied. See the License for the +# specific language governing permissions and limitations +# under the License. + +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 | 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") + language = hook.get("language", "N/A") + description = hook.get("description", "N/A") + if description == "N/A": + description = hook.get("name", "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} | {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 + + """ + ) + 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 = "PRE_COMMIT_HOOK_DOCS.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 index 107bd8b94cd3..32341e55bca9 100644 --- a/.pre-commit-config.yaml +++ b/.pre-commit-config.yaml @@ -24,13 +24,26 @@ repos: - repo: meta hooks: - id: identity + description: a simple hook which prints all arguments passed to it, useful for debugging. - id: check-hooks-apply + description: check that all the hooks apply to the repository - repo: https://github.com/thlorenz/doctoc.git rev: v2.2.0 hooks: - id: doctoc name: Add TOC for Markdown files + description: automatically keeps your table of contents up to date files: ^CONTRIBUTING\.md$|^INSTALL\.md$|^README\.md$ + - 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 - repo: https://github.com/oxipng/oxipng rev: v9.1.5 hooks: @@ -49,11 +62,13 @@ repos: hooks: - id: chmod name: set file permissions + description: manual hook to be run by macOS or Linux users for a full repository clean up args: ['644'] files: \.md$ stages: [manual] - id: insert-license name: add license for all Markdown files + description: automatically adds a licence header to all Markdown files that don't have a license header files: \.md$ args: - --comment-style @@ -74,6 +89,7 @@ repos: - --fuzzy-match-generates-todo - id: insert-license name: add license for all SQL files + description: automatically adds a licence header to all SQL files that don't have a license header files: \.sql$ args: - --comment-style @@ -96,18 +112,27 @@ repos: hooks: #- id: check-added-large-files - id: check-case-conflict + description: check for case conflicts in file names #- id: check-executables-have-shebangs - id: check-illegal-windows-names + description: check for Windows-illegal file names - id: check-merge-conflict + description: check for merge conflict markers - id: check-shebang-scripts-are-executable + description: check that scripts with shebangs are executable files: \.sh$ - id: check-symlinks + description: checks for symlinks which do not point to anything. - id: check-vcs-permalinks + description: ensures that links to vcs websites are permalinks #- id: check-yaml - id: destroyed-symlinks + description: detects symlinks which are changed to regular files with a content of a path which that symlink was pointing to - id: 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 + description: checks for the existence of private keys exclude: > (?x) ^scripts/vm/systemvm/id_rsa\.cloud$| @@ -124,14 +149,20 @@ repos: ^systemvm/agent/certs/realhostip\.key$| ^test/integration/smoke/test_ssl_offloading\.py$ - id: end-of-file-fixer + description: makes sure files end in a newline and only a newline exclude: \.vhd$|\.svg$ - id: 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 + description: removes UTF-8 byte order marker - id: forbid-submodules + description: forbids any submodules in the repository - id: mixed-line-ending + description: replaces or checks mixed line ending - id: trailing-whitespace + description: trims trailing whitespace files: \.(bat|cfg|cs|css|gitignore|header|in|install|java|md|properties|py|rb|rc|sh|sql|te|template|txt|ucls|vue|xml|xsl|yaml|yml)$|^cloud-cli/bindir/cloud-tool$|^debian/changelog$ args: [--markdown-linebreak-ext=md] exclude: ^services/console-proxy/rdpconsole/src/test/doc/freerdp-debug-log\.txt$ @@ -147,6 +178,7 @@ repos: rev: 7.0.0 hooks: - id: flake8 + description: flake8 is a Python tool that glues together pycodestyle, pyflakes, mccabe, and third-party plugins to check the style and quality of some python code args: [--config, .github/linters/.flake8] - repo: https://github.com/igorshubovych/markdownlint-cli rev: v0.45.0 diff --git a/PRE_COMMIT_HOOK_DOCS.md b/PRE_COMMIT_HOOK_DOCS.md new file mode 100644 index 000000000000..096686d2e984 --- /dev/null +++ b/PRE_COMMIT_HOOK_DOCS.md @@ -0,0 +1,53 @@ + + +# pre-commit hook documentation + + | Hook ID | Language | Description | Version | +|---|---|---|---| +| identity | N/A | a simple hook which prints all arguments passed to it, useful for debugging. | N/A | +| check-hooks-apply | N/A | check that all the hooks apply to the repository | N/A | +| [doctoc](https://github.com/thlorenz/doctoc.git) | N/A | automatically keeps your table of contents up to date | v2.2.0 | +| create-pre-commit-docs | python | creates a Markdown file with information on the pre-commit hooks | N/A | +| [oxipng](https://github.com/oxipng/oxipng) | N/A | optimize PNG images with lossless compression | v9.1.5 | +| [gitleaks](https://github.com/gitleaks/gitleaks) | N/A | detect hardcoded secrets | v8.27.2 | +| [chmod](https://github.com/Lucas-C/pre-commit-hooks) | N/A | manual hook to be run by macOS or Linux users for a full repository clean up | v1.5.5 | +| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | automatically adds a licence header to all Markdown files that don't have a license header | v1.5.5 | +| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | automatically adds a licence header to all Shell files that don't have a license header | v1.5.5 | +| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | automatically adds a licence header to all SQL files that don't have a license header | v1.5.5 | +| [insert-license](https://github.com/Lucas-C/pre-commit-hooks) | N/A | automatically adds a licence header to all YAML files that don't have a license header | v1.5.5 | +| [check-case-conflict](https://github.com/pre-commit/pre-commit-hooks) | N/A | check for case conflicts in file names | v6.0.0 | +| [check-illegal-windows-names](https://github.com/pre-commit/pre-commit-hooks) | N/A | check for Windows-illegal file names | v6.0.0 | +| [check-merge-conflict](https://github.com/pre-commit/pre-commit-hooks) | N/A | check for merge conflict markers | v6.0.0 | +| [check-shebang-scripts-are-executable](https://github.com/pre-commit/pre-commit-hooks) | N/A | check that scripts with shebangs are executable | v6.0.0 | +| [check-symlinks](https://github.com/pre-commit/pre-commit-hooks) | N/A | checks for symlinks which do not point to anything. | v6.0.0 | +| [check-vcs-permalinks](https://github.com/pre-commit/pre-commit-hooks) | N/A | ensures that links to vcs websites are permalinks | v6.0.0 | +| [destroyed-symlinks](https://github.com/pre-commit/pre-commit-hooks) | N/A | detects symlinks which are changed to regular files with a content of a path which that symlink was pointing to | v6.0.0 | +| [detect-aws-credentials](https://github.com/pre-commit/pre-commit-hooks) | N/A | checks for the existence of AWS secrets that you have set up with the AWS CLI | v6.0.0 | +| [detect-private-key](https://github.com/pre-commit/pre-commit-hooks) | N/A | checks for the existence of private keys | v6.0.0 | +| [end-of-file-fixer](https://github.com/pre-commit/pre-commit-hooks) | N/A | makes sure files end in a newline and only a newline | v6.0.0 | +| [file-contents-sorter](https://github.com/pre-commit/pre-commit-hooks) | N/A | sort the lines in specified files (defaults to alphabetical) | v6.0.0 | +| [fix-byte-order-marker](https://github.com/pre-commit/pre-commit-hooks) | N/A | removes UTF-8 byte order marker | v6.0.0 | +| [forbid-submodules](https://github.com/pre-commit/pre-commit-hooks) | N/A | forbids any submodules in the repository | v6.0.0 | +| [mixed-line-ending](https://github.com/pre-commit/pre-commit-hooks) | N/A | replaces or checks mixed line ending | v6.0.0 | +| [trailing-whitespace](https://github.com/pre-commit/pre-commit-hooks) | N/A | trims trailing whitespace | v6.0.0 | +| [codespell](https://github.com/codespell-project/codespell) | N/A | Check spelling with codespell | v2.4.1 | +| [flake8](https://github.com/pycqa/flake8) | N/A | flake8 is a Python tool that glues together pycodestyle, pyflakes, mccabe, and third-party plugins to check the style and quality of some python code | 7.0.0 | +| [markdownlint](https://github.com/igorshubovych/markdownlint-cli) | N/A | check Markdown files with markdownlint | v0.45.0 | +| [yamllint](https://github.com/adrienverge/yamllint) | N/A | check YAML files with yamllint | v1.37.1 | diff --git a/requirements-dev.txt b/requirements-dev.txt index 99ad3943160d..02098fbfb7b7 100644 --- a/requirements-dev.txt +++ b/requirements-dev.txt @@ -16,3 +16,4 @@ # under the License. pre-commit +pyyaml