From 49ca699f5a1238d853be6bd4cfa58a45b8d1d6f5 Mon Sep 17 00:00:00 2001 From: Heath Stewart Date: Wed, 15 Jul 2026 16:54:00 -0700 Subject: [PATCH 1/2] Switch pack flow to generate_api Route Pack-Crates.ps1 through generate_api so packaged crates keep the existing APIView artifact shape by default while exposing a temporary -APIReview path for crate-root API.md generation. Update the generate_api README to describe the current pipeline flow and the temporary markdown testing path. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 666bbd92-9ac2-46b9-ba17-90e61a463272 --- eng/scripts/Pack-Crates.ps1 | 41 ++++++++++++++++++++++++------- eng/tools/generate_api/Cargo.toml | 1 + eng/tools/generate_api/README.md | 36 +++++++++++++-------------- 3 files changed, 50 insertions(+), 28 deletions(-) diff --git a/eng/scripts/Pack-Crates.ps1 b/eng/scripts/Pack-Crates.ps1 index dda47a4cb40..d14c0030e10 100755 --- a/eng/scripts/Pack-Crates.ps1 +++ b/eng/scripts/Pack-Crates.ps1 @@ -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 @@ -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 + } } } diff --git a/eng/tools/generate_api/Cargo.toml b/eng/tools/generate_api/Cargo.toml index 1b3bc0ed960..ebd8fabd6fd 100644 --- a/eng/tools/generate_api/Cargo.toml +++ b/eng/tools/generate_api/Cargo.toml @@ -1,5 +1,6 @@ [package] name = "generate_api" +version = "2.0.0" authors.workspace = true edition.workspace = true license.workspace = true diff --git a/eng/tools/generate_api/README.md b/eng/tools/generate_api/README.md index 06082373fc4..fc050a2b82c 100644 --- a/eng/tools/generate_api/README.md +++ b/eng/tools/generate_api/README.md @@ -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 + `/.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 +``` From 245241b71bd5b4ec203bcafb45cf89d44e206103 Mon Sep 17 00:00:00 2001 From: Heath Stewart Date: Thu, 16 Jul 2026 14:34:33 -0700 Subject: [PATCH 2/2] Resolve API review token naming Use the Rust APIView token naming contract when staging generated review files and update the Rust API review artifact finder to look for the same `_rust.json` file name. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com> Copilot-Session: 6b7c45e8-f2e6-4fb1-a24d-3aed4f9bb98e --- eng/scripts/Language-Settings.ps1 | 2 +- eng/scripts/Pack-Crates.ps1 | 2 +- eng/tools/generate_api/README.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/eng/scripts/Language-Settings.ps1 b/eng/scripts/Language-Settings.ps1 index e1b809c7f24..34d0afef2b2 100644 --- a/eng/scripts/Language-Settings.ps1 +++ b/eng/scripts/Language-Settings.ps1 @@ -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" diff --git a/eng/scripts/Pack-Crates.ps1 b/eng/scripts/Pack-Crates.ps1 index d14c0030e10..8923515efa5 100755 --- a/eng/scripts/Pack-Crates.ps1 +++ b/eng/scripts/Pack-Crates.ps1 @@ -217,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 diff --git a/eng/tools/generate_api/README.md b/eng/tools/generate_api/README.md index fc050a2b82c..5e22e547153 100644 --- a/eng/tools/generate_api/README.md +++ b/eng/tools/generate_api/README.md @@ -39,7 +39,7 @@ From that path: - `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 - `/.rust.json`. + `/_rust.json`. - The shared `create-apireview` pipeline step consumes that staged JSON artifact. For local testing, `Pack-Crates.ps1 -APIReview` temporarily switches to markdown generation and