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 dda47a4cb40..8923515efa5 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 @@ -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 + } } } 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..5e22e547153 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 +```