lint.yml

# Linting Workflow
#
# Purpose:
#   Performs comprehensive linting and validation checks on YAML, Markdown,
#   and pre-commit configuration files to maintain code quality standards.
#
# Description:
#   This workflow executes multiple linting tools to validate file formatting,
#   syntax, and pre-commit configuration integrity. It ensures consistency
#   across documentation and configuration files.
#
# Trigger Events:
#   - pull_request: On pull requests targeting main branch
#
# Permissions:
#   - Workflow level: None (empty permissions object for security)
#   - Lint job level:
#     * contents: read - Required for checking out repository code
#
# Environment Variables:
#   - environment: Set to 'base' (default environment)
#   - timezone: Retrieved from repository variable TIMEZONE
#
# Jobs:
#
#   1. setup (Infrastructure 🔧):
#      Description: Configures infrastructure and environment context
#      Runner: ubuntu-latest
#      Outputs:
#        - environment: The deployment environment name ('base')
#        - timezone: The configured timezone
#      Steps:
#        - Logs the environment configuration
#        - Logs the timezone configuration
#
#   2. lint (Lint ✏️):
#      Description: Executes linting checks on repository files
#      Dependencies: Requires 'setup' job completion
#      Runner: ubuntu-latest
#      Environment: Uses environment output from setup job
#      Steps:
#        1. Repository checkout (actions/checkout@v6.0.1)
#        2. Node.js setup using version from vars.NODE_VERSION
#        3. npm dependencies installation (npm ci --ignore-scripts)
#        4. YAML validation (npm run validate:yml)
#           - Validates .github/workflows/*.yml syntax
#           - Checks .pre-commit-*.yaml files
#           - Uses yamllint for standards compliance
#        5. Markdown validation (npm run validate:md)
#           - Validates README.md, CHANGELOG.md syntax
#           - Checks documentation formatting
#           - Uses markdownlint for style enforcement
#        6. Python setup using version from vars.PYTHON_VERSION
#        7. Pre-commit installation (pip install pre-commit)
#        8. Pre-commit validation
#           - Validates .pre-commit-hooks.yaml manifest
#           - Validates .pre-commit-config.yaml configuration
#           - Ensures hook definitions are correct
#
# Required Variables:
#   - TIMEZONE: Repository timezone configuration
#   - NODE_VERSION: Node.js version for npm operations
#   - PYTHON_VERSION: Python version for pre-commit operations
#
# Required Secrets:
#   - None (GITHUB_TOKEN automatically provided but not explicitly used)
#
# Validation Tools:
#   - yamllint: YAML syntax and style validation
#   - markdownlint: Markdown formatting and style validation
#   - pre-commit: Pre-commit hook validation
#   - cspell: Spell checking (via npm run spellcheck, if triggered)
#
# Validation Rules:
#   - YAML: Indentation, line length, trailing spaces, duplicate keys
#   - Markdown: Headers, lists, links, code blocks, line length
#   - Pre-commit: Hook syntax, configuration structure, repository URLs
#
# Failure Conditions:
#   - Invalid YAML syntax
#   - Markdown formatting violations
#   - Pre-commit configuration errors
#   - Missing required files
#   - Malformed hook definitions
#
# Security Features:
#   - Pinned action versions with commit SHAs
#   - Minimal required permissions
#   - No code execution from external sources
#   - Validation only (no modifications)
#
# Integration:
#   - Required for PR approval (can be configured in branch protection)
#   - Runs in parallel with unit tests
#   - Blocks merge on failure (when configured)
#   - Provides detailed error output in PR checks
#
# Configuration Files:
#   - .yamllint.yml: YAML linting rules (if present)
#   - .markdownlint.json: Markdown linting rules
#   - .markdownlintignore: Files to exclude from Markdown linting
#   - .pre-commit-hooks.yaml: Hook manifest
#   - .pre-commit-config.yaml: Local configuration
#
# Notes:
#   - Fast execution (~1-2 minutes typical)
#   - Catches common formatting errors early
#   - Enforces consistent code style
#   - Prevents malformed configuration from merging
#   - British English spelling enforced via cspell
#

name: Lint check ✏️
run-name: Lint check ✏️

on:
  pull_request:
    branches: ["**"]

permissions: {}

env:
  environment: base
  timezone: ${{ vars.TIMEZONE }}

jobs:
  # 1. Setup infrastructure
  setup:
    name: Infrastructure 🔧
    runs-on: ubuntu-latest
    outputs:
      environment: ${{ env.environment }}
      timezone: ${{ env.timezone }}
    steps:
      - name: Environment 🧪
        run: echo "Environment set to ${{ env.environment }}"

      - name: Timezone 🌐
        run: echo "Timezone set to ${{ env.timezone }}"

  # 2. Execute linting checks
  lint:
    permissions:
      contents: read

    name: Lint ✏️
    needs: setup
    environment:
      name: ${{ needs.setup.outputs.environment }}
    runs-on: ubuntu-latest

    steps:
      - name: Commit
        uses: ministryofjustice/devsecops-actions/github/commit@f965eb1771ec66cfc41d7d57dc607fa6dfbc10ed # v1.4.0

      - name: Repository
        uses: actions/checkout@0c366fd6a839edf440554fa01a7085ccba70ac98 # frozen: v6.0.1

      - name: Node
        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # frozen: v6.1.0
        with:
          node-version: ${{ vars.NODE_VERSION }}

      - name: Install
        run: npm ci --ignore-scripts

      - name: SH
        run: npm run validate:sh

      - name: YML
        run: npm run validate:yml

      - name: MD
        run: npm run validate:md

      - name: Python
        uses: actions/setup-python@28f2168f4d98ee0445e3c6321f6e6616c83dd5ec # frozen: v6.1.0
        with:
          python-version-file: ./.python-version

      - name: Install
        working-directory: ./
        run: python -m pip install -r requirements.txt

      - name: Pre-commit
        run: |
          pre-commit validate-manifest
          pre-commit validate-config