moai-adk 0.9.0__py3-none-any.whl → 0.15.0__py3-none-any.whl

moai_adk/templates/.github/workflows/spec-issue-sync.yml

@@ -3,7 +3,7 @@ name: 📋 SPEC Issue Sync
 on:
   pull_request:
     paths:
-      - '{{SPEC_DIR}}/SPEC-*/spec.md'
+      - '.moai/specs/SPEC-*/spec.md'
     types: [opened, synchronize]
 
 permissions:
@@ -25,33 +25,62 @@ jobs:
 
       - name: Find and parse SPEC file
         id: spec
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
         run: |
           set -x  # Enable debug mode
 
-          # Debug: Show current directory and files
-          echo "=== Debug: Current directory ==="
-          pwd
-          ls -la
+          echo "=== STEP 1: Get PR branch name ==="
+          branch_name="${{ github.head_ref }}"
+          echo "Branch: $branch_name"
 
-          echo "=== Debug: Looking for {{SPEC_DIR}} ==="
-          ls -la {{SPEC_DIR}}/ 2>&1 || echo "{{SPEC_DIR}}/ directory not found"
+          echo ""
+          echo "=== STEP 2: Get changed files from PR ==="
+          # Get list of changed files from PR
+          changed_files=$(gh pr view ${{ github.event.pull_request.number }} --json files --jq '.files[].path' 2>&1)
+
+          if [ $? -ne 0 ]; then
+            echo "⚠️  Failed to fetch PR files, falling back to git diff"
+            changed_files=$(git diff --name-only origin/main HEAD 2>&1)
+          fi
 
-          # Find SPEC files in the PR
-          echo "=== Debug: Searching for SPEC files ==="
-          find . -name "spec.md" -type f 2>&1 || echo "find command failed"
+          echo "Changed files:"
+          echo "$changed_files"
 
-          spec_file=$(find {{SPEC_DIR}} -name "spec.md" -type f 2>&1 | head -1)
-          echo "Found spec_file: [$spec_file]"
+          echo ""
+          echo "=== STEP 3: Find SPEC files that were actually changed ==="
+          # Find spec files that were actually modified in this PR
+          spec_files=$(echo "$changed_files" | grep -E '\.moai/specs/SPEC-.*/spec\.md$' || true)
 
-          if [ -z "$spec_file" ]; then
-            echo "⚠️  No SPEC file found in {{SPEC_DIR}}"
+          if [ -z "$spec_files" ]; then
+            echo "⚠️  No SPEC file changes detected in this PR"
             echo "Exiting gracefully (this is expected if no SPEC files changed)"
             exit 0
           fi
 
-          echo "✅ Found SPEC file: $spec_file"
+          echo "Found SPEC files:"
+          echo "$spec_files"
+
+          # Count SPEC files
+          spec_file_count=$(echo "$spec_files" | wc -l)
+          echo "Count: $spec_file_count"
+
+          if [ "$spec_file_count" -gt 1 ]; then
+            echo ""
+            echo "⚠️  WARNING: Multiple SPEC files detected in this PR"
+            echo "   This is unusual. Using first SPEC file."
+            echo "   Files:"
+            echo "$spec_files" | sed 's/^/     /'
+          fi
+
+          # Select first SPEC file
+          spec_file=$(echo "$spec_files" | head -1)
+          echo ""
+          echo "✅ Selected SPEC file: $spec_file"
           echo "spec_file=$spec_file" >> $GITHUB_OUTPUT
 
+          echo ""
+          echo "=== STEP 4: Extract YAML metadata ==="
           # Extract YAML metadata using grep
           spec_id=$(grep "^id:" "$spec_file" | sed 's/^id: *//' | tr -d ' "')
           spec_version=$(grep "^version:" "$spec_file" | sed 's/^version: *//' | tr -d ' "')
@@ -59,11 +88,7 @@ jobs:
           spec_priority=$(grep "^priority:" "$spec_file" | sed 's/^priority: *//' | tr -d ' "')
 
           # Extract title from H1 heading
-          {% if ENABLE_TAG_SYSTEM -%}
           spec_title=$(grep "^# @SPEC:" "$spec_file" | sed 's/^# @SPEC:[^:]*: //')
-          {% else -%}
-          spec_title=$(grep "^# " "$spec_file" | head -1 | sed 's/^# //')
-          {% endif -%}
 
           echo "✅ Extracted SPEC metadata:"
           echo "  ID: $spec_id"
@@ -72,13 +97,93 @@ jobs:
           echo "  Status: $spec_status"
           echo "  Priority: $spec_priority"
 
+          echo ""
+          echo "=== STEP 5: Validate SPEC status ==="
+          # Skip if SPEC is already completed (historical document)
+          if [ "$spec_status" = "completed" ]; then
+            echo "⚠️  SPEC status is 'completed' (historical document)"
+            echo "   Skipping issue creation for completed SPEC"
+            exit 0
+          fi
+
+          echo "✅ SPEC status is valid (not completed)"
+
+          echo ""
+          echo "=== STEP 6: Validate branch name matches SPEC ID ==="
+          # Extract SPEC ID from branch name (feature/SPEC-UPDATE-REFACTOR-002 -> UPDATE-REFACTOR-002)
+          branch_spec_id=$(echo "$branch_name" | grep -oE 'SPEC-[A-Z0-9_-]+' | sed 's/^SPEC-//' || true)
+
+          if [ -n "$branch_spec_id" ]; then
+            if [ "$branch_spec_id" != "$spec_id" ]; then
+              echo "⚠️  WARNING: Branch name mismatch!"
+              echo "   Branch SPEC ID: $branch_spec_id"
+              echo "   File SPEC ID:   $spec_id"
+              echo "   Continuing anyway (might be intentional)"
+            else
+              echo "✅ Branch name matches SPEC ID"
+            fi
+          else
+            echo "⚠️  Could not extract SPEC ID from branch name"
+            echo "   Branch: $branch_name"
+            echo "   Continuing anyway"
+          fi
+
+          echo ""
+          echo "=== STEP 7: Output all variables ==="
           echo "spec_id=$spec_id" >> $GITHUB_OUTPUT
           echo "spec_version=$spec_version" >> $GITHUB_OUTPUT
           echo "spec_status=$spec_status" >> $GITHUB_OUTPUT
           echo "spec_priority=$spec_priority" >> $GITHUB_OUTPUT
           echo "spec_title=$spec_title" >> $GITHUB_OUTPUT
 
-      - name: Create GitHub Issue
+      - name: Check for existing issue
+        if: steps.spec.outputs.spec_id
+        id: check-issue
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          spec_id="${{ steps.spec.outputs.spec_id }}"
+
+          echo "=== Checking for existing issue ==="
+          echo "Searching for existing GitHub issue with SPEC-$spec_id..."
+
+          # PRIMARY: Search with label filter (efficient)
+          echo "  Attempt 1: Searching with 'spec' label filter..."
+          existing_issue=$(gh issue list \
+            --label "spec" \
+            --state all \
+            --search "[SPEC-$spec_id]" \
+            --json number,title,state \
+            --jq '.[] | select(.title | contains("[SPEC-'$spec_id']")) | .number' \
+            2>/dev/null | head -1)
+
+          # FALLBACK: Search without label filter (in case labels missing)
+          if [ -z "$existing_issue" ]; then
+            echo "  Attempt 2: Searching WITHOUT label filter (fallback for missing labels)..."
+            existing_issue=$(gh issue list \
+              --state all \
+              --search "[SPEC-$spec_id]" \
+              --json number,title,state,labels \
+              --jq '.[] | select(.title | contains("[SPEC-'$spec_id']")) | .number' \
+              2>/dev/null | head -1)
+
+            if [ -n "$existing_issue" ]; then
+              echo "  ⚠️  Found issue without 'spec' label, adding labels..."
+              # Add missing labels to existing issue
+              gh issue edit "$existing_issue" --add-label "spec,planning" 2>/dev/null || true
+            fi
+          fi
+
+          if [ -n "$existing_issue" ]; then
+            echo "✅ Found existing issue: #$existing_issue"
+            echo "issue_exists=true" >> $GITHUB_OUTPUT
+            echo "issue_number=$existing_issue" >> $GITHUB_OUTPUT
+          else
+            echo "📋 No existing issue found for SPEC-$spec_id"
+            echo "issue_exists=false" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Create or Update GitHub Issue
         if: steps.spec.outputs.spec_id
         id: create-issue
         env:
@@ -90,6 +195,8 @@ jobs:
           spec_status="${{ steps.spec.outputs.spec_status }}"
           spec_priority="${{ steps.spec.outputs.spec_priority }}"
           spec_file="${{ steps.spec.outputs.spec_file }}"
+          issue_exists="${{ steps.check-issue.outputs.issue_exists }}"
+          existing_issue="${{ steps.check-issue.outputs.issue_number }}"
 
           # Read SPEC content (skip YAML frontmatter: 9 lines + 1 blank = 10 lines total)
           # Start reading from line 11
@@ -118,33 +225,93 @@ jobs:
             echo "📝 **Auto-synced**: This issue is automatically synchronized from the SPEC document"
           } > /tmp/issue_body.txt
 
-          echo "📋 Creating GitHub Issue..."
-          echo "  Title: [SPEC-$spec_id] $spec_title (v$spec_version)"
-          echo "  Body file: /tmp/issue_body.txt"
-          wc -l /tmp/issue_body.txt
+          if [ "$issue_exists" = "true" ]; then
+            echo "📝 Updating existing issue #$existing_issue..."
+            echo "  Title: [SPEC-$spec_id] $spec_title (v$spec_version)"
+            echo "  Labels: spec, planning, $spec_priority"
 
-          # Create issue with labels using body-file
-          issue_output=$(gh issue create \
-            --title "[SPEC-$spec_id] $spec_title (v$spec_version)" \
-            --body-file /tmp/issue_body.txt \
-            --label "spec" \
-            --label "planning" \
-            --label "$spec_priority" 2>&1)
+            # Update existing issue with new content and ensure proper labels
+            gh issue edit "$existing_issue" \
+              --title "[SPEC-$spec_id] $spec_title (v$spec_version)" \
+              --body-file /tmp/issue_body.txt \
+              --add-label "spec,planning,$spec_priority" \
+              --state open
+
+            issue_num=$existing_issue
+            echo "✅ Updated issue #$issue_num with latest SPEC version"
+          else
+            echo "📋 Creating new GitHub Issue..."
+            echo "  Title: [SPEC-$spec_id] $spec_title (v$spec_version)"
+            echo "  Body file: /tmp/issue_body.txt"
+            wc -l /tmp/issue_body.txt
+
+            # Create issue with labels using body-file
+            issue_output=$(gh issue create \
+              --title "[SPEC-$spec_id] $spec_title (v$spec_version)" \
+              --body-file /tmp/issue_body.txt \
+              --label "spec" \
+              --label "planning" \
+              --label "$spec_priority" 2>&1)
 
-          echo "$issue_output" | tee /tmp/issue_output.txt
+            echo "$issue_output" | tee /tmp/issue_output.txt
 
-          # Extract issue number from output
-          issue_num=$(echo "$issue_output" | grep -oE '/issues/[0-9]+' | grep -oE '[0-9]+' | head -1)
+            # Extract issue number from output
+            issue_num=$(echo "$issue_output" | grep -oE '/issues/[0-9]+' | grep -oE '[0-9]+' | head -1)
 
-          if [ -z "$issue_num" ]; then
-            echo "⚠️  Could not extract issue number from output"
-            echo "Full output:"
-            cat /tmp/issue_output.txt
-            exit 1
+            if [ -z "$issue_num" ]; then
+              echo "⚠️  Could not extract issue number from output"
+              echo "Full output:"
+              cat /tmp/issue_output.txt
+              exit 1
+            fi
+
+            echo "✅ Created issue #$issue_num"
           fi
 
           echo "issue_number=$issue_num" >> $GITHUB_OUTPUT
-          echo "✅ Created issue #$issue_num"
+
+      - name: Validate SPEC issue labels
+        if: steps.create-issue.outputs.issue_number
+        id: validate-labels
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          issue_num="${{ steps.create-issue.outputs.issue_number }}"
+          spec_priority="${{ steps.spec.outputs.spec_priority }}"
+
+          echo "🔍 Validating SPEC issue #$issue_num labels..."
+
+          # Get current labels
+          current_labels=$(gh issue view $issue_num --json labels --jq '.labels[].name' | tr '\n' ',' | sed 's/,$//')
+          echo "Current labels: $current_labels"
+
+          # Check for mandatory labels
+          needs_update=false
+
+          if [[ ! "$current_labels" =~ "spec" ]]; then
+            echo "⚠️  Missing 'spec' label, adding..."
+            gh issue edit $issue_num --add-label "spec"
+            needs_update=true
+          fi
+
+          if [[ ! "$current_labels" =~ "planning" ]]; then
+            echo "⚠️  Missing 'planning' label, adding..."
+            gh issue edit $issue_num --add-label "planning"
+            needs_update=true
+          fi
+
+          # Check for priority label
+          if [[ ! "$current_labels" =~ (critical|high|medium|low) ]]; then
+            echo "⚠️  No priority label found, adding '$spec_priority' as default"
+            gh issue edit $issue_num --add-label "$spec_priority"
+            needs_update=true
+          fi
+
+          if [ "$needs_update" = true ]; then
+            echo "✅ SPEC labels validated and corrected"
+          else
+            echo "✅ SPEC labels already valid"
+          fi
 
       - name: Add PR comment
         if: steps.create-issue.outputs.issue_number
@@ -162,7 +329,7 @@ jobs:
             echo "This SPEC has been synchronized to GitHub Issue."
             echo ""
             echo "📋 **Issue**: [#$issue_num - SPEC-$spec_id: $spec_title](../issues/$issue_num)"
-            echo "🔗 **SPEC File**: \`{{SPEC_DIR}}/SPEC-$spec_id/spec.md\`"
+            echo "🔗 **SPEC File**: \`.moai/specs/SPEC-$spec_id/spec.md\`"
             echo ""
             echo "The issue will be automatically updated as you modify the SPEC document."
           } > /tmp/pr_comment.txt

moai_adk/templates/.github/workflows/swift-tag-validation.yml

@@ -0,0 +1,11 @@
+name: Swift TAG Validation
+on:
+  push:
+    branches: [ develop, main ]
+jobs:
+  validate-tags:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - name: Validate Swift TAGs
+        run: echo "Validating Swift TAGs"

moai_adk/templates/.github/workflows/tag-report.yml

@@ -0,0 +1,269 @@
+# @CODE:DOC-TAG-004 | Component 4: Automated TAG reporting workflow
+name: TAG Report Generation
+
+on:
+  # Scheduled: Daily at 09:00 UTC
+  schedule:
+    - cron: '0 9 * * *'
+
+  # Event: Push to main/develop
+  push:
+    branches:
+      - main
+      - develop
+
+  # Manual: Workflow dispatch
+  workflow_dispatch:
+    inputs:
+      output_format:
+        description: 'Report format (all|inventory|matrix|statistics)'
+        required: false
+        default: 'all'
+
+jobs:
+  generate-tag-reports:
+    name: Generate TAG Reports
+    runs-on: ubuntu-latest
+
+    permissions:
+      contents: write  # Required to commit reports back to repo
+      pull-requests: write  # Required to comment on PRs
+
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Full history for accurate file modification times
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install MoAI-ADK
+        run: |
+          uv pip install --system -e .
+          uv pip install --system requests
+
+      - name: Create reports directory
+        run: |
+          mkdir -p docs/reports
+          echo "Reports will be generated in docs/reports/"
+
+      - name: Generate TAG Inventory
+        run: |
+          python -c "
+          from moai_adk.core.tags.reporter import ReportGenerator
+
+          generator = ReportGenerator()
+          inventory = generator.generate_inventory_report('.')
+
+          with open('docs/reports/tag-inventory.md', 'w') as f:
+              f.write(inventory)
+
+          print('✅ Generated tag-inventory.md')
+          "
+
+      - name: Generate TAG Coverage Matrix
+        run: |
+          python -c "
+          from moai_adk.core.tags.reporter import ReportGenerator
+
+          generator = ReportGenerator()
+          matrix = generator.generate_matrix_report('.')
+
+          with open('docs/reports/tag-matrix.md', 'w') as f:
+              f.write(matrix)
+
+          print('✅ Generated tag-matrix.md')
+          "
+
+      - name: Generate TAG Statistics
+        run: |
+          python -c "
+          from moai_adk.core.tags.reporter import ReportGenerator
+
+          generator = ReportGenerator()
+          stats = generator.generate_statistics_report('.')
+
+          with open('docs/reports/tag-statistics.json', 'w') as f:
+              f.write(stats)
+
+          print('✅ Generated tag-statistics.json')
+          "
+
+      - name: Generate combined report
+        run: |
+          python -c "
+          from moai_adk.core.tags.reporter import ReportGenerator
+          from pathlib import Path
+          import json
+
+          generator = ReportGenerator()
+          result = generator.generate_all_reports('.', 'docs/reports')
+
+          if result.success:
+              print(f'✅ All reports generated successfully')
+              print(f'   - Inventory: {result.inventory_path}')
+              print(f'   - Matrix: {result.matrix_path}')
+              print(f'   - Statistics: {result.statistics_path}')
+
+              # Read statistics for summary
+              stats = json.loads(result.statistics_path.read_text())
+              print(f'')
+              print(f'📊 Summary:')
+              print(f'   - Total TAGs: {stats[\"total_tags\"]}')
+              print(f'   - By Type: SPEC={stats[\"by_type\"].get(\"SPEC\", 0)}, CODE={stats[\"by_type\"].get(\"CODE\", 0)}, TEST={stats[\"by_type\"].get(\"TEST\", 0)}, DOC={stats[\"by_type\"].get(\"DOC\", 0)}')
+              print(f'   - Coverage: {stats[\"coverage\"].get(\"overall_percentage\", 0)}%')
+          else:
+              print(f'❌ Report generation failed: {result.error_message}')
+              exit(1)
+          "
+
+      - name: Check for changes
+        id: git_status
+        run: |
+          if [ -n "$(git status --porcelain docs/reports/)" ]; then
+            echo "changes=true" >> $GITHUB_OUTPUT
+            echo "📝 TAG reports have changed"
+          else
+            echo "changes=false" >> $GITHUB_OUTPUT
+            echo "✅ TAG reports unchanged (no commit needed)"
+          fi
+
+      - name: Commit reports
+        if: steps.git_status.outputs.changes == 'true'
+        run: |
+          git config --global user.name 'github-actions[bot]'
+          git config --global user.email 'github-actions[bot]@users.noreply.github.com'
+          git add docs/reports/
+          git commit -m "docs(tags): Update TAG reports [automated]
+
+          - Updated tag-inventory.md
+          - Updated tag-matrix.md
+          - Updated tag-statistics.json
+
+          Generated by: GitHub Actions workflow (tag-report.yml)
+          Triggered: ${{ github.event_name }}
+          Commit: ${{ github.sha }}
+
+          🤖 Generated with MoAI-ADK TAG Reporting System
+          "
+          git push
+
+      - name: Create GitHub Release Notes
+        if: github.ref == 'refs/heads/main' && steps.git_status.outputs.changes == 'true'
+        run: |
+          echo "📊 TAG System Health Report" > report_summary.md
+          echo "" >> report_summary.md
+          echo "Generated: $(date -u +'%Y-%m-%d %H:%M:%S UTC')" >> report_summary.md
+          echo "" >> report_summary.md
+
+          # Extract key metrics from statistics
+          python -c "
+          import json
+          from pathlib import Path
+
+          stats = json.loads(Path('docs/reports/tag-statistics.json').read_text())
+
+          print(f'## Summary')
+          print(f'')
+          print(f'- **Total TAGs**: {stats[\"total_tags\"]}')
+          print(f'- **By Type**:')
+          print(f'  - SPEC: {stats[\"by_type\"].get(\"SPEC\", 0)}')
+          print(f'  - CODE: {stats[\"by_type\"].get(\"CODE\", 0)}')
+          print(f'  - TEST: {stats[\"by_type\"].get(\"TEST\", 0)}')
+          print(f'  - DOC: {stats[\"by_type\"].get(\"DOC\", 0)}')
+          print(f'')
+          print(f'## Coverage')
+          print(f'')
+          print(f'- **Overall**: {stats[\"coverage\"].get(\"overall_percentage\", 0)}%')
+          print(f'- **SPEC → CODE**: {stats[\"coverage\"].get(\"spec_to_code\", 0)}%')
+          print(f'- **CODE → TEST**: {stats[\"coverage\"].get(\"code_to_test\", 0)}%')
+          print(f'')
+          print(f'## Issues')
+          print(f'')
+          print(f'- **Orphan TAGs**: {stats[\"issues\"].get(\"orphan_count\", 0)}')
+          print(f'- **Incomplete Chains**: {stats[\"issues\"].get(\"incomplete_chains\", 0)}')
+          print(f'')
+          print(f'## Reports')
+          print(f'')
+          print(f'- [TAG Inventory](./docs/reports/tag-inventory.md)')
+          print(f'- [Coverage Matrix](./docs/reports/tag-matrix.md)')
+          print(f'- [Statistics (JSON)](./docs/reports/tag-statistics.json)')
+          " >> report_summary.md
+
+          cat report_summary.md
+
+      - name: Upload reports as artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: tag-reports-${{ github.sha }}
+          path: docs/reports/
+          retention-days: 90
+
+      - name: Post summary to GitHub Actions UI
+        run: |
+          echo "## 📊 TAG Report Generation Complete" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          python -c "
+          import json
+          from pathlib import Path
+
+          stats = json.loads(Path('docs/reports/tag-statistics.json').read_text())
+
+          print(f'### Summary')
+          print(f'')
+          print(f'| Metric | Value |')
+          print(f'|--------|-------|')
+          print(f'| Total TAGs | {stats[\"total_tags\"]} |')
+          print(f'| SPEC | {stats[\"by_type\"].get(\"SPEC\", 0)} |')
+          print(f'| CODE | {stats[\"by_type\"].get(\"CODE\", 0)} |')
+          print(f'| TEST | {stats[\"by_type\"].get(\"TEST\", 0)} |')
+          print(f'| DOC | {stats[\"by_type\"].get(\"DOC\", 0)} |')
+          print(f'| Overall Coverage | {stats[\"coverage\"].get(\"overall_percentage\", 0)}% |')
+          print(f'| Orphan TAGs | {stats[\"issues\"].get(\"orphan_count\", 0)} |')
+          print(f'| Incomplete Chains | {stats[\"issues\"].get(\"incomplete_chains\", 0)} |')
+          print(f'')
+          print(f'### Generated Files')
+          print(f'')
+          print(f'- ✅ tag-inventory.md')
+          print(f'- ✅ tag-matrix.md')
+          print(f'- ✅ tag-statistics.json')
+          " >> $GITHUB_STEP_SUMMARY
+
+      - name: Fail workflow if issues detected (optional)
+        if: always()
+        run: |
+          python -c "
+          import json
+          from pathlib import Path
+          import sys
+
+          stats = json.loads(Path('docs/reports/tag-statistics.json').read_text())
+
+          orphan_count = stats['issues'].get('orphan_count', 0)
+          incomplete_count = stats['issues'].get('incomplete_chains', 0)
+
+          # Optional: Fail workflow if too many issues
+          # Uncomment to enable strict validation
+          # if orphan_count > 10 or incomplete_count > 10:
+          #     print(f'❌ Too many TAG issues detected!')
+          #     print(f'   Orphans: {orphan_count}')
+          #     print(f'   Incomplete: {incomplete_count}')
+          #     sys.exit(1)
+
+          print(f'✅ TAG system health check passed')
+          print(f'   Orphans: {orphan_count}')
+          print(f'   Incomplete: {incomplete_count}')
+          "