Merge branch 'feature/mkdocforge-setup-dev-environment' into develop

Author: Mdevpro78

.gitattributes

@@ -1,15 +1,58 @@
-# Set default behavior to automatically normalize line endings
-* text=auto
-
-# Explicitly declare files that should use LF
-*.sh text eol=lf
-Makefile text eol=lf
-*.mk text eol=lf
-
-# Denote all files that are truly binary and should not be modified
-*.png binary
-*.jpg binary
-*.gif binary
-*.ico binary
-*.zip binary
-*.pdf binary
+# Default: Auto-detect text files and normalize line endings to LF
+* text=auto eol=lf
+
+# Python source files: Enforce UTF‑8 encoding and enable Python-aware diffs
+*.py     text diff=python encoding=utf-8
+*.pyi    text diff=python encoding=utf-8
+*.pyw    text diff=python encoding=utf-8
+
+# Python project configuration files: Consistent UTF‑8 encoding
+*.toml                   text encoding=utf-8
+pyproject.toml           text encoding=utf-8
+requirements*.txt         text encoding=utf-8
+.pre-commit-config.yaml   text encoding=utf-8
+
+# Documentation, configuration, and data files: Uniform encoding and enhanced diffs for Markdown
+*.md   text encoding=utf-8 diff=markdown
+*.rst  text encoding=utf-8
+*.json text encoding=utf-8
+*.yaml text encoding=utf-8
+*.yml  text encoding=utf-8
+*.ini  text encoding=utf-8
+*.cfg  text encoding=utf-8
+
+# Explicitly declare files that should use LF line endings (scripts and makefiles)
+*.sh       text eol=lf
+Makefile   text eol=lf
+*.mk       text eol=lf
+
+# Jupyter Notebooks: Ensure UTF‑8 encoding for proper text processing
+*.ipynb text encoding=utf-8
+
+# Cython source files: Enable proper diffing with enforced UTF‑8 encoding
+*.pyx   text diff=python encoding=utf-8
+
+# Scalable Vector Graphics: Enforce UTF‑8 encoding and enable XML-aware diffs
+*.svg  text encoding=utf-8 diff=xml
+
+# Additional text files: Enforce LF and UTF‑8 for plain text files
+*.txt  text eol=lf working-tree-encoding=utf-8
+
+# Binary and compiled files: Prevent alterations by marking as binary
+*.db     binary
+*.p      binary
+*.pkl    binary
+*.pickle binary
+*.pyc    binary
+*.pyd    binary
+*.pyo    binary
+*.png   binary
+*.jpg   binary
+*.gif   binary
+*.ico   binary
+*.zip   binary
+*.pdf   binary
+
+# Exclude Git-specific files from exports
+.gitattributes export-ignore
+.gitignore     export-ignore

.markdownlint.yaml

@@ -1,3 +1,4 @@
+---
 # MkDocs-compatible markdownlint configuration
 
 # Default state for all rules

.mdformat.toml

@@ -32,5 +32,5 @@ plugin.black.line_length = 88
 
 plugin.ruff.enable = true
 plugin.ruff.line_length = 88
-plugin.ruff.select = ["E", "F", "W"]
-plugin.ruff.ignore = ["ANN101"]
+plugin.ruff.select = [ "E", "F", "W" ]
+plugin.ruff.ignore = [ "ANN101" ]

.pre-commit-config.yaml

@@ -0,0 +1,247 @@
+%YAML 1.2
+---
+# Pre-commit Configuration
+# This file configures pre-commit hooks that run automatically before git commits
+# to ensure code quality, formatting, and prevent security issues.
+# https://pre-commit.com/
+default_install_hook_types:
+  - pre-commit
+  - commit-msg
+
+repos:
+
+  #########################################
+  # General Code Quality Checks
+  #########################################
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    # Standard collection of pre-commit hooks for various checks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+        name: "✂️ whitespace · Remove trailing whitespace"
+        # Removes trailing whitespace at end of lines
+      - id: check-ast
+        name: "🔍 python · Check Python AST"
+        # Validates Python syntax without executing code
+      - id: end-of-file-fixer
+        name: "📄 files · Fix end of files"
+        # Ensures files end with a newline
+      - id: check-yaml
+        name: "📋 yaml · Validate YAML files"
+        exclude: "mkdocs.yml"
+        # Validates YAML syntax
+      - id: check-toml
+        name: "📋 toml · Validate TOML files"
+        # Validates TOML syntax
+      - id: check-json
+        name: "📋 json · Validate JSON files"
+        # Validates JSON syntax
+      - id: check-added-large-files
+        name: "📏 files · Check for added large files"
+        # Prevents large files from being committed
+      - id: detect-private-key
+        name: "🔑 security · Detect private keys"
+        # Prevents accidental commit of private keys
+      - id: pretty-format-json
+        name: "📋 json · Format JSON files"
+        # Formats JSON files for readability
+      - id: check-merge-conflict
+        name: "🔀 git · Check for merge conflicts"
+      - id: forbid-new-submodules
+        name: "🌳 git · Prevent submodule creation"
+
+      - id: no-commit-to-branch
+        name: "🌳 git · Protect main branches"
+        args: ["--branch", "main", "--branch", "master"]
+        # Prevents direct commits to protected branches
+        # Detects unresolved merge conflicts
+      - id: check-executables-have-shebangs
+        name: "📜 files · Check executables have shebangs"
+        # Ensures executable files have proper shebangs
+      - id: check-shebang-scripts-are-executable
+        name: "📜 files · Check shebang scripts are executable"
+        # Makes sure files with shebangs are executable
+      - id: pretty-format-json
+        name: "📋 json · Format JSON files"
+        args: [--autofix, --no-sort-keys]  # Fix formatting but don't sort keys
+      - id: name-tests-test
+        name: "🧪 tests · Check test file naming"
+        args: [--pytest-test-first]  # Enforces pytest naming conventions
+      - id: mixed-line-ending
+        name: "📄 files · Fix mixed line endings"
+        args: ['--fix=lf']  # Standardize on LF line endings
+      - id: check-case-conflict
+        name: "📁 filesystem/📝 names · Check case sensitivity"
+      - id: check-illegal-windows-names
+        name: "📁 filesystem/📝 names · Validate Windows filenames"
+      - id: check-symlinks
+        name: "📁 filesystem/🔗 symlink · Check symlink validity"
+      - id: destroyed-symlinks
+        name: "📁 filesystem/🔗 symlink · Detect broken symlinks"
+
+  #########################################
+  # Python Formatting and Linting
+  #########################################
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    # Ruff is a fast Python linter and formatter written in Rust
+    rev: v0.11.2
+    hooks:
+      - id: ruff
+        name: "🐍 python · Format with Ruff"
+        args: [--fix, --exit-non-zero-on-fix]  # Automatically fix issues when possible
+      - id: ruff-format
+        name: "🐍 python · Format with Ruff"
+        # Automatically formats Python code
+
+
+  #########################################
+  # Python Code Modernization
+  #########################################
+  - repo: https://github.com/asottile/pyupgrade
+    # Automatically upgrades Python syntax to newer versions
+    rev: v3.19.1
+    hooks:
+      - id: pyupgrade
+        name: "🔄 python · Upgrade Python syntax"
+        args: ["--py311-plus"]  # Use Python 3.11+ specific syntax improvements
+        # Upgrades syntax to use newer Python features
+
+  - repo: https://github.com/asottile/add-trailing-comma
+    # Adds trailing commas to function calls and definitions
+    rev: v3.1.0
+    hooks:
+      - id: add-trailing-comma
+        name: "🔤 python · Add trailing commas"
+        # Makes future diffs cleaner and multiline constructs more consistent
+
+  #########################################
+  # API Documentation Validation
+  #########################################
+  - repo: https://github.com/python-openapi/openapi-spec-validator
+    rev: 0.7.1
+    hooks:
+      - id: openapi-spec-validator
+        name: "📝 api · Validate OpenAPI Spec"
+        # Ensures OpenAPI specifications are valid
+
+  #########################################
+  # Python Project Configuration Validation
+  #########################################
+  - repo: https://github.com/abravalheri/validate-pyproject
+    # Validates pyproject.toml file format
+    rev: v0.24.1
+    hooks:
+      - id: validate-pyproject
+        name: "🐍 python · Validate pyproject.toml"
+        additional_dependencies: ["validate-pyproject-schema-store[all]"]
+        # Ensures pyproject.toml follows PEP specifications
+
+  #########################################
+  # Documentation Formatting
+  #########################################
+  - repo: https://github.com/hukkin/mdformat
+    # Markdown formatter for consistent documents
+    rev: 0.7.22
+    hooks:
+      - id: mdformat
+        name: "📝 markdown · Format markdown"
+        # Formats markdown files for consistency
+        exclude: |
+          (?x)^(
+            .*\{\{.*\}\}.*
+          )$
+        entry: mdformat
+        language: python
+        types: [markdown]
+        verbose: true
+        log_file: .logs/mdformat.log
+        fail_fast: false
+        files: \.(md|markdown)$
+        args:
+          - "--wrap=no"  # Wrap lines at 80 characters (customize as needed)
+          - "--end-of-line=lf"  # Use LF line endings (Unix-style, recommended for consistency)
+          # - "--check"  # Exit with error if formatting changes are needed
+        additional_dependencies:
+          - mdformat-gfm==0.4.1  # GitHub Flavored Markdown support
+          - mdformat-mkdocs[recommended]==4.1.2  # MkDocs-specific formatting
+          - mdformat-frontmatter==2.0.8  # YAML frontmatter support
+          - mdformat-footnote==0.1.1  # Footnote support
+          - mdformat-tables==1.0.0  # Table formatting
+          - mdformat-toc==0.3.0  # Table of contents formatting
+          - mdformat-beautysh==0.1.1  # Shell code block formatting
+          - mdformat-black==0.1.1  # Python code block formatting
+          - mdformat-gfm-alerts==1.0.1  # GitHub-style alerts
+          - mdformat-myst==0.2.1  # MyST Markdown support
+          - mdformat-config==0.2.1  # Configuration file parsing
+          - mdformat-ruff==0.1.3  # Ruff linting for Python code blocks
+          - mdformat-web==0.2.0  # Web-related Markdown formatting
+          - mdformat-simple-breaks==0.0.1  # Consistent line break handling
+          - ruff
+
+  #########################################
+  - repo: https://github.com/DavidAnson/markdownlint-cli2
+    rev: v0.17.2
+    hooks:
+      - id: markdownlint-cli2
+        name: "📝 markdown · Lint markdown with markdownlint"
+        args: [--fix]
+        exclude: ^CHANGELOG
+        # Lints markdown files for style and consistency issues
+
+  #########################################
+  # YAML File Validation
+  #########################################
+  - repo: https://github.com/adrienverge/yamllint.git
+    rev: v1.37.0
+    hooks:
+      - id: yamllint
+        name: "📋 yaml · Lint YAML files with yamllint"
+        args: [--strict, -c=./.yamllint.yaml]
+        # Validates YAML files for style and syntax issues
+
+  #########################################
+  # A pre-commit hook to format and lint TOML files
+  #########################################
+  - repo: https://github.com/ComPWA/taplo-pre-commit
+    rev: v0.9.3
+    hooks:
+      - id: taplo-format
+        name: "📋 toml · Format TOML files with taplo"
+        # Formats TOML files for consistency
+      - id: taplo-lint
+        name: "📋 toml · Lint TOML files with taplo"
+        # Validates TOML files for errors and style issues
+
+  #########################################
+  # Makefile Validation
+  #########################################
+  - repo: https://github.com/mrtazz/checkmake.git
+    # Makefile linter
+    rev: 0.2.2
+    hooks:
+      - id: checkmake
+        name: "🐮 Makefile · Lint Makefile"
+        # Validates Makefile structure and conventions
+        # No clear documentation on how to skip certain checks.
+        # Fixed as many as I could, but best option is to ignore the file.
+        exclude: |
+          (?x)^(
+            .*\{\{.*\}\}.*|
+          )$
+
+  #########################################
+  # Scanning Hardcoded Secrets
+  #########################################
+  - repo: https://github.com/gitleaks/gitleaks
+    rev: v8.24.2
+    hooks:
+      - id: gitleaks
+        name: "🔒 security · Scan for hardcoded secrets"
+        # Detects and prevents secrets from being committed
+
+# Set default Python version for all hooks
+default_language_version:
+  python: python3.11
+
+# Define which git hooks these run on (defaults to pre-commit)
+default_stages: [pre-commit]

.yamllint.yaml

@@ -0,0 +1,28 @@
+extends: default
+
+rules:
+  braces:
+    level: warning
+    max-spaces-inside: 1
+  brackets:
+    level: warning
+    max-spaces-inside: 1
+  colons:
+    level: warning
+  commas:
+    level: warning
+  comments: disable
+  comments-indentation: disable
+  document-start: disable
+  empty-lines:
+    level: warning
+  hyphens:
+    level: warning
+  indentation:
+    level: warning
+    indent-sequences: consistent
+  line-length:
+    max: 110
+    level: warning
+    allow-non-breakable-inline-mappings: true
+  truthy: disable