Refactor review create script to Python.

Author: tjprescott

.github/skills/create-api-review-pr/SKILL.md

@@ -5,20 +5,19 @@ description: Create a GitHub PR for API review by comparing a baseline API surfa
 
 # Create API Review PR
 
-Creates a dedicated API review PR that shows the diff between a baseline release and a target tag or branch's API surface using `scripts/api_md_workflow/create_api_review_pr.js`.
+Creates a dedicated API review PR that shows the diff between a baseline release and a target tag or branch's API surface using `scripts/api_md_workflow/create_api_review_pr.py`.
 
 ## Unsupported Requests
 
-If the user asks to create an API review PR for a new package, explain that new packages do not use API review PRs and stop. Do not gather script inputs or run `create_api_review_pr.js` for new packages.
+If the user asks to create an API review PR for a new package, explain that new packages do not use API review PRs and stop. Do not gather script inputs or run `create_api_review_pr.py` for new packages.
 
 ## Prerequisites
 
 1. The user must have `gh` CLI installed and authenticated (`gh auth login`), or `GITHUB_TOKEN`/`GH_TOKEN` set with permission to create and update pull requests in this repository.
 2. The working tree must be clean (no uncommitted changes).
-3. The latest Node.js LTS must be installed.
-4. API.md workflow Node dependencies must be installed (`npm ci` from `scripts/api_md_workflow`).
-5. `azpysdk` must be installed (`pip install -e ./eng/tools/azure-sdk-tools`).
-6. ApiView stub generator dependencies must be installed (`pip install -r ./eng/apiview_reqs.txt`).
+3. Python 3.10 or later must be available.
+4. `azpysdk` must be installed (`pip install -e ./eng/tools/azure-sdk-tools`).
+5. ApiView stub generator dependencies must be installed (`pip install -r ./eng/apiview_reqs.txt`).
 
 ## Information to Gather
 
@@ -52,31 +51,31 @@ Before running the script:
 
 This is a long-running operation. The script may take several minutes because it generates API surfaces for both the baseline and target, creates or reuses review branches, pushes branches, and then opens the draft PR. Do not treat quiet terminal periods during `apistub` generation as failure unless the command exits, prints an error, or waits for input.
 
-If `create_api_review_pr.js` fails while running this skill, do not patch the script, modify package files, retry with workaround edits, or try to manually complete branch/PR creation. Stop the workflow, report the failure clearly, include the relevant error details, and suggest practical next steps.
+If `create_api_review_pr.py` fails while running this skill, do not patch the script, modify package files, retry with workaround edits, or try to manually complete branch/PR creation. Stop the workflow, report the failure clearly, include the relevant error details, and suggest practical next steps.
 
 If the script reports that there are no API differences, relay that message to the user and stop. Do not create branches or a PR manually.
 
 Run the following command from the repository root:
 
 ```bash
-node scripts/api_md_workflow/create_api_review_pr.js --package-name <package-name> --base <tag> [--target <target>]
+python scripts/api_md_workflow/create_api_review_pr.py --package-name <package-name> --base <tag> [--target <target>]
 ```
 
 ### Examples
 
 **Standard review (comparing a release tag to a PR branch):**
 ```bash
-node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-storage-blob --base azure-storage-blob_12.29.0 --target someone:feature-branch
+python scripts/api_md_workflow/create_api_review_pr.py --package-name azure-storage-blob --base azure-storage-blob_12.29.0 --target someone:feature-branch
 ```
 
 **Release-to-release review (comparing two package tags):**
 ```bash
-node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-ai-projects --base azure-ai-projects_2.1.0 --target azure-ai-projects_2.2.0
+python scripts/api_md_workflow/create_api_review_pr.py --package-name azure-ai-projects --base azure-ai-projects_2.1.0 --target azure-ai-projects_2.2.0
 ```
 
 **Review against main (no target specified):**
 ```bash
-node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-cosmos --base azure-cosmos_4.14.0
+python scripts/api_md_workflow/create_api_review_pr.py --package-name azure-cosmos --base azure-cosmos_4.14.0
 ```
 
 ## Post-Execution

scripts/api_md_workflow/adapter_config.js …src/api-md-consistency/adapter_config.jsscripts/api_md_workflow/adapter_config.js renamed to .github/workflows/src/api-md-consistency/adapter_config.js scripts/api_md_workflow/adapter_config.js renamed to .github/workflows/src/api-md-consistency/adapter_config.js

@@ -79,7 +79,7 @@ function formatIssueSection(title, apiFiles) {
 module.exports = async function apiMdConsistency({ core }) {
   const workspace = process.env.GITHUB_WORKSPACE || process.cwd();
 
-  await runNode("scripts/api_md_workflow/find_affected.js", workspace, core);
+  await runNode(".github/workflows/src/api-md-consistency/find_affected.js", workspace, core);
 
   const affected = readLines(process.env.API_MD_PACKAGES_FILE, workspace);
   const changedCount = affected.length;
@@ -97,8 +97,8 @@ module.exports = async function apiMdConsistency({ core }) {
     };
   }
 
-  await runNode("scripts/api_md_workflow/regenerate.js", workspace, core);
-  await runNode("scripts/api_md_workflow/find_mismatches.js", workspace, core);
+  await runNode(".github/workflows/src/api-md-consistency/regenerate.js", workspace, core);
+  await runNode(".github/workflows/src/api-md-consistency/find_mismatches.js", workspace, core);
 
   const mismatches = readLines(process.env.API_MD_MISMATCHES_FILE, workspace);
   const missing = readLines(process.env.API_MD_MISSING_FILE, workspace);

…ripts/api_md_workflow/adapters/python.js …rc/api-md-consistency/adapters/python.jsscripts/api_md_workflow/adapters/python.js renamed to .github/workflows/src/api-md-consistency/adapters/python.js scripts/api_md_workflow/adapters/python.js renamed to .github/workflows/src/api-md-consistency/adapters/python.js

@@ -4,7 +4,7 @@ const fs = require("fs");
 const path = require("path");
 const { pathToFileURL } = require("url");
 
-const REPO_ROOT = path.resolve(__dirname, "..", "..");
+const REPO_ROOT = path.resolve(__dirname, "..", "..", "..", "..");
 const SHARED_SRC_ROOT = path.join(REPO_ROOT, ".github", "shared", "src");
 const sharedModuleCache = new Map();
 

.github/workflows/src/api-md-consistency/api-md-consistency.js

@@ -1,111 +1,21 @@
-# api.md Workflow Helpers
+# API Review PR Helper
 
-This folder contains the helper scripts used by the GitHub Actions workflows that validate and update `api.md` files for changed SDK packages.
+This folder contains the standalone Python helper used to create API review PRs from generated `api.md` files.
 
 ## Purpose
 
-The workflow validates that when a pull request changes one or more SDK packages, the committed `api.md` files are still up to date.
-`api.md` content is diff-gated by this workflow, and `api.metadata.yml` must be committed alongside it.
-The workflow also validates adapter-selected metadata fields, such as `apiMdSha256` and `parserVersion`, so metadata differences can affect pass/fail.
+`create_api_review_pr.py` compares a baseline package release tag with a target API surface, creates or reuses dedicated API review branches, and opens a draft PR that shows the `api.md` diff.
 
-The logic is split between GitHub workflow YAML files and helper scripts in Python and JavaScript.
+The API consistency workflow helpers live under `.github/workflows/src/api-md-consistency`.
 
-## Workflow Files
+## Usage
 
-### `.github/workflows/api-consistency.yml`
+The script includes Python package discovery, version parsing, `api.md` generation, git branch orchestration, and GitHub PR creation in one file.
 
-This is the main workflow.
-
-It runs on pull requests for changes under `sdk/**`.
-
-- Detects affected package directories from the PR diff.
-- Regenerates `api.md` for those packages.
-- Fails if the generated files differ from the committed files.
-- Fails if an affected package does not have a committed `api.md`.
-- Prints the mismatched or missing packages and the `azpysdk apistub --md --extract-metadata <package-name> --dest-dir .` command needed to regenerate each `api.md` file from the repository root.
-
-## Script Layout
-
-### `common.js`
-
-Shared helpers used by the other scripts:
-
-- repository root resolution
-- subprocess execution
-- reading/writing line-based artifact files
-- writing GitHub Actions outputs
-- GitHub REST API helpers for listing/updating comments
-
-### `find_affected.js`
-
-Used by the `consistency` job.
-
-Reads `API_MD_BASE_REF`, compares the PR branch to `origin/<base>`, and writes:
-
-- changed package directories to `API_MD_CHANGED_FILE`
-- valid package roots to `API_MD_PACKAGES_FILE`
-
-Also writes `count=<n>` to `GITHUB_OUTPUT`.
-
-### `regenerate.js`
-
-Reads package directories from `API_MD_PACKAGES_FILE` and runs `azpysdk apistub --md --extract-metadata <package-name> --dest-dir <package-dir>` for each package from the repository root.
-
-This script is used by the consistency check.
-
-### `find_mismatches.js`
-
-Reads package directories from `API_MD_PACKAGES_FILE`, checks whether `<package>/api.md` is missing/untracked or differs from git, and writes:
-
-- mismatched files to `API_MD_MISMATCHES_FILE`
-- missing files to `API_MD_MISSING_FILE`
-
-Also writes `mismatch_count=<n>`, `missing_count=<n>`, and `issue_count=<n>` to `GITHUB_OUTPUT`.
-
-`api.metadata.yml` is also required and selected metadata fields are mismatch-checked according to the active adapter.
-
-### `create_api_review_pr.js` and adapters
-
-API review PR creation now uses a shared JavaScript orchestrator with a language adapter boundary:
-
-- `create_api_review_pr.js`: shared git/branch/PR orchestration logic.
-- `adapters/python.js`: Python-specific package discovery, version parsing, and `api.md` generation.
-
-This split allows the core workflow to be reused across other language repos while keeping generation behavior language-specific.
-
-`create_api_review_pr.js` compares a baseline package release tag with a target API surface. The target can be a package release tag, an `origin` branch, or an `owner:branch` fork reference. When the target is a tag, the generated PR body identifies it as a target tag instead of a working branch.
+`create_api_review_pr.py` compares a baseline package release tag with a target API surface. The target can be a package release tag, an `origin` branch, or an `owner:branch` fork reference. When the target is a tag, the generated PR body identifies it as a target tag instead of a working branch.
 
 Example comparing two package release tags:
 
 ```bash
-node scripts/api_md_workflow/create_api_review_pr.js --package-name azure-ai-projects --base azure-ai-projects_2.1.0 --target azure-ai-projects_2.2.0
+python scripts/api_md_workflow/create_api_review_pr.py --package-name azure-ai-projects --base azure-ai-projects_2.1.0 --target azure-ai-projects_2.2.0
 ```
-
-### `api_md_workflow.config.json`
-
-Shared configuration for adapter selection across `api_md_workflow` scripts.
-
-- `adapter`: default adapter name (for this repo: `python`)
-
-Both `create_api_review_pr.js` and `find_affected.js` read this file for adapter selection.
-
-## Environment Variables Used
-
-The scripts are intentionally simple and read inputs from environment variables set by the workflow steps.
-
-Common variables include:
-
-- `API_MD_BASE_REF`
-- `API_MD_PACKAGES_FILE`
-- `API_MD_CHANGED_FILE`
-- `API_MD_MISMATCHES_FILE`
-- `API_MD_MISSING_FILE`
-
-## End-to-End Flow
-
-1. A PR changes files under `sdk/**`.
-2. `consistency.yml` runs.
-3. `find_affected.js` determines which packages were touched.
-4. `regenerate.js` rebuilds `api.md` for those packages.
-5. `find_mismatches.js` records any `api.md` drift, including missing or untracked `api.md` files.
-6. If drift is found, the workflow fails and prints the affected packages plus the `azpysdk apistub --md --extract-metadata <package-name> --dest-dir .` command to regenerate each `api.md` file locally from the repository root.