Stirling-PDF/.taskfiles/pre-commit.yml

version: '3'

# Repo-wide lint/format/secret checks - the single source of truth that the git
# pre-commit hook (.pre-commit-config.yaml) and CI (pre_commit.yml) both call.

vars:
  # File selections as git pathspecs: git does the include/exclude matching, so
  # there is no grep/xargs and it behaves identically on every platform.
  PY_FILES: >-
    'scripts/*.py'
    '.github/scripts/*.py'
    'app/core/src/main/resources/static/python/*.py'
    ':(exclude)*split_photos.py'
    ':(exclude)scripts/lint/fixtures/*'
  SPELL_FILES: >-
    '*.html'
    '*.css'
    '*.js'
    '*.py'
    '*.md'
    ':(exclude).vscode/*'
    ':(exclude).devcontainer/*'
    ':(exclude)app/core/src/main/resources/*'
    ':(exclude)app/proprietary/src/main/resources/*'
    ':(exclude)frontend/editor/public/vendor/*'
    ':(exclude)*Dockerfile*'
    ':(exclude)*pdfjs*'
    ':(exclude)*thirdParty*'
    ':(exclude)*bootstrap*'
    ':(exclude)*.min.*'
    ':(exclude)*diff.js'
  WS_FILES: >-
    '*.js'
    '*.java'
    '*.py'
    '*.yml'
    ':(exclude)*pdfjs*'
    ':(exclude)*thirdParty*'
    ':(exclude)*bootstrap*'
    ':(exclude)*.min.*'
    ':(exclude)*diff.js'
    ':(exclude).github/workflows/*'
  LOCALE_TOML: 'frontend/editor/public/locales/*/translation.toml'

  # gitleaks is pinned + checksum-verified by scripts/pre-commit/install_gitleaks.py,
  # which owns the version and caches the binary here.
  GITLEAKS_BIN: '.task/bin/gitleaks{{if eq OS "windows"}}.exe{{end}}'

env:
  # Keep repository-wide checks isolated from the engine runtime environment.
  UV_PROJECT_ENVIRONMENT: '.venv-pre-commit'

tasks:
  default:
    desc: "Check formatting, spelling, and secrets across the repo"
    cmds:
      - task: ruff
      - task: ruff-format
      - task: codespell
      - task: gitleaks
      - task: whitespace
      - task: toml-sort
      - task: comment-lint

  fix:
    desc: "Auto-fix formatting, spelling, and secrets issues across the repo"
    cmds:
      # Auto-fixers first, then the report-only tools (codespell, gitleaks) so a
      # finding there does not stop the fixers from running.
      - task: ruff
        vars: { FIX: '1' }
      - task: ruff-format
        vars: { FIX: '1' }
      - task: whitespace
        vars: { FIX: '1' }
      - task: toml-sort
        vars: { FIX: '1' }
      - task: codespell
      - task: gitleaks
      - task: comment-lint

  install:
    desc: "Install the pinned pre-commit Python tools"
    run: once
    cmds:
      - uv sync --project engine --locked --group pre-commit
    sources:
      - engine/uv.lock
      - engine/pyproject.toml
    status:
      - test -d engine/.venv-pre-commit

  clean:
    desc: "Remove the cached gitleaks binary and the pre-commit virtualenv"
    cmds:
      - cmd: rm -rf engine/.venv-pre-commit .task/bin/gitleaks
        platforms: [linux, darwin]
      - cmd: cmd /c "rmdir /s /q engine\.venv-pre-commit & del /q .task\bin\gitleaks.exe"
        platforms: [windows]
        ignore_error: true

  # Individual checks (hidden from `task --list`, but callable, e.g.
  # `task pre-commit:toml-sort FIX=1`). Pass FIX=1 to auto-fix where supported.
  ruff:
    deps: [install]
    cmds:
      - uv run --project engine --locked --group pre-commit ruff check --isolated --line-length=120 {{if .FIX}}--fix {{end}}$(git ls-files {{.PY_FILES}})

  ruff-format:
    deps: [install]
    cmds:
      - uv run --project engine --locked --group pre-commit ruff format --isolated --line-length=120 {{if .FIX}}{{else}}--check {{end}}$(git ls-files {{.PY_FILES}})

  codespell:
    deps: [install]
    cmds:
      - uv run --project engine --locked --group pre-commit codespell --ignore-words-list=thirdParty,tabEl,tabEls,Sie,ist,fulfilment --quiet-level=2 $(git ls-files {{.SPELL_FILES}})

  toml-sort:
    deps: [install]
    cmds:
      - uv run --project engine --locked --group pre-commit python scripts/pre-commit/sort_locale_toml.py {{if .FIX}}--fix {{end}}{{.LOCALE_TOML}}

  whitespace:
    cmds:
      - uv run --project engine --locked --group pre-commit python scripts/pre-commit/whitespace.py {{if .FIX}}--fix {{end}}{{.WS_FILES}}

  gitleaks:
    deps: [gitleaks-bin]
    # Scan staged changes only, matching the old hook: the git-mode fingerprints
    # in .gitleaksignore (file:rule:line) still apply, and with nothing staged
    # this is a no-op. Secrets are never auto-fixed, so FIX has no effect.
    cmds:
      - "{{.GITLEAKS_BIN}} git --pre-commit --redact --staged --verbose"

  comment-lint:
    desc: "Check comment quality on the lines this branch adds"
    summary: |
      Blocks a comment that restates the code below it, a section banner, or a
      block of commented-out code. Everything else it reports is advisory.

      Scoped to added lines, so touching an old file never surfaces the standing
      backlog. The standard is devGuide/CODE_COMMENTS.md.

      With no arguments it diffs the working tree against HEAD, which is what a
      pre-commit run wants: the lines you are about to commit. On a CI pull request
      it diffs against the target branch instead, via GITHUB_BASE_REF.

      To ask what a whole branch adds instead, use the branch variant, which
      needs no argument passing:
        task comment-lint:branch

      Full tree (report only):     task pre-commit:comment-lint:all
      Fixture corpus:             task pre-commit:comment-lint:selftest
    # Depends on the frontend install because the .ts/.tsx half of the rule set
    # runs as an oxlint plugin. Without it the TS engine warns and skips, which
    # would leave the frontend silently unchecked on CI.
    deps: [":frontend:install"]
    cmds:
      - node scripts/lint/comment-lint.mjs {{.CLI_ARGS}}

  comment-lint:branch:
    desc: "Check comment quality on everything this branch adds over its base"
    summary: |
      Like `task comment-lint`, but scoped to the whole branch rather than to
      uncommitted work, so it still reports after you commit.

      Exists as its own task because passing `-- --since origin/main` through Task
      is not portable: with the npm build of Task the launcher is a PowerShell
      script, and PowerShell strips the `--` before Task sees it, leaving Task to
      print its own usage.

      Override the base with BASE=<ref>.
    vars:
      BASE: '{{.BASE | default "origin/main"}}'
    deps: [":frontend:install"]
    cmds:
      - node scripts/lint/comment-lint.mjs --since {{.BASE}}

  comment-lint:ci:
    desc: "Comment gate as CI runs it: fixture corpus, then the diff"
    summary: |
      The corpus checks the rules themselves rather than the code under review, so
      it belongs on CI and not on every local commit. Run this before changing a
      rule, and let CI run it on every pull request.
    deps: [":frontend:install"]
    cmds:
      - node scripts/lint/comment-lint.mjs --selftest
      - node scripts/lint/comment-lint.mjs {{.CLI_ARGS}}

  comment-lint:hook:
    desc: "Comment gate for the editor hook: everything this turn changed"
    summary: |
      Same scope as `task comment-lint`, kept as its own name so the hook has a
      stable entry point and the taskfile shows every way the linter is invoked.

      Not in the frontend-install dependency chain on purpose: this runs at the end
      of every turn, so it stays as short as it can be. If oxlint is missing the TS
      half warns and skips.
    cmds:
      - node scripts/lint/comment-lint.mjs

  comment-lint:all:
    desc: "Report every comment finding in the tree (never fails)"
    deps: [":frontend:install"]
    cmds:
      - node scripts/lint/comment-lint.mjs --all

  comment-lint:selftest:
    desc: "Check both comment-lint engines against the fixture corpus"
    deps: [":frontend:install"]
    cmds:
      - node scripts/lint/comment-lint.mjs --selftest

  gitleaks-bin:
    internal: true
    desc: "Ensure the pinned, checksum-verified gitleaks binary is cached in .task/bin"
    cmds:
      - uv run --project engine --locked --group pre-commit python scripts/pre-commit/install_gitleaks.py