feat: Add automated workflow documentation generation and standardization

scripts/cicd/generate-workflow-docs.ts

@@ -0,0 +1,389 @@
+#!/usr/bin/env tsx
+/**
+ * Generate workflow documentation from GitHub Actions workflow files
+ *
+ * This script:
+ * 1. Scans all workflow YAML files in .github/workflows
+ * 2. Extracts metadata (name, description, triggers, labels)
+ * 3. Updates the workflows README.md with current information
+ */
+import { readFileSync, readdirSync, writeFileSync } from 'fs'
+import { join } from 'path'
+import { parse } from 'yaml'
+
+interface WorkflowMetadata {
+  filename: string
+  name: string
+  description?: string
+  prefix: string
+  triggers: string[]
+  labelTriggers: string[]
+}
+
+interface WorkflowsByPrefix {
+  [prefix: string]: {
+    description: string
+    workflows: WorkflowMetadata[]
+  }
+}
+
+const WORKFLOWS_DIR = join(process.cwd(), '.github/workflows')
+const README_PATH = join(WORKFLOWS_DIR, 'README.md')
+
+// Category descriptions for workflow prefixes
+const PREFIX_DESCRIPTIONS: Record<string, string> = {
+  'ci-': 'Testing, linting, validation',
+  'release-': 'Version management, publishing',
+  'pr-': 'PR automation (triggered by labels)',
+  'api-': 'External API type generation',
+  'i18n-': 'Internationalization updates',
+  'publish-': 'Publishing and deployment',
+  'version-': 'Version management'
+}
+
+/**
+ * Extract label triggers from workflow content
+ */
+function extractLabelTriggers(content: string, workflowData: any): string[] {
+  const labels: string[] = []
+
+  // Check for label_trigger in anthropics/claude-code-action
+  const labelTriggerMatch = content.match(/label_trigger:\s*["']([^"']+)["']/i)
+  if (labelTriggerMatch) {
+    labels.push(labelTriggerMatch[1])
+  }
+
+  // Check for github.event.label.name == 'label-name' pattern
+  const labelNameMatches = content.matchAll(
+    /github\.event\.label\.name\s*==\s*['"]([^'"]+)['"]/gi
+  )
+  for (const match of labelNameMatches) {
+    if (!labels.includes(match[1])) {
+      labels.push(match[1])
+    }
+  }
+
+  // Check for startsWith or contains patterns with label names
+  const labelCommentMatches = content.matchAll(
+    /startsWith\(github\.event\.comment\.body,\s*['"]([^'"]+)['"]\)/gi
+  )
+  for (const match of labelCommentMatches) {
+    const command = match[1]
+    if (command && !labels.includes(command)) {
+      labels.push(command)
+    }
+  }
+
+  return labels
+}
+
+/**
+ * Extract trigger information from workflow
+ */
+function extractTriggers(workflowData: any): string[] {
+  const triggers: string[] = []
+  const on = workflowData.on
+
+  if (!on) return triggers
+
+  if (typeof on === 'string') {
+    triggers.push(on)
+  } else if (Array.isArray(on)) {
+    triggers.push(...on)
+  } else if (typeof on === 'object') {
+    // Handle workflow_dispatch
+    if (on.workflow_dispatch !== undefined) {
+      triggers.push('workflow_dispatch (manual)')
+    }
+
+    // Handle pull_request with types
+    if (on.pull_request) {
+      if (typeof on.pull_request === 'object' && on.pull_request.types) {
+        const types = Array.isArray(on.pull_request.types)
+          ? on.pull_request.types.join(', ')
+          : on.pull_request.types
+        triggers.push(`pull_request (${types})`)
+      } else {
+        triggers.push('pull_request')
+      }
+    }
+
+    // Handle pull_request_target
+    if (on.pull_request_target) {
+      if (
+        typeof on.pull_request_target === 'object' &&
+        on.pull_request_target.types
+      ) {
+        const types = Array.isArray(on.pull_request_target.types)
+          ? on.pull_request_target.types.join(', ')
+          : on.pull_request_target.types
+        triggers.push(`pull_request_target (${types})`)
+      } else {
+        triggers.push('pull_request_target')
+      }
+    }
+
+    // Handle push
+    if (on.push) {
+      triggers.push('push')
+    }
+
+    // Handle schedule
+    if (on.schedule) {
+      triggers.push('schedule')
+    }
+
+    // Handle issue_comment
+    if (on.issue_comment) {
+      if (typeof on.issue_comment === 'object' && on.issue_comment.types) {
+        const types = Array.isArray(on.issue_comment.types)
+          ? on.issue_comment.types.join(', ')
+          : on.issue_comment.types
+        triggers.push(`issue_comment (${types})`)
+      } else {
+        triggers.push('issue_comment')
+      }
+    }
+  }
+
+  return triggers
+}
+
+/**
+ * Parse a single workflow file and extract metadata
+ */
+function parseWorkflowFile(filename: string): WorkflowMetadata | null {
+  try {
+    const filepath = join(WORKFLOWS_DIR, filename)
+    const content = readFileSync(filepath, 'utf-8')
+    const workflowData = parse(content)
+
+    if (!workflowData || !workflowData.name) {
+      console.warn(`Skipping ${filename}: no name field`)
+      return null
+    }
+
+    // Determine prefix from filename
+    const prefixMatch = filename.match(/^([a-z0-9]+)-/)
+    const prefix = prefixMatch ? prefixMatch[1] + '-' : 'other-'
+
+    const metadata: WorkflowMetadata = {
+      filename,
+      name: workflowData.name,
+      description: workflowData.description,
+      prefix,
+      triggers: extractTriggers(workflowData),
+      labelTriggers: extractLabelTriggers(content, workflowData)
+    }
+
+    return metadata
+  } catch (error) {
+    console.error(`Error parsing ${filename}:`, error)
+    return null
+  }
+}
+
+/**
+ * Group workflows by prefix
+ */
+function groupWorkflowsByPrefix(
+  workflows: WorkflowMetadata[]
+): WorkflowsByPrefix {
+  const grouped: WorkflowsByPrefix = {}
+
+  for (const workflow of workflows) {
+    if (!grouped[workflow.prefix]) {
+      grouped[workflow.prefix] = {
+        description: PREFIX_DESCRIPTIONS[workflow.prefix] || 'Other workflows',
+        workflows: []
+      }
+    }
+    grouped[workflow.prefix].workflows.push(workflow)
+  }
+
+  // Sort workflows within each group by filename
+  for (const prefix in grouped) {
+    grouped[prefix].workflows.sort((a, b) =>
+      a.filename.localeCompare(b.filename)
+    )
+  }
+
+  return grouped
+}
+
+/**
+ * Generate markdown table for workflow categories
+ */
+function generateCategoryTable(grouped: WorkflowsByPrefix): string {
+  const prefixOrder = [
+    'ci-',
+    'pr-',
+    'release-',
+    'api-',
+    'i18n-',
+    'publish-',
+    'version-',
+    'other-'
+  ]
+
+  let table =
+    '| Prefix     | Purpose                             | Example                              |\n'
+  table +=
+    '| ---------- | ----------------------------------- | ------------------------------------ |\n'
+
+  for (const prefix of prefixOrder) {
+    if (grouped[prefix]) {
+      const example = grouped[prefix].workflows[0]?.filename || ''
+      const purpose = grouped[prefix].description
+      table += `| \`${prefix}\` | ${purpose} | \`${example}\` |\n`
+    }
+  }
+
+  return table
+}
+
+/**
+ * Generate detailed workflow list with descriptions
+ */
+function generateWorkflowList(grouped: WorkflowsByPrefix): string {
+  const prefixOrder = [
+    'ci-',
+    'pr-',
+    'release-',
+    'api-',
+    'i18n-',
+    'publish-',
+    'version-',
+    'other-'
+  ]
+  let markdown = ''
+
+  for (const prefix of prefixOrder) {
+    if (!grouped[prefix]) continue
+
+    const category = grouped[prefix]
+    const prefixName =
+      prefix === 'other-'
+        ? 'Other Workflows'
+        : prefix.replace('-', '').toUpperCase()
+
+    markdown += `\n### ${prefixName}\n\n`
+
+    for (const workflow of category.workflows) {
+      markdown += `#### [\`${workflow.filename}\`](./${workflow.filename})\n\n`
+      markdown += `**Name:** ${workflow.name}\n\n`
+
+      if (workflow.description) {
+        markdown += `**Description:** ${workflow.description}\n\n`
+      }
+
+      if (workflow.triggers.length > 0) {
+        markdown += `**Triggers:** ${workflow.triggers.join(', ')}\n\n`
+      }
+
+      if (workflow.labelTriggers.length > 0) {
+        markdown += `**Label Triggers:** \`${workflow.labelTriggers.join('`, `')}\`\n\n`
+      }
+    }
+  }
+
+  return markdown
+}
+
+/**
+ * Generate the complete README content
+ */
+function generateReadme(grouped: WorkflowsByPrefix): string {
+  const categoryTable = generateCategoryTable(grouped)
+  const workflowList = generateWorkflowList(grouped)
+
+  return `# GitHub Workflows
+
+This directory contains GitHub Actions workflow files that automate various aspects of the ComfyUI frontend development and release process.
+
+> **Note:** This documentation is auto-generated from workflow files. Do not edit manually.
+> Run \`pnpm workflow:docs\` to regenerate.
+
+## Naming Convention
+
+Workflow files follow a consistent naming pattern: \`<prefix>-<descriptive-name>.yaml\`
+
+### Category Prefixes
+
+${categoryTable}
+
+## Quick Reference
+
+For label-triggered workflows, add the corresponding label to a PR to trigger the workflow:
+- \`claude-review\` - Trigger AI-powered code review
+- \`New Browser Test Expectations\` - Update Playwright test snapshots
+
+For manual workflows, use the "Run workflow" button in the Actions tab.
+
+## Workflow Details
+
+${workflowList}
+
+## Documentation
+
+For more information about GitHub Actions, see:
+- [Events that trigger workflows](https://docs.github.com/en/actions/writing-workflows/choosing-when-your-workflow-runs/events-that-trigger-workflows)
+- [Workflow syntax](https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions)
+
+## Maintaining Workflows
+
+### Adding a New Workflow
+
+1. Create a new workflow file following the naming convention
+2. Include \`name\` and \`description\` fields at the top of the workflow
+3. Run \`pnpm workflow:docs\` to update this README
+4. Commit both the workflow file and updated README
+
+### Best Practices
+
+1. **Always include a description**: Add a \`description\` field after the \`name\` field
+2. **Use consistent prefixes**: Follow the established prefix conventions
+3. **Label-triggered workflows**: For PR automation, use the \`pr-\` prefix
+4. **Document triggers**: Make trigger conditions clear in the workflow description
+5. **Keep docs in sync**: Run \`pnpm workflow:docs\` after any workflow changes
+`
+}
+
+/**
+ * Main function
+ */
+function main() {
+  // Read all workflow files
+  const files = readdirSync(WORKFLOWS_DIR).filter(
+    (f) => f.endsWith('.yaml') || f.endsWith('.yml')
+  )
+  const workflowFiles = files.filter((f) => f !== 'README.md')
+
+  // Parse each workflow
+  const workflows: WorkflowMetadata[] = []
+  for (const filename of workflowFiles) {
+    const metadata = parseWorkflowFile(filename)
+    if (metadata) {
+      workflows.push(metadata)
+    }
+  }
+
+  // Group workflows by prefix
+  const grouped = groupWorkflowsByPrefix(workflows)
+
+  // Generate README
+  const readme = generateReadme(grouped)
+  writeFileSync(README_PATH, readme, 'utf-8')
+
+  // Show label-triggered workflows for validation
+  const labelWorkflows = workflows.filter((w) => w.labelTriggers.length > 0)
+  if (labelWorkflows.length > 0 && process.env.VERBOSE) {
+    for (const workflow of labelWorkflows) {
+      console.warn(
+        `Label-triggered: ${workflow.name}: ${workflow.labelTriggers.join(', ')}`
+      )
+    }
+  }
+}
+
+main()