name: Create Stale Documentation Issues

on:
  workflow_call:
    inputs:
      threshold-days:
        description: 'Number of days before ms.date is considered stale'
        required: false
        type: number
        default: 90
      artifact-name:
        description: 'Name of the artifact containing freshness check results'
        required: false
        type: string
        default: msdate-freshness-results
      results-file:
        description: 'Path to JSON results file after artifact download'
        required: false
        type: string
        default: logs/msdate-freshness-results.json

permissions:
  contents: read
  issues: write

jobs:
  create-stale-docs-issues:
    name: Create or Update Issues for Stale Documentation
    runs-on: ubuntu-latest
    permissions:
      contents: read
      issues: write
    steps:
      - name: Checkout code
        uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7.0.0
        with:
          persist-credentials: false

      - name: Download freshness check results
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
        with:
          name: ${{ inputs.artifact-name }}
          path: logs

      - name: Create or Update Issues (One Per File)
        shell: pwsh
        env:
          GH_TOKEN: ${{ github.token }}
          RESULTS_FILE: ${{ inputs.results-file }}
          THRESHOLD_DAYS: ${{ inputs.threshold-days }}
          REPO: ${{ github.repository }}
          SERVER_URL: ${{ github.server_url }}
          RUN_ID: ${{ github.run_id }}
        run: |
          $results = Get-Content $env:RESULTS_FILE | ConvertFrom-Json
          $staleFiles = $results | Where-Object { $_.IsStale -eq $true }

          if (-not $staleFiles) {
            Write-Host "No stale files found, skipping issue creation"
            exit 0
          }

          foreach ($file in $staleFiles) {
            $filePath = $file.File
            $msDate = $file.MsDate
            $ageDays = $file.AgeDays

            $issueTitle = "docs: Update stale documentation - $filePath"
            $automationMarker = "<!-- automation:stale-docs:$filePath -->"

            $searchQuery = "repo:$env:REPO is:issue is:open in:body `"automation:stale-docs:$filePath`""
            $existingIssueJson = gh issue list `
              --repo $env:REPO `
              --search $searchQuery `
              --limit 1 `
              --json number `
              --jq '.[0].number // empty'

            $existingIssue = if ($existingIssueJson) { $existingIssueJson.Trim() } else { $null }

            $issueBody = @"
          ## Stale Documentation Detected

          **File:** ``$filePath``
          **Current ms.date:** ``$msDate``
          **Age:** $ageDays days (threshold: $env:THRESHOLD_DAYS days)

          ---
          **Workflow Run:** $env:SERVER_URL/$env:REPO/actions/runs/$env:RUN_ID
          **Detection Date:** $(Get-Date -Format 'yyyy-MM-dd' -AsUTC)

          ### Action Required
          - [ ] Review and update this documentation file
          - [ ] Update ``ms.date`` frontmatter to current date
          - [ ] Verify technical accuracy of content
          - [ ] Close this issue manually after fixes are merged

          $automationMarker
          "@

            if ($existingIssue) {
              Write-Host "Updating existing issue #$existingIssue for $filePath"
              gh issue edit $existingIssue `
                --repo $env:REPO `
                --body $issueBody

              $updateDate = Get-Date -Format 'yyyy-MM-dd' -AsUTC
              gh issue comment $existingIssue `
                --repo $env:REPO `
                --body "🔄 **Weekly validation update:** Still stale ($ageDays days) as of $updateDate"
            } else {
              Write-Host "Creating new issue for $filePath"
              gh issue create `
                --repo $env:REPO `
                --title $issueTitle `
                --body $issueBody `
                --label "documentation,stale-docs,automated,needs-triage"
            }
          }