[Yingjie Chen (Y1ngJ1eChen)]

Summary

alzlibtool generate architecture --output now writes every per-asset JSON file indented with two spaces instead of on a single line, so the library files vendored by the ALZ Bicep accelerator can be read and reviewed.

Refs Azure/Azure-Landing-Zones#4278. This PR does not close the issue by itself: the accelerator still has to regenerate its library with a release that contains this change.

No flag is added. Only whitespace changes in the exported files, and the JSON printed to stdout (without --output) is unchanged.

Problem

The library files in alz-bicep-accelerator, for example templates/core/governance/lib/alz/landingzones/Audit-AppGW-WAF.alz_policy_assignment.json, are a single line of JSON, while the source files in Azure-Landing-Zones-Library are formatted. Users who review library updates before merging them cannot read these files without reformatting them first.

The single line comes from writeJSONFile in deployment/writer_fs.go, which encodes each asset with a json.Encoder that has no indentation. All four asset types (policy assignments, policy definitions, policy set definitions and role definitions) are written through it, with or without --for-alz-bicep. All 679 library files committed in alz-bicep-accelerator@bfe88af (319 under templates/core/governance/lib, 360 under examples/slz/templates/core/governance/lib) are exactly what this encoder produces for their content, and no later step in the accelerator reformats them.

Changes

File	Change
deployment/writer_fs.go	writeJSONFile: add enc.SetIndent("", " ")
deployment/writer_fs_test.go	Add Test_writeJSONFile_indented, which asserts the exact bytes written

Two spaces match the source library files. HTML escaping (still disabled), key order, ARM escaping, file names and the trailing newline are unchanged.

Deployment size

The issue discussion raised the concern that formatted files could push deployments towards the 4 MB ARM template limit. The indentation does not reach the deployed template:

• The accelerator reads these files only through loadJsonContent() (319 references in the main templates, 360 in the SLZ example, no loadTextContent()). Bicep parses the JSON and re-serializes it into the compiled template.
• With Bicep CLI 0.47.16, all 15 governance templates in alz-bicep-accelerator@bfe88af compile to byte-identical ARM JSON from the current single-line library and from the indented library. The largest compiled template (int-root, 1,600,990 bytes) does not change.
• The only limit that counts whitespace is the loadJsonContent() per-file limit of 1,048,576 characters. The largest file, Deploy-Private-DNS-Zones.alz_policy_set_definition.json, is 97,552 bytes when indented (9.3% of the limit).
• The main library in the repository grows from 928,402 to 1,339,581 bytes (from 319 to 36,172 lines).

Testing

• Test_writeJSONFile_indented fails on main (the file is one line) and passes with this change. It also pins disabled HTML escaping, empty {} and [], and [[ ARM escapes.
• The existing deployment writer tests and the cmd/alzlibtool/command/generate tests pass. These run offline.
• Built alzlibtool from main and from this branch and ran generate architecture on testdata/simple, with and without --for-alz-bicep. In both modes the 8 exported files differ only in whitespace and are the canonical two-space indentation of the previous output. Stdout without --output is byte-identical.
• For each of the 679 committed accelerator library files, encoding its content with the new settings gives exactly the two-space indentation of that file. For the 319 main library files, that output is byte-identical to the indented library used in the Bicep comparison above.
• go vet ./..., GOOS=linux GOARCH=386 go build ./... and golangci-lint v2.11.4 with the repository configuration: no findings on main or on this branch.
• Run locally on Windows with Go 1.26.8; CI (Linux, Go 1.25.2) is authoritative.
• Not run: regenerating the accelerator library end to end from Azure-Landing-Zones-Library, which needs Azure credentials to read built-in policy definitions.

Backwards compatibility

• The bytes written by generate architecture --output (deployment.FSWriter) change, whitespace only. Anything that parses the files as JSON is unaffected. Repositories that commit the generated files get a one-time, whitespace-only diff on their next regeneration.
• No API or CLI change: FSWriterOptions and all flags are unchanged.

Out of scope

• Regenerating the library in alz-bicep-accelerator. After the next alzlib release, templates/core/governance/lib/alz and examples/slz/templates/core/governance/lib/alz should be regenerated with the new alzlibtool in a format-only PR that keeps the library ref unchanged. The "Updating the ALZ Library Version" guide already tells users to download the latest alzlibtool, so no documentation change is needed.
• An option to keep the compact output. It can be added later as an FSWriterOptions field if a consumer needs it; none does today.

[Codecov Comments Bot (codecov-commenter)]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 49.59%. Comparing base (d5b42ab) to head (bd6a809).

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #251      +/-   ##
==========================================
+ Coverage   49.54%   49.59%   +0.05%     
==========================================
  Files          54       54              
  Lines        4967     4968       +1     
==========================================
+ Hits         2461     2464       +3     
+ Misses       2210     2209       -1     
+ Partials      296      295       -1     

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.