Azure / Azure/typespec-azure

ARM Linting Rules - Prioritization

Open
#4,290 0 comments 0 reactions 0 assignees View on GitHub
epic lib:azure-resource-manager linter
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

## New Linting Rules for `typespec-azure-resource-manager`

### Duplication / Commonality / Contradiction Analysis

| Relationship | Rules Involved | Analysis |
|---|---|---|
| **Can merge** | #542 + #1056 | Both deal with inappropriate `tags` mixin usage. Single **"tags-mixin-misuse"** rule. |
| **Can merge** | RPC006/§2.2 + §2.3 | Both are "missing operations" gaps. Single **"arm-resource-required-operations"** rule. |
| **Can merge** | #3939 + #406 + #2643 | All relate to PATCH body schema correctness and MergePatch support. Fixing #3939 satisfies #406; #2643 extends with MergePatch linting. |
| **Can merge** | #267 + #848 | Both concern unnecessary/anonymous model definitions. Single rule, shared with azure-core. |
| **Complying with one ⟹ another** | #1475 → #3405 | Same-resource interface (#1475) largely prevents bad operation grouping (#3405). |
| **Complying with one ⟹ another** | RPC006 complete-ops → #856 | Singleton-aware complete-ops rule subsumes #856. |
| **Tension** | #2383 vs. #3351 | Both touch LRO header validation; must be co-designed. |

### Proposed Rules

| # | Description | Priority | Feasibility | Link | Notes |
|---|---|---|---|---|---|
| 1 | **Complete operation set for tracked + nested resources** | High | High | [RPC §2.2, §2.3](https://azure.github.io/typespec-azure/docs/howtos/ARM/rpc-guidelines-coverage/) | Single rule. Singleton-aware (subsumes #856). |
| 2 | **Fix `patch-envelope` / PATCH body schema + MergePatch support** | High | High | #3939, #406, #2643 | Fixing #3939 satisfies #406. MergePatch linting rules (#2643) merged here. |
| 3 | **No paths differing only by casing** | High | High | #4279 | Simple string-comparison check. |
| 4 | **LRO POST Response/FinalResult mismatch** | High | High | #2524 | `getLroMetadata` already available. |
| 5 | **Even-segmented path for PUT** | High | High | #519 | Path segment counting. |
| 6 | **No OpenAPI decorators in ARM specs** | High | High | #3066 | Check for OpenAPI decorator imports/usage. |
| 12 | **Version progression validation** | High | High | [RPC §11.2](https://azure.github.io/typespec-azure/docs/howtos/ARM/rpc-guidelines-coverage/) | Date-string parsing + chronological check. |
| 7 | **Tags mixin misuse** — prevent on TrackedResource + warn on proxy | Medium | High | #542, #1056 | Single rule covers both. |
| 8 | **All ops in ARM interface must be for same resource** | Medium | High | #1475 | Largely prevents #3405. |
| 9 | **Require overriding default POST action descriptions** | Medium | High | #1883 | Check if `@doc` unchanged from template default. |
| 10 | **Resource key must be read-only in CreateOrReplace** | Medium | High | #2352 | Check `@visibility("read")` on key properties. |
| 11 | **Revisit `retry-after` rule** | Medium | High | #3351 | ⚠️ Co-design with #15 (LRO headers). |
| 13 | **Anonymous types / spread-only models** | Medium | Medium | #267, #848 | Single rule. Shared with azure-core. |
| 14 | **Prevent bad operation sorting by name** | Medium | Medium | #3405 | Largely mitigated by #8; may still be needed for extension resources. |
| 15 | **LRO templates prefer Azure-AsyncOperation** | Medium | Medium | #2383 | ⚠️ Co-design with #11 (retry-after). |
| 16 | **Cross-resource type in responses** | Medium | Medium | [RPC019](https://azure.github.io/typespec-azure/docs/howtos/ARM/rpc-guidelines-coverage/) | May have false positives. |
| 17 | **Singleton resources exempt from delete rule** | Low | High | #856 | Subsumed if #1 is singleton-aware; otherwise quick fix. |
| 18 | **Improve `no-empty-model` for `Record`** | Low | High | #2192 | Enhance existing rule's suggestion message. |
| 19 | **Proper decorator for non-resource op interfaces** | Low | Medium | #3250 | Needs new decorator + rule update. |
| 20 | **Encourage minimal ResourceNameParameter usage** | Low | Medium | #3017 | Needs definition of "minimal". |
| 21 | **POST vs. PUT/PATCH intent** | Low | Low | [RPC010](https://azure.github.io/typespec-azure/docs/howtos/ARM/rpc-guidelines-coverage/) | Heuristics; prone to false positives. |
| 22 | **Implicit child resource creation in PUT** | Low | Low | [RPC011](https://azure.github.io/typespec-azure/docs/howtos/ARM/rpc-guidelines-coverage/) | Hard to detect reliably. |

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the linked issues and the ARM RPC guidance referenced in the prioritization table, then inspect the existing lint-rule entry points; getLroMetadata is specifically mentioned for LRO validation. The issue does not name files or tests, and completion would require narrowing this list to a concrete rule with defined scope and acceptance criteria.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Quiet
Clarity
Needs clarification
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.