Azure · audunn · Nov 22, 2023 · Nov 22, 2023 · Nov 22, 2023 · Nov 23, 2023
@@ -1,10 +1,12 @@
 # ARM (Control Plane) API Specification Update Pull Request 
 
+> Tip: overwhelmed by all this guidance? See the `Getting help` section at the bottom of this PR description.
+
 ## PR review workflow diagram
 
 Please understand this diagram before proceeding. It explains how to get your PR approved & merged.
 
-![diagram](https://github.com/Azure/azure-rest-api-specs/assets/4429827/029a11fd-eaf9-4865-9d77-a16b5ea5eb26)
+![diagram](https://github.com/Azure/azure-rest-api-specs/assets/20296335/35140fb9-639e-4e44-ac4b-38b1a20dddf9)
 
 <details>
 <summary> Click here to see the details of Step 1 </summary>
@@ -36,13 +38,11 @@ If the automation determines you have breaking changes, i.e. Step 1 from the dia
 
 ### Diagram footnotes
 
-[1] [ARM review queue] (for **merge** queues, see [4])  
+[1] [ARM review queue] (for **merge** queues, see [2])  
 The PRs are processed by time opened, ascending. Your PR may show up on 2nd or later page. 
 If you addressed Step 1 from the diagram and your PR is not showing up in the queue, ensure the label `ARMChangesRequested` 
-is removed from your PR. This should cause the label `WaitForARMFeedback` to be added.  
-[2] https://aka.ms/azsdk/support/specreview-channel  
-[3] [List of SDK breaking changes approvers] in pinned Teams announcement  
-[4] [public repo merge queue], [private repo merge queue] (for **ARM review** queue, [1])
+is removed from your PR. This should cause the label `WaitForARMFeedback` to be added.
+[2] [public repo merge queue], [private repo merge queue] (for **ARM review** queue, [1])
 
 If you need further help with anything, see `Getting help` section below.
 
@@ -89,15 +89,15 @@ to get approval.
 
 ## Getting help
 
-- For general PR approval workflow, see the diagram at the top of this comment.
+- First, please carefully read through this PR description, from top to bottom. Please fill out the `Purpose of this PR` and `Due diligence checklist`.
+- To understand what you must do next to merge this PR, see the `Next Steps to Merge` comment. It will appear within few minutes of submitting this PR and will continue to be up-to-date with current PR state.
 - For guidance on fixing this PR CI check failures, see the hyperlinks provided in given failure 
   and https://aka.ms/ci-fix.
 - If the PR CI checks appear to be stuck in `queued` state, please add a comment with contents `/azp run`.
-This should result in a new comment denoting a `PR validation pipeline` has started and the checks should be updated after few minutes.
+  This should result in a new comment denoting a `PR validation pipeline` has started and the checks should be updated after few minutes.
 - If the help provided by the previous points is not enough, post to https://aka.ms/azsdk/support/specreview-channel and link to this PR.
 
 [ARM review queue]: https://github.com/search?q=org%3AAzure+is%3Apr+is%3Aopen+label%3AWaitForARMFeedback+-label%3AIDCDevDiv++draft%3Afalse+sort%3Acreated-asc+&type=pullrequests
-[List of SDK breaking changes approvers]: https://teams.microsoft.com/l/message/19:0351f5f9404446e4b4fd4eaf2c27448d@thread.skype/1689115217750?tenantId=72f988bf-86f1-41af-91ab-2d7cd011db47&groupId=3e17dcb0-4257-4a30-b843-77f47f1d4121&parentMessageId=1689115217750&teamName=Azure%20SDK&channelName=API%20Spec%20Review&createdTime=1689115217750
 [public repo merge queue]: https://github.com/Azure/azure-rest-api-specs/pulls?q=is%3Aopen+is%3Apr+label%3AMergeRequested+draft%3Afalse+sort%3Acreated-asc
 [private repo merge queue]: https://github.com/Azure/azure-rest-api-specs-pr/pulls?q=is%3Aopen+is%3Apr+label%3AMergeRequested+-label%3AApproved-OkToMerge+draft%3Afalse+sort%3Acreated-asc
 [breaking changes process]: https://eng.ms/docs/cloud-ai-platform/azure-core/azure-core-pm-and-design/trusted-platform-pm-karimb/service-lifecycle-and-actions-team/service-lifecycle-actions-team/apex/media/launchingproductbreakingchanges#breaking-change-process-1
@@ -2529,16 +2529,7 @@ configuration:
       then:
       - removeLabel:
           label: no-recent-activity
-      description:
-    - if:
-      - payloadType: Pull_Request
-      then:
-      - if:
-        - filesMatchPattern:
-            pattern: specification/.*(\.tsp|tspconfig.yaml)
-        then:
-        - addLabel:
-            label: TypeSpec
+      description: 
     - if:
       - payloadType: Issue_Comment
       - and:

diff --git a/custom-words.txt b/custom-words.txt
@@ -56,6 +56,7 @@ adla
 adlarge
 adls
 adlsgen
+adma
 adminmanagement
 adou
 adsis
@@ -181,6 +182,7 @@ appfigures
 appid
 appinsights
 applynetworkconfigurationupdates
+approveRollingUpgrade
 appservice
 appsettings
 appsource
@@ -214,6 +216,7 @@ asyncoperation
 asyncrhonously
 asyncronously
 atascada
+atleast
 attachednetworks
 attestationcollateral
 attestationmechanism
@@ -526,6 +529,7 @@ codespaces
 coffeelake
 cognitiveservices
 collectiondetails
+cogservice
 colls
 colocation
 cololocation
@@ -539,6 +543,7 @@ compilationjobs
 compilefile
 compositeentities
 computervision
+computeusage
 concurrentappend
 conda
 configreferences
@@ -567,6 +572,7 @@ Contoso's
 contosodataset
 contosomedia
 contributer
+CONV
 convolutional
 cooldown
 copyid
@@ -734,6 +740,8 @@ deletedstorage
 deletedwithversions
 deletefailed
 deleteissuers
+deletejob
+deletejobs
 deleteprivateendpointconnection
 deletesas
 deletetype
@@ -953,6 +961,8 @@ exploitability
 exportconfiguration
 exportdevices
 exporterrors
+exportjob
+exportjobs
 exportstatus
 externaldatasources
 externaldnsipaddress01
@@ -1242,6 +1252,7 @@ hypernet
 hyperparameters
 hyperparams
 hyperscale
+hyperthread
 hyperv
 hypervcollectors
 iaas
@@ -1293,6 +1304,8 @@ immutabilitypolicy
 importances
 importcollectors
 importdevices
+importjob
+importjobs
 imsi
 inari
 inbuild
@@ -1645,6 +1658,7 @@ manytoone
 mapbox
 mapconfiguration
 mapconfigurations
+mapextensions
 mapp
 mapred
 mapreduce
@@ -2438,6 +2452,8 @@ ruleset
 rulesets
 rulestack
 rulestacks
+runasaccount
+runasaccounts
 runbook
 runbooks
 runid
@@ -2493,6 +2509,7 @@ scsv
 scvmm
 sddc
 sddl
+sdflex
 sdks
 sdwan
 searchbuffer
@@ -2629,6 +2646,7 @@ snmp
 snomed
 snssai
 sobol
+softwareinventories
 softwareplan
 sohsv
 solaris
@@ -2770,6 +2788,7 @@ subvolumes
 subwoofer
 subword
 subwords
+succeded
 suceeded
 sudoer
 suggesters
@@ -3013,6 +3032,7 @@ unrepaired
 unrestorable
 unsecure
 unsubstituted
+unsynchronized
 untagged
 untracked
 untrust
@@ -3084,9 +3104,11 @@ versioner
 versionid
 versionswithin
 vertica
+vffs
 vfyc
 vhds
 vhdx
+vmfs
 videoanalyzer
 videosearch
 viewp
@@ -3152,11 +3174,13 @@ vpndeviceconfigurationscript
 vray
 vrfs
 vrops
+vsan
 vsphere
 vsts
 vstsrm
 vuln
 vusers
+vvol
 vwan
 vxlan
 w3clogfile
@@ -3884,6 +3908,10 @@ usedCPUMHz
 totalCPUMHz
 docon
 DialOut
+vectorizers
+ONTAP
+SVM
+SVM's
 Vectorizable
 vectorizers
 Entra

diff --git a/documentation/Semantic-and-Model-Violations-Reference.md b/documentation/Semantic-and-Model-Violations-Reference.md
@@ -850,7 +850,7 @@ This document lists the set of automated rules that can be validated against swa
 
 **Output Message**: Long running operation should return {header} in header but not being provided.
 
-**Description**: Long running operation must return location header or azure-AsyncOperation header in response when this operation is annotated with x-ms-long-running-operation:true.
+**Description**: Long running operation must return `Operation-Id`, `Operation-Location`, or `azure-AsyncOperation` header in response when this operation is annotated with x-ms-long-running-operation:true.
 
 **How to fix the violation**: Adding one of these headers to the response in example or in traffic payload. Refer to this [example](https://github.com/Azure/azure-rest-api-specs/blob/5e638554b6/specification/appplatform/resource-manager/Microsoft.AppPlatform/stable/2020-07-01/examples/Apps_Update.json#L64) for the fix.
 

diff --git a/documentation/ci-fix.md b/documentation/ci-fix.md
@@ -10,9 +10,31 @@ Most guides here require for you to have `npm` installed, which you can get by i
 
 ## Spell check
 
-Please add your words to `./custom-words.txt` if you think you have the correct spell.
+If you receive a spelling failure either fix the spelling to match or if there are words that need to be suppressed for your service then add the word to the override list in [cspell.json](https://github.com/Azure/azure-rest-api-specs/blob/main/cSpell.json). Either
+add to your existing section or create a new section for your specific spec or service family if the work is more generally used in losts of files under your service.
+```
+ "overrides": [
+    ... example of specific file override
+    {
+        "filename": "**/specification/hdinsight/resource-manager/Microsoft.HDInsight/preview/2015-03-01-preview/cluster.json",
+        "words": [
+            "saskey"
+        ]
+    }
+    ... example of specific service family override
+    {
+        "filename": "**/specification/cognitiveservices/**/*.json",
+        "words": [
+            "flac",
+            "mpga"
+        ]
+    }
+```
+Words are case-insensitive so use lower case for the word list.
+
+If you need more information on see [cspell configuration](https://cspell.org/configuration/). 
 
-If your problem is some existing error name that is not a word and need to suppress the error in that file (and don't want to add to custom-words.txt), you can add it to `./cSpell.txt`.
+*Note*: We are trying to move away from one shared dictionary file so try and avoid editing custom-words.txt in the root as it will likely go away in the future.
 
 ## Prettier check
 

@@ -19,6 +19,23 @@ pr:
     - eng
     - specification/common-types
 
+resources:
+  pipelines:
+  - pipeline: typespec
+    source: typespec - CI
+    project: internal
+    trigger:
+      branches:
+        include:
+        - main
+  - pipeline: typespec-azure
+    source: typespec-azure - CI
+    project: internal
+    trigger:
+      branches:
+        include:
+        - main
+
 jobs:
 - job: Validate_All_Specs
 

@@ -6,10 +6,10 @@ import { FormatRule } from "./rules/format.js";
 import { GitDiffRule } from "./rules/git-diff.js";
 import { LinterRulesetRule } from "./rules/linter-ruleset.js";
 import { NpmPrefixRule } from "./rules/npm-prefix.js";
-import path from "path";
 import { TsvRunnerHost } from "./tsv-runner-host.js";
 
 export async function main() {
+  const host = new TsvRunnerHost();
   const args = process.argv.slice(2);
   const options = {
     folder: {
@@ -18,10 +18,10 @@ export async function main() {
     },
   };
   const parsedArgs = parseArgs({ args, options, allowPositionals: true } as ParseArgsConfig);
-  const folder = parsedArgs.positionals[0].split(path.sep).join("/");
-  console.log("Running TypeSpecValidation on folder:", folder);
+  const folder = parsedArgs.positionals[0];
+  const absolutePath = host.normalizePath(folder);
 
-  const host = new TsvRunnerHost();
+  console.log("Running TypeSpecValidation on folder: ", absolutePath);
 
   const rules = [
     new FolderStructureRule(),
@@ -36,7 +36,7 @@ export async function main() {
   for (let i = 0; i < rules.length; i++) {
     const rule = rules[i];
     console.log("\nExecuting rule: " + rule.name);
-    const result = await rule.execute(host, folder);
+    const result = await rule.execute(host, absolutePath);
     if (result.stdOutput) console.log(result.stdOutput);
     if (!result.success) {
       success = false;

@@ -1,4 +1,3 @@
-import { globby } from "globby";
 import path from "path";
 import { Rule } from "../rule.js";
 import { RuleResult } from "../rule-result.js";
@@ -11,6 +10,8 @@ export class FolderStructureRule implements Rule {
     let success = true;
     let stdOutput = "";
     let errorOutput = "";
+    let gitRoot = host.normalizePath(await host.gitOperation(folder).revparse("--show-toplevel"));
+    let relativePath = path.relative(gitRoot, folder).split(path.sep).join("/");
 
     stdOutput += `folder: ${folder}\n`;
     if (!(await host.checkFileExists(folder))) {
@@ -21,7 +22,7 @@ export class FolderStructureRule implements Rule {
       };
     }
 
-    const tspConfigs = await globby([`${folder}/**tspconfig.*`]);
+    const tspConfigs = await host.globby([`${folder}/**tspconfig.*`]);
     stdOutput += `config files: ${JSON.stringify(tspConfigs)}\n`;
     tspConfigs.forEach((file: string) => {
       if (!file.endsWith("tspconfig.yaml")) {
@@ -30,8 +31,8 @@ export class FolderStructureRule implements Rule {
       }
     });
 
-    // Verify top level folder is lower case
-    let folderStruct = folder.split("/");
+    // Verify top level folder is lower case and remove empty entries when splitting by slash
+    let folderStruct = relativePath.split("/").filter(Boolean);
     if (folderStruct[1].match(/[A-Z]/g)) {
       success = false;
       errorOutput += `Invalid folder name. Folders under specification/ must be lower case.\n`;

@@ -1,4 +1,3 @@
-import path from "path";
 import { Rule } from "../rule.js";
 import { RuleResult } from "../rule-result.js";
 import { TsvHost } from "../tsv-host.js";
@@ -13,7 +12,7 @@ export class NpmPrefixRule implements Rule {
     let expected_npm_prefix: string | undefined;
     try {
       // If spec folder is inside a git repo, returns repo root
-      expected_npm_prefix = path.normalize(await git.revparse("--show-toplevel"));
+      expected_npm_prefix = host.normalizePath(await git.revparse("--show-toplevel"));
     } catch (err) {
       // If spec folder is outside git repo, or if problem running git, throws error
       return {
@@ -22,7 +21,9 @@ export class NpmPrefixRule implements Rule {
       };
     }
 
-    const actual_npm_prefix = path.normalize((await host.runCmd(`npm prefix`, folder))[1].trim());
+    const actual_npm_prefix = host.normalizePath(
+      (await host.runCmd(`npm prefix`, folder))[1].trim(),
+    );
 
     let success = true;
     let stdOutput =