validate-docs.yml

name: Validate documentation

on:
  pull_request:
    types: [opened, synchronize, reopened]
    branches: [main]
    paths:
      - '**.md'
      - '**.mdx'
      - 'docs.json'
      - '.mintlify/ia-map.yml'
      - '.mintignore'
      - 'images/**'
      - 'scripts/**'
      - 'test/**'
      - 'package.json'
      - 'package-lock.json'
      - 'tsconfig.json'
      - '.github/workflows/**'
  schedule:
    - cron: '17 8 * * 1'
  workflow_dispatch:

permissions:
  contents: read

concurrency:
  group: docs-validation-${{ github.event.pull_request.number || github.ref }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

jobs:
  validate:
    name: Validate documentation
    runs-on: ubuntu-24.04
    timeout-minutes: 10

    steps:
      - name: Set report directory
        run: echo "REPORT_DIR=$RUNNER_TEMP/docs-validation" >> "$GITHUB_ENV"

      - name: Checkout source
        uses: actions/checkout@v7
        with:
          fetch-depth: 0
          persist-credentials: false
          ref: ${{ github.event.pull_request.head.sha || github.sha }}

      - name: Set up Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '24'
          cache: npm

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

      - name: Install Mintlify CLI
        run: npm install --global mint@4.2.917 --ignore-scripts

      - name: Type-check and test utilities
        run: npm run check

      - name: List changed files
        if: github.event_name == 'pull_request'
        env:
          BASE_SHA: ${{ github.event.pull_request.base.sha }}
          HEAD_SHA: ${{ github.event.pull_request.head.sha }}
        run: git diff --name-only --diff-filter=ACMRD "$BASE_SHA" "$HEAD_SHA" > changed-files.txt

      - name: Run documentation validator
        id: validation
        env:
          EVENT_NAME: ${{ github.event_name }}
        run: |
          mkdir -p "$REPORT_DIR"
          arguments=(--output "$REPORT_DIR/docs-validation.json")
          if [[ "$EVENT_NAME" == 'pull_request' ]]; then
            arguments+=(--changed-files changed-files.txt)
          fi

          set +e
          node scripts/docs/validate.ts "${arguments[@]}"
          exit_code=$?
          set -e
          if [[ ! -f "$REPORT_DIR/docs-validation.json" ]]; then
            printf '%s\n' '{"schemaVersion":1,"status":"tool_failure","scope":"unknown","summary":{"errors":0,"autoFixable":0},"findings":[],"error":"Validator exited before writing its report."}' > "$REPORT_DIR/docs-validation.json"
            exit_code=2
          fi
          echo "exit_code=$exit_code" >> "$GITHUB_OUTPUT"

      - name: Audit internal links and anchors
        id: internal-links
        run: |
          mkdir -p "$REPORT_DIR"
          set +e
          node scripts/docs/audit-internal-links.ts --output "$REPORT_DIR/internal-links.json"
          exit_code=$?
          set -e
          if [[ ! -f "$REPORT_DIR/internal-links.json" ]]; then
            printf '%s\n' '{"schemaVersion":1,"status":"tool_failure","scope":"all","summary":{"errors":0,"autoFixable":0},"findings":[],"error":"Internal link audit exited before writing its report."}' > "$REPORT_DIR/internal-links.json"
            exit_code=2
          fi
          echo "exit_code=$exit_code" >> "$GITHUB_OUTPUT"

      - name: Check the component baseline
        id: components
        env:
          EVENT_NAME: ${{ github.event_name }}
        run: |
          mkdir -p "$REPORT_DIR"
          arguments=(--baseline --output "$REPORT_DIR/component-audit.json")
          if [[ "$EVENT_NAME" == 'pull_request' ]]; then
            arguments+=(--changed-files changed-files.txt)
          fi

          set +e
          node scripts/docs/audit-components.ts "${arguments[@]}"
          exit_code=$?
          set -e
          if [[ ! -f "$REPORT_DIR/component-audit.json" ]]; then
            printf '%s\n' '{"schemaVersion":1,"status":"tool_failure","scope":"all","summary":{"warnings":0,"byRule":{},"byArea":{}},"findings":[],"error":"Component audit exited before writing its report."}' > "$REPORT_DIR/component-audit.json"
            exit_code=2
          fi
          echo "exit_code=$exit_code" >> "$GITHUB_OUTPUT"

      - name: Upload component findings
        if: ${{ !cancelled() && steps.components.outcome == 'success' }}
        uses: actions/upload-artifact@v7
        with:
          name: component-audit
          path: ${{ env.REPORT_DIR }}/component-audit.json
          if-no-files-found: error
          retention-days: 14

      - name: Upload structured findings
        if: ${{ !cancelled() && steps.validation.outcome == 'success' }}
        uses: actions/upload-artifact@v7
        with:
          name: docs-validation
          path: |
            ${{ env.REPORT_DIR }}/docs-validation.json
            ${{ env.REPORT_DIR }}/internal-links.json
          if-no-files-found: error
          retention-days: 14

      - name: Write job summary
        if: always()
        run: |
          node - <<'NODE' >> "$GITHUB_STEP_SUMMARY"
          const fs = require('node:fs');
          const path = require('node:path');
          function readReport(name) {
            try {
              return JSON.parse(fs.readFileSync(path.join(process.env.REPORT_DIR, name), 'utf8'));
            } catch {
              return undefined;
            }
          }
          const report = readReport('docs-validation.json');
          console.log('## Documentation validation');
          console.log('');
          if (!report) {
            console.log('Validation report is unavailable. Inspect the preceding steps for setup or execution failures.');
          } else if (report.status === 'tool_failure') {
            console.log('Validator failure. Inspect the job log and structured artifact.');
          } else {
            console.log(`${report.summary.errors} blocking finding(s), ${report.summary.autoFixable} auto-fixable.`);
          }
          const internalLinks = readReport('internal-links.json');
          if (!internalLinks) {
            console.log('\nInternal link report is unavailable.');
          } else if (internalLinks.status === 'tool_failure') {
            console.log('\nInternal link audit failed. Inspect the job log and structured artifact.');
          } else {
            console.log(`\n${internalLinks.summary.errors} broken internal link or anchor finding(s).`);
          }
          const components = readReport('component-audit.json');
          if (!components) {
            console.log('\nComponent audit report is unavailable.');
          } else if (components.status === 'tool_failure') {
            console.log('\nComponent audit failed. Inspect the job log and structured artifact.');
          } else {
            const baseline = require('./scripts/docs/component-baseline.json');
            const grown = Object.entries(components.summary.byRule || {})
              .filter(([rule, count]) => count > (baseline.rules[rule] ?? 0));
            console.log('');
            console.log('## Component system');
            console.log('');
            console.log(`${components.summary.warnings} finding(s) against a baseline of ${Object.values(baseline.rules).reduce((a, b) => a + b, 0)}.`);
            for (const [rule, count] of grown) {
              console.log(`- \`${rule}\` rose to ${count} from ${baseline.rules[rule] ?? 0}`);
            }
          }
          NODE

      - name: Set validation result
        if: ${{ !cancelled() && steps.validation.outcome == 'success' }}
        env:
          EXIT_CODE: ${{ steps.validation.outputs.exit_code }}
          INTERNAL_LINK_EXIT_CODE: ${{ steps.internal-links.outputs.exit_code }}
          COMPONENT_EXIT_CODE: ${{ steps.components.outputs.exit_code }}
        run: |
          if [[ "${EXIT_CODE:-2}" != '0' ]]; then exit "${EXIT_CODE:-2}"; fi
          if [[ "${INTERNAL_LINK_EXIT_CODE:-2}" != '0' ]]; then exit "${INTERNAL_LINK_EXIT_CODE:-2}"; fi
          exit "${COMPONENT_EXIT_CODE:-2}"

  external-links:
    name: Audit external links
    if: github.event_name == 'schedule' || github.event_name == 'workflow_dispatch'
    runs-on: ubuntu-24.04
    timeout-minutes: 30

    steps:
      - name: Checkout source
        uses: actions/checkout@v7
        with:
          persist-credentials: false

      - name: Set up Node.js
        uses: actions/setup-node@v7
        with:
          node-version: '24'

      - name: Check external links
        id: external
        run: |
          set +e
          node scripts/docs/audit-external-links.ts --output external-links.json
          exit_code=$?
          set -e
          if [[ ! -f external-links.json ]]; then
            printf '%s\n' '{"schemaVersion":1,"status":"tool_failure","scope":"all","summary":{"warnings":0},"findings":[],"error":"External link checker exited before writing its report."}' > external-links.json
            exit_code=2
          fi
          echo "exit_code=$exit_code" >> "$GITHUB_OUTPUT"

      - name: Upload advisory findings
        if: always()
        uses: actions/upload-artifact@v7
        with:
          name: external-links
          path: external-links.json
          if-no-files-found: error
          retention-days: 14

      - name: Fail on checker errors
        if: always() && steps.external.outputs.exit_code == '2'
        run: exit 2