add PSscript to convert APIView json token files to md#14344
add PSscript to convert APIView json token files to md#14344swathipil wants to merge 1 commit intoAzure:mainfrom
Conversation
|
The following pipelines have been queued for testing: |
There was a problem hiding this comment.
Pull request overview
Adds a PowerShell utility and Pester coverage to convert APIView token JSON (tree format) into markdown with fenced code blocks for easier API review workflows.
Changes:
- Introduces
Export-APIViewMarkdown.ps1to renderReviewLines(and nestedChildren) into markdown. - Adds Pester tests plus sample/golden APIView fixtures to validate formatting, spacing, language tags, and error handling.
Reviewed changes
Copilot reviewed 5 out of 11 changed files in this pull request and generated 4 comments.
Show a summary per file
| File | Description |
|---|---|
| eng/common/scripts/Export-APIViewMarkdown.ps1 | New script that converts APIView token JSON to fenced markdown output. |
| eng/common-tests/apiview-markdown/tests/Export-APIViewMarkdown.Tests.ps1 | New Pester suite validating rendering, indentation, spacing flags, language tags, and errors. |
| eng/common-tests/apiview-markdown/testfiles/Export-APIViewMarkdown/simple_tokens.json | Minimal fixture JSON with nested children and whitespace metadata. |
| eng/common-tests/apiview-markdown/testfiles/Export-APIViewMarkdown/azure-core_python.md | Golden markdown output fixture for Python. |
| eng/common-tests/apiview-markdown/testfiles/Export-APIViewMarkdown/azure-core_js.md | Golden markdown output fixture for JavaScript. |
| $fenceOpen = "``````$language" | ||
| $fenceClose = "``````" |
There was a problem hiding this comment.
The script generates fences using six backticks, but the added golden markdown fixtures (e.g., azure-core_python.md, azure-core_js.md) use standard triple-backtick fences (lang ... ). This mismatch will prevent the script output from matching the golden files and is also non-standard markdown. Switch to triple backticks for both open/close (and keep the language tag on the opening fence).
| $fenceOpen = "``````$language" | |
| $fenceClose = "``````" | |
| $fenceOpen = "```$language" | |
| $fenceClose = "```" |
| $content | Should -Match "^``````py" | ||
| $content | Should -Match "``````$" |
There was a problem hiding this comment.
The tests assert six-backtick fences here, but later tests assert triple-backtick fences (e.g., expecting ```py for alias mapping) and the golden files also start with triple backticks. This inconsistency will make the test suite fail once the fence format is corrected; update these assertions to match the chosen (and golden) fence style.
| $content | Should -Match "^``````py" | |
| $content | Should -Match "``````$" | |
| $content | Should -Match '^```py' | |
| $content | Should -Match '```$' |
| Write-Error "Token JSON file not found: $TokenJsonPath" | ||
| exit 1 | ||
| } | ||
|
|
||
| $tokenJson = Get-Content -Path $TokenJsonPath -Raw | ConvertFrom-Json | ||
|
|
||
| if (-not $tokenJson.ReviewLines) { | ||
| Write-Error "The token JSON file does not contain a 'ReviewLines' property." | ||
| exit 1 |
There was a problem hiding this comment.
Write-Error combined with exit is risky for a script that may be dot-sourced or invoked from a larger PowerShell session (including CI), because exit can terminate the entire host if the error is caught upstream. Prefer throw (or Write-Error -ErrorAction Stop without exit) and remove exit 1 so failures remain catchable without killing the process.
| Write-Error "Token JSON file not found: $TokenJsonPath" | |
| exit 1 | |
| } | |
| $tokenJson = Get-Content -Path $TokenJsonPath -Raw | ConvertFrom-Json | |
| if (-not $tokenJson.ReviewLines) { | |
| Write-Error "The token JSON file does not contain a 'ReviewLines' property." | |
| exit 1 | |
| throw "Token JSON file not found: $TokenJsonPath" | |
| } | |
| $tokenJson = Get-Content -Path $TokenJsonPath -Raw | ConvertFrom-Json | |
| if (-not $tokenJson.ReviewLines) { | |
| throw "The token JSON file does not contain a 'ReviewLines' property." |
| It "Closes the fence with a plain triple-backtick" { | ||
| $outFile = Join-Path $TestDrive "close.md" | ||
| & $scriptPath -TokenJsonPath $simpleTokensJson -OutputPath $outFile | ||
|
|
||
| $lines = Get-Content $outFile | ||
| $lines[-1] | Should -Be "``````" |
There was a problem hiding this comment.
The test name says "triple-backtick" but asserts a six-backtick fence. After aligning fences to standard markdown, update both the test title and assertion to consistently refer to (and validate) the same fence format.
|
The following pipelines have been queued for testing: |
Following up on review in #13259.
Addressing: #12851