Python POC for GitHub-based API Reviews (Phase 2)

.github/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "azure-sdk-for-python-github-tools",
+  "private": true,
+  "type": "module",
+  "description": "Pinned Node dependencies used by GitHub automation and API markdown workflows.",
+  "dependencies": {
+    "@apidevtools/json-schema-ref-parser": "^15.1.3",
+    "debug": "^4.4.3",
+    "js-yaml": "^4.1.0",
+    "marked": "^18.0.0",
+    "simple-git": "^3.36.0",
+    "zod": "^4.3.5"
+  },
+  "devDependencies": {
+    "@chronus/chronus": "1.3.1",
+    "@chronus/github": "1.0.6",
+    "@eslint/js": "^10.0.0",
+    "@tsconfig/node20": "^20.1.4",
+    "@types/debug": "^4.1.12",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.0.0",
+    "@types/semver": "^7.7.1",
+    "@vitest/coverage-v8": "^4.1.0",
+    "cross-env": "^10.1.0",
+    "eslint": "^10.0.0",
+    "globals": "^17.0.0",
+    "prettier": "3.8.3",
+    "prettier-plugin-organize-imports": "^4.2.0",
+    "semver": "^7.7.1",
+    "tinybench": "^6.0.0",
+    "typescript": "~6.0.2",
+    "typescript-eslint": "^8.58.0",
+    "vitest": "^4.1.0"
+  }
+}

.github/workflows/api-consistency.yml

@@ -59,3 +59,12 @@ jobs:
             const { default: apiMdConsistency } =
               await import('${{ github.workspace }}/.github/workflows/src/api-md-consistency/api-md-consistency.js');
             return await apiMdConsistency({ github, context, core });
+
+      - name: Upload affected API.md packages
+        if: always()
+        uses: actions/upload-artifact@v7
+        with:
+          name: api-md-affected-packages
+          path: .artifacts/affected_package_dirs.txt
+          if-no-files-found: error
+          include-hidden-files: true

.github/workflows/api-md-dispatch-review-syncs.yml

@@ -0,0 +1,82 @@
+name: API.md Dispatch Review Syncs
+
+on:
+  workflow_run:
+    workflows: ["API.md Consistency"]
+    types: [completed]
+  status:
+  check_run:
+    types: [completed]
+
+permissions:
+  actions: write
+  checks: read
+  contents: read
+  pull-requests: read
+  statuses: read
+
+concurrency:
+  group: api-md-dispatch-review-syncs-${{ github.event.workflow_run.head_sha || github.event.check_run.head_sha || github.event.sha }}
+  cancel-in-progress: true
+
+jobs:
+  dispatch:
+    if: >-
+      github.event_name != 'check_run' || github.event.check_run.name != 'dispatch'
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout trusted workflow scripts
+        uses: actions/checkout@v6
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: lts/*
+
+      - name: Resolve final CI gate
+        id: gate
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          node .github/workflows/src/api-md-review-sync/dispatch_review_branch_syncs.js
+          --resolve-gate
+          --working-sha "${{ github.event.workflow_run.head_sha || github.event.check_run.head_sha || github.event.sha }}"
+          --consistency-run-id "${{ github.event.workflow_run.id || '' }}"
+          --current-run-id "${{ github.run_id }}"
+
+      - name: Checkout working SHA for package metadata
+        if: ${{ steps.gate.outputs.should_dispatch == 'true' }}
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ steps.gate.outputs.working_owner }}/azure-sdk-for-python
+          ref: ${{ steps.gate.outputs.working_sha }}
+          path: working
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Download API.md consistency artifacts
+        if: ${{ steps.gate.outputs.should_dispatch == 'true' }}
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh run download "${{ steps.gate.outputs.consistency_run_id }}" --name api-md-affected-packages --dir .artifacts
+
+      - name: Dispatch matching review branch syncs
+        if: ${{ steps.gate.outputs.should_dispatch == 'true' && hashFiles('.artifacts/affected_package_dirs.txt') != '' }}
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          node .github/workflows/src/api-md-review-sync/dispatch_review_branch_syncs.js
+          --packages-file .artifacts/affected_package_dirs.txt
+          --working-owner "${{ steps.gate.outputs.working_owner }}"
+          --working-branch "${{ steps.gate.outputs.working_branch }}"
+          --working-sha "${{ steps.gate.outputs.working_sha }}"
+          --repo-root working
+
+      - name: No affected packages
+        if: ${{ steps.gate.outputs.should_dispatch == 'true' && hashFiles('.artifacts/affected_package_dirs.txt') == '' }}
+        run: echo "No affected API.md packages were published by the consistency run."
+
+      - name: Final CI gate not ready
+        if: ${{ steps.gate.outputs.should_dispatch != 'true' }}
+        run: echo "${{ steps.gate.outputs.reason }}"

.github/workflows/api-md-sync-review-branch.yml

@@ -0,0 +1,72 @@
+name: API.md Sync Review Branch
+
+on:
+  workflow_dispatch:
+    inputs:
+      packageDir:
+        description: Package directory containing api.md and api.metadata.yml.
+        required: true
+      reviewBranch:
+        description: API review branch to update.
+        required: true
+      workingOwner:
+        description: Owner of the working branch repository.
+        required: true
+      workingBranch:
+        description: Working branch name.
+        required: true
+      workingSha:
+        description: Consistency-verified working branch SHA.
+        required: true
+
+permissions:
+  contents: write
+
+concurrency:
+  group: api-md-sync-review-branch-${{ inputs.reviewBranch }}
+  cancel-in-progress: false
+
+jobs:
+  sync:
+    if: ${{ startsWith(inputs.reviewBranch, 'apireview/review_') && !startsWith(inputs.workingBranch, 'apireview/') }}
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout trusted workflow scripts
+        uses: actions/checkout@v6
+        with:
+          path: trusted
+
+      - name: Checkout working SHA
+        uses: actions/checkout@v6
+        with:
+          repository: ${{ inputs.workingOwner }}/azure-sdk-for-python
+          ref: ${{ inputs.workingSha }}
+          path: working
+          fetch-depth: 1
+          persist-credentials: false
+
+      - name: Checkout review branch
+        uses: actions/checkout@v6
+        with:
+          ref: ${{ inputs.reviewBranch }}
+          path: review
+          fetch-depth: 1
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v6
+        with:
+          node-version: lts/*
+
+      - name: Sync API.md artifacts
+        working-directory: review
+        env:
+          GITHUB_TOKEN: ${{ github.token }}
+        run: >-
+          node ../trusted/.github/workflows/src/api-md-review-sync/sync_review_branch.js
+          --working-root ../working
+          --review-root .
+          --package-dir "${{ inputs.packageDir }}"
+          --review-branch "${{ inputs.reviewBranch }}"
+          --working-owner "${{ inputs.workingOwner }}"
+          --working-branch "${{ inputs.workingBranch }}"
+          --working-sha "${{ inputs.workingSha }}"