# WHAT THIS WORKFLOW SHOULD DO (Intent-Driven Architecture)
#
# PURPOSE:
# This workflow should ensure Table of Contents in markdown files stays synchronized
# with actual content WITHOUT automatically modifying the repository. It should fail
# CI if TOC is out of date, forcing developers to update it locally.
#
# RESPONSIBILITIES:
# 1. Validate TOC is current in all markdown documentation
# 2. Fail CI check if TOC is outdated
# 3. Provide clear instructions on how to fix TOC issues
# 4. Only run when markdown files are modified (path filtering)
# 5. Never commit changes automatically to avoid merge conflicts
#
# CONSTRAINTS:
# - Must use CHECK_ONLY mode (never auto-commit)
# - Must only trigger on pull requests, not pushes to master
# - Must filter for markdown file changes only
# - Must complete quickly (<5 minutes typical)
# - Must provide actionable error messages when failing
#
# ERROR HANDLING:
# - TOC outdated → Fail check with instructions on how to regenerate
# - Tool error → Fail with diagnostic information
# - Network issue → Retry once, then fail
#
# CORE TEAM BEST PRACTICE:
# CI validates, it never modifies. Developers own their commits completely.
#
# REFACTORING PRIORITIES:
# - [P1] Add comment to PR when TOC validation fails with fix command
# - [P2] Cache dependencies for faster runs

name: TOC Validation

on:
  pull_request:
    paths:
      - 'README.md'
      - 'docs/**/*.md'

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

jobs:
  validate-toc:
    name: Validate Table of Contents
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
      - name: Checkout
        uses: actions/checkout@v4
        with:
          fetch-depth: 0

      - name: Validate TOC is up to date
        uses: technote-space/toc-generator@v4
        with:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
          TARGET_PATHS: 'README.md,docs/**/*.md'
          CHECK_ONLY: 'true'
