diff --git a/.github/skills/azure-typespec-author/SKILL.md b/.github/skills/azure-typespec-author/SKILL.md index 2bc6264dc6d..028d4dcf86a 100644 --- a/.github/skills/azure-typespec-author/SKILL.md +++ b/.github/skills/azure-typespec-author/SKILL.md @@ -3,7 +3,7 @@ name: azure-typespec-author license: MIT metadata: version: "1.0.0" -description: "Authors and modifies Azure TypeSpec (.tsp) API specifications. USE FOR: any TypeSpec/tsp change — api versions (add, bump, preview, stable, promote), resources, operations, models, properties, decorators, visibility, constraints, breaking changes, LRO, suppressions, operationId, spread model. Covers ARM resource-manager and data-plane services. DO NOT USE FOR: SDK generation, releasing SDK packages, or single MCP tool calls. INVOKES: azure-sdk-mcp:azsdk_typespec_generate_authoring_plan, azure-sdk-mcp:azsdk_run_typespec_validation." +description: "Authors and modifies Azure TypeSpec (.tsp) API specifications. MUST BE USED FOR ALL TypeSpec changes regardless of complexity — even adding a single property or enum value requires this skill's validation workflow. USE FOR: any TypeSpec/tsp change — api versions (add, bump, preview, stable, promote), resources, operations, models, properties, decorators, visibility, constraints, breaking changes, LRO, suppressions, operationId, spread model. Covers both ARM resource-manager (Azure.ResourceManager) and data-plane (Azure.Core) services. DO NOT USE FOR: SDK generation, releasing SDK packages, or single MCP tool calls. INVOKES: azure-sdk-mcp:azsdk_typespec_generate_authoring_plan, azure-sdk-mcp:azsdk_run_typespec_validation." compatibility: "azure-sdk-mcp server with azsdk_typespec_generate_authoring_plan and azsdk_run_typespec_validation tools" --- @@ -20,9 +20,11 @@ compatibility: "azure-sdk-mcp server with azsdk_typespec_generate_authoring_plan # When to invoke the azure-typespec-author skill -The `azure-typespec-author` skill **must** be invoked immediately in all modes (including plan mode) for any task that involves creating and modifying TypeSpec (`.tsp`) files except for `client.tsp` under the specification directory in this repository. This includes but is not limited to: +The `azure-typespec-author` skill **must** be invoked immediately in all modes (including plan mode) for any task that involves creating and modifying TypeSpec (`.tsp`) files except for `client.tsp` under the specification directory in this repository. **This skill MUST be used regardless of how simple the task appears** — there are no "simple" TypeSpec edits. Even trivial-seeming changes (adding a single enum value, one property, one operation) require the full workflow because versioning decorators, validation, and compliance checks are mandatory. -- Adding, bumping, or promoting API versions (preview, stable) +This includes but is not limited to: + +- Adding, bumping, or promoting API versions (preview, stable) for ARM or data-plane services - Adding or modifying resources, operations, models, properties, or decorators - Changing visibility, constraints, breaking changes, LRO patterns, or suppressions - Defining or updating operationId, spread models, or extension resources @@ -30,6 +32,7 @@ The `azure-typespec-author` skill **must** be invoked immediately in all modes ( ## Constraints +- **Do NOT skip this skill for "simple" tasks** — there are no simple TypeSpec edits. A single property addition can require `@added` decorators, version gating, and validation. Always invoke this skill. - **Always follow the full workflow** — even seemingly simple changes (e.g. adding a default value) can require complex versioning decorator changes. Never skip steps. - **Mandatory for ALL `.tsp` edits** — even a single `?` change can be breaking. - **Minimal, scoped edits** — only change what the request requires. @@ -88,3 +91,6 @@ Output all referenced document URLs from Step 3. This gives the user direct link - "Add a new preview API version 2026-01-01-preview for widget resource manager" - "Add an ARM resource named Asset with CRUD operations" - "Add a new property to the Widget model" +- "Add a list operation for the WidgetSuite resource using Azure.Core templates" +- "Add a new preview API version to a data-plane service" +- "Create a data-plane resource interface with full CRUD and list operations" diff --git a/.github/skills/azure-typespec-author/evaluate/.vally.yaml b/.github/skills/azure-typespec-author/evaluate/.vally.yaml index e0308b86996..6f319fbadfb 100644 --- a/.github/skills/azure-typespec-author/evaluate/.vally.yaml +++ b/.github/skills/azure-typespec-author/evaluate/.vally.yaml @@ -43,5 +43,7 @@ suites: evals: ["evals/004001.eval.yaml","evals/004002.eval.yaml","evals/004003.eval.yaml"] warning: evals: ["evals/005001.eval.yaml"] + dataplane: + evals: ["evals/006001.eval.yaml","evals/006002.eval.yaml","evals/006003.eval.yaml","evals/006004.eval.yaml","evals/006005.eval.yaml","evals/006006.eval.yaml","evals/006007.eval.yaml","evals/006008.eval.yaml","evals/006009.eval.yaml"] all: evals: ["evals/*.eval.yaml"] \ No newline at end of file diff --git a/.github/skills/azure-typespec-author/evaluate/README.md b/.github/skills/azure-typespec-author/evaluate/README.md index 4a385de5201..5c862a2d5b7 100644 --- a/.github/skills/azure-typespec-author/evaluate/README.md +++ b/.github/skills/azure-typespec-author/evaluate/README.md @@ -23,6 +23,7 @@ eval $(node scripts/setup-environment.js) ``` This script: + 1. Clones `package.json` and `package-lock.json` from [azure-rest-api-specs](https://github.com/Azure/azure-rest-api-specs) into `fixtures/Microsoft.Widget/Widget/`. 2. Runs `npm ci` in that directory. 3. Outputs the shell command to set `FIXTURE_NODE_MODULES` for symlink usage. @@ -65,6 +66,7 @@ Test suites are defined in `.vally.yaml` under the `suites` key. Available suite | `longrunningoperation` | Long-running operation cases (003xxx) | | `decorators` | Decorator cases (004xxx) | | `warning` | Warning cases (005xxx) | +| `dataplane` | Data-plane cases (006xxx) | | `all` | Every eval case | Run a suite by name: @@ -75,11 +77,11 @@ vally eval --suite versioning --output-dir versioning ### Useful flags -| Flag | Purpose | -|---|---| +| Flag | Purpose | +| ------------------------------ | -------------------------------------------------------------- | | `--keep-executor-session-logs` | Preserve agent session logs under `--output-dir` for debugging | -| `--verbose` | Show full agent output during the run | -| `--workers ` | Run multiple stimuli in parallel (default: 5) | +| `--verbose` | Show full agent output during the run | +| `--workers ` | Run multiple stimuli in parallel (default: 5) | ### Parallel run the environment diff --git a/.github/skills/azure-typespec-author/evaluate/evals/006001.eval.yaml b/.github/skills/azure-typespec-author/evaluate/evals/006001.eval.yaml new file mode 100644 index 00000000000..f2e0f9264b8 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/evals/006001.eval.yaml @@ -0,0 +1,63 @@ +name: azure-typespec-author-eval +description: Evaluation suite for azure-typespec-author. +version: "1.0" +type: capability + +environment: azsdk-mcp + +config: + runs: 1 + timeout: "1800s" + model: claude-opus-4.6 + executor: copilot-sdk + +stimuli: +- name: 006001-dp-add-create-operation + prompt: | + Add a create or update operation for the WidgetSuite resource to the Widgets interface. The operation should allow creating or updating a Widget asynchronously. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006001-dp-add-create-operation\main.tsp + dest: main.tsp + - src: ../fixtures/006001-dp-add-create-operation\shared.tsp + dest: shared.tsp + - src: ../fixtures/Microsoft.Widget/Widget/package.json + dest: package.json + - src: ../fixtures/Microsoft.Widget/Widget/package-lock.json + dest: package-lock.json + - src: ../fixtures/006001-dp-add-create-operation\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'LongRunningResourceCreateOrUpdate|ResourceCreateOrReplace|ResourceCreateOrUpdate' + - type: file-matches + config: + path: main.tsp + pattern: '@doc\(' + - type: prompt + config: + prompt: The Widgets interface should include a create or update operation for WidgetSuite using one of the Azure.Core resource operation templates. The operation should have a descriptive @doc decorator. + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +scoring: + weights: + tool-calls: 1 + skill-invocation: 1 + file-matches: 3 + prompt: 2 + threshold: 0.95 diff --git a/.github/skills/azure-typespec-author/evaluate/evals/006002.eval.yaml b/.github/skills/azure-typespec-author/evaluate/evals/006002.eval.yaml new file mode 100644 index 00000000000..2f88ab2cae9 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/evals/006002.eval.yaml @@ -0,0 +1,63 @@ +name: azure-typespec-author-eval +description: Evaluation suite for azure-typespec-author. +version: "1.0" +type: capability + +environment: azsdk-mcp + +config: + runs: 1 + timeout: "1800s" + model: claude-opus-4.6 + executor: copilot-sdk + +stimuli: +- name: 006002-dp-add-get-operation + prompt: | + Add a get operation for the WidgetSuite resource to the Widgets interface. The operation should allow fetching a Widget by name. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006002-dp-add-get-operation\main.tsp + dest: main.tsp + - src: ../fixtures/006002-dp-add-get-operation\shared.tsp + dest: shared.tsp + - src: ../fixtures/Microsoft.Widget/Widget/package.json + dest: package.json + - src: ../fixtures/Microsoft.Widget/Widget/package-lock.json + dest: package-lock.json + - src: ../fixtures/006002-dp-add-get-operation\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'ResourceRead' + - type: file-matches + config: + path: main.tsp + pattern: '@doc\(' + - type: prompt + config: + prompt: The Widgets interface should include a get/read operation for WidgetSuite using the ResourceRead Azure.Core operation template. The operation should have a descriptive @doc decorator. + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +scoring: + weights: + tool-calls: 1 + skill-invocation: 1 + file-matches: 3 + prompt: 2 + threshold: 1.0 diff --git a/.github/skills/azure-typespec-author/evaluate/evals/006003.eval.yaml b/.github/skills/azure-typespec-author/evaluate/evals/006003.eval.yaml new file mode 100644 index 00000000000..df03c2e179b --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/evals/006003.eval.yaml @@ -0,0 +1,63 @@ +name: azure-typespec-author-eval +description: Evaluation suite for azure-typespec-author. +version: "1.0" +type: capability + +environment: azsdk-mcp + +config: + runs: 1 + timeout: "1800s" + model: claude-opus-4.6 + executor: copilot-sdk + +stimuli: +- name: 006003-dp-add-list-operation + prompt: | + Add a list operation for the WidgetSuite resource to the Widgets interface. The operation should allow listing Widget resources with standard list query parameters. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006003-dp-add-list-operation\main.tsp + dest: main.tsp + - src: ../fixtures/006003-dp-add-list-operation\shared.tsp + dest: shared.tsp + - src: ../fixtures/Microsoft.Widget/Widget/package.json + dest: package.json + - src: ../fixtures/Microsoft.Widget/Widget/package-lock.json + dest: package-lock.json + - src: ../fixtures/006003-dp-add-list-operation\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'ResourceList Azure.Core operation template. The operation should have a descriptive @doc decorator. + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +scoring: + weights: + tool-calls: 1 + skill-invocation: 1 + file-matches: 3 + prompt: 2 + threshold: 1.0 diff --git a/.github/skills/azure-typespec-author/evaluate/evals/006004.eval.yaml b/.github/skills/azure-typespec-author/evaluate/evals/006004.eval.yaml new file mode 100644 index 00000000000..8534c405dcf --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/evals/006004.eval.yaml @@ -0,0 +1,76 @@ +name: azure-typespec-author-eval +description: Evaluation suite for azure-typespec-author. +version: "1.0" +type: capability + +environment: azsdk-mcp + +config: + runs: 1 + timeout: "1800s" + model: claude-opus-4.6 + executor: copilot-sdk + +stimuli: +- name: 006004-dp-create-resource-with-crud + prompt: | + Add a Widgets interface with full CRUD and list operations for the WidgetSuite resource. The interface should include operations to create or update, get, list, and delete widgets. Use the appropriate Azure.Core resource operation templates. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006004-dp-create-resource-with-crud\main.tsp + dest: main.tsp + - src: ../fixtures/006004-dp-create-resource-with-crud\shared.tsp + dest: shared.tsp + - src: ../fixtures/Microsoft.Widget/Widget/package.json + dest: package.json + - src: ../fixtures/Microsoft.Widget/Widget/package-lock.json + dest: package-lock.json + - src: ../fixtures/006004-dp-create-resource-with-crud\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'ResourceRead' + - type: file-matches + config: + path: main.tsp + pattern: 'LongRunningResourceCreateOrUpdate|ResourceCreateOrReplace|ResourceCreateOrUpdate' + - type: file-matches + config: + path: main.tsp + pattern: 'ResourceList|LongRunningResourceDelete' + - type: prompt + config: + prompt: | + A Widgets interface should be defined with operations for the WidgetSuite resource including: + 1. A get/read operation using ResourceRead + 2. A create or update operation using an Azure.Core create template + 3. A list operation using ResourceList + 4. A delete operation using ResourceDelete or LongRunningResourceDelete + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +scoring: + weights: + tool-calls: 1 + skill-invocation: 1 + file-matches: 3 + prompt: 2 + threshold: 1.0 diff --git a/.github/skills/azure-typespec-author/evaluate/evals/006005.eval.yaml b/.github/skills/azure-typespec-author/evaluate/evals/006005.eval.yaml new file mode 100644 index 00000000000..a82909e3ba4 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/evals/006005.eval.yaml @@ -0,0 +1,56 @@ +name: azure-typespec-author-eval +description: Evaluation suite for azure-typespec-author. +version: "1.0" +type: capability + +environment: azsdk-mcp + +config: + runs: 1 + timeout: "1800s" + model: claude-opus-4.6 + executor: copilot-sdk + +stimuli: +- name: 006005-dp-version-add-preview + prompt: | + Add a new preview version `2023-06-01-preview` to the Versions enum. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006005-dp-version-add-preview\main.tsp + dest: main.tsp + - src: ../fixtures/006005-dp-version-add-preview\shared.tsp + dest: shared.tsp + - src: ../fixtures/Microsoft.Widget/Widget/package.json + dest: package.json + - src: ../fixtures/Microsoft.Widget/Widget/package-lock.json + dest: package-lock.json + - src: ../fixtures/006005-dp-version-add-preview\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'v2023_06_01_Preview' + - type: file-matches + config: + path: main.tsp + pattern: '2023-06-01-preview' +scoring: + weights: + tool-calls: 1 + skill-invocation: 1 + file-matches: 3 + threshold: 1.0 diff --git a/.github/skills/azure-typespec-author/evaluate/evals/006006.eval.yaml b/.github/skills/azure-typespec-author/evaluate/evals/006006.eval.yaml new file mode 100644 index 00000000000..4beb29d5b4d --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/evals/006006.eval.yaml @@ -0,0 +1,61 @@ +name: azure-typespec-author-eval +description: Evaluation suite for azure-typespec-author. +version: "1.0" +type: capability + +environment: azsdk-mcp + +config: + runs: 1 + timeout: "1800s" + model: claude-opus-4.6 + executor: copilot-sdk + +stimuli: +- name: 006006-dp-version-add-stable + prompt: | + Add a new stable version `2023-06-01` to the Versions enum. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006006-dp-version-add-stable\main.tsp + dest: main.tsp + - src: ../fixtures/006006-dp-version-add-stable\shared.tsp + dest: shared.tsp + - src: ../fixtures/Microsoft.Widget/Widget/package.json + dest: package.json + - src: ../fixtures/Microsoft.Widget/Widget/package-lock.json + dest: package-lock.json + - src: ../fixtures/006006-dp-version-add-stable\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'v2023_06_01' + - type: file-matches + config: + path: main.tsp + pattern: '"2023-06-01"' + - type: file-not-matches + config: + path: main.tsp + pattern: '2023-06-01-preview' +scoring: + weights: + tool-calls: 1 + skill-invocation: 1 + file-matches: 3 + file-not-matches: 2 + threshold: 1.0 diff --git a/.github/skills/azure-typespec-author/evaluate/evals/006007.eval.yaml b/.github/skills/azure-typespec-author/evaluate/evals/006007.eval.yaml new file mode 100644 index 00000000000..dcccb88aece --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/evals/006007.eval.yaml @@ -0,0 +1,67 @@ +name: azure-typespec-author-eval +description: Evaluation suite for azure-typespec-author. +version: "1.0" +type: capability + +environment: azsdk-mcp + +config: + runs: 1 + timeout: "1800s" + model: claude-opus-4.6 + executor: copilot-sdk + +stimuli: +- name: 006007-dp-version-property-added + prompt: | + Add a new optional `description` property of type `string` to the WidgetSuite model only for version `2023-06-01-preview`. Also add this new version to the Versions enum. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006007-dp-version-property-added\main.tsp + dest: main.tsp + - src: ../fixtures/006007-dp-version-property-added\shared.tsp + dest: shared.tsp + - src: ../fixtures/Microsoft.Widget/Widget/package.json + dest: package.json + - src: ../fixtures/Microsoft.Widget/Widget/package-lock.json + dest: package-lock.json + - src: ../fixtures/006007-dp-version-property-added\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'v2023_06_01_Preview' + - type: file-matches + config: + path: main.tsp + pattern: '@added\(Versions\.v2023_06_01_Preview\)' + - type: file-matches + config: + path: main.tsp + pattern: 'description\?\: string' + - type: prompt + config: + prompt: The description property should be added to WidgetSuite with @added(Versions.v2023_06_01_Preview) decorator. A new version v2023_06_01_Preview should be added to the Versions enum. + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +scoring: + weights: + tool-calls: 1 + skill-invocation: 1 + file-matches: 3 + prompt: 2 + threshold: 1.0 diff --git a/.github/skills/azure-typespec-author/evaluate/evals/006008.eval.yaml b/.github/skills/azure-typespec-author/evaluate/evals/006008.eval.yaml new file mode 100644 index 00000000000..5da2e699c54 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/evals/006008.eval.yaml @@ -0,0 +1,67 @@ +name: azure-typespec-author-eval +description: Evaluation suite for azure-typespec-author. +version: "1.0" +type: capability + +environment: azsdk-mcp + +config: + runs: 1 + timeout: "1800s" + model: claude-opus-4.6 + executor: copilot-sdk + +stimuli: +- name: 006008-dp-version-property-removed + prompt: | + Remove the `color` property from the WidgetSuite model only for version `2023-06-01-preview`. Also add this new version to the Versions enum. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006008-dp-version-property-removed\main.tsp + dest: main.tsp + - src: ../fixtures/006008-dp-version-property-removed\shared.tsp + dest: shared.tsp + - src: ../fixtures/Microsoft.Widget/Widget/package.json + dest: package.json + - src: ../fixtures/Microsoft.Widget/Widget/package-lock.json + dest: package-lock.json + - src: ../fixtures/006008-dp-version-property-removed\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'v2023_06_01_Preview' + - type: file-matches + config: + path: main.tsp + pattern: '@removed\(Versions\.v2023_06_01_Preview\)' + - type: file-matches + config: + path: main.tsp + pattern: 'color' + - type: prompt + config: + prompt: The color property in WidgetSuite should have @removed(Versions.v2023_06_01_Preview) decorator added. The property itself should NOT be deleted from the model. A new version v2023_06_01_Preview should be added to the Versions enum. + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +scoring: + weights: + tool-calls: 1 + skill-invocation: 1 + file-matches: 3 + prompt: 2 + threshold: 1.0 diff --git a/.github/skills/azure-typespec-author/evaluate/evals/006009.eval.yaml b/.github/skills/azure-typespec-author/evaluate/evals/006009.eval.yaml new file mode 100644 index 00000000000..3a079255df1 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/evals/006009.eval.yaml @@ -0,0 +1,67 @@ +name: azure-typespec-author-eval +description: Evaluation suite for azure-typespec-author. +version: "1.0" +type: capability + +environment: azsdk-mcp + +config: + runs: 1 + timeout: "1800s" + model: claude-opus-4.6 + executor: copilot-sdk + +stimuli: +- name: 006009-dp-version-property-renamed + prompt: | + Rename the `color` property to `widgetColor` in the WidgetSuite model only for version `2023-06-01-preview`. Also add this new version to the Versions enum. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006009-dp-version-property-renamed\main.tsp + dest: main.tsp + - src: ../fixtures/006009-dp-version-property-renamed\shared.tsp + dest: shared.tsp + - src: ../fixtures/Microsoft.Widget/Widget/package.json + dest: package.json + - src: ../fixtures/Microsoft.Widget/Widget/package-lock.json + dest: package-lock.json + - src: ../fixtures/006009-dp-version-property-renamed\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'v2023_06_01_Preview' + - type: file-matches + config: + path: main.tsp + pattern: '@renamedFrom\(Versions\.v2023_06_01_Preview,\s*"color"\)' + - type: file-matches + config: + path: main.tsp + pattern: 'widgetColor' + - type: prompt + config: + prompt: The color property should be renamed to widgetColor and decorated with @renamedFrom(Versions.v2023_06_01_Preview, "color"). A new version v2023_06_01_Preview should be added to the Versions enum. + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +scoring: + weights: + tool-calls: 1 + skill-invocation: 1 + file-matches: 3 + prompt: 2 + threshold: 1.0 diff --git a/.github/skills/azure-typespec-author/evaluate/evals/eval.yaml b/.github/skills/azure-typespec-author/evaluate/evals/eval.yaml index 686217fde5c..25da7edcac2 100644 --- a/.github/skills/azure-typespec-author/evaluate/evals/eval.yaml +++ b/.github/skills/azure-typespec-author/evaluate/evals/eval.yaml @@ -3,7 +3,7 @@ # Keep this combined file synchronized with evals/*.eval.yaml single-case specs. # Preserve ordering for readability: stimulus uses name first; grader uses type before config. name: azure-typespec-author-eval -description: Combined evaluation suite for azure-typespec-author (all 29 cases). +description: Combined evaluation suite for azure-typespec-author (all 38 cases). version: "1.0" type: capability @@ -1663,3 +1663,392 @@ scoring: file-not-exists: 1 tool-calls: 1 threshold: 1.0 +# ── Data-plane operation cases (006xxx) ────────────────────────────────────── +- name: 006001-dp-add-create-operation + prompt: | + Add a create or update operation for the WidgetSuite resource to the Widgets interface. The operation should allow creating or updating a Widget asynchronously. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006001-dp-add-create-operation\main.tsp + dest: main.tsp + - src: ../fixtures/006001-dp-add-create-operation\shared.tsp + dest: shared.tsp + - src: ../fixtures/006001-dp-add-create-operation\package.json + dest: package.json + - src: ../fixtures/006001-dp-add-create-operation\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'LongRunningResourceCreateOrUpdate|ResourceCreateOrReplace|ResourceCreateOrUpdate' + - type: file-matches + config: + path: main.tsp + pattern: '@doc\(' + - type: prompt + config: + prompt: The Widgets interface should include a create or update operation for WidgetSuite using one of the Azure.Core resource operation templates. The operation should have a descriptive @doc decorator. + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +- name: 006002-dp-add-get-operation + prompt: | + Add a get operation for the WidgetSuite resource to the Widgets interface. The operation should allow fetching a Widget by name. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006002-dp-add-get-operation\main.tsp + dest: main.tsp + - src: ../fixtures/006002-dp-add-get-operation\shared.tsp + dest: shared.tsp + - src: ../fixtures/006002-dp-add-get-operation\package.json + dest: package.json + - src: ../fixtures/006002-dp-add-get-operation\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'ResourceRead' + - type: file-matches + config: + path: main.tsp + pattern: '@doc\(' + - type: prompt + config: + prompt: The Widgets interface should include a get/read operation for WidgetSuite using the ResourceRead Azure.Core operation template. The operation should have a descriptive @doc decorator. + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +- name: 006003-dp-add-list-operation + prompt: | + Add a list operation for the WidgetSuite resource to the Widgets interface. The operation should allow listing Widget resources with standard list query parameters. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006003-dp-add-list-operation\main.tsp + dest: main.tsp + - src: ../fixtures/006003-dp-add-list-operation\shared.tsp + dest: shared.tsp + - src: ../fixtures/006003-dp-add-list-operation\package.json + dest: package.json + - src: ../fixtures/006003-dp-add-list-operation\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'ResourceList Azure.Core operation template. The operation should have a descriptive @doc decorator. + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +- name: 006004-dp-create-resource-with-crud + prompt: | + Add a Widgets interface with full CRUD and list operations for the WidgetSuite resource. The interface should include operations to create or update, get, list, and delete widgets. Use the appropriate Azure.Core resource operation templates. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006004-dp-create-resource-with-crud\main.tsp + dest: main.tsp + - src: ../fixtures/006004-dp-create-resource-with-crud\shared.tsp + dest: shared.tsp + - src: ../fixtures/006004-dp-create-resource-with-crud\package.json + dest: package.json + - src: ../fixtures/006004-dp-create-resource-with-crud\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'ResourceRead' + - type: file-matches + config: + path: main.tsp + pattern: 'LongRunningResourceCreateOrUpdate|ResourceCreateOrReplace|ResourceCreateOrUpdate' + - type: file-matches + config: + path: main.tsp + pattern: 'ResourceList|LongRunningResourceDelete' + - type: prompt + config: + prompt: | + A Widgets interface should be defined with operations for the WidgetSuite resource including: + 1. A get/read operation using ResourceRead + 2. A create or update operation using an Azure.Core create template + 3. A list operation using ResourceList + 4. A delete operation using ResourceDelete or LongRunningResourceDelete + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +# ── Data-plane versioning cases (006xxx) ───────────────────────────────────── +- name: 006005-dp-version-add-preview + prompt: | + Add a new preview version `2023-06-01-preview` to the Versions enum. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006005-dp-version-add-preview\main.tsp + dest: main.tsp + - src: ../fixtures/006005-dp-version-add-preview\shared.tsp + dest: shared.tsp + - src: ../fixtures/006005-dp-version-add-preview\package.json + dest: package.json + - src: ../fixtures/006005-dp-version-add-preview\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'v2023_06_01_Preview' + - type: file-matches + config: + path: main.tsp + pattern: '2023-06-01-preview' +- name: 006006-dp-version-add-stable + prompt: | + Add a new stable version `2023-06-01` to the Versions enum. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006006-dp-version-add-stable\main.tsp + dest: main.tsp + - src: ../fixtures/006006-dp-version-add-stable\shared.tsp + dest: shared.tsp + - src: ../fixtures/006006-dp-version-add-stable\package.json + dest: package.json + - src: ../fixtures/006006-dp-version-add-stable\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'v2023_06_01' + - type: file-matches + config: + path: main.tsp + pattern: '"2023-06-01"' + - type: file-not-matches + config: + path: main.tsp + pattern: '2023-06-01-preview' +- name: 006007-dp-version-property-added + prompt: | + Add a new optional `description` property of type `string` to the WidgetSuite model only for version `2023-06-01-preview`. Also add this new version to the Versions enum. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006007-dp-version-property-added\main.tsp + dest: main.tsp + - src: ../fixtures/006007-dp-version-property-added\shared.tsp + dest: shared.tsp + - src: ../fixtures/006007-dp-version-property-added\package.json + dest: package.json + - src: ../fixtures/006007-dp-version-property-added\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'v2023_06_01_Preview' + - type: file-matches + config: + path: main.tsp + pattern: '@added\(Versions\.v2023_06_01_Preview\)' + - type: file-matches + config: + path: main.tsp + pattern: 'description\?\: string' + - type: prompt + config: + prompt: The description property should be added to WidgetSuite with @added(Versions.v2023_06_01_Preview) decorator. A new version v2023_06_01_Preview should be added to the Versions enum. + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +- name: 006008-dp-version-property-removed + prompt: | + Remove the `color` property from the WidgetSuite model only for version `2023-06-01-preview`. Also add this new version to the Versions enum. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006008-dp-version-property-removed\main.tsp + dest: main.tsp + - src: ../fixtures/006008-dp-version-property-removed\shared.tsp + dest: shared.tsp + - src: ../fixtures/006008-dp-version-property-removed\package.json + dest: package.json + - src: ../fixtures/006008-dp-version-property-removed\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'v2023_06_01_Preview' + - type: file-matches + config: + path: main.tsp + pattern: '@removed\(Versions\.v2023_06_01_Preview\)' + - type: file-matches + config: + path: main.tsp + pattern: 'color' + - type: prompt + config: + prompt: The color property in WidgetSuite should have @removed(Versions.v2023_06_01_Preview) decorator added. The property itself should NOT be deleted from the model. A new version v2023_06_01_Preview should be added to the Versions enum. + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +- name: 006009-dp-version-property-renamed + prompt: | + Rename the `color` property to `widgetColor` in the WidgetSuite model only for version `2023-06-01-preview`. Also add this new version to the Versions enum. + constraints: + max_turns: 10 + max_tokens: 5000 + environment: + files: + - src: ../fixtures/006009-dp-version-property-renamed\main.tsp + dest: main.tsp + - src: ../fixtures/006009-dp-version-property-renamed\shared.tsp + dest: shared.tsp + - src: ../fixtures/006009-dp-version-property-renamed\package.json + dest: package.json + - src: ../fixtures/006009-dp-version-property-renamed\tspconfig.yaml + dest: tspconfig.yaml + graders: + - type: tool-calls + config: + required: + - edit + - azure-sdk-mcp-azsdk_run_typespec_validation + - type: skill-invocation + config: + required: + - azure-typespec-author + - type: file-matches + config: + path: main.tsp + pattern: 'v2023_06_01_Preview' + - type: file-matches + config: + path: main.tsp + pattern: '@renamedFrom\(Versions\.v2023_06_01_Preview,\s*"color"\)' + - type: file-matches + config: + path: main.tsp + pattern: 'widgetColor' + - type: prompt + config: + prompt: The color property should be renamed to widgetColor and decorated with @renamedFrom(Versions.v2023_06_01_Preview, "color"). A new version v2023_06_01_Preview should be added to the Versions enum. + model: claude-opus-4.6 + scoring: scale_1_5 + threshold: 1.0 +scoring: + weights: + file-matches: 3 + file-not-matches: 2 + file-exists: 1 + file-not-exists: 1 + tool-calls: 1 + skill-invocation: 1 + prompt: 2 + threshold: 1.0 diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006001-dp-add-create-operation/main.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006001-dp-add-create-operation/main.tsp new file mode 100644 index 00000000000..8f2ce8c618f --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006001-dp-add-create-operation/main.tsp @@ -0,0 +1,52 @@ +import "@typespec/http"; +import "@typespec/rest"; +import "@typespec/versioning"; +import "@azure-tools/typespec-azure-core"; +import "./shared.tsp"; + +using TypeSpec.Http; +using TypeSpec.Rest; +using TypeSpec.Versioning; +using Azure.Core; + +@useAuth(AadOauth2Auth<["https://azure.com/.default"]>) +@service(#{ title: "WidgetAnalytics" }) +@versioned(WidgetAnalytics.Versions) +namespace WidgetAnalytics; + +@doc("Versions info.") +enum Versions { + @doc("The 2022-11-01-preview version.") + v2022_11_01_Preview: "2022-11-01-preview", + + @doc("The 2022-12-01 version.") + v2022_12_01: "2022-12-01", +} + +@doc("A widget.") +@resource("widgets") +model WidgetSuite { + @key("widgetName") + @doc("The widget name.") + @visibility(Lifecycle.Read) + name: string; + + @doc("The ID of the widget's manufacturer.") + manufacturerId: string; + + @doc("The faked shared model.") + sharedModel?: FakedSharedModel; +} + +interface Widgets { + @doc("Fetch a Widget by name.") + getWidget is ResourceRead; + + @doc("List Widget resources") + listWidgets is ResourceList< + WidgetSuite, + { + parameters: StandardListQueryParameters; + } + >; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006001-dp-add-create-operation/shared.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006001-dp-add-create-operation/shared.tsp new file mode 100644 index 00000000000..276c7071c1f --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006001-dp-add-create-operation/shared.tsp @@ -0,0 +1,5 @@ +@doc("A faked shared model for testing.") +model FakedSharedModel { + @doc("A shared property.") + sharedProperty?: string; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006001-dp-add-create-operation/tspconfig.yaml b/.github/skills/azure-typespec-author/evaluate/fixtures/006001-dp-add-create-operation/tspconfig.yaml new file mode 100644 index 00000000000..80cf2bc71d7 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006001-dp-add-create-operation/tspconfig.yaml @@ -0,0 +1,12 @@ +parameters: + "service-dir": + default: "sdk/widget" +emit: + - "@azure-tools/typespec-autorest" +options: + "@azure-tools/typespec-autorest": + emitter-output-dir: "{project-root}" + output-file: "{version-status}/{version}/widgetanalytics.json" +linter: + extends: + - "@azure-tools/typespec-azure-rulesets/data-plane" diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006002-dp-add-get-operation/main.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006002-dp-add-get-operation/main.tsp new file mode 100644 index 00000000000..b9219424bf4 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006002-dp-add-get-operation/main.tsp @@ -0,0 +1,52 @@ +import "@typespec/http"; +import "@typespec/rest"; +import "@typespec/versioning"; +import "@azure-tools/typespec-azure-core"; +import "./shared.tsp"; + +using TypeSpec.Http; +using TypeSpec.Rest; +using TypeSpec.Versioning; +using Azure.Core; + +@useAuth(AadOauth2Auth<["https://azure.com/.default"]>) +@service(#{ title: "WidgetAnalytics" }) +@versioned(WidgetAnalytics.Versions) +namespace WidgetAnalytics; + +@doc("Versions info.") +enum Versions { + @doc("The 2022-11-01-preview version.") + v2022_11_01_Preview: "2022-11-01-preview", + + @doc("The 2022-12-01 version.") + v2022_12_01: "2022-12-01", +} + +@doc("A widget.") +@resource("widgets") +model WidgetSuite { + @key("widgetName") + @doc("The widget name.") + @visibility(Lifecycle.Read) + name: string; + + @doc("The ID of the widget's manufacturer.") + manufacturerId: string; + + @doc("The faked shared model.") + sharedModel?: FakedSharedModel; +} + +interface Widgets { + @doc("Gets status of a Widget operation.") + getWidgetOperationStatus is GetResourceOperationStatus; + + @doc("Creates or updates a Widget asynchronously.") + @pollingOperation(Widgets.getWidgetOperationStatus) + createOrUpdateWidget is StandardResourceOperations.LongRunningResourceCreateOrUpdate; + + @doc("Delete a Widget asynchronously.") + @pollingOperation(Widgets.getWidgetOperationStatus) + deleteWidget is LongRunningResourceDelete; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006002-dp-add-get-operation/shared.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006002-dp-add-get-operation/shared.tsp new file mode 100644 index 00000000000..276c7071c1f --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006002-dp-add-get-operation/shared.tsp @@ -0,0 +1,5 @@ +@doc("A faked shared model for testing.") +model FakedSharedModel { + @doc("A shared property.") + sharedProperty?: string; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006002-dp-add-get-operation/tspconfig.yaml b/.github/skills/azure-typespec-author/evaluate/fixtures/006002-dp-add-get-operation/tspconfig.yaml new file mode 100644 index 00000000000..80cf2bc71d7 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006002-dp-add-get-operation/tspconfig.yaml @@ -0,0 +1,12 @@ +parameters: + "service-dir": + default: "sdk/widget" +emit: + - "@azure-tools/typespec-autorest" +options: + "@azure-tools/typespec-autorest": + emitter-output-dir: "{project-root}" + output-file: "{version-status}/{version}/widgetanalytics.json" +linter: + extends: + - "@azure-tools/typespec-azure-rulesets/data-plane" diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006003-dp-add-list-operation/main.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006003-dp-add-list-operation/main.tsp new file mode 100644 index 00000000000..b11d6720ed3 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006003-dp-add-list-operation/main.tsp @@ -0,0 +1,51 @@ +import "@typespec/http"; +import "@typespec/rest"; +import "@typespec/versioning"; +import "@azure-tools/typespec-azure-core"; +import "./shared.tsp"; + +using TypeSpec.Http; +using TypeSpec.Rest; +using TypeSpec.Versioning; +using Azure.Core; + +@useAuth(AadOauth2Auth<["https://azure.com/.default"]>) +@service(#{ title: "WidgetAnalytics" }) +@versioned(WidgetAnalytics.Versions) +namespace WidgetAnalytics; + +@doc("Versions info.") +enum Versions { + @doc("The 2022-11-01-preview version.") + v2022_11_01_Preview: "2022-11-01-preview", + + @doc("The 2022-12-01 version.") + v2022_12_01: "2022-12-01", +} + +@doc("A widget.") +@resource("widgets") +model WidgetSuite { + @key("widgetName") + @doc("The widget name.") + @visibility(Lifecycle.Read) + name: string; + + @doc("The ID of the widget's manufacturer.") + manufacturerId: string; + + @doc("The faked shared model.") + sharedModel?: FakedSharedModel; +} + +interface Widgets { + @doc("Fetch a Widget by name.") + getWidget is ResourceRead; + + @doc("Gets status of a Widget operation.") + getWidgetOperationStatus is GetResourceOperationStatus; + + @doc("Creates or updates a Widget asynchronously.") + @pollingOperation(Widgets.getWidgetOperationStatus) + createOrUpdateWidget is StandardResourceOperations.LongRunningResourceCreateOrUpdate; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006003-dp-add-list-operation/shared.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006003-dp-add-list-operation/shared.tsp new file mode 100644 index 00000000000..276c7071c1f --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006003-dp-add-list-operation/shared.tsp @@ -0,0 +1,5 @@ +@doc("A faked shared model for testing.") +model FakedSharedModel { + @doc("A shared property.") + sharedProperty?: string; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006003-dp-add-list-operation/tspconfig.yaml b/.github/skills/azure-typespec-author/evaluate/fixtures/006003-dp-add-list-operation/tspconfig.yaml new file mode 100644 index 00000000000..80cf2bc71d7 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006003-dp-add-list-operation/tspconfig.yaml @@ -0,0 +1,12 @@ +parameters: + "service-dir": + default: "sdk/widget" +emit: + - "@azure-tools/typespec-autorest" +options: + "@azure-tools/typespec-autorest": + emitter-output-dir: "{project-root}" + output-file: "{version-status}/{version}/widgetanalytics.json" +linter: + extends: + - "@azure-tools/typespec-azure-rulesets/data-plane" diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006004-dp-create-resource-with-crud/main.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006004-dp-create-resource-with-crud/main.tsp new file mode 100644 index 00000000000..27b033d4f85 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006004-dp-create-resource-with-crud/main.tsp @@ -0,0 +1,39 @@ +import "@typespec/http"; +import "@typespec/rest"; +import "@typespec/versioning"; +import "@azure-tools/typespec-azure-core"; +import "./shared.tsp"; + +using TypeSpec.Http; +using TypeSpec.Rest; +using TypeSpec.Versioning; +using Azure.Core; + +@useAuth(AadOauth2Auth<["https://azure.com/.default"]>) +@service(#{ title: "WidgetAnalytics" }) +@versioned(WidgetAnalytics.Versions) +namespace WidgetAnalytics; + +@doc("Versions info.") +enum Versions { + @doc("The 2022-11-01-preview version.") + v2022_11_01_Preview: "2022-11-01-preview", + + @doc("The 2022-12-01 version.") + v2022_12_01: "2022-12-01", +} + +@doc("A widget.") +@resource("widgets") +model WidgetSuite { + @key("widgetName") + @doc("The widget name.") + @visibility(Lifecycle.Read) + name: string; + + @doc("The ID of the widget's manufacturer.") + manufacturerId: string; + + @doc("The faked shared model.") + sharedModel?: FakedSharedModel; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006004-dp-create-resource-with-crud/shared.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006004-dp-create-resource-with-crud/shared.tsp new file mode 100644 index 00000000000..276c7071c1f --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006004-dp-create-resource-with-crud/shared.tsp @@ -0,0 +1,5 @@ +@doc("A faked shared model for testing.") +model FakedSharedModel { + @doc("A shared property.") + sharedProperty?: string; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006004-dp-create-resource-with-crud/tspconfig.yaml b/.github/skills/azure-typespec-author/evaluate/fixtures/006004-dp-create-resource-with-crud/tspconfig.yaml new file mode 100644 index 00000000000..80cf2bc71d7 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006004-dp-create-resource-with-crud/tspconfig.yaml @@ -0,0 +1,12 @@ +parameters: + "service-dir": + default: "sdk/widget" +emit: + - "@azure-tools/typespec-autorest" +options: + "@azure-tools/typespec-autorest": + emitter-output-dir: "{project-root}" + output-file: "{version-status}/{version}/widgetanalytics.json" +linter: + extends: + - "@azure-tools/typespec-azure-rulesets/data-plane" diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006005-dp-version-add-preview/main.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006005-dp-version-add-preview/main.tsp new file mode 100644 index 00000000000..ae741c9a518 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006005-dp-version-add-preview/main.tsp @@ -0,0 +1,47 @@ +import "@typespec/http"; +import "@typespec/rest"; +import "@typespec/versioning"; +import "@azure-tools/typespec-azure-core"; +import "./shared.tsp"; + +using TypeSpec.Http; +using TypeSpec.Rest; +using TypeSpec.Versioning; +using Azure.Core; + +@useAuth(AadOauth2Auth<["https://azure.com/.default"]>) +@service(#{ title: "WidgetAnalytics" }) +@versioned(WidgetAnalytics.Versions) +namespace WidgetAnalytics; + +@doc("Versions info.") +enum Versions { + @doc("The 2022-11-01-preview version.") + v2022_11_01_Preview: "2022-11-01-preview", + + @doc("The 2022-12-01 version.") + v2022_12_01: "2022-12-01", +} + +@doc("A widget.") +@resource("widgets") +model WidgetSuite { + @key("widgetName") + @doc("The widget name.") + @visibility(Lifecycle.Read) + name: string; + + @doc("The ID of the widget's manufacturer.") + manufacturerId: string; + + @doc("The faked shared model.") + sharedModel?: FakedSharedModel; +} + +interface Widgets { + @doc("Fetch a Widget by name.") + getWidget is ResourceRead; + + @doc("List Widget resources") + listWidgets is ResourceList; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006005-dp-version-add-preview/shared.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006005-dp-version-add-preview/shared.tsp new file mode 100644 index 00000000000..276c7071c1f --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006005-dp-version-add-preview/shared.tsp @@ -0,0 +1,5 @@ +@doc("A faked shared model for testing.") +model FakedSharedModel { + @doc("A shared property.") + sharedProperty?: string; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006005-dp-version-add-preview/tspconfig.yaml b/.github/skills/azure-typespec-author/evaluate/fixtures/006005-dp-version-add-preview/tspconfig.yaml new file mode 100644 index 00000000000..80cf2bc71d7 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006005-dp-version-add-preview/tspconfig.yaml @@ -0,0 +1,12 @@ +parameters: + "service-dir": + default: "sdk/widget" +emit: + - "@azure-tools/typespec-autorest" +options: + "@azure-tools/typespec-autorest": + emitter-output-dir: "{project-root}" + output-file: "{version-status}/{version}/widgetanalytics.json" +linter: + extends: + - "@azure-tools/typespec-azure-rulesets/data-plane" diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006006-dp-version-add-stable/main.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006006-dp-version-add-stable/main.tsp new file mode 100644 index 00000000000..ae741c9a518 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006006-dp-version-add-stable/main.tsp @@ -0,0 +1,47 @@ +import "@typespec/http"; +import "@typespec/rest"; +import "@typespec/versioning"; +import "@azure-tools/typespec-azure-core"; +import "./shared.tsp"; + +using TypeSpec.Http; +using TypeSpec.Rest; +using TypeSpec.Versioning; +using Azure.Core; + +@useAuth(AadOauth2Auth<["https://azure.com/.default"]>) +@service(#{ title: "WidgetAnalytics" }) +@versioned(WidgetAnalytics.Versions) +namespace WidgetAnalytics; + +@doc("Versions info.") +enum Versions { + @doc("The 2022-11-01-preview version.") + v2022_11_01_Preview: "2022-11-01-preview", + + @doc("The 2022-12-01 version.") + v2022_12_01: "2022-12-01", +} + +@doc("A widget.") +@resource("widgets") +model WidgetSuite { + @key("widgetName") + @doc("The widget name.") + @visibility(Lifecycle.Read) + name: string; + + @doc("The ID of the widget's manufacturer.") + manufacturerId: string; + + @doc("The faked shared model.") + sharedModel?: FakedSharedModel; +} + +interface Widgets { + @doc("Fetch a Widget by name.") + getWidget is ResourceRead; + + @doc("List Widget resources") + listWidgets is ResourceList; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006006-dp-version-add-stable/shared.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006006-dp-version-add-stable/shared.tsp new file mode 100644 index 00000000000..276c7071c1f --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006006-dp-version-add-stable/shared.tsp @@ -0,0 +1,5 @@ +@doc("A faked shared model for testing.") +model FakedSharedModel { + @doc("A shared property.") + sharedProperty?: string; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006006-dp-version-add-stable/tspconfig.yaml b/.github/skills/azure-typespec-author/evaluate/fixtures/006006-dp-version-add-stable/tspconfig.yaml new file mode 100644 index 00000000000..80cf2bc71d7 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006006-dp-version-add-stable/tspconfig.yaml @@ -0,0 +1,12 @@ +parameters: + "service-dir": + default: "sdk/widget" +emit: + - "@azure-tools/typespec-autorest" +options: + "@azure-tools/typespec-autorest": + emitter-output-dir: "{project-root}" + output-file: "{version-status}/{version}/widgetanalytics.json" +linter: + extends: + - "@azure-tools/typespec-azure-rulesets/data-plane" diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006007-dp-version-property-added/main.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006007-dp-version-property-added/main.tsp new file mode 100644 index 00000000000..ae741c9a518 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006007-dp-version-property-added/main.tsp @@ -0,0 +1,47 @@ +import "@typespec/http"; +import "@typespec/rest"; +import "@typespec/versioning"; +import "@azure-tools/typespec-azure-core"; +import "./shared.tsp"; + +using TypeSpec.Http; +using TypeSpec.Rest; +using TypeSpec.Versioning; +using Azure.Core; + +@useAuth(AadOauth2Auth<["https://azure.com/.default"]>) +@service(#{ title: "WidgetAnalytics" }) +@versioned(WidgetAnalytics.Versions) +namespace WidgetAnalytics; + +@doc("Versions info.") +enum Versions { + @doc("The 2022-11-01-preview version.") + v2022_11_01_Preview: "2022-11-01-preview", + + @doc("The 2022-12-01 version.") + v2022_12_01: "2022-12-01", +} + +@doc("A widget.") +@resource("widgets") +model WidgetSuite { + @key("widgetName") + @doc("The widget name.") + @visibility(Lifecycle.Read) + name: string; + + @doc("The ID of the widget's manufacturer.") + manufacturerId: string; + + @doc("The faked shared model.") + sharedModel?: FakedSharedModel; +} + +interface Widgets { + @doc("Fetch a Widget by name.") + getWidget is ResourceRead; + + @doc("List Widget resources") + listWidgets is ResourceList; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006007-dp-version-property-added/shared.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006007-dp-version-property-added/shared.tsp new file mode 100644 index 00000000000..276c7071c1f --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006007-dp-version-property-added/shared.tsp @@ -0,0 +1,5 @@ +@doc("A faked shared model for testing.") +model FakedSharedModel { + @doc("A shared property.") + sharedProperty?: string; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006007-dp-version-property-added/tspconfig.yaml b/.github/skills/azure-typespec-author/evaluate/fixtures/006007-dp-version-property-added/tspconfig.yaml new file mode 100644 index 00000000000..80cf2bc71d7 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006007-dp-version-property-added/tspconfig.yaml @@ -0,0 +1,12 @@ +parameters: + "service-dir": + default: "sdk/widget" +emit: + - "@azure-tools/typespec-autorest" +options: + "@azure-tools/typespec-autorest": + emitter-output-dir: "{project-root}" + output-file: "{version-status}/{version}/widgetanalytics.json" +linter: + extends: + - "@azure-tools/typespec-azure-rulesets/data-plane" diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006008-dp-version-property-removed/main.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006008-dp-version-property-removed/main.tsp new file mode 100644 index 00000000000..9f4fcc60dc9 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006008-dp-version-property-removed/main.tsp @@ -0,0 +1,50 @@ +import "@typespec/http"; +import "@typespec/rest"; +import "@typespec/versioning"; +import "@azure-tools/typespec-azure-core"; +import "./shared.tsp"; + +using TypeSpec.Http; +using TypeSpec.Rest; +using TypeSpec.Versioning; +using Azure.Core; + +@useAuth(AadOauth2Auth<["https://azure.com/.default"]>) +@service(#{ title: "WidgetAnalytics" }) +@versioned(WidgetAnalytics.Versions) +namespace WidgetAnalytics; + +@doc("Versions info.") +enum Versions { + @doc("The 2022-11-01-preview version.") + v2022_11_01_Preview: "2022-11-01-preview", + + @doc("The 2022-12-01 version.") + v2022_12_01: "2022-12-01", +} + +@doc("A widget.") +@resource("widgets") +model WidgetSuite { + @key("widgetName") + @doc("The widget name.") + @visibility(Lifecycle.Read) + name: string; + + @doc("The ID of the widget's manufacturer.") + manufacturerId: string; + + @doc("The color of the widget.") + color?: string; + + @doc("The faked shared model.") + sharedModel?: FakedSharedModel; +} + +interface Widgets { + @doc("Fetch a Widget by name.") + getWidget is ResourceRead; + + @doc("List Widget resources") + listWidgets is ResourceList; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006008-dp-version-property-removed/shared.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006008-dp-version-property-removed/shared.tsp new file mode 100644 index 00000000000..276c7071c1f --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006008-dp-version-property-removed/shared.tsp @@ -0,0 +1,5 @@ +@doc("A faked shared model for testing.") +model FakedSharedModel { + @doc("A shared property.") + sharedProperty?: string; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006008-dp-version-property-removed/tspconfig.yaml b/.github/skills/azure-typespec-author/evaluate/fixtures/006008-dp-version-property-removed/tspconfig.yaml new file mode 100644 index 00000000000..80cf2bc71d7 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006008-dp-version-property-removed/tspconfig.yaml @@ -0,0 +1,12 @@ +parameters: + "service-dir": + default: "sdk/widget" +emit: + - "@azure-tools/typespec-autorest" +options: + "@azure-tools/typespec-autorest": + emitter-output-dir: "{project-root}" + output-file: "{version-status}/{version}/widgetanalytics.json" +linter: + extends: + - "@azure-tools/typespec-azure-rulesets/data-plane" diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006009-dp-version-property-renamed/main.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006009-dp-version-property-renamed/main.tsp new file mode 100644 index 00000000000..9f4fcc60dc9 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006009-dp-version-property-renamed/main.tsp @@ -0,0 +1,50 @@ +import "@typespec/http"; +import "@typespec/rest"; +import "@typespec/versioning"; +import "@azure-tools/typespec-azure-core"; +import "./shared.tsp"; + +using TypeSpec.Http; +using TypeSpec.Rest; +using TypeSpec.Versioning; +using Azure.Core; + +@useAuth(AadOauth2Auth<["https://azure.com/.default"]>) +@service(#{ title: "WidgetAnalytics" }) +@versioned(WidgetAnalytics.Versions) +namespace WidgetAnalytics; + +@doc("Versions info.") +enum Versions { + @doc("The 2022-11-01-preview version.") + v2022_11_01_Preview: "2022-11-01-preview", + + @doc("The 2022-12-01 version.") + v2022_12_01: "2022-12-01", +} + +@doc("A widget.") +@resource("widgets") +model WidgetSuite { + @key("widgetName") + @doc("The widget name.") + @visibility(Lifecycle.Read) + name: string; + + @doc("The ID of the widget's manufacturer.") + manufacturerId: string; + + @doc("The color of the widget.") + color?: string; + + @doc("The faked shared model.") + sharedModel?: FakedSharedModel; +} + +interface Widgets { + @doc("Fetch a Widget by name.") + getWidget is ResourceRead; + + @doc("List Widget resources") + listWidgets is ResourceList; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006009-dp-version-property-renamed/shared.tsp b/.github/skills/azure-typespec-author/evaluate/fixtures/006009-dp-version-property-renamed/shared.tsp new file mode 100644 index 00000000000..276c7071c1f --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006009-dp-version-property-renamed/shared.tsp @@ -0,0 +1,5 @@ +@doc("A faked shared model for testing.") +model FakedSharedModel { + @doc("A shared property.") + sharedProperty?: string; +} diff --git a/.github/skills/azure-typespec-author/evaluate/fixtures/006009-dp-version-property-renamed/tspconfig.yaml b/.github/skills/azure-typespec-author/evaluate/fixtures/006009-dp-version-property-renamed/tspconfig.yaml new file mode 100644 index 00000000000..80cf2bc71d7 --- /dev/null +++ b/.github/skills/azure-typespec-author/evaluate/fixtures/006009-dp-version-property-renamed/tspconfig.yaml @@ -0,0 +1,12 @@ +parameters: + "service-dir": + default: "sdk/widget" +emit: + - "@azure-tools/typespec-autorest" +options: + "@azure-tools/typespec-autorest": + emitter-output-dir: "{project-root}" + output-file: "{version-status}/{version}/widgetanalytics.json" +linter: + extends: + - "@azure-tools/typespec-azure-rulesets/data-plane" diff --git a/.github/skills/azure-typespec-author/references/analyze-project.md b/.github/skills/azure-typespec-author/references/analyze-project.md index 10b5a9ecde4..cdd00d5b09f 100644 --- a/.github/skills/azure-typespec-author/references/analyze-project.md +++ b/.github/skills/azure-typespec-author/references/analyze-project.md @@ -4,7 +4,7 @@ Collect the inputs below from the TypeSpec project. Ask **up to 6 concise questi | # | Input | Example | | --- | --------------------------- | ---------------------------------------------------------------- | -| 1 | TypeSpec project root | `/specification/widget/resource-manager/Microsoft.Widget/Widget` | +| 1 | TypeSpec project root | ARM: `/specification/widget/resource-manager/Microsoft.Widget/Widget`
Data-plane: `/specification/widget/data-plane/WidgetAnalytics` | | 2 | Path to `tspconfig.yaml` | `/tspconfig.yaml` | | 3 | Service type | ARM / data-plane | | 4 | Existing API versions | `2024-01-01 (stable)`, `2024-06-01-preview` | diff --git a/.github/skills/azure-typespec-author/references/authoring-plan.md b/.github/skills/azure-typespec-author/references/authoring-plan.md index ffad8361602..2fb1a08c7d5 100644 --- a/.github/skills/azure-typespec-author/references/authoring-plan.md +++ b/.github/skills/azure-typespec-author/references/authoring-plan.md @@ -13,13 +13,26 @@ Use **both** tools to build an authoring plan, if the retrieved results have con 2. **Agentic Search** — run [agentic search](agentic-search.md) with URLs from [reference-document-links.md](reference-document-links.md) and a query from the user's request. Synthesize extracted content into a concrete plan. +> **Fallback**: If agentic search fails (all URLs unreachable or timeout exceeded), proceed with the MCP tool result alone. Do not block the workflow on unreachable external documentation. + --- ## 3.2 Case-Specific Authoring Plan -### Case 3 — API Version Evolution +### Case 3 — API Version Evolution (ARM / Data-plane) > **Must** use Agentic Search (option 2 above) to build the plan — do not call the MCP tool. 1. Copy `.json` files from latest version's `examples/` into new version's `examples/`. Update `api-version` in each file. Delete old version's example folder if old version is no longer existed. 2. Update `readme.md`. + +> These steps apply to both ARM and data-plane services. The same versioning decorators (`@added`, `@removed`, `@renamedFrom`, `@typeChangedFrom`) apply regardless of service type. + +### Case 4 — Add Data-Plane Operations + +Use the MCP tool (`azsdk_typespec_generate_authoring_plan`) to build the plan. Key guidance for data-plane: + +1. Use `Azure.Core` resource operation templates (see [intake.md](intake.md) Case 4 for the template table). +2. Define operations inside an `interface` block. +3. Add `/** */` documentation to all operations. +4. Data-plane services use `@azure-tools/typespec-azure-core`, not `@azure-tools/typespec-azure-resource-manager`. diff --git a/.github/skills/azure-typespec-author/references/intake.md b/.github/skills/azure-typespec-author/references/intake.md index 49afba988ba..90ce3e4028a 100644 --- a/.github/skills/azure-typespec-author/references/intake.md +++ b/.github/skills/azure-typespec-author/references/intake.md @@ -7,11 +7,12 @@ 1. Run [agentic search](agentic-search.md) using the Step 1 result and the user's request. 2. Identify the case from the table below and gather more information if case matches. If no case matches, skip Step 2.2. -| Case | Name | Description | Service Type | -| ---- | ----------------------- | ----------------------------------------------------- | ------------ | -| 1 | Add Resource Type | Define a new ARM resource with operations | ARM | -| 2 | Add Resource Operations | Add CRUD or custom actions on an existing resource | ARM | -| 3 | API Version Evolution | Add, bump, or promote an API version (preview/stable) | ARM | +| Case | Name | Description | Service Type | +| ---- | ------------------------- | ------------------------------------------------------ | ---------------- | +| 1 | Add Resource Type | Define a new ARM resource with operations | ARM | +| 2 | Add Resource Operations | Add CRUD or custom actions on an existing resource | ARM | +| 3 | API Version Evolution | Add, bump, or promote an API version (preview/stable) | ARM / Data-plane | +| 4 | Add Data-Plane Operations | Add CRUD or custom operations on a data-plane resource | Data-plane | --- @@ -35,7 +36,7 @@ Defaults: never async → GET, LIST, HEAD. Default async → PUT, DELETE. Defaul > Use `createOrReplace` (not `createOrUpdate`). Use `ArmCustomPatch` for PATCH. > For async POST, use ARM combined headers: `LroHeaders = ArmCombinedLroHeaders`. -### Case 3 — API Version Evolution (ARM) +### Case 3 — API Version Evolution (ARM / Data-plane) Collect from user: @@ -48,6 +49,18 @@ Collect from user: --- +> This case applies to both ARM and data-plane services. The same versioning decorators (`@added`, `@removed`, `@renamedFrom`, `@typeChangedFrom`) apply regardless of service type. + +### Case 4 — Add Data-Plane Operations + +Collect: target resource, operation type (CRUD, list, or custom action), operation name. + +> Data-plane services use `Azure.Core` (not `Azure.ResourceManager`). No `@armProviderNamespace` decorator. +> All operations, models, enums/unions, and properties should have `/** */` documentation. +> For async operations (long-running), refer to the [Deep Dive: Long-running (Asynchronous) Operations](https://azure.github.io/typespec-azure/docs/howtos/azure-core/long-running-operations/) documentation + +--- + ## 2.3 Confirm Display and wait for user confirmation: diff --git a/.github/skills/azure-typespec-author/references/reference-document-links.md b/.github/skills/azure-typespec-author/references/reference-document-links.md index 2fbaba1d048..7101940466e 100644 --- a/.github/skills/azure-typespec-author/references/reference-document-links.md +++ b/.github/skills/azure-typespec-author/references/reference-document-links.md @@ -8,3 +8,11 @@ - [stable → preview](https://azure.github.io/typespec-azure/docs/howtos/versioning/04-preview-after-stable/): How to add a new preview version after a stable version. - [stable → stable](https://azure.github.io/typespec-azure/docs/howtos/versioning/05-stable-after-stable/): How to add a new stable version after an existing stable version. - [Evolving APIs](https://azure.github.io/typespec-azure/docs/howtos/versioning/06-evolving-apis/): How to evolve your API across versions by adding, removing, or modifying resources, operations, and properties using versioning decorators. + +## Data-Plane Operations + +- [Azure.Core overview](https://azure.github.io/typespec-azure/docs/libraries/azure-core/): Overview of the Azure.Core library for data-plane TypeSpec services. +- [Azure.Core reference](https://azure.github.io/typespec-azure/docs/libraries/azure-core/reference): Full reference for Azure.Core decorators, interfaces, operations, and models. +- [Standard resource operations](https://azure.github.io/typespec-azure/docs/libraries/azure-core/reference/interfaces): Azure.Core operation templates (ResourceRead, ResourceList, ResourceCreateOrUpdate, ResourceDelete, etc.). +- [Data-plane getting started](https://azure.github.io/typespec-azure/docs/getstarted/azure-core/step00): Getting started guide for creating data-plane TypeSpec services with Azure.Core. +- [Deep Dive: Long-running (Asynchronous) Operations](https://azure.github.io/typespec-azure/docs/howtos/azure-core/long-running-operations/): Defining asynchronous (long-running) operations