Taskfile.yml

version: "3"

vars:
  CLANG_FORMAT_CONFIGURATION_FOLDER: other/clang-format-configuration
  CLANG_FORMAT_CONFIGURATION_PATH: "{{.CLANG_FORMAT_CONFIGURATION_FOLDER}}/.clang-format"
  CLANG_FORMAT_TEST_DATA_FOLDER: "{{.CLANG_FORMAT_CONFIGURATION_FOLDER}}/testdata"
  CLANG_FORMAT_INPUT_TEST_DATA_FOLDER: "{{.CLANG_FORMAT_TEST_DATA_FOLDER}}/input"
  CLANG_FORMAT_TARGETED_INPUT_TEST_DATA_FOLDER: "{{.CLANG_FORMAT_INPUT_TEST_DATA_FOLDER}}/targeted"
  CLANG_FORMAT_GOLDEN_TEST_DATA_FOLDER: "{{.CLANG_FORMAT_TEST_DATA_FOLDER}}/golden"
  # See: https://github.com/arduino/arduino-ide/blob/main/arduino-ide-extension/package.json
  DEFAULT_CLANG_FORMAT_VERSION: 14.0.0
  # Last version of ajv-cli with support for the JSON schema "Draft 4" specification
  SCHEMA_DRAFT_4_AJV_CLI_VERSION: 3.3.0

tasks:
  check:
    desc: Check for problems with the project
    deps:
      - task: ci:validate
      - task: clang-format:check-config
      - task: clang-format:check-output
      - task: clang-format:check-testdata
      - task: clang-format:validate
      - task: dependabot:validate
      - task: eslint:validate
      - task: general:check-formatting
      - task: general:check-spelling
      - task: issue-form:validate
      - task: js:lint
      - task: labels:validate
      - task: markdown:check-links
      - task: markdown:lint
      - task: markdownlint:validate
      - task: python:lint
      - task: python:test
      - task: shell:check
      - task: shell:check-mode
      - task: yaml:lint

  fix:
    desc: Make automated corrections to the project's files
    deps:
      - task: ci:sync
      - task: config:sync
      - task: dependabot:sync
      - task: general:correct-spelling
      - task: general:format-prettier
      - task: github:sync
      - task: js:fix
      - task: markdown:fix
      - task: python:format
      - task: shell:format

  ci:sync:
    desc: Sync CI workflows from templates
    vars:
      WORKFLOWS_PATH: "./.github/workflows"
      WORKFLOW_TEMPLATES_PATH: "./workflow-templates"
    cmds:
      - |
        cp \
          "{{.WORKFLOW_TEMPLATES_PATH}}/check-general-formatting-task.yml" \
          "{{.WORKFLOW_TEMPLATES_PATH}}/check-javascript-task.yml" \
          "{{.WORKFLOW_TEMPLATES_PATH}}/check-markdown-task.yml" \
          "{{.WORKFLOW_TEMPLATES_PATH}}/check-npm-task.yml" \
          "{{.WORKFLOW_TEMPLATES_PATH}}/check-prettier-formatting-task.yml" \
          "{{.WORKFLOW_TEMPLATES_PATH}}/check-python-task.yml" \
          "{{.WORKFLOW_TEMPLATES_PATH}}/check-shell-task.yml" \
          "{{.WORKFLOW_TEMPLATES_PATH}}/check-taskfiles.yml" \
          "{{.WORKFLOW_TEMPLATES_PATH}}/check-yaml-task.yml" \
          "{{.WORKFLOW_TEMPLATES_PATH}}/sync-labels-npm.yml" \
          "{{.WORKFLOW_TEMPLATES_PATH}}/spell-check-task.yml" \
          "{{.WORKFLOW_TEMPLATES_PATH}}/test-python-poetry-task.yml" \
          "{{.WORKFLOWS_PATH}}"

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-workflows-task/Taskfile.yml
  ci:validate:
    desc: Validate GitHub Actions workflows against their JSON schema
    vars:
      # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/github-workflow.json
      WORKFLOW_SCHEMA_URL: https://json.schemastore.org/github-workflow
      WORKFLOW_SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="workflow-schema-XXXXXXXXXX.json"
      WORKFLOWS_DATA_PATH: "./.github/workflows/*.{yml,yaml}"
      TEMPLATE_WORKFLOWS_DATA_PATH: "./workflow-templates/*.{yml,yaml}"
    deps:
      - task: npm:install-deps
    cmds:
      - |
        wget \
          --quiet \
          --output-document="{{.WORKFLOW_SCHEMA_PATH}}" \
          {{.WORKFLOW_SCHEMA_URL}}
      - |
        npx \
          --package=ajv-cli \
          --package=ajv-formats \
          ajv validate \
            --all-errors \
            --strict=false \
            -c ajv-formats \
            -s "{{.WORKFLOW_SCHEMA_PATH}}" \
            -d "{{.WORKFLOWS_DATA_PATH}}"
      - |
        npx \
          --package=ajv-cli \
          --package=ajv-formats \
          ajv validate \
            --all-errors \
            --strict=false \
            -c ajv-formats \
            -s "{{.WORKFLOW_SCHEMA_PATH}}" \
            -d "{{.TEMPLATE_WORKFLOWS_DATA_PATH}}"

  clang-format:check-config:
    desc: Check that ClangFormat configuration file matches effective tool configuration
    vars:
      WORKING_FOLDER:
        sh: |
          if [[ "{{.WORKING_FOLDER}}" == "" ]]; then
            # Generate a path
            task utility:mktemp-folder TEMPLATE="clang-format-check-config-XXXXXXXXXX"
          else
            # A path was specified via the command line
            echo "{{.WORKING_FOLDER}}"
          fi
      ACTUAL_CONFIGURATION_PATH: "{{.WORKING_FOLDER}}/actual/.clang-format"
      EXPECTED_CONFIGURATION_PATH: "{{.WORKING_FOLDER}}/expected/.clang-format"
    cmds:
      - |
        mkdir "{{.WORKING_FOLDER}}/actual"
        mkdir "{{.WORKING_FOLDER}}/expected"
        cp "{{.CLANG_FORMAT_CONFIGURATION_PATH}}" "{{.WORKING_FOLDER}}/actual/"
      - task: clang-format:dump-config
        vars:
          TARGET_PATH: "{{.WORKING_FOLDER}}/expected/.clang-format"
      - |
        cd "{{.WORKING_FOLDER}}"
        diff --color=always --unified "actual/.clang-format" "expected/.clang-format"

  # Check if ClangFormat is installed and the expected version
  clang-format:check-installed:
    vars:
      EXPECTED_CLANG_FORMAT_VERSION: "{{default .DEFAULT_CLANG_FORMAT_VERSION .CLANG_FORMAT_VERSION}}"
    cmds:
      - |
        if ! which clang-format &>/dev/null; then
          echo "clang-format not found or not in PATH. Please install: https://github.com/arduino/clang-static-binaries/releases"
          exit 1
        fi
      - |
        INSTALLED_CLANG_FORMAT_VERSION_ARRAY=($(clang-format --version))
        INSTALLED_CLANG_FORMAT_VERSION="${INSTALLED_CLANG_FORMAT_VERSION_ARRAY[${#INSTALLED_CLANG_FORMAT_VERSION_ARRAY[@]}-1]}"
        if [[ "$INSTALLED_CLANG_FORMAT_VERSION" != "{{.EXPECTED_CLANG_FORMAT_VERSION}}" ]]; then
          echo "Installed version of clang-format $INSTALLED_CLANG_FORMAT_VERSION (at $(which clang-format)) does not match expected {{.EXPECTED_CLANG_FORMAT_VERSION}}"
          exit 1
        fi

  clang-format:check-output:
    desc: Compare actual vs expected output of ClangFormat
    vars:
      WORKING_FOLDER:
        sh: |
          if [[ "{{.WORKING_FOLDER}}" == "" ]]; then
            # Generate a path
            task utility:mktemp-folder TEMPLATE="clang-format-check-XXXXXXXXXX"
          else
            # A path was specified via the command line
            echo "{{.WORKING_FOLDER}}"
          fi
    deps:
      - task: clang-format:check-installed
    cmds:
      - |
        cp \
          --recursive \
          --target-directory="{{.WORKING_FOLDER}}" \
          "{{.CLANG_FORMAT_GOLDEN_TEST_DATA_FOLDER}}" \
          "{{.CLANG_FORMAT_INPUT_TEST_DATA_FOLDER}}"
      - task: clang-format:format
        vars:
          TARGET_FOLDER: "{{.WORKING_FOLDER}}/input/"
      - |
        # Give the folder an appropriate name to make the diff easier to understand
        mv "{{.WORKING_FOLDER}}/input/" "{{.WORKING_FOLDER}}/output/"
      - |
        cd "{{.WORKING_FOLDER}}"
        diff --color=always --recursive --unified "golden/" "output/"

  clang-format:check-testdata:
    desc: Check whether the targeted test data C++ code for the ClangFormat configuration is valid and correct
    cmds:
      - |
        if ! which g++ &>/dev/null; then
          echo "GCC not found or not in PATH."
          exit 1
        fi
      - |
        # Only the "targeted" test data is checked because the "samples" test data is not maintained in this repo.
        g++ \
          -fconcepts \
          -fsyntax-only \
          -I "{{.CLANG_FORMAT_TARGETED_INPUT_TEST_DATA_FOLDER}}/include" \
          -Wall \
          -Werror \
          -Wextra \
          "{{.CLANG_FORMAT_TARGETED_INPUT_TEST_DATA_FOLDER}}"/*.cpp

  clang-format:convert:
    desc: Convert the ClangFormat configuration file into the JavaScript object used by Arduino IDE 2.x
    vars:
      OUTPUT_PATH:
        sh: |
          if [[ "{{.OUTPUT_PATH}}" == "" ]]; then
            task utility:mktemp-file TEMPLATE="clang-format-js-object-XXXXXXXXXX.txt"
          else
            echo "{{.OUTPUT_PATH}}"
          fi
    deps:
      - task: npm:install-deps
    cmds:
      - |
        node \
          "{{.CLANG_FORMAT_CONFIGURATION_FOLDER}}/scripts/convert-clang-format-configuration.js" \
          "{{.CLANG_FORMAT_CONFIGURATION_PATH}}" \
          "{{.OUTPUT_PATH}}"

  # Write the effective ClangFormat configuration to the path specified by the TARGET_PATH variable
  clang-format:dump-config:
    deps:
      - task: clang-format:check-installed
    cmds:
      - |
        if ! which yq &>/dev/null; then
          echo "ec not found or not in PATH. Please install: https://github.com/mikefarah/yq/#install"
          exit 1
        fi

      - |
        # Add source comment
        echo \
          "# Source: https://github.com/arduino/tooling-project-assets/tree/main/other/clang-format-configuration" > \
            "{{.TARGET_PATH}}"

        # Dump the effective configuration to the target file
        clang-format \
          --dump-config \
          --style=file:"{{.CLANG_FORMAT_CONFIGURATION_PATH}}" >> \
            "{{.TARGET_PATH}}"

      - |
        # Correct invalid `BasedOnStyle` key value
        # The existing key is deleted before assigning it to a valid value in order to achieve consistent quoting style
        # (updating the empty string value in place causes the assigned value to be wrapped in quotes)
        yq --inplace 'del(.BasedOnStyle)' "{{.TARGET_PATH}}"
        yq --inplace '.BasedOnStyle = "LLVM"' "{{.TARGET_PATH}}"

      - |
        # Fix the inconsistent key order
        yq --inplace 'sort_keys(.)' "{{.TARGET_PATH}}"

  # Use ClangFormat to format the files under the path specified by TARGET_FOLDER recursively
  clang-format:format:
    cmds:
      - |
        find \
          "{{.TARGET_FOLDER}}" \
          \( \
            -name '*.c' -or \
            -name '*.cpp' -or \
            -name '*.h' -or \
            -name '*.ino' -or \
            -name '*.inot' -or \
            -name '*.ipp' -or \
            -name '*.tpp' -and \
            -type f \
          \) \
          -exec \
            clang-format \
              --assume-filename=foo.cpp \
              -i \
              --style=file:"{{.CLANG_FORMAT_CONFIGURATION_PATH}}" \
              {} \;

  # Print the standard version of ClangFormat for current use
  clang-format:get-version:
    cmds:
      - echo "{{.DEFAULT_CLANG_FORMAT_VERSION}}"

  clang-format:update-config:
    desc: Update ClangFormat configuration file to match effective tool configuration
    vars:
      WORKING_PATH:
        sh: task utility:mktemp-file TEMPLATE="clang-format-update-config-XXXXXXXXXX.json"
    cmds:
      - task: clang-format:dump-config
        vars:
          TARGET_PATH: "{{.WORKING_PATH}}"
      - mv --force "{{.WORKING_PATH}}" "{{.CLANG_FORMAT_CONFIGURATION_PATH}}"

  clang-format:update-golden:
    desc: Update golden master test data for current configuration
    deps:
      - task: clang-format:check-installed
    cmds:
      - rm --recursive "{{.CLANG_FORMAT_GOLDEN_TEST_DATA_FOLDER}}/"
      - cp --recursive "{{.CLANG_FORMAT_INPUT_TEST_DATA_FOLDER}}/" "{{.CLANG_FORMAT_GOLDEN_TEST_DATA_FOLDER}}/"
      - task: clang-format:format
        vars:
          TARGET_FOLDER: "{{.CLANG_FORMAT_GOLDEN_TEST_DATA_FOLDER}}/"

  clang-format:validate:
    desc: Validate ClangFormat configuration file against its JSON schema
    vars:
      # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/clang-format.json
      SCHEMA_URL: https://json.schemastore.org/clang-format.json
      SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="clang-format-configuration-schema-XXXXXXXXXX.json"
      DATA_SOURCE_PATH: "{{.CLANG_FORMAT_CONFIGURATION_PATH}}"
      # ajv-cli identifies YAML-format data files by their file extension, so renaming is required:
      # https://github.com/ajv-validator/ajv-cli/issues/117
      DATA_PATH:
        sh: task utility:mktemp-file TEMPLATE=".clang-format-XXXXXXXXXX.yml"
    deps:
      - task: npm:install-deps
    cmds:
      - wget --quiet --output-document="{{.SCHEMA_PATH}}" {{.SCHEMA_URL}}
      - cp "{{.DATA_SOURCE_PATH}}" "{{.DATA_PATH}}"
      - |
        npx \
          --package=ajv-cli \
          --package=ajv-formats \
          ajv validate \
            --all-errors \
            -c ajv-formats \
            -s "{{.SCHEMA_PATH}}" \
            -d "{{.DATA_PATH}}"

  config:sync:
    desc: Sync configuration files from templates
    vars:
      REPOSITORY_ROOT_PATH: "./"
      WORKFLOW_TEMPLATE_ASSETS_PATH: "./workflow-templates/assets"
    cmds:
      - |
        cp \
          "{{.WORKFLOW_TEMPLATE_ASSETS_PATH}}/check-javascript/.eslintrc.yml" \
          "{{.WORKFLOW_TEMPLATE_ASSETS_PATH}}/general/.editorconfig" \
          "{{.WORKFLOW_TEMPLATE_ASSETS_PATH}}/check-python/.flake8" \
          "{{.WORKFLOW_TEMPLATE_ASSETS_PATH}}/check-markdown/.markdownlint.yml" \
          "{{.REPOSITORY_ROOT_PATH}}"

  dependabot:validate:
    desc: Validate Dependabot configuration files against their JSON schema
    vars:
      # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/dependabot-2.0.json
      SCHEMA_URL: https://json.schemastore.org/dependabot-2.0
      SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="dependabot-schema-XXXXXXXXXX.json"
      DATA_PATH: "**/dependabot.yml"
      PROJECT_FOLDER:
        sh: pwd
      WORKING_FOLDER:
        sh: task utility:mktemp-folder TEMPLATE="dependabot-validate-XXXXXXXXXX"
    cmds:
      - wget --quiet --output-document="{{.SCHEMA_PATH}}" {{.SCHEMA_URL}}
      - |
        cd "{{.WORKING_FOLDER}}"  # Workaround for https://github.com/npm/cli/issues/3210
        npx ajv-cli@{{.SCHEMA_DRAFT_4_AJV_CLI_VERSION}} validate \
          --all-errors \
          -s "{{.SCHEMA_PATH}}" \
          -d "{{.PROJECT_FOLDER}}/{{.DATA_PATH}}"

  dependabot:sync:
    desc: Sync workflow duplicates for dependabot checks
    vars:
      WORKFLOW_TEMPLATES_PATH: "./workflow-templates"
      WORKFLOW_TEMPLATE_COPIES_PATH: "./workflow-templates/dependabot/workflow-template-copies/.github/workflows"
    cmds:
      # Sync workflow templates with the copies in the folder where Dependabot can check them for updates.
      - mkdir --parents "{{.WORKFLOW_TEMPLATE_COPIES_PATH}}"
      - rm --force "{{.WORKFLOW_TEMPLATE_COPIES_PATH}}"/*
      - |
        find "{{.WORKFLOW_TEMPLATES_PATH}}" \
          -maxdepth 1 \
          -type f \
          -regex '.*\.ya?ml' \
          -exec cp '{}' "{{.WORKFLOW_TEMPLATE_COPIES_PATH}}" \;

  docs:generate:
    desc: Create all generated documentation content
    # This is an "umbrella" task used to call any documentation generation processes the project has.
    # It can be left empty if there are none.

  eslint:validate:
    desc: Validate ESLint configuration file against its JSON schema
    vars:
      # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/eslintrc.json
      SCHEMA_URL: https://json.schemastore.org/eslintrc.json
      SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="eslintrc-schema-XXXXXXXXXX.json"
      DATA_PATH: workflow-templates/assets/check-javascript/.eslintrc.yml
      # ajv-cli identifies YAML-format data files by their file extension, so renaming is required:
      # https://github.com/ajv-validator/ajv-cli/issues/117
      PROJECT_FOLDER:
        sh: pwd
      WORKING_FOLDER:
        sh: task utility:mktemp-folder TEMPLATE="eslintrc-validate-XXXXXXXXXX"
    cmds:
      - wget --quiet --output-document="{{.SCHEMA_PATH}}" {{.SCHEMA_URL}}
      - |
        cd "{{.WORKING_FOLDER}}"  # Workaround for https://github.com/npm/cli/issues/3210
        npx ajv-cli@{{.SCHEMA_DRAFT_4_AJV_CLI_VERSION}} validate \
          --all-errors \
          -s "{{.SCHEMA_PATH}}" \
          -d "{{.PROJECT_FOLDER}}/{{.DATA_PATH}}"

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-general-formatting-task/Taskfile.yml
  general:check-formatting:
    desc: Check basic formatting style of all files
    cmds:
      - |
        if ! which ec &>/dev/null; then
          echo "ec not found or not in PATH. Please install: https://github.com/editorconfig-checker/editorconfig-checker#installation"
          exit 1
        fi
      - ec

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/spell-check-task/Taskfile.yml
  general:check-spelling:
    desc: Check for commonly misspelled words
    deps:
      - task: poetry:install-deps
    cmds:
      - poetry run codespell

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/spell-check-task/Taskfile.yml
  general:correct-spelling:
    desc: Correct commonly misspelled words where possible
    deps:
      - task: poetry:install-deps
    cmds:
      - poetry run codespell --write-changes

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-prettier-formatting-task/Taskfile.yml
  general:format-prettier:
    desc: Format all supported files with Prettier
    deps:
      - task: npm:install-deps
    cmds:
      - npx prettier --write .

  github:sync:
    desc: Sync GitHub community health files
    vars:
      ISSUE_TEMPLATES_INSTALLATION_PATH: "./.github/ISSUE_TEMPLATE"
      ISSUE_TEMPLATES_PATH: "./issue-templates"
    cmds:
      - |
        cp \
          "{{.ISSUE_TEMPLATES_PATH}}/minimal/bug-report.md" \
          "{{.ISSUE_TEMPLATES_PATH}}/minimal/feature-request.md" \
          "{{.ISSUE_TEMPLATES_INSTALLATION_PATH}}"

  issue-form:validate:
    desc: Validate GitHub issue form configuration files against their JSON schema
    vars:
      # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/github-issue-forms.json
      SCHEMA_URL: https://json.schemastore.org/github-issue-forms.json
      SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="github-issue-forms-schema-XXXXXXXXXX.json"
      DATA_PATH: "issue-templates/forms/**/*.{yml,yaml}"
    deps:
      - task: npm:install-deps
    cmds:
      - wget --quiet --output-document="{{.SCHEMA_PATH}}" {{.SCHEMA_URL}}
      - |
        npx \
          --package=ajv-cli \
          --package=ajv-formats \
          ajv validate \
            --all-errors \
            -c ajv-formats \
            -s "{{.SCHEMA_PATH}}" \
            -d "{{.DATA_PATH}}"

  js:fix:
    desc: Fix JavaScript code linting violations
    deps:
      - task: npm:install-deps
    cmds:
      - npx eslint --ext .js,.jsx --fix .

  js:lint:
    desc: Lint JavaScript code
    deps:
      - task: npm:install-deps
    cmds:
      - npx eslint --ext .js,.jsx .

  labels:validate:
    desc: Validate GitHub repository label configuration files against their JSON schema
    vars:
      SCHEMA_PATH: workflow-templates/assets/sync-labels/arduino-tooling-gh-label-configuration-schema.json
      DATA_PATH: "workflow-templates/assets/sync-labels/*.{yml,yaml}"
    deps:
      - task: npm:install-deps
    cmds:
      - |
        npx \
          --package=ajv-cli \
          --package=ajv-formats \
          ajv validate \
            --all-errors \
            --strict=false \
            -c ajv-formats \
            -s "{{.SCHEMA_PATH}}" \
            -d "{{.DATA_PATH}}"

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
  markdown:check-links:
    desc: Check for broken links
    deps:
      - task: docs:generate
      - task: npm:install-deps
    cmds:
      - |
        if [[ "{{.OS}}" == "Windows_NT" ]]; then
          # npx --call uses the native shell, which makes it too difficult to use npx for this application on Windows,
          # so the Windows user is required to have markdown-link-check installed and in PATH.
          if ! which markdown-link-check &>/dev/null; then
            echo "markdown-link-check not found or not in PATH. Please install: https://github.com/tcort/markdown-link-check#readme"
            exit 1
          fi
          # Default behavior of the task on Windows is to exit the task when the first broken link causes a non-zero
          # exit status, but it's better to check all links before exiting.
          set +o errexit
          STATUS=0
          # Using -regex instead of -name to avoid Task's behavior of globbing even when quoted on Windows
          # The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
          # \ characters special treatment on Windows in an attempt to support them as path separators.
          for file in $(
            find . \
              -type d -name '.git' -prune -o \
              -type d -name '.licenses' -prune -o \
              -type d -name '__pycache__' -prune -o \
              -type d -name 'node_modules' -prune -o \
              -path './{{.CLANG_FORMAT_GOLDEN_TEST_DATA_FOLDER}}/samples' -prune -o \
              -path './{{.CLANG_FORMAT_INPUT_TEST_DATA_FOLDER}}/samples' -prune -o \
              -regex ".*[.]md" -print
          ); do
            markdown-link-check \
              --quiet \
              --config "./.markdown-link-check.json" \
              "$file"
            STATUS=$(( $STATUS + $? ))
          done
          exit $STATUS
        else
          npx --package=markdown-link-check --call='
            STATUS=0
            for file in $(
              find . \
                -type d -name '.git' -prune -o \
                -type d -name '.licenses' -prune -o \
                -type d -name '__pycache__' -prune -o \
                -type d -name 'node_modules' -prune -o \
                -path './{{.CLANG_FORMAT_GOLDEN_TEST_DATA_FOLDER}}/samples' -prune -o \
                -path './{{.CLANG_FORMAT_INPUT_TEST_DATA_FOLDER}}/samples' -prune -o \
                -regex ".*[.]md" -print
            ); do
              markdown-link-check \
                --quiet \
                --config "./.markdown-link-check.json" \
                "$file"
              STATUS=$(( $STATUS + $? ))
            done
            exit $STATUS
          '
        fi

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
  markdown:fix:
    desc: Automatically correct linting violations in Markdown files where possible
    deps:
      - task: npm:install-deps
    cmds:
      - npx markdownlint-cli --fix "**/*.md"

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-markdown-task/Taskfile.yml
  markdown:lint:
    desc: Check for problems in Markdown files
    deps:
      - task: npm:install-deps
    cmds:
      - npx markdownlint-cli "**/*.md"

  markdownlint:validate:
    desc: Validate markdownlint configuration files against their JSON schema
    vars:
      # Source: https://github.com/DavidAnson/markdownlint/blob/main/schema/markdownlint-config-schema.json
      SCHEMA_URL: https://raw.githubusercontent.com/DavidAnson/markdownlint/main/schema/markdownlint-config-schema.json
      SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="markdownlint-schema-XXXXXXXXXX.json"
      DATA_PATH: "**/.markdownlint.{yml,yaml}"
    deps:
      - task: npm:install-deps
    cmds:
      - wget --quiet --output-document="{{.SCHEMA_PATH}}" {{.SCHEMA_URL}}
      - |
        npx \
          --package=ajv-cli \
          --package=ajv-formats \
          ajv validate \
            --all-errors \
            --strict=false \
            --allow-union-types \
            -c ajv-formats \
            -s "{{.SCHEMA_PATH}}" \
            -d "{{.DATA_PATH}}"

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/npm-task/Taskfile.yml
  npm:install-deps:
    desc: Install dependencies managed by npm
    cmds:
      - npm install

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-npm-task/Taskfile.yml
  npm:validate:
    desc: Validate npm configuration files against their JSON schema
    vars:
      # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/package.json
      SCHEMA_URL: https://json.schemastore.org/package.json
      SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="package-json-schema-XXXXXXXXXX.json"
      # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/ava.json
      AVA_SCHEMA_URL: https://json.schemastore.org/ava.json
      AVA_SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="ava-schema-XXXXXXXXXX.json"
      # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/eslintrc.json
      ESLINTRC_SCHEMA_URL: https://json.schemastore.org/eslintrc.json
      ESLINTRC_SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="eslintrc-schema-XXXXXXXXXX.json"
      # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/jscpd.json
      JSCPD_SCHEMA_URL: https://json.schemastore.org/jscpd.json
      JSCPD_SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="jscpd-schema-XXXXXXXXXX.json"
      # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/prettierrc.json
      PRETTIERRC_SCHEMA_URL: https://json.schemastore.org/prettierrc.json
      PRETTIERRC_SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="prettierrc-schema-XXXXXXXXXX.json"
      # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/semantic-release.json
      SEMANTIC_RELEASE_SCHEMA_URL: https://json.schemastore.org/semantic-release.json
      SEMANTIC_RELEASE_SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="semantic-release-schema-XXXXXXXXXX.json"
      # Source: https://github.com/SchemaStore/schemastore/blob/master/src/schemas/json/stylelintrc.json
      STYLELINTRC_SCHEMA_URL: https://json.schemastore.org/stylelintrc.json
      STYLELINTRC_SCHEMA_PATH:
        sh: task utility:mktemp-file TEMPLATE="stylelintrc-schema-XXXXXXXXXX.json"
      INSTANCE_PATH: "**/package.json"
      PROJECT_FOLDER:
        sh: pwd
      WORKING_FOLDER:
        sh: task utility:mktemp-folder TEMPLATE="dependabot-validate-XXXXXXXXXX"
    cmds:
      - wget --quiet --output-document="{{.SCHEMA_PATH}}" {{.SCHEMA_URL}}
      - wget --quiet --output-document="{{.AVA_SCHEMA_PATH}}" {{.AVA_SCHEMA_URL}}
      - wget --quiet --output-document="{{.ESLINTRC_SCHEMA_PATH}}" {{.ESLINTRC_SCHEMA_URL}}
      - wget --quiet --output-document="{{.JSCPD_SCHEMA_PATH}}" {{.JSCPD_SCHEMA_URL}}
      - wget --quiet --output-document="{{.PRETTIERRC_SCHEMA_PATH}}" {{.PRETTIERRC_SCHEMA_URL}}
      - wget --quiet --output-document="{{.SEMANTIC_RELEASE_SCHEMA_PATH}}" {{.SEMANTIC_RELEASE_SCHEMA_URL}}
      - wget --quiet --output-document="{{.STYLELINTRC_SCHEMA_PATH}}" {{.STYLELINTRC_SCHEMA_URL}}
      - |
        cd "{{.WORKING_FOLDER}}"  # Workaround for https://github.com/npm/cli/issues/3210
        npx ajv-cli@{{.SCHEMA_DRAFT_4_AJV_CLI_VERSION}} validate \
          --all-errors \
          -s "{{.SCHEMA_PATH}}" \
          -r "{{.AVA_SCHEMA_PATH}}" \
          -r "{{.ESLINTRC_SCHEMA_PATH}}" \
          -r "{{.JSCPD_SCHEMA_PATH}}" \
          -r "{{.PRETTIERRC_SCHEMA_PATH}}" \
          -r "{{.SEMANTIC_RELEASE_SCHEMA_PATH}}" \
          -r "{{.STYLELINTRC_SCHEMA_PATH}}" \
          -d "{{.PROJECT_FOLDER}}/{{.INSTANCE_PATH}}"

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/poetry-task/Taskfile.yml
  poetry:install-deps:
    desc: Install dependencies managed by Poetry
    cmds:
      - poetry install --no-root

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/poetry-task/Taskfile.yml
  poetry:update-deps:
    desc: Update all dependencies managed by Poetry to their newest versions
    cmds:
      - poetry update

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-python-task/Taskfile.yml
  python:format:
    desc: Format Python files
    deps:
      - task: poetry:install-deps
    cmds:
      - poetry run black .

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-python-task/Taskfile.yml
  python:lint:
    desc: Lint Python code
    deps:
      - task: poetry:install-deps
    cmds:
      - poetry run flake8 --show-source

  python:test:
    desc: Run Python tests
    deps:
      - task: poetry:install-deps
    cmds:
      - poetry run pytest workflow-templates/assets/deploy-mkdocs-versioned/siteversion/tests

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml
  shell:check:
    desc: Check for problems with shell scripts
    cmds:
      - |
        if ! which shellcheck &>/dev/null; then
          echo "shellcheck not installed or not in PATH. Please install: https://github.com/koalaman/shellcheck#installing"
          exit 1
        fi
      - |
        # There is something odd about shellcheck that causes the task to always exit on the first fail, despite any
        # measures that would prevent this with any other command. So it's necessary to call shellcheck only once with
        # the list of script paths as an argument. This could lead to exceeding the maximum command length on Windows if
        # the repository contained a large number of scripts, but it's unlikely to happen in reality.
        shellcheck \
          --format={{default "tty" .SHELLCHECK_FORMAT}} \
          $(
            # The odd method for escaping . in the regex is required for windows compatibility because mvdan.cc/sh gives
            # \ characters special treatment on Windows in an attempt to support them as path separators.
            find . \
              -type d -name '.git' -prune -or \
              -type d -name '.licenses' -prune -or \
              -type d -name '__pycache__' -prune -or \
              -type d -name 'node_modules' -prune -or \
              \( \
                -regextype posix-extended \
                -regex '.*[.](bash|sh)' -and \
                -type f \
              \) \
              -print
          )

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml
  shell:check-mode:
    desc: Check for non-executable shell scripts
    cmds:
      - |
        EXIT_STATUS=0
        while read -r nonExecutableScriptPath; do
          # The while loop always runs once, even if no file was found
          if [[ "$nonExecutableScriptPath" == "" ]]; then
            continue
          fi

          echo "::error file=${nonExecutableScriptPath}::non-executable script file: $nonExecutableScriptPath";
          EXIT_STATUS=1
        done <<<"$(
          # The odd approach to escaping `.` in the regex is required for windows compatibility because mvdan.cc/sh
          # gives `\` characters special treatment on Windows in an attempt to support them as path separators.
          find . \
            -type d -name '.git' -prune -or \
            -type d -name '.licenses' -prune -or \
            -type d -name '__pycache__' -prune -or \
            -type d -name 'node_modules' -prune -or \
            \( \
              -regextype posix-extended \
              -regex '.*[.](bash|sh)' -and \
              -type f -and \
              -not -executable \
              -print \
            \)
        )"
        exit $EXIT_STATUS

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-shell-task/Taskfile.yml
  shell:format:
    desc: Format shell script files
    cmds:
      - |
        if ! which shfmt &>/dev/null; then
          echo "shfmt not installed or not in PATH. Please install: https://github.com/mvdan/sh#shfmt"
          exit 1
        fi
      - shfmt -w .

  # Make a temporary file named according to the passed TEMPLATE variable and print the path passed to stdout
  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
  utility:mktemp-file:
    vars:
      RAW_PATH:
        sh: mktemp --tmpdir "{{.TEMPLATE}}"
    cmds:
      - task: utility:normalize-path
        vars:
          RAW_PATH: "{{.RAW_PATH}}"

  # Make a temporary folder named according to the passed TEMPLATE variable and print the path passed to stdout
  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
  utility:mktemp-folder:
    vars:
      RAW_PATH:
        sh: mktemp --directory --tmpdir "{{.TEMPLATE}}"
    cmds:
      - task: utility:normalize-path
        vars:
          RAW_PATH: "{{.RAW_PATH}}"

  # Print a normalized version of the path passed via the RAW_PATH variable to stdout
  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/windows-task/Taskfile.yml
  utility:normalize-path:
    cmds:
      - |
        if [[ "{{.OS}}" == "Windows_NT" ]] && which cygpath &>/dev/null; then
            # Even though the shell handles POSIX format absolute paths as expected, external applications do not.
            # So paths passed to such applications must first be converted to Windows format.
            cygpath -w "{{.RAW_PATH}}"
        else
          echo "{{.RAW_PATH}}"
        fi

  # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/check-yaml-task/Taskfile.yml
  yaml:lint:
    desc: Check for problems with YAML files
    deps:
      - task: poetry:install-deps
    cmds:
      - poetry run yamllint --format {{default "colored" .YAMLLINT_FORMAT}} .