coder · EdwardAngert · Apr 7, 2025 · Apr 7, 2025 · Apr 7, 2025 · Apr 7, 2025
diff --git a/.github/actions/docs-analysis/INTEGRATION.md b/.github/actions/docs-analysis/INTEGRATION.md
@@ -0,0 +1,140 @@
+# Integrating with docs-preview-link Workflow
+
+This guide shows how to integrate the `docs-analysis` composite action with the existing `docs-preview-link.yml` workflow, eliminating duplication and consolidating documentation processing.
+
+## Current State
+
+The docs-preview-link.yml workflow currently embeds document analysis functionality directly in the workflow steps, which leads to:
+- Code duplication across workflows
+- Harder maintenance when metrics need to be updated
+- Inconsistent reporting between workflows
+
+## Integration Strategy
+
+We can refactor the `docs-preview-link.yml` workflow to use our new composite action, bringing these benefits:
+- Single source of truth for document analysis
+- Consistent metrics across all documentation workflows
+- Easier maintenance and feature additions
+- Improved security and error handling
+
+## Example Integration
+
+Here's how to replace the verify-docs-changes job in the docs-preview-link.yml workflow with our composite action:
+
+```yaml
+verify-docs-changes:
+  needs: [validate-workflow, delay-start]
+  runs-on: ubuntu-latest
+  timeout-minutes: 3 # Reduced timeout for verification step
+  if: |
+    always() && 
+    (needs.validate-workflow.result == 'success' || needs.validate-workflow.result == 'skipped')
+  permissions:
+    contents: read
+    pull-requests: read
+    checks: write # For creating check runs
+    statuses: write # For creating commit statuses
+  if: |
+    always() && (
+      (github.event_name == 'pull_request_target' && 
+       (github.event.pull_request.draft == false || contains(github.event.pull_request.labels.*.name, 'run-checks-on-draft'))) ||
+      (github.event_name == 'workflow_dispatch') ||
+      (github.event_name == 'issue_comment' && github.event.issue.pull_request && 
+       (contains(github.event.comment.body, '/docs-preview') || contains(github.event.comment.body, '/docs-help')))
+    )
+  outputs:
+    docs_changed: ${{ steps.docs-analysis.outputs.docs-changed }}
+    pr_number: ${{ steps.pr_info.outputs.pr_number }}
+    branch_name: ${{ steps.pr_info.outputs.branch_name }}
+    repo_owner: ${{ steps.pr_info.outputs.repo_owner }}
+    is_fork: ${{ steps.pr_info.outputs.is_fork }}
+    is_comment: ${{ steps.pr_info.outputs.is_comment }}
+    is_manual: ${{ steps.pr_info.outputs.is_manual }}
+    skip: ${{ steps.pr_info.outputs.skip }}
+    execution_start_time: ${{ steps.timing.outputs.start_time }}
+    has_non_docs_changes: ${{ steps.docs-analysis.outputs.has-non-docs-changes }}
+    words_added: ${{ steps.docs-analysis.outputs.words-added }}
+    words_removed: ${{ steps.docs-analysis.outputs.words-removed }}
+    docs_files_count: ${{ steps.docs-analysis.outputs.docs-files-count }}
+    images_added: ${{ steps.docs-analysis.outputs.images-added }}
+    manifest_changed: ${{ steps.docs-analysis.outputs.manifest-changed }}
+    format_only: ${{ steps.docs-analysis.outputs.format-only }}
+  steps:
+    # Start timing the execution for performance tracking
+    - name: Capture start time
+      id: timing
+      run: |
+        echo "start_time=$(date +%s)" >> $GITHUB_OUTPUT
+        echo "::notice::Starting docs preview workflow at $(date)"
+
+    # Apply security hardening to the runner
+    - name: Harden Runner
+      uses: step-security/harden-runner@latest
+      with:
+        egress-policy: audit
+
+    - name: Create verification check run
+      id: create_check
+      uses: actions/github-script@latest
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        script: |
+          // [existing script code...]
+
+    - name: Get PR info
+      id: pr_info
+      run: |
+        # [existing script code to get PR number, branch, etc.]
+
+    # Only check out the DEFAULT branch (not the PR code) to verify changes safely
+    - name: Check out base repository code
+      if: steps.pr_info.outputs.skip != 'true'
+      uses: actions/checkout@latest
+      with:
+        ref: main  # Always use the main branch
+        fetch-depth: 5  # Reduce checkout depth for faster runs
+        sparse-checkout: |
+          ${{ env.DOCS_PRIMARY_PATH }}
+          *.md
+          README.md
+        sparse-checkout-cone-mode: false
+
+    # NEW: Use our composite action instead of duplicate logic
+    - name: Analyze documentation changes
+      id: doc
8000
s-analysis
+      if: steps.pr_info.outputs.skip != 'true'
+      uses: ./.github/actions/docs-analysis
+      with:
+        docs-path: ${{ env.DOCS_PRIMARY_PATH }}
+        pr-ref: ${{ steps.pr_info.outputs.branch_name }}
+        base-ref: 'main'
+        significant-words-threshold: ${{ env.SIGNIFICANT_WORDS_THRESHOLD }}
+        throttle-large-repos: 'true'
+        debug-mode: ${{ github.event_name == 'workflow_dispatch' && github.event.inputs.debug == 'true' || 'false' }}
+
+    # Remaining steps can use the outputs from docs-analysis
+    - name: Update verification status
+      if: github.event_name == 'pull_request_target' || (github.event_name == 'workflow_dispatch' && steps.pr_info.outputs.skip != 'true')
+      uses: actions/github-script@latest
+      with:
+        github-token: ${{ secrets.GITHUB_TOKEN }}
+        script: |
+          // [script modified to use step.docs-analysis outputs]
+```
+
+## Benefits of Integration
+
+1. **Reduced Duplication**: The core document analysis logic is maintained in one place
+2. **Consistent Features**: All documentation workflows get the same analysis capabilities
+3. **Better Versioning**: Can pin to specific versions of the docs-analysis action
+4. **Cleaner Workflow Files**: Simplified workflow YAML with better separation of concerns
+5. **Improved Maintenance**: Changes to analysis logic only need to be made in one place
+6. **Common Security Model**: Same input validation and security practices across workflows
+
+## Implementation Plan
+
+1. Create a small PR with the composite action (completed)
+2. Test the action in isolation on sample PRs
+3. Create a new PR that refactors docs-preview-link.yml to use the composite action
+4. Refactor any other documentation workflows to use the same action
+5. Establish a process for maintaining the shared action
diff --git a/.github/actions/docs-analysis/README.md b/.github/actions/docs-analysis/README.md
@@ -0,0 +1,252 @@
+# Docs Analysis Action
+
+A composite GitHub Action to analyze documentation changes in pull requests and provide useful metrics and insights.
+
+## Features
+
+- Detects documentation files changed in a PR
+- Calculates metrics (files changed, words added/removed)
+- Tracks image modifications with detailed reporting
+- Analyzes document structure (headings, titles)
+- Identifies the most significantly changed files
+- Integrates with other doc workflows (weekly checks, PR previews)
+- Provides standardized outputs that can be used by any workflow
+
+## Usage
+
+This action analyzes documentation changes to help provide better context and metrics for documentation PRs. 
+It only runs on PRs that modify files in the docs directory or markdown files elsewhere in the repo.
+
+### Basic Example
+
+```yaml
+- name: Analyze Documentation Changes
+  uses: ./.github/actions/docs-analysis
+  id: docs-analysis
+  with:
+    docs-path: 'docs/'
+    pr-ref: ${{ github.event.pull_request.head.ref }}
+    base-ref: 'main'
+```
+
+### Integration with tj-actions/changed-files (Recommended)
+
+For optimal performance and reliability, we recommend using with `tj-actions/changed-files`:
+
+```yaml
+- uses: tj-actions/changed-files@v45
+  id: changed-files
+  with:
+    files: |
+      docs/**
+      **.md
+    separator: ","
+
+- name: Analyze Documentation Changes
+  id: docs-analysis
+  uses: ./.github/actions/docs-analysis
+  with:
+    docs-path: 'docs/'
+    changed-files: ${{ steps.changed-files.outputs.all_changed_files }}
+    files-pattern: 'docs/**|**.md'
+```
+
+### Complete Example with Conditionals
+
+```yaml
+jobs:
+  check-docs-changes:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - uses: tj-actions/changed-files@v45
+        id: changed-files
+        with:
+          files: |
+            docs/**
+            **.md
+          separator: ","
+
+      - name: Analyze Documentation Changes
+        uses: ./.github/actions/docs-analysis
+        id: docs-analysis
+        with:
+          docs-path: 'docs/'
+          changed-files: ${{ steps.changed-files.outputs.all_changed_files }}
+          significant-words-threshold: '100'
+          skip-if-no-docs: 'true'
+          debug-mode: 'false'
+
+      - name: Create Preview Comment
+        if: steps.docs-analysis.outputs.docs-changed == 'true'
+        run: |
+          echo "Found ${{ steps.docs-analysis.outputs.docs-files-count }} changed docs files"
+          echo "Words: +${{ steps.docs-analysis.outputs.words-added }}/-${{ steps.docs-analysis.outputs.words-removed }}"
+
+          if [[ "${{ steps.docs-analysis.outputs.images-total }}" != "0" ]]; then
+            echo "Images changed: ${{ steps.docs-analysis.outputs.images-total }}"
+          fi
+
+          if [[ "${{ steps.docs-analysis.outputs.significant-change }}" == "true" ]]; then
+            echo "This is a significant docs change!"
+          fi
+```
+
+## Inputs
+
+| Name | Description | Required | Default |
+|------|-------------|----------|---------|
+| `docs-path` | Path to the documentation directory | No | `docs/` |
+| `files-pattern` | Glob pattern(s) for documentation files (use vertical bar \| to separate multiple patterns) | No | `**.md\|docs/**` |
+| `changed-files` | Comma-separated list of changed files (from tj-actions/changed-files) | No | `` |
+| `pr-ref` | PR reference to analyze | No | `github.event.pull_request.head.ref` |
+| `base-ref` | Base reference to compare against | No | `main` |
+| `files-changed` | Comma-separated list of files changed (legacy input, use `changed-files` instead) | No | `` |
+| `max-scan-files` | Maximum number of files to scan | No | `100` |
+| `max-files-to-analyze` | Maximum files to analyze in detail (for performance) | No | `20` |
+| `throttle-large-repos` | Enable throttling for large repositories | No | `true` |
+| `significant-words-threshold` | Threshold for significant text changes | No | `100` |
+| `skip-if-no-docs` | Whether to skip if no docs files are changed | No | `true` |
+| `debug-mode` | Enable verbose debugging output | No | `false` |
+| `use-changed-files-action` | Whether to use tj-actions/changed-files instead of git commands | No | `false` |
+
+## Outputs
+
+| Name | Description |
+|------|-------------|
+| `docs-changed` | Whether documentation files were changed (`true`/`false`) |
+| `docs-files-count` | Number of documentation files changed |
+| `words-added` | Number of words added to documentation |
+| `words-removed` | Number of words removed from documentation |
+| `images-added` | Number of images added |
+| `images-modified` | Number of images modified |
+| `images-deleted` | Number of images deleted |
+| `images-total` | Total number of images changed |
+| `image-names` | Comma-separated list of changed image files |
+| `manifest-changed` | Whether manifest.json was changed (`true`/`false`) |
+| `format-only` | Whether changes are formatting-only (`true`/`false`) |
+| `significant-change` | Whether changes are significant (`true`/`false`) |
+| `has-non-docs-changes` | Whether PR contains non-docs changes (`true`/`false`) |
+| `most-changed-file` | Path to the most changed file |
+| `most-changed-url-path` | URL path for the most changed file |
+| `most-significant-image` | Path to the most significant image |
+| `doc-structure` | JSON structure of document heading counts |
+| `execution-time` | Execution time in seconds |
+| `cache-key` | Cache key for this analysis run |
+
+## Security Features
+
+- Stronger input validation with whitelist approach for branch references
+- Enhanced path sanitization with traversal detection
+- Secure command execution (no eval) in git retry operations
+- Error tracing with line numbers for better debugging
+- Cross-platform compatibility with fallbacks
+- Repository size detection with adaptive throttling
+- Python integration for safer JSON handling (with bash fallbacks)
+- Performance monitoring with execution metrics
+
+## Performance Optimization
+
+- Configurable document scan limits
+- Intelligent throttling for large repositories
+- Git performance tuning
+- Execution time tracking
+- Content-based caching
+- Debug mode for troubleshooting
+
+## Examples
+
+### Analyzing Documentation Changes for a PR
+
+```yaml
+- name: Analyze Documentation Changes
+  uses: ./.github/actions/docs-analysis
+  id: docs-analysis
+  with:
+    docs-path: 'docs/'
+```
+
+### Analyzing Non-Git Files
+
+```yaml
+- name: Analyze Documentation Files
+  uses: ./.github/actions/docs-analysis
+  id: docs-analysis
+  with:
+    files-changed: 'docs/file1.md,docs/file2.md,README.md'
+    docs-path: 'docs/'
+```
+
+### Debug Mode for Troubleshooting
+
+```yaml
+- name: Analyze Documentation with Debug Output
+  uses: ./.github/actions/docs-analysis
+  id: docs-analysis
+  with:
+    docs-path: 'docs/'
+    debug-mode: 'true'
+```
+
+## Unified Documentation Workflows
+
+This action is designed to work seamlessly with Coder's other documentation-related workflows:
+
+### How to Use with docs-ci.yaml
+
+The `docs-ci.yaml` workflow uses this action to analyze documentation changes for linting and formatting:
+
+```yaml
+# From .github/workflows/docs-ci.yaml
+- uses: tj-actions/changed-files@v45
+  id: changed-files
+  with:
+    files: |
+      docs/**
+      **.md
+    separator: ","
+
+- name: Analyze documentation changes
+  id: docs-analysis
+  uses: ./.github/actions/docs-analysis
+  with:
+    docs-path: "docs/"
+    changed-files: ${{ steps.changed-files.outputs.all_changed_files }}
+    files-pattern: "docs/**|**.md"
+```
+
+### How to Use with docs-preview-link.yml
+
+This action can be used in the `docs-preview-link.yml` workflow to analyze documentation changes for preview generation:
+
+```yaml
+# Example integration with docs-preview-link.yml
+- name: Analyze documentation changes
+  id: docs-analysis
+  uses: ./.github/actions/docs-analysis
+  with:
+    docs-path: "docs/"
+    pr-ref: ${{ steps.pr_info.outputs.branch_name }}
+    base-ref: 'main'
+```
+
+### How to Use with weekly-docs.yaml
+
+This action can be used to enhance the weekly documentation checks:
+
+```yaml
+# Example integration with weekly-docs.yaml
+- name: Analyze documentation structure
+  id: docs-analysis
+  uses: ./.github/actions/docs-analysis
+  with:
+    docs-path: "docs/"
+    files-pattern: "docs/**"
+    max-scan-files: "500"  # Higher limit for full repo scan
+```
+
+By using this shared action across all documentation workflows, you ensure consistent analysis, metrics, and reporting for all documentation-related tasks.