.pre-commit-config.yaml

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
# SPDX-License-Identifier: Apache-2.0

# NemoClaw — prek hook configuration
# prek: https://github.com/j178/prek — single binary, no Python required for the runner
# Installed as an npm devDependency (@j178/prek) — available after `npm install`.
# All git hooks (pre-commit, commit-msg, pre-push) are managed by prek via this file only.
# The "prepare" script in package.json runs `prek install` (writes `.git/hooks/*`).
# If you previously used Husky, run: git config --unset core.hooksPath
# then `npm install` again so Git uses the hooks prek installs.
#
# Usage:
#   npx prek install
#   npx prek run --all-files
#   npx prek run --all-files --stage manual  # full CLI/plugin coverage
#
# Routine PR validation for automatic commit, commit-message, and push checks:
#   npm run validate:pr
#
# Priority groups (prek runs same-priority hooks in parallel):
#   0  — General file fixers (whitespace, EOF, line endings)
#   4  — SPDX header insertion (--fix)
#   5  — Shell / JS / TS formatters (shfmt, Biome)
#   6  — Fixes that should follow formatters (ruff check --fix, Biome lint --write)
#  10  — Linters and read-only checks
#  20  — Project-level checks (vitest, coverage, ratchet)

exclude: ^(nemoclaw/dist/|nemoclaw/node_modules/|docs/_build/|\.venv/)

# Stage-less hooks run only while creating a commit. Hooks for later Git
# lifecycle stages declare their own `stages` explicitly below.
default_stages:
  - pre-commit

# Which git hook shims `prek install` writes (separate from each hook's `stages:`).
# https://prek.j178.dev/configuration/#default_install_hook_types
default_install_hook_types:
  - pre-commit
  - commit-msg
  - pre-push
  - post-merge
  - post-checkout

repos:
  # ── Priority 0: general file fixers ───────────────────────────────────────
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: trailing-whitespace
        exclude: ^skills/[^/]+/skill\.oms\.sig$
        stages: [pre-commit]
        priority: 0
      - id: end-of-file-fixer
        exclude: ^skills/[^/]+/skill\.oms\.sig$
        stages: [pre-commit]
        priority: 0
      - id: mixed-line-ending
        args: ["--fix=lf"]
        exclude: ^skills/[^/]+/skill\.oms\.sig$
        priority: 0

  # ── Priority 0: reject force-added ignored files ───────────────────────────
  # Catches `git add -f` of files that .gitignore would normally block.
  # Single source of truth stays in .gitignore — no duplicate list here.
  - repo: local
    hooks:
      - id: no-force-added-ignored
        name: Reject force-added ignored files
        entry: bash -c 'IGNORED=$(git ls-files --ignored --exclude-standard --cached -- "$@") && if [ -n "$IGNORED" ]; then echo "Force-added files that .gitignore would block:" && echo "$IGNORED" && exit 1; fi' --
        language: system
        always_run: true
        pass_filenames: false
        priority: 0

  # ── Priority 4: SPDX headers (insert if missing; runs before language formatters) ──
  - repo: local
    hooks:
      - id: spdx-headers
        name: SPDX license headers (insert if missing)
        entry: bash scripts/check-spdx-headers.sh --fix
        language: system
        files: ^(nemoclaw/src/.*\.ts|scripts/.*\.ts|nemoclaw-blueprint/.*\.py|.*\.sh)$
        exclude: ^nemoclaw-blueprint/.*__init__\.py$
        pass_filenames: true
        priority: 4

  # ── Priority 3: sync generated docs before read-only validation ───────────
  - repo: local
    hooks:
      - id: platform-matrix-sync
        name: Sync platform matrix to docs
        entry: bash -c 'python3 scripts/generate-platform-docs.py && git add docs/get-started/prerequisites.mdx docs/inference/choose-inference-provider.mdx docs/reference/platform-support.mdx'
        language: system
        files: ^(ci/platform-matrix\.json|docs/get-started/prerequisites\.mdx|docs/inference/choose-inference-provider\.mdx|docs/reference/platform-support\.mdx|scripts/generate-platform-docs\.py)$
        pass_filenames: false
        priority: 3

  # ── Priority 5: formatters ────────────────────────────────────────────────
  - repo: https://github.com/scop/pre-commit-shfmt
    rev: v3.12.0-2
    hooks:
      - id: shfmt
        args:
          - -w
          - -i
          - "2"
          - -ci
          - -bn
        stages: [pre-commit]
        priority: 5

  - repo: local
    hooks:
      - id: biome-format
        name: Biome format
        entry: npx biome format --write --no-errors-on-unmatched
        language: system
        files: ^(biome\.json|package(-lock)?\.json|nemoclaw/package(-lock)?\.json|commitlint\.config\.js|bin/.*\.js|scripts/.*\.js|test/.*\.js|.*\.ts)$
        pass_filenames: true
        priority: 5

  # ── Priority 6: auto-fix after formatting ─────────────────────────────────
  - repo: local
    hooks:
      - id: biome-lint-fix
        name: Biome lint fixes
        entry: npx biome lint --write
        language: system
        files: ^(commitlint\.config\.js|bin/.*\.js|scripts/.*\.js|test/.*\.js|.*\.ts)$
        pass_filenames: true
        priority: 6

  # ── Priority 10: linters and validation ─────────────────────────────────────
  - repo: https://github.com/pre-commit/pre-commit-hooks
    rev: v6.0.0
    hooks:
      - id: check-merge-conflict
        priority: 10
      - id: check-added-large-files
        args: ["--maxkb=2000"]
        stages: [pre-commit]
        priority: 10
      - id: check-case-conflict
        priority: 10
      - id: check-yaml
        # Helm templates use Go templating ({{ ... }}) that isn't valid standalone YAML.
        exclude: ^deploy/helm/.*/templates/
        priority: 10
      - id: check-toml
        priority: 10
      - id: check-json
        priority: 10
      - id: detect-private-key
        priority: 10
      - id: check-executables-have-shebangs
        stages: [pre-commit]
        priority: 10
      - id: check-shebang-scripts-are-executable
        stages: [pre-commit]
        priority: 10

  - repo: local
    hooks:
      - id: validate-config-schemas
        name: Validate config files against JSON schemas
        entry: npx tsx scripts/validate-configs.mts
        language: system
        pass_filenames: false
        files: ^(nemoclaw-blueprint/.*\.yaml$|nemoclaw/openclaw\.plugin\.json$|schemas/.*\.json$)
        priority: 10

      - id: validate-managed-inference-catalog
        name: Validate managed inference catalog
        entry: npm run catalog:check
        language: system
        pass_filenames: false
        files: ^(managed-inference/(?:presets|recipes)/.*\.yaml$|managed-inference/schemas/.*\.json$|src/lib/inference/serving/(?:adapter-registry|catalog|generate-catalog|types)\.ts$)
        priority: 10

      - id: repository-checks
        name: Repository checks
        entry: npm run checks:repository
        language: system
        files: ^(\.pre-commit-config\.yaml$|\.github/workflows/e2e\.yaml$|Dockerfile(?:\.base)?$|agents/openclaw/manifest\.yaml$|agents/hermes/(?:Dockerfile(?:\.base)?|manifest\.yaml|mcp-config-transaction\.py)$|docs/resources/starter-prompt\.md$|nemoclaw-blueprint/blueprint\.yaml$|nemoclaw/package\.json$|package\.json$|scripts/(?:brev-launchable-ci-cpu|check-installer-hash|install-openshell|update-hermes-agent)\.sh$|src/lib/actions/sandbox/openshell-child-visible-credentials\.v[0-9]+\.[0-9]+\.[0-9]+\.json$|bin/.*\.(cjs|js|mjs)$|src/.*\.(cts|mts|ts|tsx)$|scripts/.*\.(cjs|cts|js|mjs|mts|ts|tsx)$|test/.*\.(cjs|cts|js|mjs|mts|ts|tsx)$|nemoclaw/src/.*\.(cts|mts|ts|tsx)$)
        pass_filenames: false
        priority: 10

      - id: env-var-docs
        name: NEMOCLAW_* env-var documentation gate
        entry: npx tsx scripts/check-env-var-docs.mts
        language: system
        # Triggers the audit when src/, bin/, the docs file, the allowlist,
        # or the gate script itself changes. The script always rescans the
        # whole repo so pass_filenames is false. See #3184.
        files: ^(src/.*\.(ts|tsx|js)|bin/.*\.(ts|js)|docs/reference/commands\.mdx|ci/env-var-doc-allowlist\.json|scripts/check-env-var-docs\.mts)$
        pass_filenames: false
        priority: 10

  - repo: https://github.com/shellcheck-py/shellcheck-py
    rev: v0.11.0.1
    hooks:
      - id: shellcheck
        priority: 10

  - repo: local
    hooks:
      - id: hadolint
        name: hadolint
        entry: hadolint
        language: system
        files: (Dockerfile[^/]*|.*\.dockerfile)$
        types: [file]
        priority: 10

  - repo: https://github.com/gitleaks/gitleaks
    rev: v8.30.1
    hooks:
      - id: gitleaks
        name: gitleaks (secret scan)
        priority: 10

  - repo: https://github.com/DavidAnson/markdownlint-cli2
    rev: v0.22.0
    hooks:
      - id: markdownlint-cli2
        priority: 10

  # ── commit-msg hooks ────────────────────────────────────────────────────────
  - repo: https://github.com/alessandrojcm/commitlint-pre-commit-hook
    rev: v9.24.0
    hooks:
      - id: commitlint
        stages: [commit-msg]
        additional_dependencies: ["@commitlint/config-conventional@20"]
        priority: 10

  # ── pre-push hooks ─────────────────────────────────────────────────────────
  - repo: local
    hooks:
      - id: tsc-plugin
        name: TypeScript (plugin)
        entry: npm --prefix nemoclaw run typecheck
        language: system
        pass_filenames: false
        files: ^nemoclaw/
        stages: [pre-push]
        priority: 10

      - id: tsc-js
        name: TypeScript (JS config)
        entry: bash -c 'npm run build:cli && npx tsc -p jsconfig.json'
        language: system
        pass_filenames: false
        files: ^(bin|test|scripts)/.*\.js$|^(jsconfig\.json|package(-lock)?\.json)$
        stages: [pre-push]
        priority: 10

      - id: tsc-cli
        name: TypeScript (CLI)
        entry: npm run typecheck:cli -- --incremental
        language: system
        pass_filenames: false
        files: ^(agents/hermes|bin|scripts|src|test|tools|nemoclaw-blueprint/scripts)/.*\.(ts|tsx|mts|cts|json)$|^\.agents/skills/nemoclaw-maintainer-day/scripts/(check-gates|shared)\.ts$|^nemoclaw/src/(lib/subprocess-env|blueprint/private-networks)\.ts$|^(package(-lock)?\.json|tsconfig\.cli\.json|vitest\.config\.ts)$
        stages: [pre-push]
        priority: 10

      - id: version-tag-sync
        name: package.json ↔ git tag version sync
        entry: bash scripts/check-version-tag-sync.sh
        language: system
        always_run: true
        pass_filenames: false
        stages: [pre-push]
        priority: 10

  # ── post-merge / post-checkout: warn about stale compiled dist/ ───────────
  # See #1958 — dist/ is gitignored, so git pull / checkout can leave stale
  # compiled output. This hook warns the developer immediately after the git
  # operation so they rebuild before hitting cryptic runtime errors.
  # The hook always exits 0 — it never blocks a git operation.
  - repo: local
    hooks:
      - id: stale-dist-check
        name: Warn if dist/ is older than src/
        entry: node --experimental-strip-types scripts/check-stale-dist.mts
        language: system
        always_run: true
        pass_filenames: false
        stages: [post-merge, post-checkout]
        priority: 10

  # ── Priority 20: project-level checks (full coverage is manual) ────────────
  - repo: local
    hooks:
      - id: e2e-semantic-phase-plans
        name: E2E semantic phase plans
        entry: npm run test:e2e-phases:check
        language: system
        pass_filenames: false
        files: ^(\.github/workflows/e2e\.yaml|test/vllm-docker-storage\.test\.ts|test/e2e/live/.*\.ts|test/e2e/fixtures/.*\.ts|test/e2e/risk-signal-reporter\.ts|test/e2e/support/(e2e-semantic-phase-check|workflow-e2e-progress)\.test\.ts|tools/e2e/(check-semantic-phases|credential-free-tests|workflow-boundary|workflow-plan)\.mts|vitest\.config\.ts|package\.json)$
        priority: 20

      - id: test-cli
        name: Test (CLI)
        entry: npm run test:coverage:cli
        language: system
        pass_filenames: false
        files: ^(bin/|src/.*\.(ts|tsx|js|mjs|cjs)$|test/.*\.(ts|tsx|js|mjs|cjs)$)
        require_serial: true
        stages: [manual]
        priority: 20

      - id: test-plugin
        name: Test (plugin)
        entry: npm run test:coverage:plugin
        language: system
        pass_filenames: false
        files: ^nemoclaw/
        stages: [manual]
        priority: 20

      - id: source-shape-test-budget
        name: Source-shape test budget
        entry: npm run source-shape:check
        language: system
        pass_filenames: false
        files: ^(.+\.(test|spec)\.(js|ts|mjs|mts|cjs|cts)|scripts/find-source-shape-tests\.mts|ci/source-shape-test-budget\.json)$
        priority: 20

      - id: test-file-size-budget
        name: Test file size budget
        entry: npm run test-size:check
        language: system
        pass_filenames: false
        files: ^(test/|src/.*\.(test|spec)\.(ts|js|mts|mjs|cts|cjs)$|nemoclaw/src/.*\.(test|spec)\.(ts|js|mts|mjs|cts|cjs)$|scripts/check-test-file-size-budget\.mts$|ci/test-file-size-budget\.json$)
        priority: 20

      - id: test-skills-yaml
        name: Test (skills YAML)
        entry: npx vitest run test/skills-frontmatter.test.ts
        language: system
        pass_filenames: false
        files: ^(\.agents/skills/|skills/|test/skills-frontmatter\.test\.ts$)
        priority: 20

default_language_version:
  python: python3

fail_fast: false