Azure / Azure/typespec-azure

Operations in client.tsp should not raise arm-resource-operation / documentation-required warnings

Open
#5,093 0 comments 0 reactions 0 assignees View on GitHub
bug lib:azure-core triaged:core
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

## Description

When an operation defined in a `client.tsp` file is used only as the **source of an `@@override`** (i.e. it is not a real service operation but a client-shaping helper), it still triggers linter warnings that require manual suppressions.

For example, an operation must carry two suppressions purely because it is an override source:

```tsp
// overrides: subscriptionId should be method level
#suppress "@azure-tools/typespec-azure-resource-manager/arm-resource-operation" "FIXME: Update justification"
#suppress "@azure-tools/typespec-azure-core/documentation-required" "FIXME: Update justification"
op quotaRequestStatusGet(
...ApiVersionParameter,
...SubscriptionIdParameter,
...
): ArmResponse | ExceptionResponse;
@@override(QuotaRequestStatus.get, quotaRequestStatusGet);
@@clientLocation(
quotaRequestStatusGet::parameters.subscriptionId,
quotaRequestStatusGet
);
```

Without the two `#suppress` lines, compilation raises:
- `@azure-tools/typespec-azure-resource-manager/arm-resource-operation`
- `@azure-tools/typespec-azure-core/documentation-required`

## Expected behavior

An operation that is only used as an `@@override` source should not raise these warnings. It is a client customization construct, not a service operation, so ARM resource-operation and documentation-required rules should not apply to it.

## Actual behavior

The operation is linted like a normal service operation, forcing spec authors to add boilerplate `#suppress` directives (currently generated with placeholder `FIXME` justifications by the conversion tooling).

Contributor guide

Open the contributing guide

Research direction

Start by locating the implementations of the arm-resource-operation and documentation-required rules, then inspect how an operation used only as an @@override source is identified. Reproduce the client.tsp example without its suppressions and verify that compilation no longer emits either warning, while normal service operations retain both checks.

Written by the indexing model from the issue text.

Assessment

Tech stack
typescript
Domain
tooling
Issue type
Bug
Difficulty
3/5
Estimated time
1-2 days
Activity status
Quiet
Clarity
Mostly clear
Newbie friendliness
65/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.