Azure / Azure/typespec-azure

Linter: enforce two-letter acronym casing (`Db`→`DB`, `Ip`→`IP`, `Os`→`OS`, …) with `Vm`/`Id` exceptions

Open
#4,458 1 comment 0 reactions 0 assignees View on GitHub
feature lib:tcgc linter
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 21h
Merged PRs (30d)
164

Description

Parent: #4442

## Convention

Two-letter acronyms should be all-uppercase when not part of longer compound identifiers, with exceptions like `Vm`, `Id`.

> Source: [Azure SDK for .NET Mgmt Naming Conventions](https://github.com/Azure/azure-sdk-for-net/blob/main/doc/dev/Mgmt-Naming-Conventions.md)

## Observed today

A scan of `Azure/azure-rest-api-specs` (334 `client.tsp` files, 10,754 csharp-scoped `@@clientName` decorators) shows **221** decorators currently encoding this rule by hand. Examples:

- `VirtualMachineScaleSetIpTag` → `ComputeFleetVmssIPTag` (azurefleet/resource-manager/Microsoft.AzureFleet/AzureFleet/client.tsp)
- `IpAddress` → `LargeInstanceIPAddress` (azurelargeinstance/resource-manager/Microsoft.AzureLargeInstance/AzureLargeInstance/client.tsp)
- `cosmosDbResourceId` → `cosmosDBResourceId` (agricultureplatform/AgriculturePlatform.Management/client.tsp)
- `CosmosDb` → `CosmosDB` (billingbenefits/BillingBenefits.Management/client.tsp)
- `OsProfile` → `LargeInstanceOSProfile` (azurelargeinstance/resource-manager/Microsoft.AzureLargeInstance/AzureLargeInstance/client.tsp)
- `HciOsProfile` → `HciOSProfile` (azurestackhci/resource-manager/Microsoft.AzureStackHCI/StackHCI/client.tsp)

## Proposed linter

**Detection**

Walk all model / property / parameter / enum names. Flag any segment matching the acronym dictionary (`Db`, `Ip`, `Os`, `Sql`, `Url`, `Uri`, `Tls`, `Ssl`, `Cpu`, `Gpu`, `Dns`, `Tcp`, `Udp`, `Sas`, `Aks`, `Acl`, `Api`, `Http`, `Https`, `Xml`, `Json`, ...) where the canonical .NET casing is fully upper. Honor exceptions: `Vm`, `Id`.

**Auto-fix**

Insert `@@clientName(..., "csharp")` with the corrected acronym casing.

**Scope**

The rule should be csharp-scoped — it only flags violations of the .NET convention, not the underlying TypeSpec name. It should suggest inserting a `@@clientName(..., "csharp")` override when the underlying TypeSpec name is intentional, or renaming the TypeSpec model when the convention applies cross-language.

## Acceptance criteria

- [ ] New lint rule registered in the appropriate ruleset (`@azure-tools/typespec-client-generator-core` or `@azure-tools/typespec-azure-resource-manager`).
- [ ] Doc page under `website/src/content/docs/docs/libraries/.../rules/`.
- [ ] Unit tests covering positive / negative cases and the auto-fix.
- [ ] A `.chronus/changes/` entry.

Contributor guide

Open the contributing guide

Research direction

Start by locating the appropriate ruleset in @azure-tools/typespec-client-generator-core or @azure-tools/typespec-azure-resource-manager and review nearby lint rules. Then inspect the unit-test layout, website/src/content/docs/docs/libraries/.../rules/, and .chronus/changes/ entries. Done means the rule is registered, documented, tested for positive and negative cases plus auto-fix behavior, and has a changes entry.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Feature
Difficulty
4/5
Estimated time
3-5 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
55/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.