chore(dev): static api analysis

.github/workflows/api-report-approval.yaml

@@ -0,0 +1,78 @@
+name: API Report Approval
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'packages/aft/api_reports/*.api.json'
+
+jobs:
+  label-api-changes:
+    name: Label API Changes
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Check for API changes
+        id: check-api-changes
+        run: |
+          # Check for changes in API JSON files
+          API_JSON_CHANGES=$(git diff --name-only origin/main...HEAD | grep -E 'packages/aft/api_reports/.*\.api\.json' || true)
+
+          if [[ -n "$API_JSON_CHANGES" ]]; then
+            echo "API_CHANGES_DETECTED=true" >> $GITHUB_ENV
+            echo "API changes detected in the following files:"
+            echo "$API_JSON_CHANGES"
+          else
+            echo "API_CHANGES_DETECTED=false" >> $GITHUB_ENV
+            echo "No API changes detected."
+          fi
+
+      - name: Add API changes label
+        if: env.API_CHANGES_DETECTED == 'true'
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            github.rest.issues.addLabels({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              labels: ['api-changes']
+            })
+
+      - name: Comment on PR
+        if: env.API_CHANGES_DETECTED == 'true'
+        uses: actions/github-script@v6
+        with:
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          script: |
+            // Check if we already commented about API changes
+            const commentMarker = '⚠️ This PR contains API changes';
+            const { data: comments } = await github.rest.issues.listComments({
+              issue_number: context.issue.number,
+              owner: context.repo.owner,
+              repo: context.repo.repo
+            });
+
+            // Look for an existing comment with our marker
+            const apiChangeComment = comments.find(comment => 
+              comment.body.includes(commentMarker) && 
+              comment.user.login === 'github-actions[bot]'
+            );
+
+            // Only create a comment if we haven't already
+            if (!apiChangeComment) {
+              await github.rest.issues.createComment({
+                issue_number: context.issue.number,
+                owner: context.repo.owner,
+                repo: context.repo.repo,
+                body: '⚠️ This PR contains API changes and requires careful review. Please ensure these changes are intentional and backward compatible where possible.'
+              });
+            } else {
+              console.log('API changes comment already exists, skipping comment creation');
+            }

.github/workflows/api-report-check.yaml

@@ -0,0 +1,115 @@
+name: API Report Check
+
+on:
+  pull_request:
+    branches:
+      - main
+    paths:
+      - 'packages/**/*.dart'
+      - 'packages/**/pubspec.yaml'
+      - '!packages/**/example/**'
+      - '!packages/**/test/**'
+
+jobs:
+  check-api-reports:
+    name: Check API Reports
+    runs-on: ubuntu-latest
+    steps:
+      - name: Git Checkout
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Setup Flutter
+        uses: subosito/flutter-action@v2
+        with:
+          cache: true
+          channel: 'stable'
+          flutter-version: '3.32.4'
+
+      - name: Setup aft
+        run: flutter pub global activate -spath packages/aft
+
+      - name: Bootstrap
+        id: bootstrap
+        timeout-minutes: 20
+        run: aft bootstrap --fail-fast --include=aft --verbose
+
+      - name: Install dart_apitool
+        run: flutter pub global activate dart_apitool
+
+      - name: Generate API reports
+        run: aft generate api-report
+
+      - name: Check for changes in API reports
+        id: check-changes
+        run: |
+          # Debug: Print git status
+          echo "=== DEBUG: Git status ==="
+          git status --porcelain
+
+          # Check API JSON files for changes
+          API_JSON_CHANGES=$(git status --porcelain | grep 'packages/aft/api_reports/.*\.api\.json' || true)
+
+          if [[ -n "$API_JSON_CHANGES" ]]; then
+            echo "API report files have changes. Checking if they are actual API changes..."
+            git diff --name-only | grep -E 'packages/aft/api_reports/.*\.api\.json'
+
+            ACTUAL_API_CHANGES=false
+
+            # Compare API interfaces using sets instead of text diff
+            # We're comparing the PR's committed API reports vs freshly generated ones
+            for file in $(git diff --name-only | grep -E 'packages/aft/api_reports/.*\.api\.json'); do
+              echo "=== Checking API changes in: $file ==="
+
+              # Get the version from the PR (what developer committed)
+              git show HEAD:"$file" | jq -r '.interfaceDeclarations[] | tostring' > /tmp/pr_interfaces.txt 2>/dev/null || touch /tmp/pr_interfaces.txt
+
+              # Get the freshly generated version (what CI just created)
+              jq -r '.interfaceDeclarations[] | tostring' "$file" > /tmp/generated_interfaces.txt
+
+              # Compare the interface sets
+              if ! cmp -s /tmp/pr_interfaces.txt /tmp/generated_interfaces.txt; then
+                echo "=== ACTUAL API CHANGES DETECTED in: $file ==="
+                echo "The API report in your PR doesn't match the current code. Please run 'aft generate api-report' and commit the changes."
+                echo "Full diff for debugging:"
+                git diff "$file"
+                ACTUAL_API_CHANGES=true
+              else
+                echo "API report is up-to-date for: $file"
+              fi
+
+              rm -f /tmp/pr_interfaces.txt /tmp/generated_interfaces.txt
+            done
+
+            if [[ "$ACTUAL_API_CHANGES" == "true" ]]; then
+              echo "ERROR: API report files are not up-to-date. Please run 'aft generate api-report' and commit the changes."
+              exit 1
+            else
+              echo "All API reports are up-to-date (detected only ordering differences)."
+            fi
+          else
+            echo "API report files are up-to-date."
+          fi
+
+      - name: Check if API reports are included in PR
+        run: |
+          # Get the list of changed files in the PR
+          CHANGED_FILES=$(git diff --name-only origin/main...HEAD)
+
+          # Check if any Dart files were modified
+          DART_FILES=$(echo "$CHANGED_FILES" | grep -E '\.dart$' || true)
+          if [[ -z "$DART_FILES" ]]; then
+            echo "No Dart files were modified, skipping API report check."
+            exit 0
+          fi
+
+          # Check if API report files are included
+          API_REPORTS=$(echo "$CHANGED_FILES" | grep -E 'packages/aft/api_reports/.*\.api\.json' || true)
+          if [[ -z "$API_REPORTS" ]]; then
+            echo "Error: API report files are not included in this PR."
+            echo "Please run 'aft generate api-report' and commit the changes."
+            exit 1
+          fi
+
+          echo "API report files are included in the PR."

packages/aft/README.md

@@ -18,6 +18,7 @@ A CLI tool for managing the Amplify Flutter repository.
 - `exec`: Execute a command in all repo packages
 - `generate`: Generates various repo items
   - `workflows`: Generates GitHub actions workflows for all packages in the repo
+  - `api-report`: Generates API reports for all packages (run before every PR)
 - `link`: Links all packages together using `pubspec_overrides.yaml`
 - `list`: Lists all packages in the repo
 - `publish`: Runs `dart pub publish`/`flutter pub publish` for all packages which need publishing
@@ -133,3 +134,13 @@ Currently, a Map with the following shape is available for querying:
 ```
 
 The script passed to `run` is templated each time it is run with the current package. So when using `{{ package.name }}` in a script, for example, it will always reference the package currently running the script.
+
+## API Reports
+
+Before submitting a pull request that modifies Dart code, you must generate updated API reports:
+
+```sh
+$ aft generate api-report
+```
+
+This command analyzes the public API of all packages and generates JSON reports that are checked in CI. The reports help track API changes and ensure they are intentional. Always run this command and commit the generated files when your PR modifies any `.dart` files. Use the ```--include``` option to run on specific packages.

packages/aft/api_reports/.gitignore

@@ -0,0 +1,2 @@
+# Don't ignore any files in this directory
+!*