Add @featureFile decorators in Azure.ResourceManager and fix template suppression propagation

- Add @featureFile, @featureFiles, @featureFileOptions decorators in Azure.ResourceManager
  namespace as alternatives to the Legacy @feature, @features, @featureOptions decorators
- Fix arm-custom-resource-usage-discourage rule to propagate suppressions from model
  templates to their instantiations
- Regenerate reference docs
- Update tests to use new decorator names

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: markcowl

.chronus/changes/markcowl-featurefile-decorators-2026-6-29-18-25-0.md

@@ -0,0 +1,8 @@
+---
+changeKind: feature
+packages:
+  - "@azure-tools/typespec-azure-resource-manager"
+  - "@azure-tools/typespec-autorest"
+---
+
+Add `@featureFile`, `@featureFiles`, and `@featureFileOptions` decorators in `Azure.ResourceManager` namespace as alternatives to the Legacy `@feature`, `@features`, and `@featureOptions` decorators. Fix `arm-custom-resource-usage-discourage` rule to propagate suppressions from model templates to their instantiations.

packages/typespec-autorest/test/arm/arm.test.ts

@@ -509,7 +509,7 @@ it("generates PATCH bodies for resource patch of common resource envelope mixins
 it("can split resources and operations by feature", async () => {
   const { privateLink, privateEndpoint } = await CompileOpenApiWithFeatures(
     `
-      @Azure.ResourceManager.Legacy.features(Features)
+      @Azure.ResourceManager.featureFiles(Features)
       @armProviderNamespace
       @armCommonTypesVersion(Azure.ResourceManager.CommonTypes.Versions.v5)
       namespace Microsoft.PrivateLinkTest;
@@ -522,7 +522,7 @@ it("can split resources and operations by feature", async () => {
       
       interface Operations extends Azure.ResourceManager.Operations {}
       
-      @Azure.ResourceManager.Legacy.feature(Features.privateEndpoint)
+      @Azure.ResourceManager.featureFile(Features.privateEndpoint)
       @tenantResource
       model PrivateEndpointConnectionResource is ProxyResource<PrivateEndpointConnectionProperties> {
         @path
@@ -531,20 +531,20 @@ it("can split resources and operations by feature", async () => {
         name: string;
       }
       
-      @Azure.ResourceManager.Legacy.feature(Features.privateEndpoint)
+      @Azure.ResourceManager.featureFile(Features.privateEndpoint)
       @armResourceOperations(PrivateEndpointConnectionResource)
       interface PrivateEndpointConnections {
         #suppress "deprecated" "PrivateLinkResourceListResultV5 validation"
         listConnections is ArmResourceListByParent<PrivateEndpointConnectionResource,
          Response = ArmResponse<Azure.ResourceManager.CommonTypes.PrivateEndpointConnectionListResultV5>>;
       }
 
-      @Azure.ResourceManager.Legacy.feature(Features.privateLink)
+      @Azure.ResourceManager.featureFile(Features.privateLink)
       model PrivateLinkResource is ProxyResource<PrivateLinkResourceProperties> {
         ...PrivateLinkResourceParameter;
       }
 
-      @Azure.ResourceManager.Legacy.feature(Features.privateLink)
+      @Azure.ResourceManager.featureFile(Features.privateLink)
       @armResourceOperations(PrivateLinkResource)
       interface PrivateLinkResources {
         #suppress "deprecated" "PrivateLinkResourceListResultV5 validation"
@@ -576,49 +576,49 @@ it("can represent type references within and between features", async () => {
   const { featureA, featureB, shared } = await CompileOpenApiWithFeatures(
     `
 
-@Azure.ResourceManager.Legacy.features(Features)
+@Azure.ResourceManager.featureFiles(Features)
 @armProviderNamespace("Microsoft.Test")
 namespace Microsoft.Test;
 enum Features {
-  @Azure.ResourceManager.Legacy.featureOptions(#{featureName: "Common", fileName: "shared", description: "The data for common features"})
+  @Azure.ResourceManager.featureFileOptions(#{featureName: "Common", fileName: "shared", description: "The data for common features"})
   Common: "Common",
-  @Azure.ResourceManager.Legacy.featureOptions(#{featureName: "FeatureA", fileName: "featureA", description: "The data for feature A"})
+  @Azure.ResourceManager.featureFileOptions(#{featureName: "FeatureA", fileName: "featureA", description: "The data for feature A"})
   FeatureA: "Feature A",
-  @Azure.ResourceManager.Legacy.featureOptions(#{featureName: "FeatureB", fileName: "featureB", description: "The data for feature B"})
+  @Azure.ResourceManager.featureFileOptions(#{featureName: "FeatureB", fileName: "featureB", description: "The data for feature B"})
   FeatureB: "Feature B",
 }
       @secret
       scalar secretString extends string;
 
-      @Azure.ResourceManager.Legacy.feature(Features.FeatureA)
+      @Azure.ResourceManager.featureFile(Features.FeatureA)
       model FooResource is TrackedResource<FooResourceProperties> {
          ...ResourceNameParameter<FooResource>;
       }
       
-      @Azure.ResourceManager.Legacy.feature(Features.FeatureA)
+      @Azure.ResourceManager.featureFile(Features.FeatureA)
       model FooResourceProperties { 
         ...DefaultProvisioningStateProperty;
         password: secretString;
       }
 
-      @Azure.ResourceManager.Legacy.feature(Features.FeatureB)
+      @Azure.ResourceManager.featureFile(Features.FeatureB)
       model BarResource is ProxyResource<BarResourceProperties> {
           ...ResourceNameParameter<BarResource>;
       }
-      @Azure.ResourceManager.Legacy.feature(Features.FeatureB)
+      @Azure.ResourceManager.featureFile(Features.FeatureB)
       model BarResourceProperties { 
         ...DefaultProvisioningStateProperty;
         password: secretString;
       }
 
-      @Azure.ResourceManager.Legacy.feature(Features.FeatureA)
+      @Azure.ResourceManager.featureFile(Features.FeatureA)
       @armResourceOperations
       interface Foos extends Azure.ResourceManager.TrackedResourceOperations<FooResource, FooResourceProperties> {}
 
-      @Azure.ResourceManager.Legacy.feature(Features.FeatureB)
+      @Azure.ResourceManager.featureFile(Features.FeatureB)
       @armResourceOperations
       interface Bars extends Azure.ResourceManager.TrackedResourceOperations<BarResource, BarResourceProperties> {}
-      @@Azure.ResourceManager.Legacy.feature(Bars.get, Features.FeatureA);
+      @@Azure.ResourceManager.featureFile(Bars.get, Features.FeatureA);
       `,
     ["featureA", "featureB", "shared"],
     { preset: "azure" },

packages/typespec-azure-resource-manager/README.md

@@ -87,6 +87,9 @@ Available ruleSets:
 - [`@armResourceUpdate`](#@armresourceupdate)
 - [`@armVirtualResource`](#@armvirtualresource)
 - [`@extensionResource`](#@extensionresource)
+- [`@featureFile`](#@featurefile)
+- [`@featureFileOptions`](#@featurefileoptions)
+- [`@featureFiles`](#@featurefiles)
 - [`@identifiers`](#@identifiers)
 - [`@locationResource`](#@locationresource)
 - [`@resourceBaseType`](#@resourcebasetype)
@@ -398,6 +401,63 @@ See more details on [different Azure Resource Manager resource type here.](https
 
 None
 
+#### `@featureFile`
+
+Decorator to associate a feature file with a model, interface, or namespace
+
+```typespec
+@Azure.ResourceManager.featureFile(featureName: EnumMember)
+```
+
+##### Target
+
+The target to associate the feature file with
+`Model | Operation | Interface | Namespace`
+
+##### Parameters
+
+| Name        | Type         | Description                              |
+| ----------- | ------------ | ---------------------------------------- |
+| featureName | `EnumMember` | The feature to associate with the target |
+
+#### `@featureFileOptions`
+
+Decorator to define options for a specific feature file
+
+```typespec
+@Azure.ResourceManager.featureFileOptions(options: valueof Azure.ResourceManager.Legacy.ArmFeatureOptions)
+```
+
+##### Target
+
+The enum member that represents the feature
+`EnumMember`
+
+##### Parameters
+
+| Name    | Type                                              | Description                      |
+| ------- | ------------------------------------------------- | -------------------------------- |
+| options | [valueof `ArmFeatureOptions`](#armfeatureoptions) | The options for the feature file |
+
+#### `@featureFiles`
+
+Decorator to define a set of feature files for splitting output
+
+```typespec
+@Azure.ResourceManager.featureFiles(features: Enum)
+```
+
+##### Target
+
+The service namespace
+`Namespace`
+
+##### Parameters
+
+| Name     | Type   | Description                         |
+| -------- | ------ | ----------------------------------- |
+| features | `Enum` | The enum that contains the features |
+
 #### `@identifiers`
 
 This decorator is used to indicate the identifying properties of objects in the array, e.g. size

packages/typespec-azure-resource-manager/generated-defs/Azure.ResourceManager.ts

@@ -1,6 +1,7 @@
 import type {
   DecoratorContext,
   DecoratorValidatorCallbacks,
+  Enum,
   EnumMember,
   EnumValue,
   Interface,
@@ -17,6 +18,14 @@ export interface ResourceOperationOptions {
   readonly omitTags?: boolean;
 }
 
+export interface ArmFeatureOptions {
+  readonly featureName: string;
+  readonly fileName: string;
+  readonly description: string;
+  readonly title?: string;
+  readonly termsOfService?: string;
+}
+
 /**
  * Marks the operation as being a collection action
  */
@@ -348,6 +357,42 @@ export type ResourceBaseTypeDecorator = (
   baseTypeIt: Type,
 ) => DecoratorValidatorCallbacks | void;
 
+/**
+ * Decorator to define a set of feature files for splitting output
+ *
+ * @param target The service namespace
+ * @param features The enum that contains the features
+ */
+export type FeatureFilesDecorator = (
+  context: DecoratorContext,
+  target: Namespace,
+  features: Enum,
+) => DecoratorValidatorCallbacks | void;
+
+/**
+ * Decorator to define options for a specific feature file
+ *
+ * @param target The enum member that represents the feature
+ * @param options The options for the feature file
+ */
+export type FeatureFileOptionsDecorator = (
+  context: DecoratorContext,
+  target: EnumMember,
+  options: ArmFeatureOptions,
+) => DecoratorValidatorCallbacks | void;
+
+/**
+ * Decorator to associate a feature file with a model, interface, or namespace
+ *
+ * @param target The target to associate the feature file with
+ * @param featureName The feature to associate with the target
+ */
+export type FeatureFileDecorator = (
+  context: DecoratorContext,
+  target: Model | Operation | Interface | Namespace,
+  featureName: EnumMember,
+) => DecoratorValidatorCallbacks | void;
+
 export type AzureResourceManagerDecorators = {
   armResourceCollectionAction: ArmResourceCollectionActionDecorator;
   armProviderNameValue: ArmProviderNameValueDecorator;
@@ -372,4 +417,7 @@ export type AzureResourceManagerDecorators = {
   armCommonTypesVersion: ArmCommonTypesVersionDecorator;
   armVirtualResource: ArmVirtualResourceDecorator;
   resourceBaseType: ResourceBaseTypeDecorator;
+  featureFiles: FeatureFilesDecorator;
+  featureFileOptions: FeatureFileOptionsDecorator;
+  featureFile: FeatureFileDecorator;
 };

packages/typespec-azure-resource-manager/lib/decorators.tsp

@@ -274,3 +274,27 @@ extern dec resourceBaseType(
  * ```
  */
 extern dec identifiers(entity: ModelProperty | Array<unknown>, properties: valueof string[]);
+
+/**
+ * Decorator to define a set of feature files for splitting output
+ * @param target The service namespace
+ * @param features The enum that contains the features
+ */
+extern dec featureFiles(target: Namespace, features: Enum);
+
+/**
+ * Decorator to define options for a specific feature file
+ * @param target The enum member that represents the feature
+ * @param options The options for the feature file
+ */
+extern dec featureFileOptions(
+  target: EnumMember,
+  options: valueof Azure.ResourceManager.Legacy.ArmFeatureOptions
+);
+
+/**
+ * Decorator to associate a feature file with a model, interface, or namespace
+ * @param target The target to associate the feature file with
+ * @param featureName The feature to associate with the target
+ */
+extern dec featureFile(target: Model | Operation | Interface | Namespace, featureName: EnumMember);

packages/typespec-azure-resource-manager/src/resource.ts

@@ -33,6 +33,9 @@ import {
   ArmResourceOperationsDecorator,
   ArmVirtualResourceDecorator,
   ExtensionResourceDecorator,
+  FeatureFileDecorator,
+  FeatureFileOptionsDecorator,
+  FeatureFilesDecorator,
   IdentifiersDecorator,
   LocationResourceDecorator,
   ResourceBaseTypeDecorator,
@@ -1659,3 +1662,9 @@ export const $featureOptions: FeatureOptionsDecorator = (
 ) => {
   setResourceFeatureOptions(context.program, entity, options);
 };
+
+// New Azure.ResourceManager namespace decorators (aliases of Legacy decorators)
+export const $featureFile: FeatureFileDecorator = $feature as unknown as FeatureFileDecorator;
+export const $featureFiles: FeatureFilesDecorator = $features as unknown as FeatureFilesDecorator;
+export const $featureFileOptions: FeatureFileOptionsDecorator =
+  $featureOptions as unknown as FeatureFileOptionsDecorator;

packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-usage-discourage.ts

@@ -1,5 +1,9 @@
-import { createRule, Model } from "@typespec/compiler";
-import { isCustomAzureResource } from "../resource.js";
+import { createRule, isTemplateInstance, Model, Program } from "@typespec/compiler";
+import { SyntaxKind, type Node } from "@typespec/compiler/ast";
+import { getCustomResourceOptions, isCustomAzureResource } from "../resource.js";
+
+const armCustomResourceUsageDiscourageCode =
+  "@azure-tools/typespec-azure-resource-manager/arm-custom-resource-usage-discourage";
 
 export const armCustomResourceUsageDiscourage = createRule({
   name: "arm-custom-resource-usage-discourage",
@@ -12,7 +16,10 @@ export const armCustomResourceUsageDiscourage = createRule({
   create(context) {
     return {
       model: (model: Model) => {
-        if (isCustomAzureResource(context.program, model)) {
+        if (
+          isCustomAzureResource(context.program, model) &&
+          !hasSuppressedCustomResourceTemplateBase(context.program, model)
+        ) {
           context.reportDiagnostic({
             code: "arm-custom-resource-usage-discourage",
             target: model,
@@ -22,3 +29,59 @@ export const armCustomResourceUsageDiscourage = createRule({
     };
   },
 });
+
+function hasSuppressedCustomResourceTemplateBase(program: Program, model: Model): boolean {
+  return hasSuppressedCustomResourceTemplate(program, model, new Set<Model>());
+}
+
+function hasSuppressedCustomResourceTemplate(
+  program: Program,
+  model: Model,
+  visited: Set<Model>,
+): boolean {
+  if (visited.has(model)) {
+    return false;
+  }
+  visited.add(model);
+
+  if (
+    getCustomResourceOptions(program, model) &&
+    isTemplateInstance(model) &&
+    hasSuppression(model.node)
+  ) {
+    return true;
+  }
+
+  if (model.baseModel && hasSuppressedCustomResourceTemplate(program, model.baseModel, visited)) {
+    return true;
+  }
+
+  for (const sourceModel of model.sourceModels) {
+    if (hasSuppressedCustomResourceTemplate(program, sourceModel.model, visited)) {
+      return true;
+    }
+  }
+
+  return false;
+}
+
+function hasSuppression(node: Node | undefined): boolean {
+  let current = node;
+  while (current) {
+    for (const directive of current.directives ?? []) {
+      const firstArgument = directive.arguments[0];
+      if (
+        directive.target.sv === "suppress" &&
+        firstArgument &&
+        ((firstArgument.kind === SyntaxKind.StringLiteral &&
+          firstArgument.value === armCustomResourceUsageDiscourageCode) ||
+          (firstArgument.kind === SyntaxKind.Identifier &&
+            firstArgument.sv === armCustomResourceUsageDiscourageCode))
+      ) {
+        return true;
+      }
+    }
+    current = current.parent;
+  }
+  return false;
+}