Linter: avoid single-word class names — must be descriptive

[haiyuazhang]

Parent: #4442

Convention

DO Avoid using single-word class names. Use more descriptive names after consulting with the service development team. DO NOT duplicate names across different RPs.

Source: Azure SDK for .NET Mgmt Naming Conventions

Observed today

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

• Control → RecommendationControlType (advisor/resource-manager/Microsoft.Advisor/Advisor/client.tsp)
• Duration → AdvisorLowCpuEvaluationDuration (advisor/resource-manager/Microsoft.Advisor/Advisor/client.tsp)
• Category → RecommendationCategory (advisor/resource-manager/Microsoft.Advisor/Advisor/client.tsp)
• Impact → RecommendationBusinessImpact (advisor/resource-manager/Microsoft.Advisor/Advisor/client.tsp)
• Priority → RecommendationPriority (advisor/resource-manager/Microsoft.Advisor/Advisor/client.tsp)
• Reason → RecommendationStateChangeReason (advisor/resource-manager/Microsoft.Advisor/Advisor/client.tsp)

Proposed linter

Detection

Flag any exported model whose csharp name is a single PascalCase word matching one of a curated dictionary of generic terms (Resource, Connector, Control, Category, Duration, Impact, Priority, Status, Type, Settings, Properties, ...), OR which collides with a model from another RP (cross-spec check).

Auto-fix

Suggest a service-prefixed name via @@clientName(..., "csharp"). Cross-spec collision detection can run in a separate sweep.

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.

[timotheeguerin]

wondering if we should combine most of those naming rules into a single rule with options instead of having 20+ new linting rule.

[markcowl]

This really should not be a linting rule. Anytime we are attempting to do fuzzy pattern-matching, we should question whether a linting rule is the correct way to do this. This seems more like instructions for an authoring skill.

[haiyuazhang]

Impact analysis: Single-word class names

Findings

• ~1,401 single-word model names (e.g., Status, Category, Impact, Policy, Resource, etc.)
• 585 existing @@clientName renames (42% adoption — highest of all rules)
• 494 unique single-word names across the spec repo
• Determining whether a single-word name is "too generic" requires semantic judgment — Status in one RP is fine, but Status shared across RPs causes naming collisions

Recommendation: Not a good candidate for a static linter rule

This rule requires semantic understanding to distinguish "too generic" from "appropriately named." A curated dictionary approach would be brittle and hard to maintain. Better suited for LLM-based detection or a cross-spec collision analysis tool.