Azure Core linter rules docs and cleanup - Pass 2

.chronus/changes/linter-rules-docs-2-2024-8-16-17-22-2.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: fix
+packages:
+  - "@azure-tools/typespec-azure-core"
+---
+
+Add docs for linting rules and stop excluding non `Azure.` namespace

.chronus/changes/linter-rules-docs-2-2024-8-16-21-23-23.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: fix
+packages:
+  - "@azure-tools/typespec-azure-rulesets"
+---
+
+Disable `@azure-tools/typespec-azure-core/standard-names` for `resource-manager` ruleset. Rule was already excluding ARM operations automatically this just configure the ruleset correctly

docs/libraries/azure-core/rules/auth-required.md

@@ -0,0 +1,46 @@
+---
+title: "auth-required"
+---
+
+```text title="Full name"
+@azure-tools/typespec-azure-core/auth-required
+```
+
+Ensure Azure Service define the authentication requirements. See https://azure.github.io/typespec-azure/docs/reference/azure-style-guide#security-definitions
+
+#### ❌ Incorrect
+
+```tsp
+@service
+namespace Azure.Service;
+```
+
+#### ✅ Correct
+
+- OAuth2
+
+```tsp
+@useAuth(AADToken)
+namespace Contoso.WidgetManager;
+
+@doc("The Azure Active Directory OAuth2 Flow")
+model AADToken
+  is OAuth2Auth<[
+    {
+      type: OAuth2FlowType.authorizationCode;
+      authorizationUrl: "https://api.example.com/oauth2/authorize";
+      tokenUrl: "https://api.example.com/oauth2/token";
+      scopes: ["https://management.azure.com/read", "https://management.azure.com/write"];
+    }
+  ]>;
+```
+
+- Api Key
+
+```tsp
+@useAuth(AzureKey)
+namespace Contoso.WidgetManager;
+
+@doc("The secret key for your Azure Cognitive Services subscription.")
+model AzureKey is ApiKeyAuth<ApiKeyLocation.header, "Ocp-Apim-Subscription-Key">;
+```

docs/libraries/azure-core/rules/casing-style.md

@@ -0,0 +1,51 @@
+---
+title: "casing-style"
+---
+
+```text title="Full name"
+@azure-tools/typespec-azure-core/casing-style
+```
+
+Validate names follow the [TypeSpec Style guide](https://typespec.io/docs/next/handbook/style-guide)
+
+#### ❌ Incorrect
+
+```tsp
+model pet {}
+model pet_food {}
+```
+
+```tsp
+model Pet {
+  Name: string;
+}
+```
+
+```tsp
+op CreatePet(): void;
+```
+
+```tsp
+interface petStores {}
+```
+
+#### ✅ Correct
+
+```tsp
+model Pet {}
+model PetFood {}
+```
+
+```tsp
+model Pet {
+  name: string;
+}
+```
+
+```tsp
+op createPet(): void;
+```
+
+```tsp
+interface PetStores {}
+```

docs/libraries/azure-core/rules/operation-missing-api-version.md

@@ -0,0 +1,25 @@
+---
+title: "operation-missing-api-version"
+---
+
+```text title="Full name"
+@azure-tools/typespec-azure-core/operation-missing-api-version
+```
+
+Ensure all operations have an `apiVersion` parameter.
+
+:::warning
+Seeing this error is also a sign that you are not using the Azure Standard templates. First double check why you cannot use them.
+:::
+
+#### ❌ Incorrect
+
+```tsp
+op createPet(pet: Pet): void;
+```
+
+### ✅ Correct
+
+```tsp
+op createPet(pet: Pet, ...Azure.Core.Foundations.ApiVersionParameter): void;
+```

docs/libraries/azure-core/rules/use-standard-names.md

@@ -0,0 +1,39 @@
+---
+title: "use-standard-names"
+---
+
+```text title="Full name"
+@azure-tools/typespec-azure-core/use-standard-names
+```
+
+Ensure Azure Service operations follow the naming recommendations.
+
+| Operation type                       | Naming convention                                 |
+| ------------------------------------ | ------------------------------------------------- |
+| `GET` returning single object        | Start with `get`                                  |
+| `GET` returning list of object       | Start with `list`                                 |
+| `PUT` returning both `200` and `201` | Start with `createOrReplace`                      |
+| `PUT` returning only `201`           | Start with `create` or `createOrReplace`          |
+| `PUT` returning only `200`           | Start with `replace` or `createOrReplace`         |
+| `PATCH` returning `201`              | Start with `create`, `update` or `createOrUpdate` |
+| `DELETE`                             | Start with `delete`                               |
+
+#### ❌ Incorrect
+
+```tsp
+op addPet is ResourceCreate<Pet>;
+```
+
+```tsp
+op getPets is ResourceList<Pet>;
+```
+
+#### ✅ Correct
+
+```tsp
+op createPet is ResourceCreate<Pet>;
+```
+
+```tsp
+op listPets is ResourceList<Pet>;
+```

packages/samples/specs/data-plane/api-path-parameter/main.tsp

@@ -13,6 +13,7 @@ using Azure.Core.Traits;
   title: "Contoso Widget Manager",
 })
 @versioned(Contoso.WidgetManager.Versions)
+@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-Key">)
 namespace Contoso.WidgetManager;
 
 @doc("The Contoso Widget Manager service version.")

packages/samples/specs/data-plane/azure-core-scalars/main.tsp

@@ -3,13 +3,15 @@ import "@typespec/rest";
 import "@typespec/versioning";
 import "@azure-tools/typespec-azure-core";
 
+using Http;
 using TypeSpec.Rest;
 using TypeSpec.Versioning;
 using Azure.Core;
 using Azure.Core.Traits;
 
 @service
 @versioned(Contoso.WidgetManager.Versions)
+@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-Key">)
 namespace Contoso.WidgetManager;
 
 @doc("The Contoso Widget Manager service version.")

packages/samples/specs/data-plane/custom-error-type/main.tsp

@@ -13,6 +13,7 @@ using Azure.Core.Traits;
   title: "Contoso Widget Manager",
 })
 @versioned(Contoso.WidgetManager.Versions)
+@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-Key">)
 namespace Contoso.WidgetManager;
 
 @doc("The Contoso Widget Manager service version.")

packages/samples/specs/data-plane/trait-versioning/main.tsp

@@ -13,6 +13,7 @@ using Azure.Core.Traits;
   title: "Contoso Widget Manager",
 })
 @versioned(Contoso.WidgetManager.Versions)
+@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-Key">)
 namespace Contoso.WidgetManager;
 
 @doc("The Contoso Widget Manager service version.")

packages/samples/specs/data-plane/widget-manager/main.tsp

@@ -13,6 +13,7 @@ using Azure.Core.Traits;
   title: "Contoso Widget Manager",
 })
 @versioned(Contoso.WidgetManager.Versions)
+@useAuth(ApiKeyAuth<ApiKeyLocation.header, "X-Key">)
 namespace Contoso.WidgetManager;
 
 @doc("The Contoso Widget Manager service version.")

packages/samples/test/output/azure/core/data-plane/api-path-parameter/@azure-tools/typespec-autorest/2022-08-31/openapi.json

@@ -18,6 +18,18 @@
   "consumes": [
     "application/json"
   ],
+  "security": [
+    {
+      "ApiKeyAuth": []
+    }
+  ],
+  "securityDefinitions": {
+    "ApiKeyAuth": {
+      "type": "apiKey",
+      "name": "X-Key",
+      "in": "header"
+    }
+  },
   "tags": [],
   "paths": {
     "/api/{api-version}/manufacturers": {

packages/samples/test/output/azure/core/data-plane/api-path-parameter/@typespec/openapi3/openapi.2022-08-31.yaml

@@ -647,6 +647,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Azure.Core.Foundations.ErrorResponse'
+security:
+  - ApiKeyAuth: []
 components:
   parameters:
     ApiVersionPathParameter:
@@ -907,3 +909,8 @@ components:
           type: string
           description: The ID of the widget's manufacturer.
       description: A widget.
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-Key

packages/samples/test/output/azure/core/data-plane/azure-core-scalars/@azure-tools/typespec-autorest/2022-08-31/openapi.json

@@ -18,6 +18,18 @@
   "consumes": [
     "application/json"
   ],
+  "security": [
+    {
+      "ApiKeyAuth": []
+    }
+  ],
+  "securityDefinitions": {
+    "ApiKeyAuth": {
+      "type": "apiKey",
+      "name": "X-Key",
+      "in": "header"
+    }
+  },
   "tags": [],
   "paths": {
     "/widgets/{widgetName}": {

packages/samples/test/output/azure/core/data-plane/azure-core-scalars/@typespec/openapi3/openapi.2022-08-31.yaml

@@ -45,6 +45,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/WidgetServiceErrorResponse'
+security:
+  - ApiKeyAuth: []
 components:
   parameters:
     Azure.Core.ClientRequestIdHeader:
@@ -170,3 +172,8 @@ components:
           type: string
           description: The error message.
       description: A custom error type for the Widget Manager service.
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-Key

packages/samples/test/output/azure/core/data-plane/custom-error-type/@azure-tools/typespec-autorest/2022-08-31/openapi.json

@@ -18,6 +18,18 @@
   "consumes": [
     "application/json"
   ],
+  "security": [
+    {
+      "ApiKeyAuth": []
+    }
+  ],
+  "securityDefinitions": {
+    "ApiKeyAuth": {
+      "type": "apiKey",
+      "name": "X-Key",
+      "in": "header"
+    }
+  },
   "tags": [],
   "paths": {
     "/widgets": {

packages/samples/test/output/azure/core/data-plane/custom-error-type/@typespec/openapi3/openapi.2022-08-31.yaml

@@ -296,6 +296,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/WidgetServiceErrorResponse'
+security:
+  - ApiKeyAuth: []
 components:
   parameters:
     Azure.Core.ClientRequestIdHeader:
@@ -523,3 +525,8 @@ components:
           type: string
           description: The error message.
       description: A custom error type for the Widget Manager service.
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-Key

packages/samples/test/output/azure/core/data-plane/trait-versioning/@azure-tools/typespec-autorest/2022-08-31/openapi.json

@@ -18,6 +18,18 @@
   "consumes": [
     "application/json"
   ],
+  "security": [
+    {
+      "ApiKeyAuth": []
+    }
+  ],
+  "securityDefinitions": {
+    "ApiKeyAuth": {
+      "type": "apiKey",
+      "name": "X-Key",
+      "in": "header"
+    }
+  },
   "tags": [],
   "paths": {
     "/manufacturers": {

packages/samples/test/output/azure/core/data-plane/trait-versioning/@azure-tools/typespec-autorest/2023-02-07/openapi.json

@@ -18,6 +18,18 @@
   "consumes": [
     "application/json"
   ],
+  "security": [
+    {
+      "ApiKeyAuth": []
+    }
+  ],
+  "securityDefinitions": {
+    "ApiKeyAuth": {
+      "type": "apiKey",
+      "name": "X-Key",
+      "in": "header"
+    }
+  },
   "tags": [],
   "paths": {
     "/manufacturers": {

packages/samples/test/output/azure/core/data-plane/trait-versioning/@typespec/openapi3/openapi.2022-08-31.yaml

@@ -593,6 +593,8 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Azure.Core.Foundations.ErrorResponse'
+security:
+  - ApiKeyAuth: []
 components:
   parameters:
     Azure.Core.ClientRequestIdHeader:
@@ -826,3 +828,8 @@ components:
           type: string
           description: The ID of the widget's manufacturer.
       description: A widget.
+  securitySchemes:
+    ApiKeyAuth:
+      type: apiKey
+      in: header
+      name: X-Key