moai-adk 0.8.1__py3-none-any.whl → 0.8.2__py3-none-any.whl

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

@@ -0,0 +1,261 @@
+# @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
+
+    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: '3.11'
+          cache: 'pip'
+
+      - name: Install MoAI-ADK
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e .
+
+      - 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}')
+          "

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

@@ -0,0 +1,176 @@
+name: TAG Validation
+
+# @DOC:DOC-TAG-004 | Component 2: CI/CD workflow for TAG validation
+# Validates TAG annotations on every PR to ensure quality and consistency
+
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review]
+  push:
+    branches: [main, develop, "feature/**"]
+
+jobs:
+  validate-tags:
+    name: 🏷️ Validate TAG Annotations
+    runs-on: ubuntu-latest
+
+    # Skip validation on draft PRs (allow WIP)
+    if: github.event.pull_request.draft == false || github.event_name == 'push'
+
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0  # Fetch all history for comprehensive validation
+
+      - name: Setup Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.12'
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          version: "latest"
+
+      - name: Install dependencies
+        run: |
+          uv pip install --system -e .
+          uv pip install --system requests
+
+      - name: Get PR number
+        id: pr
+        run: |
+          if [ "${{ github.event_name }}" == "pull_request" ]; then
+            echo "number=${{ github.event.pull_request.number }}" >> $GITHUB_OUTPUT
+          else
+            echo "number=0" >> $GITHUB_OUTPUT
+          fi
+
+      - name: Run TAG validation (info mode)
+        if: github.event_name == 'push' || github.event.pull_request.draft == false
+        id: validate_info
+        continue-on-error: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          if [ "${{ steps.pr.outputs.number }}" != "0" ]; then
+            python -m moai_adk.core.tags.ci_validator \
+              --pr-number ${{ steps.pr.outputs.number }} \
+              --output-json validation-report.json \
+              --output-comment pr-comment.md
+          else
+            echo "Skipping PR validation on push event"
+            echo '{"status": "skipped", "message": "Push event - no PR validation"}' > validation-report.json
+            echo "# TAG Validation Skipped\n\nPush event detected. TAG validation runs on PRs." > pr-comment.md
+          fi
+
+      - name: Run TAG validation (strict mode)
+        if: github.event.pull_request.ready_for_review == true
+        id: validate_strict
+        continue-on-error: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          python -m moai_adk.core.tags.ci_validator \
+            --pr-number ${{ steps.pr.outputs.number }} \
+            --strict \
+            --output-json validation-report-strict.json \
+            --output-comment pr-comment-strict.md
+
+      - name: Upload validation report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: tag-validation-report
+          path: |
+            validation-report*.json
+            pr-comment*.md
+          retention-days: 30
+
+      - name: Post PR comment (info mode)
+        if: github.event_name == 'pull_request' && steps.pr.outputs.number != '0'
+        uses: actions/github-script@v7
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            const fs = require('fs');
+
+            // Read the comment file
+            let comment = '';
+            try {
+              comment = fs.readFileSync('pr-comment.md', 'utf8');
+            } catch (error) {
+              comment = '## ⚠️ TAG Validation\n\nCould not read validation results.';
+            }
+
+            // Find existing comment
+            const { data: comments } = await github.rest.issues.listComments({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              issue_number: context.issue.number,
+            });
+
+            const botComment = comments.find(comment =>
+              comment.user.login === 'github-actions[bot]' &&
+              comment.body.includes('TAG Validation')
+            );
+
+            // Create or update comment
+            const commentBody = comment + '\n\n---\n\n*Automated validation by [MoAI-ADK TAG System](https://github.com/YOUR_ORG/MoAI-ADK)*';
+
+            if (botComment) {
+              await github.rest.issues.updateComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                comment_id: botComment.id,
+                body: commentBody
+              });
+            } else {
+              await github.rest.issues.createComment({
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                issue_number: context.issue.number,
+                body: commentBody
+              });
+            }
+
+      - name: Validation summary
+        if: always()
+        run: |
+          echo "## TAG Validation Summary" >> $GITHUB_STEP_SUMMARY
+          echo "" >> $GITHUB_STEP_SUMMARY
+
+          if [ -f validation-report.json ]; then
+            echo "### Info Mode Results" >> $GITHUB_STEP_SUMMARY
+            cat validation-report.json | python -c "import json, sys; r=json.load(sys.stdin); print(f\"- Status: {r.get('status', 'unknown')}\"); print(f\"- Errors: {r.get('statistics', {}).get('total_errors', 0)}\"); print(f\"- Warnings: {r.get('statistics', {}).get('total_warnings', 0)}\")" >> $GITHUB_STEP_SUMMARY || echo "- Could not parse report" >> $GITHUB_STEP_SUMMARY
+          fi
+
+          if [ -f validation-report-strict.json ]; then
+            echo "" >> $GITHUB_STEP_SUMMARY
+            echo "### Strict Mode Results" >> $GITHUB_STEP_SUMMARY
+            cat validation-report-strict.json | python -c "import json, sys; r=json.load(sys.stdin); print(f\"- Status: {r.get('status', 'unknown')}\"); print(f\"- Errors: {r.get('statistics', {}).get('total_errors', 0)}\"); print(f\"- Warnings: {r.get('statistics', {}).get('total_warnings', 0)}\")" >> $GITHUB_STEP_SUMMARY || echo "- Could not parse report" >> $GITHUB_STEP_SUMMARY
+          fi
+
+      - name: Set PR status check
+        if: github.event_name == 'pull_request'
+        run: |
+          if [ -f validation-report.json ]; then
+            STATUS=$(cat validation-report.json | python -c "import json, sys; r=json.load(sys.stdin); print('success' if r.get('is_valid', False) else 'failure')")
+            echo "Validation status: $STATUS"
+            if [ "$STATUS" = "failure" ]; then
+              exit 1
+            fi
+          fi
+
+  # Optional: Require TAG validation to pass before merge
+  # Uncomment this job to enforce strict validation
+  #
+  # require-validation:
+  #   name: Require TAG Validation
+  #   runs-on: ubuntu-latest
+  #   needs: validate-tags
+  #   if: github.event.pull_request.draft == false
+  #   steps:
+  #     - name: Check validation passed
+  #       run: echo "TAG validation passed"

moai_adk/templates/.moai/config.json

@@ -4,7 +4,12 @@
     "@SPEC:PROJECT-CONFIG-001": "@SPEC:MOAI-CONFIG-001"
   },
   "moai": {
-    "version": "{{MOAI_VERSION}}"
+    "version": "{{MOAI_VERSION}}",
+    "update_check_frequency": "daily",
+    "version_check": {
+      "enabled": true,
+      "cache_ttl_hours": 24
+    }
   },
   "constitution": {
     "enforce_tdd": true,

moai_adk/templates/.moai/hooks/install.sh

@@ -0,0 +1,79 @@
+#!/bin/bash
+# @CODE:DOC-TAG-004 | Component 1: Pre-commit hook installer
+#
+# This script installs the TAG validation pre-commit hook into .git/hooks/
+#
+# Usage:
+#   ./install.sh              # Install hook
+#   ./install.sh --uninstall  # Remove hook
+
+set -e
+
+# Colors
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+RED='\033[0;31m'
+NC='\033[0m'
+
+# Get repository root
+REPO_ROOT=$(git rev-parse --show-toplevel 2>/dev/null || echo ".")
+HOOK_SOURCE="${REPO_ROOT}/.moai/hooks/pre-commit.sh"
+HOOK_TARGET="${REPO_ROOT}/.git/hooks/pre-commit"
+
+# Function to install hook
+install_hook() {
+    echo "🔧 Installing TAG validation pre-commit hook..."
+
+    # Check if source exists
+    if [ ! -f "$HOOK_SOURCE" ]; then
+        echo -e "${RED}Error: Hook source not found at $HOOK_SOURCE${NC}"
+        exit 1
+    fi
+
+    # Check if target already exists
+    if [ -f "$HOOK_TARGET" ]; then
+        echo -e "${YELLOW}Warning: Pre-commit hook already exists.${NC}"
+        echo "Backing up existing hook to ${HOOK_TARGET}.backup"
+        cp "$HOOK_TARGET" "${HOOK_TARGET}.backup"
+    fi
+
+    # Create .git/hooks directory if it doesn't exist
+    mkdir -p "$(dirname "$HOOK_TARGET")"
+
+    # Copy hook
+    cp "$HOOK_SOURCE" "$HOOK_TARGET"
+    chmod +x "$HOOK_TARGET"
+
+    echo -e "${GREEN}✓ Pre-commit hook installed successfully!${NC}"
+    echo ""
+    echo "The hook will now validate TAG annotations on every commit."
+    echo ""
+    echo "To uninstall: $0 --uninstall"
+}
+
+# Function to uninstall hook
+uninstall_hook() {
+    echo "🔧 Uninstalling TAG validation pre-commit hook..."
+
+    if [ ! -f "$HOOK_TARGET" ]; then
+        echo -e "${YELLOW}No pre-commit hook installed.${NC}"
+        exit 0
+    fi
+
+    # Check if backup exists
+    if [ -f "${HOOK_TARGET}.backup" ]; then
+        echo "Restoring backup..."
+        mv "${HOOK_TARGET}.backup" "$HOOK_TARGET"
+        echo -e "${GREEN}✓ Backup restored.${NC}"
+    else
+        rm "$HOOK_TARGET"
+        echo -e "${GREEN}✓ Pre-commit hook removed.${NC}"
+    fi
+}
+
+# Parse command line arguments
+if [ "$1" = "--uninstall" ]; then
+    uninstall_hook
+else
+    install_hook
+fi

moai_adk/templates/.moai/hooks/pre-commit.sh

@@ -0,0 +1,66 @@
+#!/bin/bash
+# @CODE:DOC-TAG-004 | Component 1: Pre-commit hook for TAG validation
+#
+# This hook validates TAG annotations in staged files before commit.
+# It checks:
+# - TAG format (@DOC:DOMAIN-TYPE-NNN)
+# - Duplicate TAG detection
+# - Orphan TAG detection (warnings only)
+#
+# Exit codes:
+#   0 - Validation passed
+#   1 - Validation failed (duplicates or format errors)
+
+set -e  # Exit on error
+
+# Colors for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+NC='\033[0m' # No Color
+
+# Get repository root
+REPO_ROOT=$(git rev-parse --show-toplevel)
+
+# Check if Python module is available
+if ! python3 -c "import moai_adk.core.tags.pre_commit_validator" 2>/dev/null; then
+    echo -e "${YELLOW}Warning: moai_adk TAG validator not found.${NC}"
+    echo "Skipping TAG validation. Install moai_adk to enable validation."
+    exit 0
+fi
+
+# Get staged files
+STAGED_FILES=$(git diff --cached --name-only --diff-filter=ACM)
+
+if [ -z "$STAGED_FILES" ]; then
+    echo -e "${GREEN}No staged files to validate.${NC}"
+    exit 0
+fi
+
+echo "🔍 Validating TAG annotations in staged files..."
+
+# Run TAG validation
+# Pass staged files as arguments to validator
+python3 -m moai_adk.core.tags.pre_commit_validator \
+    --files $STAGED_FILES
+
+VALIDATION_RESULT=$?
+
+# Check result
+if [ $VALIDATION_RESULT -eq 0 ]; then
+    echo -e "${GREEN}✓ TAG validation passed.${NC}"
+    exit 0
+else
+    echo -e "${RED}✗ TAG validation failed.${NC}"
+    echo ""
+    echo "Commit blocked due to TAG validation errors."
+    echo ""
+    echo "To fix:"
+    echo "  1. Fix duplicate TAGs or format errors shown above"
+    echo "  2. Stage your changes with 'git add'"
+    echo "  3. Try committing again"
+    echo ""
+    echo "To skip this validation (not recommended):"
+    echo "  git commit --no-verify"
+    exit 1
+fi