type-check.yml

name: PEP 561 Type Distribution

on:
  # Run on push to master and pull requests
  push:
    branches:
      - "master"
    paths:
      # GitHub Action workflow files
      - ".github/workflows/type-check.yml"
      # Type definition files
      - "agent_assembly/types.py"
      - "agent_assembly/py.typed"
      - "agent_assembly/__init__.py"
      # Configuration files
      - "pyproject.toml"
      - "uv.lock"

  pull_request:
    branches:
      - "master"
    paths:
      # GitHub Action workflow files
      - ".github/workflows/type-check.yml"
      # Type definition files
      - "agent_assembly/types.py"
      - "agent_assembly/py.typed"
      - "agent_assembly/__init__.py"
      # Configuration files
      - "pyproject.toml"
      - "uv.lock"

  # Allow manual trigger
  workflow_dispatch:

jobs:
  verify-pep561-compliance:
    name: Verify PEP 561 Compliance
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          python-version: 3.13

      - name: Verify py.typed marker exists
        run: |
          if [ ! -f "agent_assembly/py.typed" ]; then
            echo "❌ Error: py.typed marker file not found!"
            echo "PEP 561 requires a py.typed file in the package directory."
            exit 1
          fi
          echo "✅ py.typed marker file exists"

      - name: Verify types.py module exists
        run: |
          if [ ! -f "agent_assembly/types.py" ]; then
            echo "❌ Error: types.py module not found!"
            exit 1
          fi
          echo "✅ types.py module exists"

      - name: Check types.py has __all__ export
        run: |
          if ! grep -q "__all__" agent_assembly/types.py; then
            echo "❌ Error: types.py missing __all__ export!"
            exit 1
          fi
          echo "✅ types.py has __all__ export"

      - name: Verify pyproject.toml includes py.typed
        run: |
          if ! grep -q "py.typed" pyproject.toml; then
            echo "❌ Error: pyproject.toml does not include py.typed in artifacts!"
            exit 1
          fi
          echo "✅ pyproject.toml includes py.typed in artifacts"

      - name: Build package and verify py.typed inclusion
        run: |
          uv build --sdist --wheel
          
          # Check sdist
          echo "Checking source distribution..."
          if tar -tzf dist/*.tar.gz | grep -q "agent_assembly/py.typed"; then
            echo "✅ py.typed found in source distribution"
          else
            echo "❌ Error: py.typed not found in source distribution!"
            exit 1
          fi
          
          # Check wheel
          echo "Checking wheel distribution..."
          if unzip -l dist/*.whl | grep -q "agent_assembly/py.typed"; then
            echo "✅ py.typed found in wheel distribution"
          else
            echo "❌ Error: py.typed not found in wheel distribution!"
            exit 1
          fi
          
          # Check types.py in distributions
          echo "Checking types.py in distributions..."
          if tar -tzf dist/*.tar.gz | grep -q "agent_assembly/types.py"; then
            echo "✅ types.py found in source distribution"
          else
            echo "❌ Error: types.py not found in source distribution!"
            exit 1
          fi
          
          if unzip -l dist/*.whl | grep -q "agent_assembly/types.py"; then
            echo "✅ types.py found in wheel distribution"
          else
            echo "❌ Error: types.py not found in wheel distribution!"
            exit 1
          fi

  test-type-imports:
    name: Test Type Imports
    runs-on: ubuntu-latest

    steps:
      - name: Checkout repository
        uses: actions/checkout@v6

      - name: Install uv
        uses: astral-sh/setup-uv@v7
        with:
          python-version: 3.13

      - name: Install package
        run: |
          uv sync --all-extras

      - name: Test importing agent_assembly.types module
        run: |
          uv run python -c "
          from agent_assembly import types
          print('✅ Successfully imported agent_assembly.types module')
          print(f'✅ Available exports: {len(types.__all__)} symbols')
          "

      - name: Test agent_assembly.types public exports are accessible
        run: |
          uv run python -c "
          from agent_assembly import types

          # __all__ pins the public surface; AAASM-1419 added CallStackNode + CallStackNodeKind.
          expected = {'AuditEvent', 'CallStackNode', 'CallStackNodeKind'}
          declared = set(types.__all__)
          assert expected <= declared, (
              f'agent_assembly.types.__all__ missing expected exports: '
              f'{expected - declared}; declared={declared}'
          )
          print(f'✅ __all__ contains the expected public exports: {sorted(expected)}')

          for name in expected:
              assert hasattr(types, name), f'agent_assembly.types is missing attribute {name!r}'
          print(f'✅ All expected attributes resolve on the types module')
          "

      - name: Test top-level lazy re-exports resolve to the same objects
        run: |
          uv run python -c "
          import agent_assembly
          from agent_assembly import types

          # agent_assembly/__init__.py lazily re-exports these from agent_assembly.types
          # via PEP 562; verify the lazy-import indirection still resolves to the
          # same identity (no stale cached objects, no shadowing).
          for name in ('AuditEvent', 'CallStackNode', 'CallStackNodeKind'):
              top = getattr(agent_assembly, name)
              direct = getattr(types, name)
              assert top is direct, (
                  f'agent_assembly.{name} is not agent_assembly.types.{name}: '
                  f'{top!r} vs {direct!r}'
              )
          print('✅ Top-level lazy re-exports resolve to the same objects as agent_assembly.types')
          "

  summary:
    name: PEP 561 Summary
    runs-on: ubuntu-latest
    needs: [verify-pep561-compliance, test-type-imports]
    if: always()

    steps:
      - name: Check all jobs status
        run: |
          echo "## PEP 561 Type Distribution Results" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "ℹ️ **Note**: MyPy source code checking is handled by pre-commit hooks" >> $GITHUB_STEP_SUMMARY
          echo "" >> $GITHUB_STEP_SUMMARY
          
          if [ "${{ needs.verify-pep561-compliance.result }}" == "success" ]; then
            echo "✅ PEP 561 compliance: **PASSED**" >> $GITHUB_STEP_SUMMARY
          else
            echo "❌ PEP 561 compliance: **FAILED**" >> $GITHUB_STEP_SUMMARY
          fi
          
          if [ "${{ needs.test-type-imports.result }}" == "success" ]; then
            echo "✅ Type imports: **PASSED**" >> $GITHUB_STEP_SUMMARY
          else
            echo "❌ Type imports: **FAILED**" >> $GITHUB_STEP_SUMMARY
          fi
          
          echo "" >> $GITHUB_STEP_SUMMARY
          echo "### PEP Standards Verified" >> $GITHUB_STEP_SUMMARY
          echo "- PEP 561: Distributing and Packaging Type Information" >> $GITHUB_STEP_SUMMARY
          echo "- PEP 484: Type Hints" >> $GITHUB_STEP_SUMMARY
          echo "- PEP 585: Type Hinting Generics" >> $GITHUB_STEP_SUMMARY
          echo "- PEP 544: Protocols (Structural Subtyping)" >> $GITHUB_STEP_SUMMARY

      - name: Fail if any job failed
        if: |
          needs.verify-pep561-compliance.result != 'success' ||
          needs.test-type-imports.result != 'success'
        run: |
          echo "❌ One or more PEP 561 validation jobs failed!"
          exit 1