[TCGC] Require explicit union hierarchies

[JoshLove-msft]

Summary

Fixes #5559. Related to #5390; expanded during review to include non-string union constraints and model ownership. String unions are exempt from the extends requirement; numeric and other non-string named unions are not.

• Add @azure-tools/typespec-client-generator-core/use-union-hierarchy, enabled by the client-sdk ruleset only.
• Require named unions to declare an extends constraint unless they are nonempty string unions. Use the compiler's string assignability check so string literals, extensible strings, derived string scalars, string templates, and nested string unions remain exempt. Numeric, model, boolean, enum, mixed, and nullable named unions still require constraints. Anonymous union expressions remain unaffected.
• For model-based union extends, require every model variant to be the exact declared base or inherit from it directly or transitively. Accept aliases and model is copies that retain that inheritance chain. Reject structural matches, spreads, shape-only model is copies, unrelated hierarchies, and different model-template instantiations.
• Prevent a model from being a variant of multiple model-constrained unions. Resolve aliases by model identity; allow repeated variants/references within one union and distinct variants in unions sharing the same base.
• Skip model-inheritance and ownership checks for non-model constraints/variants. Check reachable concrete union-template instantiations without diagnosing unused templates.
• Reuse the existing shared tester with the required experimental features. Keep focused rule coverage; remove redundant ruleset and compiler-library-exclusion tests.
• Use Pet/PetBase in the docs, show both a constrained numeric union and an unconstrained string union, and remove the implementation-detail scope and enablement sections requested in review. Compiler-managed library exclusion and suppression remain unchanged. Regenerate reference listings and update the feature changeset.

Uses the pinned compiler's typed Union.baseType API, existing typekit assignability API, and actual union-extends feature flag; no compiler dependency update or AST workaround.

Validation

Latest revision (ec593edb1):

• TCGC package build and all 230 linter regression tests passed, including 111 focused hierarchy-rule cases.
• Rule coverage: 100% statements, branches (16/16), functions, and lines.
• pnpm format, pnpm lint (including type-aware lint), and explicit spelling checks passed.
• Reference docs regenerated; all five documented TypeSpec examples compile with the exact expected diagnostic counts.
• The earlier external integration failure included mandatory-extends diagnostics on existing string unions. This revision exempts string-only unions; int:azure-specs remains enabled for external integration on the updated commit. The latest CI result is pending.

Earlier validation on this branch included dependency builds, context/internal-utils and ruleset tests, and pnpm validate:pr --skip-build --skip-test. The full monorepo build/test suites were not rerun for this correction. An earlier full TCGC test-project tsc --noEmit probe reported existing errors in untouched tests/test helpers and Vitest project configuration; the package build and type-aware lint pass. Initial dependency restoration also encountered an unrelated Python preparation TLS failure after JavaScript dependencies were installed.

[github-actions]

All changed packages have been documented.

• ✅ @azure-tools/typespec-azure-rulesets
• ✅ @azure-tools/typespec-client-generator-core

Show changes

@azure-tools/typespec-client-generator-core - feature ✏️

Add the use-union-hierarchy linter rule to require non-string named unions to declare an extends constraint and model variants to inherit from the declared base and belong to only one model-based union hierarchy, enabled by the client-sdk ruleset. String unions do not require extends.

@azure-tools/typespec-azure-rulesets - feature ✏️

Add the use-union-hierarchy linter rule to require non-string named unions to declare an extends constraint and model variants to inherit from the declared base and belong to only one model-based union hierarchy, enabled by the client-sdk ruleset. String unions do not require extends.

[github-actions]

📦 Package size report

✅ No notable package size changes compared to the base branch.

13 package(s) with no notable change

Package	Packed (base → head)	Δ Packed	Unpacked (base → head)	Δ Unpacked
@azure-tools/typespec-go	263.57 KB → 263.12 KB	-467 B (-0.2%)	1.35 MB → 1.34 MB	-2.83 KB (-0.2%)
@azure-tools/typespec-client-generator-core	241.52 KB → 241.66 KB	+147 B (+0.1%)	1.29 MB → 1.29 MB	+1.11 KB (+0.1%)
@azure-tools/typespec-java	13.51 MB → 13.51 MB	-35 B (-0.0%)	15.04 MB → 15.04 MB	—
@azure-tools/typespec-azure-rulesets	5.50 KB → 5.52 KB	+27 B (+0.5%)	33.67 KB → 33.85 KB	+186 B (+0.5%)
@azure-tools/typespec-ts	541.00 KB → 541.01 KB	+11 B (+0.0%)	2.60 MB → 2.60 MB	+54 B (+0.0%)
@azure-tools/azure-http-specs	148.36 KB → 148.36 KB	—	1.17 MB → 1.17 MB	—
@azure-tools/typespec-autorest	81.98 KB → 81.98 KB	—	400.59 KB → 400.59 KB	—
@azure-tools/typespec-autorest-canonical	7.42 KB → 7.42 KB	—	26.00 KB → 26.00 KB	—
@azure-tools/typespec-azure-core	133.12 KB → 133.12 KB	—	721.70 KB → 721.70 KB	—
@azure-tools/typespec-azure-portal-core	42.48 KB → 42.48 KB	—	193.20 KB → 193.20 KB	—
@azure-tools/typespec-azure-resource-manager	184.05 KB → 184.05 KB	—	1.11 MB → 1.11 MB	—
@azure-tools/typespec-metadata	15.91 KB → 15.91 KB	—	62.26 KB → 62.26 KB	—
@azure-tools/typespec-python	42.22 KB → 42.22 KB	—	164.91 KB → 164.91 KB	—

_{Packed = gzipped .tgz published to npm. Unpacked = total extracted size. 🆕 added, 🗑️ removed. Packages from the core/ submodule are not included.
🔴 grew · 🟢 shrank — only changes of at least 512 B and 0.5% are marked.}

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/@azure-tools/typespec-azure-rulesets@5561

npm i https://pkg.pr.new/@azure-tools/typespec-client-generator-core@5561

commit: ec593ed

[azure-sdk-automation]

You can try these changes here

🛝 Playground	🌐 Website

[Mark Cowlishaw (markcowl)]

The new practice is to make linting rules off by default, and enable them ins separate pRs against the aure-rest-api-specs repos.

[Mark Cowlishaw (markcowl)]

Some leftover unnecessary text in the rule documentation, and also some questions about how to manage the impact of all current string unions in libraries and specs needing to be updated.

A much less disruptive change would use the getUnionAsEnum to except string valued enums from the rule, and reserve it for other enum usages.