Azure · heaths · Jul 15, 2026 · Jul 16, 2026
@@ -272,7 +272,7 @@ function Get-rust-PackageInfoFromPackageFile([IO.FileInfo]$pkg, [string]$working
 }
 
 function Find-rust-Artifacts-For-Apireview([string]$ArtifactPath, [string]$packageName) {
-  [array]$files = Get-ChildItem -Path $ArtifactPath -Recurse -Filter "$packageName.rust.json"
+  [array]$files = Get-ChildItem -Path $ArtifactPath -Recurse -Filter "$packageName`_rust.json"
 
   if (!$files) {
     Write-Host "$($packageName) does not have api review json"

@@ -16,6 +16,8 @@ param(
   [string] $PackageInfoDirectory,
 
   [switch] $Release,
+  # Temporary testing switch; may be removed in a future version.
+  [switch] $APIReview,
   [switch] $NoVerify,
   [string] $OutBuildOrderFile
 )
@@ -109,15 +111,25 @@ function Get-OutputPackageNames($packages) {
   return $names
 }
 
-function Create-ApiViewFile($package) {
-  $packageName = $package.name
+function New-ApiFile(
+  $package,
+  [string] $Format,
+  [string] $OutputDirectory
+) {
   $manifestPath = $package.manifest_path
-  $command = "cargo run --manifest-path $RepoRoot/eng/tools/generate_api_report/Cargo.toml -- --package $packageName --manifest-path $manifestPath"
+  $command = "cargo run --manifest-path `"$RepoRoot/eng/tools/Cargo.toml`" -p generate_api -- --manifest-path `"$manifestPath`" --format $Format --output `"$OutputDirectory`""
   Invoke-LoggedCommand $command -GroupOutput | Out-Host
 
-  $packagePath = Split-Path -Path $manifestPath -Parent
+  $fileName = switch ($Format) {
+    'markdown' { 'API.md' }
+    'apiview' { 'apiview.json' }
+    default {
+      LogError "Unsupported API output format '$Format'"
+      exit 1
+    }
+  }
 
-  "$packagePath/review/$packageName.rust.json"
+  return [System.IO.Path]::Combine($OutputDirectory, $fileName)
 }
 
 function Get-CratePath(
@@ -184,6 +196,14 @@ try {
     exit $LASTEXITCODE
   }
 
+  if ($APIReview) {
+    foreach ($package in $packages) {
+      $packagePath = Split-Path -Path $package.manifest_path -Parent
+      Write-Host "Creating API review markdown at '$packagePath'"
+      New-ApiFile -package $package -Format 'markdown' -OutputDirectory $packagePath | Out-Null
+    }
+  }
+
   if ($OutputPath) {
     $OutputPath = New-Item -ItemType Directory -Path $OutputPath -Force | Select-Object -ExpandProperty FullName
 
@@ -197,7 +217,7 @@ try {
 
       $targetPath = [System.IO.Path]::Combine($OutputPath, $package.name)
       $targetContentsPath = [System.IO.Path]::Combine($targetPath, "contents")
-      $targetApiReviewFile = [System.IO.Path]::Combine($targetPath, "$($package.name).rust.json")
+      $targetApiReviewFile = [System.IO.Path]::Combine($targetPath, "$($package.name)_rust.json")
 
       if (Test-Path -Path $targetContentsPath) {
         Remove-Item -Path $targetContentsPath -Recurse -Force
@@ -210,11 +230,14 @@ try {
       Write-Host "Copying .crate file for '$($package.name)' to '$targetPath'"
       Copy-Item -Path $cratePath -Destination $targetPath -Force
 
-      Write-Host "Creating API review file"
-      $apiReviewFile = Create-ApiViewFile $package
+      if (-not $APIReview) {
+        Write-Host "Creating API review file"
+        $apiReviewFile = New-ApiFile -package $package -Format 'apiview' -OutputDirectory $targetPath
 
-      Write-Host "Copying API review file to '$targetApiReviewFile'"
-      Copy-Item -Path $apiReviewFile -Destination $targetApiReviewFile -Force
+        Write-Host "Copying API review file to '$targetApiReviewFile'"
+        Copy-Item -Path $apiReviewFile -Destination $targetApiReviewFile -Force
+        Remove-Item -Path $apiReviewFile -Force
+      }
     }
   }
 

@@ -1,5 +1,6 @@
 [package]
 name = "generate_api"
+version = "2.0.0"
 authors.workspace = true
 edition.workspace = true
 license.workspace = true

@@ -9,7 +9,7 @@ Run from the repository root:
 ```sh
 cargo run --manifest-path eng/tools/Cargo.toml -p generate_api -- \
   --manifest-path sdk/core/azure_core/Cargo.toml \
-  --output /tmp/generate_api
+  --output target/generate_api/azure_core
 ```
 
 ### Arguments
@@ -25,17 +25,7 @@ cargo run --manifest-path eng/tools/Cargo.toml -p generate_api -- \
 - `--format apiview` writes `apiview.json`
 - `--format apiview --no-docs` writes `apiview.json` without doc comment tokens
 
-## Toolchain
-
-The tool reads `eng/tools/rust-toolchain.toml` and invokes:
-
-```sh
-cargo +nightly-2025-05-09 rustdoc -Z unstable-options --output-format json
-```
-
-`rustc-dev` is included in that toolchain so the implementation can continue moving toward a more direct compiler/HIR-backed pipeline.
-
-## Pipeline entrypoints
+## Workflow
 
 The current API review caller chain under `eng/pipelines/` is:
 
@@ -45,12 +35,20 @@ The current API review caller chain under `eng/pipelines/` is:
 4. `eng/pipelines/templates/jobs/pack.yml`
 5. `eng/scripts/Pack-Crates.ps1`
 
-`pack.yml` also runs the shared `create-apireview` step. Today `Pack-Crates.ps1` still invokes
-`eng/tools/generate_api_report` to produce the API review artifact consumed by that step.
+From that path:
 
-## Current state
+- `Pack-Crates.ps1` runs `generate_api --format apiview` for each packed crate.
+- The staged package artifact keeps the existing downstream shape by renaming that output to
+  `<package>/<package>_rust.json`.
+- The shared `create-apireview` pipeline step consumes that staged JSON artifact.
 
-- The CLI is implemented and validates its APIView output shape.
-- A shared intermediate model is used by both output formats.
-- The current extraction path adapts rustdoc JSON into the shared model.
-- The implementation is intentionally structured so extraction can later move closer to direct librustdoc/HIR usage without rewriting both renderers.
+For local testing, `Pack-Crates.ps1 -APIReview` temporarily switches to markdown generation and
+writes `API.md` into each crate root directory. Pipelines do not set `-APIReview` today.
+
+## Toolchain
+
+The tool reads `eng/tools/rust-toolchain.toml` and invokes:
+
+```sh
+cargo +nightly-2025-05-09 rustdoc -Z unstable-options --output-format json
+```