diff --git a/.chronus/changes/linter-rule-docs-reference-pages-2026-07-20-13-45-00.md b/.chronus/changes/linter-rule-docs-reference-pages-2026-07-20-13-45-00.md new file mode 100644 index 0000000000..bda18c82a3 --- /dev/null +++ b/.chronus/changes/linter-rule-docs-reference-pages-2026-07-20-13-45-00.md @@ -0,0 +1,9 @@ +--- +changeKind: internal +packages: + - "@azure-tools/typespec-azure-core" + - "@azure-tools/typespec-azure-resource-manager" + - "@azure-tools/typespec-client-generator-core" +--- + +Migrate linter rule documentation to the tspd `docs` field so `tspd doc` auto-generates the per-rule reference pages. Rule extended docs now live next to each rule in `src/rules/.md` and are referenced via `docs: fileRef.fromPackageRoot(...)`. The generated pages keep their existing location (`libraries//rules/`) via the new `--rules-dir` tspd option, so rule URLs are unchanged. The generated pages are regenerated during the website build and are no longer tracked in git. diff --git a/.github/skills/create-linter-rule/SKILL.md b/.github/skills/create-linter-rule/SKILL.md index 35d2ce22b2..76188895d2 100644 --- a/.github/skills/create-linter-rule/SKILL.md +++ b/.github/skills/create-linter-rule/SKILL.md @@ -46,7 +46,7 @@ This creates: - `packages//src/rules/.ts` — rule skeleton - `packages//test/rules/.test.ts` — test skeleton -- `website/src/content/docs/docs/libraries//rules/.md` — docs skeleton +- `packages//src/rules/.md` — docs skeleton (referenced from the rule via `docs: fileRef.fromPackageRoot(...)`) - Updates `packages//src/linter.ts` — registers the rule ## Step 3: WRITE FAILING TESTS FIRST (TDD) @@ -143,12 +143,14 @@ pnpm --filter "@azure-tools/typespec-azure-rulesets..." test ## Step 7: WRITE DOCUMENTATION AND REGENERATE DOCS -Edit `website/src/content/docs/docs/libraries//rules/.md`: +Edit `packages//src/rules/.md`: - Replace all placeholder text - Write a clear description of what the rule checks and why - Provide realistic ❌ Incorrect and ✅ Correct examples using actual TypeSpec patterns -- Ensure the `Full name` code block shows the correct fully-qualified rule name +- This file holds only the extended documentation body — the page title, rule id, and + short description are generated from the rule definition. `tspd` renders the page at + `website/src/content/docs/docs/libraries//rules/.md` Then regenerate the library's reference docs (updates the rule listing): diff --git a/.gitignore b/.gitignore index 81afd13171..3fd37fc323 100644 --- a/.gitignore +++ b/.gitignore @@ -254,3 +254,8 @@ packages/typespec-java/emitter-tests/specs/** packages/typespec-java/emitter-tests/node_modules/** packages/typespec-java/emitter-tests/package-lock.json packages/typespec-java/emitter-tests/tsp-spector-coverage-*.json + +# Generated linter rule reference pages (produced by `tspd doc` / regen-docs via +# each rule's `docs` field). Regenerated during the website build (build:web), so +# they are not tracked. The rule source docs live in packages/*/src/rules/*.md. +website/src/content/docs/docs/libraries/*/rules/ diff --git a/core b/core index c6c1393efd..5510565782 160000 --- a/core +++ b/core @@ -1 +1 @@ -Subproject commit c6c1393efdaad7aff6dd9d0abfd8811815cb3ef0 +Subproject commit 551056578294891f8a3b4cb5e4c79832639937cc diff --git a/eng/feeds/test/init-templates.e2e.ts b/eng/feeds/test/init-templates.e2e.ts index 5f3bb8007a..b71a36250a 100644 --- a/eng/feeds/test/init-templates.e2e.ts +++ b/eng/feeds/test/init-templates.e2e.ts @@ -9,18 +9,20 @@ import { makeScaffoldingConfig, scaffoldNewProject, } from "../node_modules/@typespec/compiler/dist/src/init/scaffold.js"; +import { UriTemplateSource } from "../node_modules/@typespec/compiler/dist/src/init/template-source/uri-template-source.js"; const __dirname = import.meta.dirname; const root = resolve(__dirname, "../"); const testTempRoot = resolve(root, "temp/scaffolded-template-tests"); const snapshotFolder = resolve(root, "__snapshots__"); export const templatesDir = resolvePath(root); -const content = JSON.parse( - await readFile(resolvePath(templatesDir, "azure-scaffolding.json"), "utf-8"), -); +const scaffoldingIndexPath = resolvePath(templatesDir, "azure-scaffolding.json"); +const content = JSON.parse(await readFile(scaffoldingIndexPath, "utf-8")); + +/** Reads the template files referenced by the templates relative to the scaffolding index. */ +const templateSource = new UriTemplateSource(NodeHost, scaffoldingIndexPath); export const Templates = { - baseUri: templatesDir, templates: content as Record, }; @@ -86,7 +88,7 @@ describe("Init templates e2e tests", () => { makeScaffoldingConfig(template, { name, directory: targetFolder, - baseUri: Templates.baseUri, + source: templateSource, parameters, }), ); diff --git a/eng/scripts/create-linter-rule.ts b/eng/scripts/create-linter-rule.ts index 2ce5f9280b..c3b03d11e5 100644 --- a/eng/scripts/create-linter-rule.ts +++ b/eng/scripts/create-linter-rule.ts @@ -192,18 +192,7 @@ function main(): void { const packageRoot = resolve(repoRoot, "packages", config.packageDir); const rulePath = resolve(packageRoot, "src", "rules", `${options.ruleName}.ts`); const testPath = resolve(packageRoot, "test", "rules", `${options.ruleName}.test.ts`); - const docsPath = resolve( - repoRoot, - "website", - "src", - "content", - "docs", - "docs", - "libraries", - config.docsLibraryDir, - "rules", - `${options.ruleName}.md`, - ); + const docsPath = resolve(packageRoot, "src", "rules", `${options.ruleName}.md`); const linterPath = resolve(packageRoot, "src", "linter.ts"); const fileTargets = [rulePath, testPath, docsPath]; @@ -219,13 +208,14 @@ function main(): void { } const ruleFile = [ - 'import { createRule } from "@typespec/compiler";', + 'import { createRule, fileRef } from "@typespec/compiler";', "", `export const ${ruleIdentifier} = createRule({`, ` name: ${toDoubleQuotedString(options.ruleName)},`, ` description: ${toDoubleQuotedString(options.description)},`, ' severity: "warning",', ` url: ${toDoubleQuotedString(`https://azure.github.io/typespec-azure/docs/libraries/${config.docsLibraryDir}/rules/${options.ruleName}`)},`, + ` docs: fileRef.fromPackageRoot(${toDoubleQuotedString(`src/rules/${options.ruleName}.md`)}),`, " messages: {", ' default: "TODO: Add default diagnostic message.",', " },", @@ -287,14 +277,6 @@ function main(): void { ].join("\n"); const docsFile = [ - "---", - `title: ${toDoubleQuotedString(options.ruleName)}`, - "---", - "", - '```text title="Full name"', - `${config.packageNpmName}/${options.ruleName}`, - "```", - "", "TODO: Add a description of what this rule checks and why it matters.", "", "#### ❌ Incorrect", diff --git a/packages/typespec-azure-core/README.md b/packages/typespec-azure-core/README.md index 92590663dd..417e7e8d4d 100644 --- a/packages/typespec-azure-core/README.md +++ b/packages/typespec-azure-core/README.md @@ -51,7 +51,7 @@ Available ruleSets: | [`@azure-tools/typespec-azure-core/no-openapi`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-openapi) | Azure specs should not be using decorators from @typespec/openapi or @azure-tools/typespec-autorest | | [`@azure-tools/typespec-azure-core/no-unnamed-union`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-unnamed-union) | Azure services should not define a union expression but create a declaration. | | [`@azure-tools/typespec-azure-core/no-header-explode`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-header-explode) | It is recommended to serialize header parameter without explode: true | -| [`@azure-tools/typespec-azure-core/no-format`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/prevent-format) | Azure services should not use the `@format` decorator. | +| [`@azure-tools/typespec-azure-core/no-format`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-format) | Azure services should not use the `@format` decorator. | | [`@azure-tools/typespec-azure-core/no-multiple-discriminator`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-multiple-discriminator) | Classes should have at most one discriminator. | | [`@azure-tools/typespec-azure-core/no-rest-library-interfaces`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-rest-library-interfaces) | Resource interfaces from the TypeSpec.Rest.Resource library are incompatible with Azure.Core. | | [`@azure-tools/typespec-azure-core/no-unknown`](https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-unknown) | Azure services must not have properties of type `unknown`. | diff --git a/packages/typespec-azure-core/package.json b/packages/typespec-azure-core/package.json index c0c7ea5e21..5358e9ce3c 100644 --- a/packages/typespec-azure-core/package.json +++ b/packages/typespec-azure-core/package.json @@ -53,7 +53,7 @@ "test:ci": "vitest run --coverage --reporter=junit --reporter=default", "lint": "oxlint . --deny-warnings", "lint:fix": "oxlint . --fix", - "regen-docs": "tspd doc . --enable-experimental --llmstxt --output-dir ../../website/src/content/docs/docs/libraries/azure-core/reference" + "regen-docs": "tspd doc . --enable-experimental --llmstxt --rules-dir ../rules --output-dir ../../website/src/content/docs/docs/libraries/azure-core/reference" }, "files": [ "lib/**/*.tsp", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/auth-required.md b/packages/typespec-azure-core/src/rules/auth-required.md similarity index 89% rename from website/src/content/docs/docs/libraries/azure-core/rules/auth-required.md rename to packages/typespec-azure-core/src/rules/auth-required.md index ee41037c33..414fbab900 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/auth-required.md +++ b/packages/typespec-azure-core/src/rules/auth-required.md @@ -1,11 +1,3 @@ ---- -title: "auth-required" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/auth-required -``` - Ensure Azure services define their authentication requirements. See https://azure.github.io/typespec-azure/docs/reference/azure-style-guide#security-definitions #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/auth-required.ts b/packages/typespec-azure-core/src/rules/auth-required.ts index a4fef2424e..a3d668729f 100644 --- a/packages/typespec-azure-core/src/rules/auth-required.ts +++ b/packages/typespec-azure-core/src/rules/auth-required.ts @@ -1,8 +1,9 @@ -import { Namespace, createRule, getService } from "@typespec/compiler"; +import { Namespace, createRule, fileRef, getService } from "@typespec/compiler"; import { getAuthentication } from "@typespec/http"; export const authRequiredRule = createRule({ name: "auth-required", + docs: fileRef.fromPackageRoot("src/rules/auth-required.md"), description: "Enforce service authentication.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/auth-required", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/bad-record-type.md b/packages/typespec-azure-core/src/rules/bad-record-type.md similarity index 79% rename from website/src/content/docs/docs/libraries/azure-core/rules/bad-record-type.md rename to packages/typespec-azure-core/src/rules/bad-record-type.md index fee33e14e1..b8d07b2aae 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/bad-record-type.md +++ b/packages/typespec-azure-core/src/rules/bad-record-type.md @@ -1,11 +1,3 @@ ---- -title: "bad-record-type" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/bad-record-type -``` - Use of `Record` should be limited in Azure services. 1. It is recommended to use `Record` instead of `Record` diff --git a/packages/typespec-azure-core/src/rules/bad-record-type.ts b/packages/typespec-azure-core/src/rules/bad-record-type.ts index 0d57d40f50..f1d3fe0c1c 100644 --- a/packages/typespec-azure-core/src/rules/bad-record-type.ts +++ b/packages/typespec-azure-core/src/rules/bad-record-type.ts @@ -5,6 +5,7 @@ import { ModelProperty, Type, createRule, + fileRef, paramMessage, } from "@typespec/compiler"; @@ -76,6 +77,7 @@ function validatePropertyRecordType( export const badRecordTypeRule = createRule({ name: "bad-record-type", + docs: fileRef.fromPackageRoot("src/rules/bad-record-type.md"), description: "Identify bad record definitions.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/bad-record-type", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/byos.md b/packages/typespec-azure-core/src/rules/byos.md similarity index 91% rename from website/src/content/docs/docs/libraries/azure-core/rules/byos.md rename to packages/typespec-azure-core/src/rules/byos.md index 7bb91a2fd5..f42f5b0db0 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/byos.md +++ b/packages/typespec-azure-core/src/rules/byos.md @@ -1,11 +1,3 @@ ---- -title: "byos" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/byos -``` - Operations that upload binary data (using content types like `application/octet-stream` or `multipart/form-data`) should use the Bring Your Own Storage (BYOS) pattern recommended for Azure Services. See the [Azure REST API Guidelines - BYOS](https://github.com/microsoft/api-guidelines/blob/vNext/azure/Guidelines.md#bring-your-own-storage-byos) for more details. diff --git a/packages/typespec-azure-core/src/rules/byos.ts b/packages/typespec-azure-core/src/rules/byos.ts index 9dd251e3c9..e6564cb925 100644 --- a/packages/typespec-azure-core/src/rules/byos.ts +++ b/packages/typespec-azure-core/src/rules/byos.ts @@ -1,6 +1,7 @@ import { Operation, createRule, + fileRef, ignoreDiagnostics, isTemplateInstance, paramMessage, @@ -10,6 +11,7 @@ import { getHttpOperation } from "@typespec/http"; const binaryContentTypes = new Set(["application/octet-stream", "multipart/form-data"]); export const byosRule = createRule({ name: "byos", + docs: fileRef.fromPackageRoot("src/rules/byos.md"), description: "Use the BYOS pattern recommended for Azure Services.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/byos", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/casing-style.md b/packages/typespec-azure-core/src/rules/casing-style.md similarity index 80% rename from website/src/content/docs/docs/libraries/azure-core/rules/casing-style.md rename to packages/typespec-azure-core/src/rules/casing-style.md index 3d80405c0b..9464cceba7 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/casing-style.md +++ b/packages/typespec-azure-core/src/rules/casing-style.md @@ -1,11 +1,3 @@ ---- -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/handbook/style-guide) #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/casing-style.ts b/packages/typespec-azure-core/src/rules/casing-style.ts index 7da852c196..4afa9f1137 100644 --- a/packages/typespec-azure-core/src/rules/casing-style.ts +++ b/packages/typespec-azure-core/src/rules/casing-style.ts @@ -5,6 +5,7 @@ import { Namespace, Operation, createRule, + fileRef, isTemplateDeclarationOrInstance, paramMessage, } from "@typespec/compiler"; @@ -13,6 +14,7 @@ import { isCamelCaseNoAcronyms, isPascalCaseWithAcceptedAcronyms } from "./utils const acceptedAzureAcronyms = ["AI", "VM", "OS", "IP", "CPU", "GPU", "LRO"]; export const casingRule = createRule({ name: "casing-style", + docs: fileRef.fromPackageRoot("src/rules/casing-style.md"), description: "Ensure proper casing style.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/casing-style", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/composition-over-inheritance.md b/packages/typespec-azure-core/src/rules/composition-over-inheritance.md similarity index 87% rename from website/src/content/docs/docs/libraries/azure-core/rules/composition-over-inheritance.md rename to packages/typespec-azure-core/src/rules/composition-over-inheritance.md index 90a1ac79f7..d1d3601467 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/composition-over-inheritance.md +++ b/packages/typespec-azure-core/src/rules/composition-over-inheritance.md @@ -1,11 +1,3 @@ ---- -title: "composition-over-inheritance" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/composition-over-inheritance -``` - Models that extend a base model without a discriminator should use composition (`...` spread or `model is`) instead of inheritance (`extends`). If polymorphism is intended, add the `@discriminator` decorator on the base model. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/composition-over-inheritance.ts b/packages/typespec-azure-core/src/rules/composition-over-inheritance.ts index e1e4abdbcc..e929f2f834 100644 --- a/packages/typespec-azure-core/src/rules/composition-over-inheritance.ts +++ b/packages/typespec-azure-core/src/rules/composition-over-inheritance.ts @@ -1,5 +1,6 @@ import { createRule, + fileRef, getDiscriminator, getTypeName, isTemplateInstance, @@ -9,6 +10,7 @@ import { SyntaxKind } from "@typespec/compiler/ast"; export const compositionOverInheritanceRule = createRule({ name: "composition-over-inheritance", + docs: fileRef.fromPackageRoot("src/rules/composition-over-inheritance.md"), description: "Check that if a model is used in an operation and has derived models that it has a discriminator or recommend to use composition via spread or `is`.", severity: "warning", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/documentation-required.md b/packages/typespec-azure-core/src/rules/documentation-required.md similarity index 85% rename from website/src/content/docs/docs/libraries/azure-core/rules/documentation-required.md rename to packages/typespec-azure-core/src/rules/documentation-required.md index 439c0a4302..454f5f6fa6 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/documentation-required.md +++ b/packages/typespec-azure-core/src/rules/documentation-required.md @@ -1,11 +1,3 @@ ---- -title: "documentation-required" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/documentation-required -``` - Enums, models, operations, and their members/properties should have documentation. Use doc comments (`/** */`) to provide descriptions. #### ❌ Incorrect diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/friendly-name.md b/packages/typespec-azure-core/src/rules/friendly-name.md similarity index 88% rename from website/src/content/docs/docs/libraries/azure-core/rules/friendly-name.md rename to packages/typespec-azure-core/src/rules/friendly-name.md index 3d7b59392e..260725b05a 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/friendly-name.md +++ b/packages/typespec-azure-core/src/rules/friendly-name.md @@ -1,11 +1,3 @@ ---- -title: "friendly-name" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/friendly-name -``` - Ensures that `@friendlyName` is used as intended. The `@friendlyName` decorator should only be applied to template declarations and should reference template parameter properties in the friendly name string. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/friendly-name.ts b/packages/typespec-azure-core/src/rules/friendly-name.ts index 010a0464a4..25a1235e1d 100644 --- a/packages/typespec-azure-core/src/rules/friendly-name.ts +++ b/packages/typespec-azure-core/src/rules/friendly-name.ts @@ -5,6 +5,7 @@ import { DecoratorApplication, Enum, EnumMember, + fileRef, Interface, isTemplateInstance, LinterRuleContext, @@ -22,6 +23,7 @@ import { SyntaxKind } from "@typespec/compiler/ast"; export const friendlyNameRule = createRule({ name: "friendly-name", + docs: fileRef.fromPackageRoot("src/rules/friendly-name.md"), description: "Ensures that @friendlyName is used as intended.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/friendly-name", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/key-visibility-required.md b/packages/typespec-azure-core/src/rules/key-visibility-required.md similarity index 80% rename from website/src/content/docs/docs/libraries/azure-core/rules/key-visibility-required.md rename to packages/typespec-azure-core/src/rules/key-visibility-required.md index 4a7dba2168..d7a477ce88 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/key-visibility-required.md +++ b/packages/typespec-azure-core/src/rules/key-visibility-required.md @@ -1,11 +1,3 @@ ---- -title: "key-visibility-required" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/key-visibility-required -``` - Key properties need to have an explicit Lifecycle visibility setting. Use the `@visibility` decorator to specify the appropriate visibility for key properties. Without explicit visibility, the key property uses default visibility which may not match the intended behavior. #### ❌ Incorrect diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/known-encoding.md b/packages/typespec-azure-core/src/rules/known-encoding.md similarity index 89% rename from website/src/content/docs/docs/libraries/azure-core/rules/known-encoding.md rename to packages/typespec-azure-core/src/rules/known-encoding.md index 4bd1ed7d0c..857c4ddde2 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/known-encoding.md +++ b/packages/typespec-azure-core/src/rules/known-encoding.md @@ -1,11 +1,3 @@ ---- -title: "known-encoding" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/known-encoding -``` - Check that `@encode` uses a supported encoding for Azure services. Known supported encodings: diff --git a/packages/typespec-azure-core/src/rules/known-encoding.ts b/packages/typespec-azure-core/src/rules/known-encoding.ts index 521288f074..e3620b8805 100644 --- a/packages/typespec-azure-core/src/rules/known-encoding.ts +++ b/packages/typespec-azure-core/src/rules/known-encoding.ts @@ -1,4 +1,11 @@ -import { ModelProperty, Scalar, createRule, getEncode, paramMessage } from "@typespec/compiler"; +import { + ModelProperty, + Scalar, + createRule, + fileRef, + getEncode, + paramMessage, +} from "@typespec/compiler"; const knownEncodings = new Set([ // utcDateTime and offsetDateTime @@ -14,6 +21,7 @@ const knownEncodings = new Set([ ]); export const knownEncodingRule = createRule({ name: "known-encoding", + docs: fileRef.fromPackageRoot("src/rules/known-encoding.md"), description: "Check for supported encodings.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/known-encoding", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/long-running-polling-operation-required.md b/packages/typespec-azure-core/src/rules/long-running-polling-operation-required.md similarity index 85% rename from website/src/content/docs/docs/libraries/azure-core/rules/long-running-polling-operation-required.md rename to packages/typespec-azure-core/src/rules/long-running-polling-operation-required.md index fc15a29563..2f7a0954a3 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/long-running-polling-operation-required.md +++ b/packages/typespec-azure-core/src/rules/long-running-polling-operation-required.md @@ -1,11 +1,3 @@ ---- -title: "long-running-polling-operation-required" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/long-running-polling-operation-required -``` - Long-running operations that return an `Operation-Location` header should have a linked polling operation. Use the `@pollingOperation` decorator to link a status polling operation. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/lro-polling-operation.ts b/packages/typespec-azure-core/src/rules/lro-polling-operation.ts index ebbe5b6e3c..da4594e585 100644 --- a/packages/typespec-azure-core/src/rules/lro-polling-operation.ts +++ b/packages/typespec-azure-core/src/rules/lro-polling-operation.ts @@ -1,4 +1,4 @@ -import { Operation, Program, Type, createRule } from "@typespec/compiler"; +import { Operation, Program, Type, createRule, fileRef } from "@typespec/compiler"; import { getHeaderFieldName, isHeader } from "@typespec/http"; import { getOperationLink } from "../decorators/operation-link.js"; import { @@ -22,6 +22,7 @@ function hasOperationLocation(program: Program, entity: Type): boolean { export const longRunningOperationsRequirePollingOperation = createRule({ name: "long-running-polling-operation-required", + docs: fileRef.fromPackageRoot("src/rules/long-running-polling-operation-required.md"), description: "Long-running operations should have a linked polling operation.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/long-running-polling-operation-required", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-case-mismatch.md b/packages/typespec-azure-core/src/rules/no-case-mismatch.md similarity index 87% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-case-mismatch.md rename to packages/typespec-azure-core/src/rules/no-case-mismatch.md index 29e811f296..0fc34e8f27 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-case-mismatch.md +++ b/packages/typespec-azure-core/src/rules/no-case-mismatch.md @@ -1,11 +1,3 @@ ---- -title: "no-case-mismatch" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-case-mismatch -``` - Validate that no two types have the same name with different casing. Having types that differ only by casing can cause issues in case-insensitive languages and is generally confusing. This applies to models, enums, and unions. :::note diff --git a/packages/typespec-azure-core/src/rules/no-case-mismatch.ts b/packages/typespec-azure-core/src/rules/no-case-mismatch.ts index dcb6231d94..4bcdb184e3 100644 --- a/packages/typespec-azure-core/src/rules/no-case-mismatch.ts +++ b/packages/typespec-azure-core/src/rules/no-case-mismatch.ts @@ -4,6 +4,7 @@ import { type Namespace, type Union, createRule, + fileRef, isTemplateInstance, paramMessage, } from "@typespec/compiler"; @@ -13,6 +14,7 @@ type DataType = Model | Union | Enum; export const noCaseMismatchRule = createRule({ name: "no-case-mismatch", + docs: fileRef.fromPackageRoot("src/rules/no-case-mismatch.md"), description: "Validate that no two types have the same name with different casing.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-case-mismatch", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-closed-literal-union.md b/packages/typespec-azure-core/src/rules/no-closed-literal-union.md similarity index 81% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-closed-literal-union.md rename to packages/typespec-azure-core/src/rules/no-closed-literal-union.md index fff091a82e..07353f56ff 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-closed-literal-union.md +++ b/packages/typespec-azure-core/src/rules/no-closed-literal-union.md @@ -1,11 +1,3 @@ ---- -title: "no-closed-literal-union" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-closed-literal-union -``` - Azure services favor extensible enums to avoid breaking changes as new enum values are added. When using a union of only string or numeric literals it is the equivalent to a closed enum. Adding the base scalar(`string`, `int32`, `int64`, etc.) as a variant to the union makes it extensible. diff --git a/packages/typespec-azure-core/src/rules/no-closed-literal-union.ts b/packages/typespec-azure-core/src/rules/no-closed-literal-union.ts index 44825199fa..29b74a9b3f 100644 --- a/packages/typespec-azure-core/src/rules/no-closed-literal-union.ts +++ b/packages/typespec-azure-core/src/rules/no-closed-literal-union.ts @@ -1,8 +1,9 @@ -import { Union, createRule, ignoreDiagnostics } from "@typespec/compiler"; +import { Union, createRule, fileRef, ignoreDiagnostics } from "@typespec/compiler"; import { getUnionAsEnum } from "../helpers/union-enums.js"; export const noClosedLiteralUnionRule = createRule({ name: "no-closed-literal-union", + docs: fileRef.fromPackageRoot("src/rules/no-closed-literal-union.md"), description: "Unions of literals should include the base scalar type to mark them as open enum.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-closed-literal-union", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-enum.md b/packages/typespec-azure-core/src/rules/no-enum.md similarity index 84% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-enum.md rename to packages/typespec-azure-core/src/rules/no-enum.md index 163be2cf76..cb694d2d9d 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-enum.md +++ b/packages/typespec-azure-core/src/rules/no-enum.md @@ -1,11 +1,3 @@ ---- -title: "no-enum" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-enum -``` - Azure services favor extensible enums to avoid breaking changes as new enum values are added. TypeSpec enums are closed. Using a union with the base scalar(`string`, `int32`, `int64`, etc.) as a variant instead of an enum makes it extensible. diff --git a/packages/typespec-azure-core/src/rules/no-enum.ts b/packages/typespec-azure-core/src/rules/no-enum.ts index fef5e9eb7e..8cde1a50e4 100644 --- a/packages/typespec-azure-core/src/rules/no-enum.ts +++ b/packages/typespec-azure-core/src/rules/no-enum.ts @@ -2,6 +2,7 @@ import { CodeFix, Enum, createRule, + fileRef, getPositionBeforeTrivia, getSourceLocation, paramMessage, @@ -17,6 +18,7 @@ import { import { getVersionsForEnum } from "@typespec/versioning"; export const noEnumRule = createRule({ name: "no-enum", + docs: fileRef.fromPackageRoot("src/rules/no-enum.md"), description: "Azure services should not use enums.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-enum", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-error-status-codes.md b/packages/typespec-azure-core/src/rules/no-error-status-codes.md similarity index 84% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-error-status-codes.md rename to packages/typespec-azure-core/src/rules/no-error-status-codes.md index 7c0fbb1972..68c62c5d00 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-error-status-codes.md +++ b/packages/typespec-azure-core/src/rules/no-error-status-codes.md @@ -1,11 +1,3 @@ ---- -title: "no-error-status-codes" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-error-status-codes -``` - Azure REST API guidelines recommend using the `default` error response for all error cases. Avoid defining custom 4xx or 5xx error status codes individually. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/no-error-status-codes.ts b/packages/typespec-azure-core/src/rules/no-error-status-codes.ts index 3e7e1e90b6..56507dca54 100644 --- a/packages/typespec-azure-core/src/rules/no-error-status-codes.ts +++ b/packages/typespec-azure-core/src/rules/no-error-status-codes.ts @@ -1,9 +1,10 @@ -import { Operation, createRule, ignoreDiagnostics } from "@typespec/compiler"; +import { Operation, createRule, fileRef, ignoreDiagnostics } from "@typespec/compiler"; import { getHttpOperation } from "@typespec/http"; import { isAzureSubNamespace, isExcludedCoreType } from "./utils.js"; export const noErrorStatusCodesRule = createRule({ name: "no-error-status-codes", + docs: fileRef.fromPackageRoot("src/rules/no-error-status-codes.md"), description: "Recommend using the error response defined by Azure REST API guidelines.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-error-status-codes", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-explicit-routes-resource-ops.md b/packages/typespec-azure-core/src/rules/no-explicit-routes-resource-ops.md similarity index 86% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-explicit-routes-resource-ops.md rename to packages/typespec-azure-core/src/rules/no-explicit-routes-resource-ops.md index d2fe50158e..47f169cdee 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-explicit-routes-resource-ops.md +++ b/packages/typespec-azure-core/src/rules/no-explicit-routes-resource-ops.md @@ -1,11 +1,3 @@ ---- -title: "no-explicit-routes-resource-ops" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-explicit-routes-resource-ops -``` - The `@route` decorator should not be used on standard resource operation signatures. Standard resource operations already have well-defined routes. If you need to add a route prefix, use `@route` on an interface or namespace instead. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/no-explicit-routes-resource-ops.ts b/packages/typespec-azure-core/src/rules/no-explicit-routes-resource-ops.ts index a5af787ea9..50c2aaf451 100644 --- a/packages/typespec-azure-core/src/rules/no-explicit-routes-resource-ops.ts +++ b/packages/typespec-azure-core/src/rules/no-explicit-routes-resource-ops.ts @@ -1,10 +1,11 @@ -import { Operation, createRule } from "@typespec/compiler"; +import { Operation, createRule, fileRef } from "@typespec/compiler"; import { getRoutePath } from "@typespec/http"; import { isResourceOperation } from "../decorators/private/ensure-resource-type.js"; import { isExcludedCoreType } from "./utils.js"; export const noExplicitRoutesResourceOps = createRule({ name: "no-explicit-routes-resource-ops", + docs: fileRef.fromPackageRoot("src/rules/no-explicit-routes-resource-ops.md"), description: "The @route decorator should not be used on standard resource operation signatures.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-explicit-routes-resource-ops", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/prevent-format.md b/packages/typespec-azure-core/src/rules/no-format.md similarity index 90% rename from website/src/content/docs/docs/libraries/azure-core/rules/prevent-format.md rename to packages/typespec-azure-core/src/rules/no-format.md index 0c19084d4b..d6a99e1e61 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/prevent-format.md +++ b/packages/typespec-azure-core/src/rules/no-format.md @@ -1,11 +1,3 @@ ---- -title: "prevent-format" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/prevent-format -``` - Using the `@format` decorator is disallowed. While in OpenAPI `format:` was used to both represent a known string format and a more precise type, in TypeSpec `@format` is only meant to represent a known pattern for a string. This means that using `@format` would result in a `string` type with some validation. ## Mapping of format to types diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-generic-numeric.md b/packages/typespec-azure-core/src/rules/no-generic-numeric.md similarity index 79% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-generic-numeric.md rename to packages/typespec-azure-core/src/rules/no-generic-numeric.md index 0aac813129..880651bea1 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-generic-numeric.md +++ b/packages/typespec-azure-core/src/rules/no-generic-numeric.md @@ -1,11 +1,3 @@ ---- -title: "no-generic-numeric" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-generic-numeric -``` - Azure services should use numeric types that specify the bit-width instead of generic types. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/no-generic-numeric.ts b/packages/typespec-azure-core/src/rules/no-generic-numeric.ts index a7766777f0..5a7e36e86a 100644 --- a/packages/typespec-azure-core/src/rules/no-generic-numeric.ts +++ b/packages/typespec-azure-core/src/rules/no-generic-numeric.ts @@ -1,4 +1,4 @@ -import { Model, Scalar, createRule, paramMessage } from "@typespec/compiler"; +import { Model, Scalar, createRule, fileRef, paramMessage } from "@typespec/compiler"; const disallowList = new Set(["integer", "numeric", "float", "decimal"]); const alternatives = new Map([ @@ -10,6 +10,7 @@ const alternatives = new Map([ export const noGenericNumericRule = createRule({ name: "no-generic-numeric", + docs: fileRef.fromPackageRoot("src/rules/no-generic-numeric.md"), description: "Don't use generic types. Use more specific types instead.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-generic-numeric", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-header-explode.md b/packages/typespec-azure-core/src/rules/no-header-explode.md similarity index 81% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-header-explode.md rename to packages/typespec-azure-core/src/rules/no-header-explode.md index 9efb7bb944..f5aa74353a 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-header-explode.md +++ b/packages/typespec-azure-core/src/rules/no-header-explode.md @@ -1,11 +1,3 @@ ---- -title: "no-header-explode" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-header-explode -``` - Azure services favor serializing header parameter of array type using the simple style(Where each values is joined by a `,`) Using `explode: true` property specify that each individual value of the array should be sent as a separate header parameter. diff --git a/packages/typespec-azure-core/src/rules/no-header-explode.ts b/packages/typespec-azure-core/src/rules/no-header-explode.ts index e1ef44620c..3b2147beb4 100644 --- a/packages/typespec-azure-core/src/rules/no-header-explode.ts +++ b/packages/typespec-azure-core/src/rules/no-header-explode.ts @@ -1,8 +1,9 @@ -import { createRule, ignoreDiagnostics, Operation } from "@typespec/compiler"; +import { createRule, fileRef, ignoreDiagnostics, Operation } from "@typespec/compiler"; import { getHttpOperation } from "@typespec/http"; export const noHeaderExplodeRule = createRule({ name: "no-header-explode", + docs: fileRef.fromPackageRoot("src/rules/no-header-explode.md"), description: "It is recommended to serialize header parameter without explode: true", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-header-explode", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-legacy-usage.md b/packages/typespec-azure-core/src/rules/no-legacy-usage.md similarity index 84% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-legacy-usage.md rename to packages/typespec-azure-core/src/rules/no-legacy-usage.md index b52d6f9c40..f5952d82d8 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-legacy-usage.md +++ b/packages/typespec-azure-core/src/rules/no-legacy-usage.md @@ -1,11 +1,3 @@ ---- -title: "no-legacy-usage" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-legacy-usage -``` - Types, decorators and other constructs from located under a `.Legacy` namespace are considered legacy and should not be used in new code. The only acceptable usage is for brownfield services which have their existing pattern grandfathered in. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/no-legacy-usage.ts b/packages/typespec-azure-core/src/rules/no-legacy-usage.ts index 89e7ba9264..2e627c5cbd 100644 --- a/packages/typespec-azure-core/src/rules/no-legacy-usage.ts +++ b/packages/typespec-azure-core/src/rules/no-legacy-usage.ts @@ -2,6 +2,7 @@ import { createRule, DecoratedType, DiagnosticTarget, + fileRef, paramMessage, Type, } from "@typespec/compiler"; @@ -12,6 +13,7 @@ import { export const noLegacyUsage = createRule({ name: "no-legacy-usage", + docs: fileRef.fromPackageRoot("src/rules/no-legacy-usage.md"), description: "Linter warning against using elements from the Legacy namespace", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-legacy-usage", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-multiple-discriminator.md b/packages/typespec-azure-core/src/rules/no-multiple-discriminator.md similarity index 81% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-multiple-discriminator.md rename to packages/typespec-azure-core/src/rules/no-multiple-discriminator.md index 3dfa6f78a5..61b68c606f 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-multiple-discriminator.md +++ b/packages/typespec-azure-core/src/rules/no-multiple-discriminator.md @@ -1,11 +1,3 @@ ---- -title: "no-multiple-discriminator" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-multiple-discriminator -``` - Using a nested polymophic relationship is not allowed in Azure services. Most JSON serializers and deserializers do not support this feature. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/no-multiple-discriminator.ts b/packages/typespec-azure-core/src/rules/no-multiple-discriminator.ts index 69ecf1e107..dd3b58306e 100644 --- a/packages/typespec-azure-core/src/rules/no-multiple-discriminator.ts +++ b/packages/typespec-azure-core/src/rules/no-multiple-discriminator.ts @@ -2,12 +2,14 @@ import { Discriminator, Model, createRule, + fileRef, getDiscriminator, paramMessage, } from "@typespec/compiler"; export const noMultipleDiscriminatorRule = createRule({ name: "no-multiple-discriminator", + docs: fileRef.fromPackageRoot("src/rules/no-multiple-discriminator.md"), description: "Classes should have at most one discriminator.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-multiple-discriminator", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-nullable.md b/packages/typespec-azure-core/src/rules/no-nullable.md similarity index 76% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-nullable.md rename to packages/typespec-azure-core/src/rules/no-nullable.md index 0883540d1e..839bc597d1 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-nullable.md +++ b/packages/typespec-azure-core/src/rules/no-nullable.md @@ -1,11 +1,3 @@ ---- -title: "no-nullable" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-nullable -``` - Properties are most often not nullable but optional. Do not use `| null` to specify that a property is nullable. Instead, use the `?` operator to indicate that a property is optional. diff --git a/packages/typespec-azure-core/src/rules/no-nullable.ts b/packages/typespec-azure-core/src/rules/no-nullable.ts index c66a496713..faa2a8949f 100644 --- a/packages/typespec-azure-core/src/rules/no-nullable.ts +++ b/packages/typespec-azure-core/src/rules/no-nullable.ts @@ -1,7 +1,8 @@ -import { ModelProperty, createRule, isNullType } from "@typespec/compiler"; +import { ModelProperty, createRule, fileRef, isNullType } from "@typespec/compiler"; export const noNullableRule = createRule({ name: "no-nullable", + docs: fileRef.fromPackageRoot("src/rules/no-nullable.md"), description: "Use `?` for optional properties.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-nullable", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-offsetdatetime.md b/packages/typespec-azure-core/src/rules/no-offsetdatetime.md similarity index 83% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-offsetdatetime.md rename to packages/typespec-azure-core/src/rules/no-offsetdatetime.md index c49a79f40c..c17f3f3496 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-offsetdatetime.md +++ b/packages/typespec-azure-core/src/rules/no-offsetdatetime.md @@ -1,11 +1,3 @@ ---- -title: "no-offsetdatetime" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-offsetdatetime -``` - Prefer using `utcDateTime` when representing a datetime unless an offset is necessary. Most Azure services work with UTC times and `offsetDateTime` adds unnecessary complexity. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/no-offsetdatetime.ts b/packages/typespec-azure-core/src/rules/no-offsetdatetime.ts index 437ed121a8..6749433891 100644 --- a/packages/typespec-azure-core/src/rules/no-offsetdatetime.ts +++ b/packages/typespec-azure-core/src/rules/no-offsetdatetime.ts @@ -7,11 +7,13 @@ import { Type, UnionVariant, createRule, + fileRef, } from "@typespec/compiler"; import { isExcludedCoreType } from "./utils.js"; export const noOffsetDateTimeRule = createRule({ name: "no-offsetdatetime", + docs: fileRef.fromPackageRoot("src/rules/no-offsetdatetime.md"), description: "Prefer using `utcDateTime` when representing a datetime unless an offset is necessary.", severity: "warning", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-openapi.md b/packages/typespec-azure-core/src/rules/no-openapi.md similarity index 97% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-openapi.md rename to packages/typespec-azure-core/src/rules/no-openapi.md index 2ca265d254..04345ab28e 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-openapi.md +++ b/packages/typespec-azure-core/src/rules/no-openapi.md @@ -1,11 +1,3 @@ ---- -title: "no-openapi" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-openapi -``` - Azure services should not be using decorators from the OpenAPIs libraries(`@azure-tools/openapi`, `@azure-tools/typespec-autorest` or `@azure-tools/openapi3`) in their spec. Using those decorators is usually a sign that the spec is either not following the correct Azure or trying to match exactly a particular OpenAPI spec which should be a non-goal. diff --git a/packages/typespec-azure-core/src/rules/no-openapi.ts b/packages/typespec-azure-core/src/rules/no-openapi.ts index 4deaeaaad3..b6e4101ebf 100644 --- a/packages/typespec-azure-core/src/rules/no-openapi.ts +++ b/packages/typespec-azure-core/src/rules/no-openapi.ts @@ -3,12 +3,14 @@ import { Decorator, Type, createRule, + fileRef, getTypeName, paramMessage, } from "@typespec/compiler"; export const noOpenAPIRule = createRule({ name: "no-openapi", + docs: fileRef.fromPackageRoot("src/rules/no-openapi.md"), description: "Azure specs should not be using decorators from @typespec/openapi or @azure-tools/typespec-autorest", severity: "warning", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-private-usage.md b/packages/typespec-azure-core/src/rules/no-private-usage.md similarity index 78% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-private-usage.md rename to packages/typespec-azure-core/src/rules/no-private-usage.md index 6a9c8a641e..25e7015d9c 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-private-usage.md +++ b/packages/typespec-azure-core/src/rules/no-private-usage.md @@ -1,11 +1,3 @@ ---- -title: "no-private-usage" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-private-usage -``` - Verify that a spec is not referencing items from another library using a private namespace. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/no-private-usage.ts b/packages/typespec-azure-core/src/rules/no-private-usage.ts index fbe6ba01ee..28edaa633e 100644 --- a/packages/typespec-azure-core/src/rules/no-private-usage.ts +++ b/packages/typespec-azure-core/src/rules/no-private-usage.ts @@ -2,6 +2,7 @@ import { createRule, DecoratedType, DiagnosticTarget, + fileRef, paramMessage, Type, } from "@typespec/compiler"; @@ -12,6 +13,7 @@ import { export const noPrivateUsage = createRule({ name: "no-private-usage", + docs: fileRef.fromPackageRoot("src/rules/no-private-usage.md"), description: "Verify that elements inside Private namespace are not referenced.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-private-usage", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-query-explode.md b/packages/typespec-azure-core/src/rules/no-query-explode.md similarity index 82% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-query-explode.md rename to packages/typespec-azure-core/src/rules/no-query-explode.md index f431555ab6..db88ade4cb 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-query-explode.md +++ b/packages/typespec-azure-core/src/rules/no-query-explode.md @@ -1,11 +1,3 @@ ---- -title: "no-query-explode" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-query-explode -``` - Azure services favor serializing query parameter of array type using the simple style(Where each values is joined by a `,`) Using the `*` uri template modifier or `explode: true` property specify that each individual value of the array should be sent as a separate query parameter. diff --git a/packages/typespec-azure-core/src/rules/no-query-explode.ts b/packages/typespec-azure-core/src/rules/no-query-explode.ts index b4a6a299bd..3b781edffc 100644 --- a/packages/typespec-azure-core/src/rules/no-query-explode.ts +++ b/packages/typespec-azure-core/src/rules/no-query-explode.ts @@ -1,8 +1,9 @@ -import { createRule, ignoreDiagnostics, Operation } from "@typespec/compiler"; +import { createRule, fileRef, ignoreDiagnostics, Operation } from "@typespec/compiler"; import { getHttpOperation } from "@typespec/http"; export const noQueryExplodeRule = createRule({ name: "no-query-explode", + docs: fileRef.fromPackageRoot("src/rules/no-query-explode.md"), description: "It is recommended to serialize query parameter without explode: true", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-query-explode", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-response-body.md b/packages/typespec-azure-core/src/rules/no-response-body.md similarity index 89% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-response-body.md rename to packages/typespec-azure-core/src/rules/no-response-body.md index 0940d97555..b871972ca7 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-response-body.md +++ b/packages/typespec-azure-core/src/rules/no-response-body.md @@ -1,11 +1,3 @@ ---- -title: "no-response-body" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-response-body -``` - Ensure that the body is set correctly for response types. Non-204 responses should have a body, and 204 responses should not have a body. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/no-response-body.ts b/packages/typespec-azure-core/src/rules/no-response-body.ts index 6571d151ad..1296cbb31a 100644 --- a/packages/typespec-azure-core/src/rules/no-response-body.ts +++ b/packages/typespec-azure-core/src/rules/no-response-body.ts @@ -1,9 +1,10 @@ -import { Operation, createRule } from "@typespec/compiler"; +import { Operation, createRule, fileRef } from "@typespec/compiler"; import { getResponsesForOperation } from "@typespec/http"; import { isAzureSubNamespace, isTemplatedInterfaceOperation } from "./utils.js"; export const noResponseBodyRule = createRule({ name: "no-response-body", + docs: fileRef.fromPackageRoot("src/rules/no-response-body.md"), description: "Ensure that the body is set correctly for the response type.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-response-body", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-rest-library-interfaces.md b/packages/typespec-azure-core/src/rules/no-rest-library-interfaces.md similarity index 81% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-rest-library-interfaces.md rename to packages/typespec-azure-core/src/rules/no-rest-library-interfaces.md index 5eaf6d97dd..e8e19172f9 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-rest-library-interfaces.md +++ b/packages/typespec-azure-core/src/rules/no-rest-library-interfaces.md @@ -1,11 +1,3 @@ ---- -title: "no-rest-library-interfaces" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-rest-library-interfaces -``` - Resource interfaces from the `TypeSpec.Rest.Resource` library are incompatible with `Azure.Core`. Use the Azure.Core resource operation patterns instead. #### ❌ Incorrect diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-route-parameter-name-mismatch.md b/packages/typespec-azure-core/src/rules/no-route-parameter-name-mismatch.md similarity index 92% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-route-parameter-name-mismatch.md rename to packages/typespec-azure-core/src/rules/no-route-parameter-name-mismatch.md index 1210c7d1ea..425e8b842b 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-route-parameter-name-mismatch.md +++ b/packages/typespec-azure-core/src/rules/no-route-parameter-name-mismatch.md @@ -1,11 +1,3 @@ ---- -title: "no-route-parameter-name-mismatch" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-route-parameter-name-mismatch -``` - Operations over the same resource or using the same path structure should use consistent path parameter names. When two operations resolve to the same resource or path structure but use different names for corresponding path parameters, it typically indicates an inadvertent mismatch in path parameter names. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/no-route-parameter-name-mismatch.ts b/packages/typespec-azure-core/src/rules/no-route-parameter-name-mismatch.ts index 837ddd9e3b..d15d8a68c4 100644 --- a/packages/typespec-azure-core/src/rules/no-route-parameter-name-mismatch.ts +++ b/packages/typespec-azure-core/src/rules/no-route-parameter-name-mismatch.ts @@ -1,5 +1,6 @@ import { createRule, + fileRef, getNamespaceFullName, ignoreDiagnostics, Operation, @@ -33,6 +34,7 @@ function getFullyQualifiedOperationName(operation: Operation): string { export const noRouteParameterNameMismatchRule = createRule({ name: "no-route-parameter-name-mismatch", + docs: fileRef.fromPackageRoot("src/rules/no-route-parameter-name-mismatch.md"), description: "Ensure that operations with the same path use consistent path parameter names.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-route-parameter-name-mismatch", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-rpc-path-params.md b/packages/typespec-azure-core/src/rules/no-rpc-path-params.md similarity index 91% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-rpc-path-params.md rename to packages/typespec-azure-core/src/rules/no-rpc-path-params.md index 152808f60e..56b0aca9a7 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-rpc-path-params.md +++ b/packages/typespec-azure-core/src/rules/no-rpc-path-params.md @@ -1,11 +1,3 @@ ---- -title: "no-rpc-path-params" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-rpc-path-params -``` - Operations defined using `RpcOperation` or `LongRunningRpcOperation` should not have path parameters. If path parameters are needed, consider using `ResourceAction` or `ResourceCollectionAction` instead. :::note diff --git a/packages/typespec-azure-core/src/rules/no-rpc-path-params.ts b/packages/typespec-azure-core/src/rules/no-rpc-path-params.ts index fca642b669..2fbdd4141e 100644 --- a/packages/typespec-azure-core/src/rules/no-rpc-path-params.ts +++ b/packages/typespec-azure-core/src/rules/no-rpc-path-params.ts @@ -1,9 +1,10 @@ -import { Operation, createRule } from "@typespec/compiler"; +import { Operation, createRule, fileRef } from "@typespec/compiler"; import { isPathParam } from "@typespec/http"; import { isExcludedCoreType } from "./utils.js"; export const noRpcPathParamsRule = createRule({ name: "no-rpc-path-params", + docs: fileRef.fromPackageRoot("src/rules/no-rpc-path-params.md"), description: "Operations defined using RpcOperation should not have path parameters.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-rpc-path-params", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-string-discriminator.md b/packages/typespec-azure-core/src/rules/no-string-discriminator.md similarity index 84% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-string-discriminator.md rename to packages/typespec-azure-core/src/rules/no-string-discriminator.md index 067963df7c..6c9f7f6374 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-string-discriminator.md +++ b/packages/typespec-azure-core/src/rules/no-string-discriminator.md @@ -1,11 +1,3 @@ ---- -title: "no-string-discriminator" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-string-discriminator -``` - Azure services favor using an extensible union to define the discriminator property. This allow the service to add new discriminated models without being breaking. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/no-string-discriminator.ts b/packages/typespec-azure-core/src/rules/no-string-discriminator.ts index ac6e8a123c..2bc0e0581c 100644 --- a/packages/typespec-azure-core/src/rules/no-string-discriminator.ts +++ b/packages/typespec-azure-core/src/rules/no-string-discriminator.ts @@ -1,7 +1,8 @@ -import { Model, createRule, getDiscriminator, paramMessage } from "@typespec/compiler"; +import { Model, createRule, fileRef, getDiscriminator, paramMessage } from "@typespec/compiler"; export const noStringDiscriminatorRule = createRule({ name: "no-string-discriminator", + docs: fileRef.fromPackageRoot("src/rules/no-string-discriminator.md"), description: "Azure services discriminated models should define the discriminated property as an extensible union.", severity: "warning", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-unknown.md b/packages/typespec-azure-core/src/rules/no-unknown.md similarity index 80% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-unknown.md rename to packages/typespec-azure-core/src/rules/no-unknown.md index 25ec6cdf3e..7d5869444d 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-unknown.md +++ b/packages/typespec-azure-core/src/rules/no-unknown.md @@ -1,11 +1,3 @@ ---- -title: "no-unknown" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-unknown -``` - Azure services must not have properties of type `unknown`. All properties should have well-defined types to ensure proper serialization and client SDK generation. #### ❌ Incorrect diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-unnamed-union.md b/packages/typespec-azure-core/src/rules/no-unnamed-union.md similarity index 91% rename from website/src/content/docs/docs/libraries/azure-core/rules/no-unnamed-union.md rename to packages/typespec-azure-core/src/rules/no-unnamed-union.md index 001daea5b8..6e485b7cf9 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-unnamed-union.md +++ b/packages/typespec-azure-core/src/rules/no-unnamed-union.md @@ -1,11 +1,3 @@ ---- -title: "no-unnamed-union" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-unnamed-union -``` - Inline union expressions (using the `|` operator) should not be used in Azure service specifications. Instead, unions must be defined as named types. ## Rationale diff --git a/packages/typespec-azure-core/src/rules/no-unnamed-union.ts b/packages/typespec-azure-core/src/rules/no-unnamed-union.ts index 59b3793d06..5f2be131ae 100644 --- a/packages/typespec-azure-core/src/rules/no-unnamed-union.ts +++ b/packages/typespec-azure-core/src/rules/no-unnamed-union.ts @@ -1,9 +1,10 @@ -import { createRule, paramMessage, Program, Union } from "@typespec/compiler"; +import { createRule, fileRef, paramMessage, Program, Union } from "@typespec/compiler"; import { $ } from "@typespec/compiler/typekit"; import { getHeaderFieldName, isHeader, isStatusCode } from "@typespec/http"; export const noUnnamedUnionRule = createRule({ name: "no-unnamed-union", + docs: fileRef.fromPackageRoot("src/rules/no-unnamed-union.md"), description: "Azure services should not define a union expression but create a declaration.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-unnamed-union", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/non-breaking-versioning.md b/packages/typespec-azure-core/src/rules/non-breaking-versioning.md similarity index 86% rename from website/src/content/docs/docs/libraries/azure-core/rules/non-breaking-versioning.md rename to packages/typespec-azure-core/src/rules/non-breaking-versioning.md index d99b329a7f..c9b5d7e95f 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/non-breaking-versioning.md +++ b/packages/typespec-azure-core/src/rules/non-breaking-versioning.md @@ -1,11 +1,3 @@ ---- -title: "non-breaking-versioning" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/non-breaking-versioning -``` - Verify that only backward compatible changes are made to the API. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/non-breaking-versioning.ts b/packages/typespec-azure-core/src/rules/non-breaking-versioning.ts index be6c85acec..a407a20750 100644 --- a/packages/typespec-azure-core/src/rules/non-breaking-versioning.ts +++ b/packages/typespec-azure-core/src/rules/non-breaking-versioning.ts @@ -1,4 +1,4 @@ -import { ModelProperty, Type, createRule, paramMessage } from "@typespec/compiler"; +import { ModelProperty, Type, createRule, fileRef, paramMessage } from "@typespec/compiler"; import { getAddedOnVersions, getMadeOptionalOn, @@ -8,6 +8,7 @@ import { export const nonBreakingVersioningRule = createRule({ name: "non-breaking-versioning", + docs: fileRef.fromPackageRoot("src/rules/non-breaking-versioning.md"), description: "Check that only backward compatible versioning change are done to a service.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/non-breaking-versioning", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/operation-missing-api-version.md b/packages/typespec-azure-core/src/rules/operation-missing-api-version.md similarity index 72% rename from website/src/content/docs/docs/libraries/azure-core/rules/operation-missing-api-version.md rename to packages/typespec-azure-core/src/rules/operation-missing-api-version.md index e7d0b2d4c1..b97a2d118b 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/operation-missing-api-version.md +++ b/packages/typespec-azure-core/src/rules/operation-missing-api-version.md @@ -1,11 +1,3 @@ ---- -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. :::caution diff --git a/packages/typespec-azure-core/src/rules/operation-missing-api-version.ts b/packages/typespec-azure-core/src/rules/operation-missing-api-version.ts index 4b28b94b39..8803bcd149 100644 --- a/packages/typespec-azure-core/src/rules/operation-missing-api-version.ts +++ b/packages/typespec-azure-core/src/rules/operation-missing-api-version.ts @@ -1,4 +1,4 @@ -import { ModelProperty, Operation, createRule } from "@typespec/compiler"; +import { ModelProperty, Operation, createRule, fileRef } from "@typespec/compiler"; import { getVersions } from "@typespec/versioning"; function isApiVersionParam(prop: ModelProperty): boolean { @@ -7,6 +7,7 @@ function isApiVersionParam(prop: ModelProperty): boolean { export const apiVersionRule = createRule({ name: "operation-missing-api-version", + docs: fileRef.fromPackageRoot("src/rules/operation-missing-api-version.md"), description: "Operations need an api version parameter.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/operation-missing-api-version", diff --git a/packages/typespec-azure-core/src/rules/prevent-format.ts b/packages/typespec-azure-core/src/rules/prevent-format.ts index 41e6c80aab..e8c0ef5829 100644 --- a/packages/typespec-azure-core/src/rules/prevent-format.ts +++ b/packages/typespec-azure-core/src/rules/prevent-format.ts @@ -1,10 +1,11 @@ -import { ModelProperty, Scalar, createRule } from "@typespec/compiler"; +import { ModelProperty, Scalar, createRule, fileRef } from "@typespec/compiler"; export const preventFormatRule = createRule({ name: "no-format", + docs: fileRef.fromPackageRoot("src/rules/no-format.md"), description: "Azure services should not use the `@format` decorator.", severity: "warning", - url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/prevent-format", + url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-format", messages: { default: "Azure services should not use the `@format` decorator.", }, diff --git a/packages/typespec-azure-core/src/rules/prevent-rest-library.ts b/packages/typespec-azure-core/src/rules/prevent-rest-library.ts index a90dcf2839..e38daa26f5 100644 --- a/packages/typespec-azure-core/src/rules/prevent-rest-library.ts +++ b/packages/typespec-azure-core/src/rules/prevent-rest-library.ts @@ -3,6 +3,7 @@ import { Operation, Program, createRule, + fileRef, getNamespaceFullName, } from "@typespec/compiler"; import { TypeReferenceNode } from "@typespec/compiler/ast"; @@ -15,6 +16,7 @@ function getTypeReferenceNamespace(program: Program, ref: TypeReferenceNode): st export const preventRestLibraryInterfaces = createRule({ name: "no-rest-library-interfaces", + docs: fileRef.fromPackageRoot("src/rules/no-rest-library-interfaces.md"), description: "Resource interfaces from the TypeSpec.Rest.Resource library are incompatible with Azure.Core.", severity: "warning", diff --git a/packages/typespec-azure-core/src/rules/prevent-unknown.ts b/packages/typespec-azure-core/src/rules/prevent-unknown.ts index 9c9394d438..da263bc86a 100644 --- a/packages/typespec-azure-core/src/rules/prevent-unknown.ts +++ b/packages/typespec-azure-core/src/rules/prevent-unknown.ts @@ -1,7 +1,8 @@ -import { ModelProperty, createRule, isUnknownType } from "@typespec/compiler"; +import { ModelProperty, createRule, fileRef, isUnknownType } from "@typespec/compiler"; export const preventUnknownType = createRule({ name: "no-unknown", + docs: fileRef.fromPackageRoot("src/rules/no-unknown.md"), description: "Azure services must not have properties of type `unknown`.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/no-unknown", diff --git a/packages/typespec-azure-core/src/rules/request-body-array.ts b/packages/typespec-azure-core/src/rules/request-body-array.ts index bf8385365c..eb3098045e 100644 --- a/packages/typespec-azure-core/src/rules/request-body-array.ts +++ b/packages/typespec-azure-core/src/rules/request-body-array.ts @@ -1,8 +1,9 @@ -import { Operation, createRule } from "@typespec/compiler"; +import { Operation, createRule, fileRef } from "@typespec/compiler"; import { isBody, isBodyRoot } from "@typespec/http"; export const bodyArrayRule = createRule({ name: "request-body-problem", + docs: fileRef.fromPackageRoot("src/rules/request-body-problem.md"), description: "Request body should not be of raw array type.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/request-body-problem", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/request-body-problem.md b/packages/typespec-azure-core/src/rules/request-body-problem.md similarity index 83% rename from website/src/content/docs/docs/libraries/azure-core/rules/request-body-problem.md rename to packages/typespec-azure-core/src/rules/request-body-problem.md index 2bb8ae7db2..0f8289848b 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/request-body-problem.md +++ b/packages/typespec-azure-core/src/rules/request-body-problem.md @@ -1,11 +1,3 @@ ---- -title: "request-body-problem" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/request-body-problem -``` - Request body should not be of raw array type. Using an array as the top-level request body prevents adding new properties in the future without introducing breaking changes. Instead, create a container model that wraps the array. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/require-docs.ts b/packages/typespec-azure-core/src/rules/require-docs.ts index 9b41ab30a8..4705f8c624 100644 --- a/packages/typespec-azure-core/src/rules/require-docs.ts +++ b/packages/typespec-azure-core/src/rules/require-docs.ts @@ -8,6 +8,7 @@ import { Union, UnionVariant, createRule, + fileRef, getDiscriminatedTypes, getDiscriminator, getDoc, @@ -83,6 +84,7 @@ function getVariantName(variant: UnionVariant): string | undefined { export const requireDocumentation = createRule({ name: "documentation-required", + docs: fileRef.fromPackageRoot("src/rules/documentation-required.md"), description: "Require documentation over enums, models, and operations.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/documentation-required", diff --git a/packages/typespec-azure-core/src/rules/require-key-visibility.ts b/packages/typespec-azure-core/src/rules/require-key-visibility.ts index a59bd253a2..b44da83280 100644 --- a/packages/typespec-azure-core/src/rules/require-key-visibility.ts +++ b/packages/typespec-azure-core/src/rules/require-key-visibility.ts @@ -1,6 +1,7 @@ import { Model, createRule, + fileRef, getLifecycleVisibilityEnum, getVisibilityForClass, isKey, @@ -10,6 +11,7 @@ import { isExcludedCoreType, isInlineModel, isTemplateDeclarationType } from "./ export const requireKeyVisibility = createRule({ name: "key-visibility-required", + docs: fileRef.fromPackageRoot("src/rules/key-visibility-required.md"), description: "Key properties need to have a Lifecycle visibility setting.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/key-visibility-required", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/require-versioned.md b/packages/typespec-azure-core/src/rules/require-versioned.md similarity index 82% rename from website/src/content/docs/docs/libraries/azure-core/rules/require-versioned.md rename to packages/typespec-azure-core/src/rules/require-versioned.md index 0945a1186f..5db4c48884 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/require-versioned.md +++ b/packages/typespec-azure-core/src/rules/require-versioned.md @@ -1,11 +1,3 @@ ---- -title: "require-versioned" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/require-versioned -``` - Azure services should always use the versioning library even if they have a single version. This ensures that the service is ready for future versions and generate the OpenAPI 2.0 in the correct location. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/require-versioned.ts b/packages/typespec-azure-core/src/rules/require-versioned.ts index 6b866f8694..fcc2a697fb 100644 --- a/packages/typespec-azure-core/src/rules/require-versioned.ts +++ b/packages/typespec-azure-core/src/rules/require-versioned.ts @@ -2,6 +2,7 @@ import { CodeFix, createAddDecoratorCodeFix, createRule, + fileRef, listServices, Namespace, paramMessage, @@ -9,6 +10,7 @@ import { import { getVersion } from "@typespec/versioning"; export const requireVersionedRule = createRule({ name: "require-versioned", + docs: fileRef.fromPackageRoot("src/rules/require-versioned.md"), description: "Azure services should use the versioning library.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/require-versioned", diff --git a/packages/typespec-azure-core/src/rules/response-schema-multi-status-code.ts b/packages/typespec-azure-core/src/rules/response-schema-multi-status-code.ts index 9bee3b5db3..3dddff83bc 100644 --- a/packages/typespec-azure-core/src/rules/response-schema-multi-status-code.ts +++ b/packages/typespec-azure-core/src/rules/response-schema-multi-status-code.ts @@ -2,6 +2,7 @@ import { Operation, Type, createRule, + fileRef, ignoreDiagnostics, isErrorModel, paramMessage, @@ -10,6 +11,7 @@ import { Visibility, createMetadataInfo, getHttpOperation } from "@typespec/http export const responseSchemaMultiStatusCodeRule = createRule({ name: "response-schema-problem", + docs: fileRef.fromPackageRoot("src/rules/response-schema-problem.md"), description: "Warn about operations having multiple non-error response schemas.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/response-schema-problem", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/response-schema-problem.md b/packages/typespec-azure-core/src/rules/response-schema-problem.md similarity index 87% rename from website/src/content/docs/docs/libraries/azure-core/rules/response-schema-problem.md rename to packages/typespec-azure-core/src/rules/response-schema-problem.md index 6b16baa68b..1867b890b8 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/response-schema-problem.md +++ b/packages/typespec-azure-core/src/rules/response-schema-problem.md @@ -1,11 +1,3 @@ ---- -title: "response-schema-problem" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/response-schema-problem -``` - Warn about operations having multiple non-error response schemas. If an operation has multiple response types for different success status codes, you may have forgotten to add `@error` to one of them. #### ❌ Incorrect diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/rpc-operation-request-body.md b/packages/typespec-azure-core/src/rules/rpc-operation-request-body.md similarity index 89% rename from website/src/content/docs/docs/libraries/azure-core/rules/rpc-operation-request-body.md rename to packages/typespec-azure-core/src/rules/rpc-operation-request-body.md index 8c7a9d379a..3f2ac3f48f 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/rpc-operation-request-body.md +++ b/packages/typespec-azure-core/src/rules/rpc-operation-request-body.md @@ -1,11 +1,3 @@ ---- -title: "rpc-operation-request-body" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/rpc-operation-request-body -``` - Validates that `RpcOperation` request bodies are used correctly. Operations using HTTP verbs that do not support a body (like `GET` or `DELETE`) should not define one. :::note diff --git a/packages/typespec-azure-core/src/rules/rpc-operation-request-body.ts b/packages/typespec-azure-core/src/rules/rpc-operation-request-body.ts index 06070f844b..eb74c716da 100644 --- a/packages/typespec-azure-core/src/rules/rpc-operation-request-body.ts +++ b/packages/typespec-azure-core/src/rules/rpc-operation-request-body.ts @@ -1,8 +1,9 @@ -import { Operation, createRule, paramMessage } from "@typespec/compiler"; +import { Operation, createRule, fileRef, paramMessage } from "@typespec/compiler"; import { getHttpOperation, isBodyIgnore } from "@typespec/http"; export const rpcOperationRequestBodyRule = createRule({ name: "rpc-operation-request-body", + docs: fileRef.fromPackageRoot("src/rules/rpc-operation-request-body.md"), description: "Warning for RPC body problems.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/rpc-operation-request-body", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/spread-discriminated-model.md b/packages/typespec-azure-core/src/rules/spread-discriminated-model.md similarity index 82% rename from website/src/content/docs/docs/libraries/azure-core/rules/spread-discriminated-model.md rename to packages/typespec-azure-core/src/rules/spread-discriminated-model.md index c637572a48..5533731ac3 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/spread-discriminated-model.md +++ b/packages/typespec-azure-core/src/rules/spread-discriminated-model.md @@ -1,11 +1,3 @@ ---- -title: "spread-discriminated-model" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/spread-discriminated-model -``` - A model using `@discriminator` is meant to be used in a polymorphic context. It should be extended to represent the relation. Spreading this model is a sign that either the `@discriminator` decorator is unnecessary or that `model extends` should have been used instead. diff --git a/packages/typespec-azure-core/src/rules/spread-discriminated-model.ts b/packages/typespec-azure-core/src/rules/spread-discriminated-model.ts index 4a1ced8687..83dc8fc0b9 100644 --- a/packages/typespec-azure-core/src/rules/spread-discriminated-model.ts +++ b/packages/typespec-azure-core/src/rules/spread-discriminated-model.ts @@ -1,8 +1,9 @@ -import { Model, createRule, getDiscriminator, paramMessage } from "@typespec/compiler"; +import { Model, createRule, fileRef, getDiscriminator, paramMessage } from "@typespec/compiler"; import { SyntaxKind } from "@typespec/compiler/ast"; export const spreadDiscriminatedModelRule = createRule({ name: "spread-discriminated-model", + docs: fileRef.fromPackageRoot("src/rules/spread-discriminated-model.md"), description: "Check a model with a discriminator has not been used in composition.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/spread-discriminated-model", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/use-standard-names.md b/packages/typespec-azure-core/src/rules/use-standard-names.md similarity index 90% rename from website/src/content/docs/docs/libraries/azure-core/rules/use-standard-names.md rename to packages/typespec-azure-core/src/rules/use-standard-names.md index eebabdd7e9..fb73f7da69 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/use-standard-names.md +++ b/packages/typespec-azure-core/src/rules/use-standard-names.md @@ -1,11 +1,3 @@ ---- -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 | diff --git a/packages/typespec-azure-core/src/rules/use-standard-names.ts b/packages/typespec-azure-core/src/rules/use-standard-names.ts index 899c8ffc81..e0d119a5a5 100644 --- a/packages/typespec-azure-core/src/rules/use-standard-names.ts +++ b/packages/typespec-azure-core/src/rules/use-standard-names.ts @@ -1,6 +1,7 @@ import { Operation, createRule, + fileRef, ignoreDiagnostics, isList, isTemplateDeclarationOrInstance, @@ -10,6 +11,7 @@ import { isListOperation } from "@typespec/rest"; export const useStandardNames = createRule({ name: "use-standard-names", + docs: fileRef.fromPackageRoot("src/rules/use-standard-names.md"), description: "Use recommended names for operations.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/use-standard-names", diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/use-standard-operations.md b/packages/typespec-azure-core/src/rules/use-standard-operations.md similarity index 85% rename from website/src/content/docs/docs/libraries/azure-core/rules/use-standard-operations.md rename to packages/typespec-azure-core/src/rules/use-standard-operations.md index f03c25d8a2..5ac766f176 100644 --- a/website/src/content/docs/docs/libraries/azure-core/rules/use-standard-operations.md +++ b/packages/typespec-azure-core/src/rules/use-standard-operations.md @@ -1,11 +1,3 @@ ---- -title: "use-standard-operations" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/use-standard-operations -``` - Azure Data Plane services should use standard operations defined in the Azure Core library. #### ❌ Incorrect diff --git a/packages/typespec-azure-core/src/rules/use-standard-operations.ts b/packages/typespec-azure-core/src/rules/use-standard-operations.ts index a5730362cc..6a124417d8 100644 --- a/packages/typespec-azure-core/src/rules/use-standard-operations.ts +++ b/packages/typespec-azure-core/src/rules/use-standard-operations.ts @@ -1,6 +1,7 @@ import { Operation, createRule, + fileRef, getNamespaceFullName, isTemplateDeclarationOrInstance, paramMessage, @@ -25,6 +26,7 @@ function derivesFromAzureCoreOperation(operation: Operation): boolean { export const useStandardOperations = createRule({ name: "use-standard-operations", + docs: fileRef.fromPackageRoot("src/rules/use-standard-operations.md"), description: "Operations should be defined using a signature from the Azure.Core namespace.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/use-standard-operations", diff --git a/packages/typespec-azure-resource-manager/README.md b/packages/typespec-azure-resource-manager/README.md index 040a79bbe6..0bf869e036 100644 --- a/packages/typespec-azure-resource-manager/README.md +++ b/packages/typespec-azure-resource-manager/README.md @@ -34,15 +34,15 @@ Available ruleSets: | [`@azure-tools/typespec-azure-resource-manager/arm-no-path-casing-conflicts`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-no-path-casing-conflicts) | Operation paths must be unique when compared case-insensitively. | | [`@azure-tools/typespec-azure-resource-manager/no-override-props`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/no-override-props) | Disallow redefining properties already defined in a base type. | | [`@azure-tools/typespec-azure-resource-manager/arm-common-types-version`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-common-types-version) | Specify the ARM common-types version using @armCommonTypesVersion. | -| [`@azure-tools/typespec-azure-resource-manager/arm-delete-operation-response-codes`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/delete-operation-response-codes) | Ensure delete operations have the appropriate status codes. | -| [`@azure-tools/typespec-azure-resource-manager/arm-put-operation-response-codes`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/put-operation-response-codes) | Ensure put operations have the appropriate status codes. | -| [`@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/post-operation-response-codes) | Ensure post operations have the appropriate status codes. | +| [`@azure-tools/typespec-azure-resource-manager/arm-delete-operation-response-codes`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-delete-operation-response-codes) | Ensure delete operations have the appropriate status codes. | +| [`@azure-tools/typespec-azure-resource-manager/arm-put-operation-response-codes`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-put-operation-response-codes) | Ensure put operations have the appropriate status codes. | +| [`@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-post-operation-response-codes) | Ensure post operations have the appropriate status codes. | | [`@azure-tools/typespec-azure-resource-manager/arm-resource-action-no-segment`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-action-no-segment) | `@armResourceAction` should not be used with `@segment`. | | [`@azure-tools/typespec-azure-resource-manager/arm-resource-duplicate-property`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-duplicate-property) | Warn about duplicate properties in resources. | | [`@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-envelope-property`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-envelope-property) | Check for invalid resource envelope properties. | | [`@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-version-format`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-version-format) | Check for valid versions. | | [`@azure-tools/typespec-azure-resource-manager/arm-resource-key-invalid-chars`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-key-invalid-chars) | Arm resource key must contain only alphanumeric characters. | -| [`@azure-tools/typespec-azure-resource-manager/arm-resource-name-pattern`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/resource-name-pattern) | The resource name parameter should be defined with a 'pattern' restriction. | +| [`@azure-tools/typespec-azure-resource-manager/arm-resource-name-pattern`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-name-pattern) | The resource name parameter should be defined with a 'pattern' restriction. | | [`@azure-tools/typespec-azure-resource-manager/arm-resource-operation-response`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-operation-response) | [RPC 008]: PUT, GET, PATCH & LIST must return the same resource schema. | | [`@azure-tools/typespec-azure-resource-manager/arm-resource-path-segment-invalid-chars`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-path-segment-invalid-chars) | Arm resource name must contain only alphanumeric characters. | | [`@azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state`](https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-provisioning-state) | Check for properly configured provisioningState property. | diff --git a/packages/typespec-azure-resource-manager/package.json b/packages/typespec-azure-resource-manager/package.json index b67b410f18..0616a96e87 100644 --- a/packages/typespec-azure-resource-manager/package.json +++ b/packages/typespec-azure-resource-manager/package.json @@ -49,7 +49,7 @@ "test:ci": "vitest run --coverage --reporter=junit --reporter=default", "lint": "oxlint . --deny-warnings", "lint:fix": "oxlint . --fix", - "regen-docs": "tspd doc . --enable-experimental --llmstxt --output-dir ../../website/src/content/docs/docs/libraries/azure-resource-manager/reference" + "regen-docs": "tspd doc . --enable-experimental --llmstxt --rules-dir ../rules --output-dir ../../website/src/content/docs/docs/libraries/azure-resource-manager/reference" }, "files": [ "lib/**/*.tsp", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-agent-base-type-child-resources.md b/packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-child-resources.md similarity index 88% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-agent-base-type-child-resources.md rename to packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-child-resources.md index 81cf1135a6..24333c097f 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-agent-base-type-child-resources.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-child-resources.md @@ -1,11 +1,3 @@ ---- -title: arm-agent-base-type-child-resources ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-agent-base-type-child-resources -``` - Resources decorated with `@azureBaseType` for the Agent base type must have both a Conversation and a Response child resource. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-child-resources.ts b/packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-child-resources.ts index d8ed29eeba..dbf996d07d 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-child-resources.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-child-resources.ts @@ -1,4 +1,11 @@ -import { Model, Program, createRule, getNamespaceFullName, paramMessage } from "@typespec/compiler"; +import { + Model, + Program, + createRule, + fileRef, + getNamespaceFullName, + paramMessage, +} from "@typespec/compiler"; import { getParentResource } from "@typespec/rest"; import { AzureBaseTypeInfo, getAzureBaseTypes } from "../base-types.js"; @@ -6,6 +13,7 @@ import { getArmResources } from "../resource.js"; export const armAgentBaseTypeChildResourcesRule = createRule({ name: "arm-agent-base-type-child-resources", + docs: fileRef.fromPackageRoot("src/rules/arm-agent-base-type-child-resources.md"), severity: "warning", description: "Resources decorated with @azureBaseType for the Agent base type must have both a Conversation and a Response child resource.", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-agent-base-type-lifecycle-operations.md b/packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-lifecycle-operations.md similarity index 88% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-agent-base-type-lifecycle-operations.md rename to packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-lifecycle-operations.md index 95c0ad3d27..854a92a68b 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-agent-base-type-lifecycle-operations.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-lifecycle-operations.md @@ -1,11 +1,3 @@ ---- -title: arm-agent-base-type-lifecycle-operations ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-agent-base-type-lifecycle-operations -``` - Conversation and Response child resources of an Agent must define create, read, update, and delete lifecycle operations. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-lifecycle-operations.ts b/packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-lifecycle-operations.ts index e3a45b9cc1..4535c1c37a 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-lifecycle-operations.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-agent-base-type-lifecycle-operations.ts @@ -1,4 +1,11 @@ -import { Model, Program, createRule, getNamespaceFullName, paramMessage } from "@typespec/compiler"; +import { + Model, + Program, + createRule, + fileRef, + getNamespaceFullName, + paramMessage, +} from "@typespec/compiler"; import { getParentResource } from "@typespec/rest"; import { AzureBaseTypeInfo, getAzureBaseTypes } from "../base-types.js"; @@ -6,6 +13,7 @@ import { getArmResources } from "../resource.js"; export const armAgentBaseTypeLifecycleOperationsRule = createRule({ name: "arm-agent-base-type-lifecycle-operations", + docs: fileRef.fromPackageRoot("src/rules/arm-agent-base-type-lifecycle-operations.md"), severity: "warning", description: "Conversation and Response child resources of an Agent must define create, read, update, and delete lifecycle operations.", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-common-types-version.md b/packages/typespec-azure-resource-manager/src/rules/arm-common-types-version.md similarity index 87% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-common-types-version.md rename to packages/typespec-azure-resource-manager/src/rules/arm-common-types-version.md index fba88a04c3..7813f77970 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-common-types-version.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-common-types-version.md @@ -1,11 +1,3 @@ ---- -title: arm-common-types-version ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-common-types-version -``` - ARM services must specify the ARM common-types version using the `@armCommonTypesVersion` decorator. If the same common types version is used across all service versions, this decorator should be applied either on the service namespace or on each version enum member. If the common types version is updated in later versions, the decorator should appear on each version enum member. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-common-types-version.ts b/packages/typespec-azure-resource-manager/src/rules/arm-common-types-version.ts index b9df19864e..da9f3413cc 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-common-types-version.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-common-types-version.ts @@ -1,4 +1,4 @@ -import { Program, SemanticNodeListener, createRule } from "@typespec/compiler"; +import { Program, SemanticNodeListener, createRule, fileRef } from "@typespec/compiler"; import { getAllHttpServices } from "@typespec/http"; import { getVersion } from "@typespec/versioning"; import { getArmProviderNamespace } from "../namespace.js"; @@ -9,6 +9,7 @@ import { getArmProviderNamespace } from "../namespace.js"; */ export const armCommonTypesVersionRule = createRule({ name: "arm-common-types-version", + docs: fileRef.fromPackageRoot("src/rules/arm-common-types-version.md"), severity: "warning", description: "Specify the ARM common-types version using @armCommonTypesVersion.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-common-types-version", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-custom-resource-no-key.md b/packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-no-key.md similarity index 92% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-custom-resource-no-key.md rename to packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-no-key.md index a93a4423c9..45fc5713db 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-custom-resource-no-key.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-no-key.md @@ -1,7 +1,3 @@ ---- -title: arm-custom-resource-no-key ---- - ```text title=- Full name- @azure-tools/typespec-azure-resource-manager/arm-custom-resource-no-key ``` diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-no-key.ts b/packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-no-key.ts index 10dfa066e8..945d0f775b 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-no-key.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-no-key.ts @@ -1,9 +1,10 @@ -import { createRule, isKey, Model } from "@typespec/compiler"; +import { createRule, fileRef, isKey, Model } from "@typespec/compiler"; import { isCustomAzureResource } from "../resource.js"; import { getProperties } from "./utils.js"; export const armCustomResourceNoKey = createRule({ name: "arm-custom-resource-no-key", + docs: fileRef.fromPackageRoot("src/rules/arm-custom-resource-no-key.md"), description: "Validate that custom resource contains a key property.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-custom-resource-no-key", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-custom-resource-usage-discourage.md b/packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-usage-discourage.md similarity index 72% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-custom-resource-usage-discourage.md rename to packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-usage-discourage.md index 547f27231f..b5367252a5 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-custom-resource-usage-discourage.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-usage-discourage.md @@ -1,11 +1,3 @@ ---- -title: arm-custom-resource-usage-discourage ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-custom-resource-usage-discourage -``` - Avoid using the `@customAzureResource` decorator. It doesn't provide validation for ARM resources, and its usage should be limited to brownfield services migration. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-usage-discourage.ts b/packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-usage-discourage.ts index 8cce6b2a96..b9cee0d07b 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-usage-discourage.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-custom-resource-usage-discourage.ts @@ -1,4 +1,4 @@ -import { createRule, isTemplateInstance, Model, Program } from "@typespec/compiler"; +import { createRule, fileRef, isTemplateInstance, Model, Program } from "@typespec/compiler"; import { SyntaxKind, type Node } from "@typespec/compiler/ast"; import { isCustomAzureResource } from "../resource.js"; @@ -7,6 +7,7 @@ const armCustomResourceUsageDiscourageCode = export const armCustomResourceUsageDiscourage = createRule({ name: "arm-custom-resource-usage-discourage", + docs: fileRef.fromPackageRoot("src/rules/arm-custom-resource-usage-discourage.md"), severity: "warning", description: "Verify the usage of @customAzureResource decorator.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-custom-resource-usage-discourage", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/delete-operation-response-codes.md b/packages/typespec-azure-resource-manager/src/rules/arm-delete-operation-response-codes.md similarity index 84% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/delete-operation-response-codes.md rename to packages/typespec-azure-resource-manager/src/rules/arm-delete-operation-response-codes.md index 8293a7aa14..0642059f8a 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/delete-operation-response-codes.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-delete-operation-response-codes.md @@ -1,11 +1,3 @@ ---- -title: delete-operation-response-codes ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-delete-operation-response-codes -``` - ## Synchronous Synchronous delete operations should use the `ArmResourceDeleteSync` template. They must have 200, 204, default and no other responses. diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-delete-response-codes.ts b/packages/typespec-azure-resource-manager/src/rules/arm-delete-response-codes.ts index 8edff1c6ed..e39d912999 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-delete-response-codes.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-delete-response-codes.ts @@ -1,4 +1,4 @@ -import { Program, createRule } from "@typespec/compiler"; +import { Program, createRule, fileRef } from "@typespec/compiler"; import { getLroMetadata } from "@azure-tools/typespec-azure-core"; import { getArmResources } from "../resource.js"; @@ -8,8 +8,9 @@ import { getArmResources } from "../resource.js"; */ export const armDeleteResponseCodesRule = createRule({ name: "arm-delete-operation-response-codes", + docs: fileRef.fromPackageRoot("src/rules/arm-delete-operation-response-codes.md"), severity: "warning", - url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/delete-operation-response-codes", + url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-delete-operation-response-codes", description: "Ensure delete operations have the appropriate status codes.", messages: { sync: `Synchronous delete operations must have 200, 204 and default responses. They must not have any other responses. Consider using the 'ArmResourceDeleteSync' template.`, diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-feature-file-usage-discourage.md b/packages/typespec-azure-resource-manager/src/rules/arm-feature-file-usage-discourage.md similarity index 81% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-feature-file-usage-discourage.md rename to packages/typespec-azure-resource-manager/src/rules/arm-feature-file-usage-discourage.md index 2630f43ad8..db6ea583f4 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-feature-file-usage-discourage.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-feature-file-usage-discourage.md @@ -1,11 +1,3 @@ ---- -title: arm-feature-file-usage-discourage ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-feature-file-usage-discourage -``` - Avoid using the `@featureFiles` decorator. Its usage should be limited to brownfield services migration and requires explicit approval. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-feature-file-usage-discourage.ts b/packages/typespec-azure-resource-manager/src/rules/arm-feature-file-usage-discourage.ts index 34b6662a57..0640078249 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-feature-file-usage-discourage.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-feature-file-usage-discourage.ts @@ -1,8 +1,9 @@ -import { createRule, Namespace } from "@typespec/compiler"; +import { createRule, fileRef, Namespace } from "@typespec/compiler"; import { getFeatureFileSet } from "../resource.js"; export const armFeatureFileUsageDiscourage = createRule({ name: "arm-feature-file-usage-discourage", + docs: fileRef.fromPackageRoot("src/rules/arm-feature-file-usage-discourage.md"), severity: "warning", description: "Verify the usage of @featureFiles decorator.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-feature-file-usage-discourage", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-no-path-casing-conflicts.md b/packages/typespec-azure-resource-manager/src/rules/arm-no-path-casing-conflicts.md similarity index 86% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-no-path-casing-conflicts.md rename to packages/typespec-azure-resource-manager/src/rules/arm-no-path-casing-conflicts.md index 8c2c43d0ab..455501d86b 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-no-path-casing-conflicts.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-no-path-casing-conflicts.md @@ -1,11 +1,3 @@ ---- -title: arm-no-path-casing-conflicts ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-no-path-casing-conflicts -``` - ARM operation paths must be unique case-insensitively. Two operations whose paths differ only by character casing (for example `/foos` and `/Foos`, or `/{scope}/...` and `/{Scope}/...`) violate this rule. Path parameter names diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-no-path-casing-conflicts.ts b/packages/typespec-azure-resource-manager/src/rules/arm-no-path-casing-conflicts.ts index 8e0427a05d..4a804fd6b3 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-no-path-casing-conflicts.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-no-path-casing-conflicts.ts @@ -1,5 +1,6 @@ import { createRule, + fileRef, getSourceLocation, Operation, paramMessage, @@ -14,6 +15,7 @@ import { isInternalTypeSpec } from "./utils.js"; */ export const armNoPathCasingConflictsRule = createRule({ name: "arm-no-path-casing-conflicts", + docs: fileRef.fromPackageRoot("src/rules/arm-no-path-casing-conflicts.md"), severity: "warning", description: "Operation paths must be unique when compared case-insensitively.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-no-path-casing-conflicts", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-no-record.md b/packages/typespec-azure-resource-manager/src/rules/arm-no-record.md similarity index 96% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-no-record.md rename to packages/typespec-azure-resource-manager/src/rules/arm-no-record.md index 8948ae4674..52300d0ecd 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-no-record.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-no-record.md @@ -1,7 +1,3 @@ ---- -title: arm-no-record ---- - ```text title=- Full name- @azure-tools/typespec-azure-resource-manager/arm-no-record ``` diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-no-record.ts b/packages/typespec-azure-resource-manager/src/rules/arm-no-record.ts index 69d600f47e..987df70d59 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-no-record.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-no-record.ts @@ -4,10 +4,12 @@ import { SemanticNodeListener, Type, createRule, + fileRef, } from "@typespec/compiler"; export const armNoRecordRule = createRule({ name: "arm-no-record", + docs: fileRef.fromPackageRoot("src/rules/arm-no-record.md"), severity: "warning", description: "Don't use Record types for ARM resources.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-no-record", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/post-operation-response-codes.md b/packages/typespec-azure-resource-manager/src/rules/arm-post-operation-response-codes.md similarity index 86% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/post-operation-response-codes.md rename to packages/typespec-azure-resource-manager/src/rules/arm-post-operation-response-codes.md index 3a4f14f0c8..a0fb00b5d6 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/post-operation-response-codes.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-post-operation-response-codes.md @@ -1,11 +1,3 @@ ---- -title: post-operation-response-codes ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-post-operation-response-codes -``` - ## Synchronous Synchronous post operations should have one of the following combinations of responses - 200 and default, or 204 and default. They must have no other responses. diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-post-response-codes.ts b/packages/typespec-azure-resource-manager/src/rules/arm-post-response-codes.ts index 9676494756..211d382f74 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-post-response-codes.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-post-response-codes.ts @@ -1,4 +1,4 @@ -import { Program, createRule } from "@typespec/compiler"; +import { Program, createRule, fileRef } from "@typespec/compiler"; import { getLroMetadata } from "@azure-tools/typespec-azure-core"; import { HttpOperationResponse, HttpPayloadBody } from "@typespec/http"; @@ -10,8 +10,9 @@ import { getArmResources } from "../resource.js"; */ export const armPostResponseCodesRule = createRule({ name: "arm-post-operation-response-codes", + docs: fileRef.fromPackageRoot("src/rules/arm-post-operation-response-codes.md"), severity: "warning", - url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/post-operation-response-codes", + url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-post-operation-response-codes", description: "Ensure post operations have the appropriate status codes.", messages: { sync: `Synchronous post operations must have a 200 or 204 response and a default response. They must not have any other responses.`, diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/put-operation-response-codes.md b/packages/typespec-azure-resource-manager/src/rules/arm-put-operation-response-codes.md similarity index 77% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/put-operation-response-codes.md rename to packages/typespec-azure-resource-manager/src/rules/arm-put-operation-response-codes.md index 63134871b5..f5f3a0fa4a 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/put-operation-response-codes.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-put-operation-response-codes.md @@ -1,11 +1,3 @@ ---- -title: put-operation-response-codes ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-put-operation-response-codes -``` - Put operations should use the `ArmResourceCreateOrReplaceAsync` or `ArmResourceCreateOrReplaceSync` template. They must have 200, 201, default and no other responses. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-put-response-codes.ts b/packages/typespec-azure-resource-manager/src/rules/arm-put-response-codes.ts index 2b0d83c5c0..98d6253031 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-put-response-codes.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-put-response-codes.ts @@ -1,4 +1,4 @@ -import { Program, createRule } from "@typespec/compiler"; +import { Program, createRule, fileRef } from "@typespec/compiler"; import { getArmResources } from "../resource.js"; @@ -7,8 +7,9 @@ import { getArmResources } from "../resource.js"; */ export const armPutResponseCodesRule = createRule({ name: "arm-put-operation-response-codes", + docs: fileRef.fromPackageRoot("src/rules/arm-put-operation-response-codes.md"), severity: "warning", - url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/put-operation-response-codes", + url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-put-operation-response-codes", description: "Ensure put operations have the appropriate status codes.", messages: { default: `Put operations must have 200, 201 and default responses. They must not have any other responses.`, diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-action-no-segment.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-action-no-segment.md similarity index 78% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-action-no-segment.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-action-no-segment.md index c64f305feb..4f146b91f1 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-action-no-segment.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-action-no-segment.md @@ -1,11 +1,3 @@ ---- -title: arm-resource-action-no-segment ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-resource-action-no-segment -``` - The `@armResourceAction` decorator should not be used together with `@segment`. If you need to rename the action, use `@action(...)` instead or omit the segment entirely. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-resource-action-no-segment.ts b/packages/typespec-azure-resource-manager/src/rules/arm-resource-action-no-segment.ts index acd9d06b5b..28472ee121 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-resource-action-no-segment.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-action-no-segment.ts @@ -1,8 +1,9 @@ -import { DecoratorApplication, Operation, createRule } from "@typespec/compiler"; +import { DecoratorApplication, Operation, createRule, fileRef } from "@typespec/compiler"; import { isInternalTypeSpec } from "./utils.js"; export const armResourceActionNoSegmentRule = createRule({ name: "arm-resource-action-no-segment", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-action-no-segment.md"), severity: "warning", description: "`@armResourceAction` should not be used with `@segment`.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-action-no-segment", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-duplicate-property.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-duplicate-property.md similarity index 83% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-duplicate-property.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-duplicate-property.md index 600cfff2a6..45b24e9fc2 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-duplicate-property.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-duplicate-property.md @@ -1,11 +1,3 @@ ---- -title: arm-resource-duplicate-property ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-resource-duplicate-property -``` - Warns when a property defined in the resource envelope is also defined in the resource-specific properties bag. Envelope properties should not be duplicated in the `properties` model. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-resource-duplicate-property.ts b/packages/typespec-azure-resource-manager/src/rules/arm-resource-duplicate-property.ts index b783220830..0c2709621e 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-resource-duplicate-property.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-duplicate-property.ts @@ -1,9 +1,17 @@ -import { Model, ModelProperty, createRule, getProperty, paramMessage } from "@typespec/compiler"; +import { + Model, + ModelProperty, + createRule, + fileRef, + getProperty, + paramMessage, +} from "@typespec/compiler"; import { getArmResource } from "../resource.js"; export const armResourceDuplicatePropertiesRule = createRule({ name: "arm-resource-duplicate-property", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-duplicate-property.md"), severity: "warning", description: "Warn about duplicate properties in resources.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-duplicate-property", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-interface-requires-decorator.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-interface-requires-decorator.md similarity index 69% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-interface-requires-decorator.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-interface-requires-decorator.md index 4597d615c6..b3b6838bf7 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-interface-requires-decorator.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-interface-requires-decorator.md @@ -1,11 +1,3 @@ ---- -title: arm-resource-interface-requires-decorator ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-resource-interface-requires-decorator -``` - Each resource interface must have an `@armResourceOperations` decorator to associate the interface with its ARM resource type. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-resource-interfaces.ts b/packages/typespec-azure-resource-manager/src/rules/arm-resource-interfaces.ts index d6ac05722b..4d04a0a0cf 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-resource-interfaces.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-interfaces.ts @@ -1,10 +1,11 @@ -import { Interface, createRule } from "@typespec/compiler"; +import { Interface, createRule, fileRef } from "@typespec/compiler"; import { isArmOperationsListInterface } from "../private.decorators.js"; import { isInternalTypeSpec } from "./utils.js"; export const interfacesRule = createRule({ name: "arm-resource-interface-requires-decorator", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-interface-requires-decorator.md"), severity: "warning", description: "Each resource interface must have an @armResourceOperations decorator.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-interface-requires-decorator", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-action-verb.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-action-verb.md similarity index 93% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-action-verb.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-action-verb.md index f19907f040..636d75a3df 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-action-verb.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-action-verb.md @@ -1,7 +1,3 @@ ---- -title: arm-resource-invalid-action-verb ---- - ```text title=- Full name- @azure-tools/typespec-azure-resource-manager/arm-resource-invalid-action-verb ``` diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-action-verb.ts b/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-action-verb.ts index b5b647c63a..2e79d32da9 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-action-verb.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-action-verb.ts @@ -1,4 +1,4 @@ -import { Operation, createRule } from "@typespec/compiler"; +import { Operation, createRule, fileRef } from "@typespec/compiler"; import { getOperationVerb } from "@typespec/http"; import { getActionDetails } from "@typespec/rest"; @@ -6,6 +6,7 @@ import { isSourceOperationResourceManagerInternal } from "./utils.js"; export const armResourceInvalidActionVerbRule = createRule({ name: "arm-resource-invalid-action-verb", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-invalid-action-verb.md"), severity: "warning", description: "Actions must be HTTP Post or Get operations.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-action-verb", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-envelope-property.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-envelope-property.md similarity index 79% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-envelope-property.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-envelope-property.md index 22f16a5eaf..065f0c57a3 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-envelope-property.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-envelope-property.md @@ -1,11 +1,3 @@ ---- -title: arm-resource-invalid-envelope-property ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-envelope-property -``` - Resource envelope properties must originate from the `Azure.ResourceManager` namespace. Custom properties that are not part of the standard ARM resource envelope should be placed in the resource-specific property bag instead. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-envelope-property.ts b/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-envelope-property.ts index 35648a31a2..8308dc8e9e 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-envelope-property.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-envelope-property.ts @@ -1,10 +1,11 @@ -import { Model, ModelProperty, createRule, isKey, paramMessage } from "@typespec/compiler"; +import { Model, ModelProperty, createRule, fileRef, isKey, paramMessage } from "@typespec/compiler"; import { getArmResource } from "../resource.js"; import { getNamespaceName, getSourceModel } from "./utils.js"; export const armResourceEnvelopeProperties = createRule({ name: "arm-resource-invalid-envelope-property", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-invalid-envelope-property.md"), severity: "warning", description: "Check for invalid resource envelope properties.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-envelope-property", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-version-format.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-version-format.md similarity index 74% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-version-format.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-version-format.md index 9f30bb6f9d..8f060863f4 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-version-format.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-version-format.md @@ -1,11 +1,3 @@ ---- -title: arm-resource-invalid-version-format ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-resource-invalid-version-format -``` - ARM resource versions must follow the `YYYY-MM-DD` format, with an optional suffix such as `-preview` or a versioned suffix like `-alpha.1`. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-version-format.ts b/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-version-format.ts index 3f469ac6e4..f31b593861 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-version-format.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-invalid-version-format.ts @@ -1,10 +1,11 @@ -import { Namespace, createRule, paramMessage } from "@typespec/compiler"; +import { Namespace, createRule, fileRef, paramMessage } from "@typespec/compiler"; import { getVersion } from "@typespec/versioning"; import { isInternalTypeSpec } from "./utils.js"; export const armResourceInvalidVersionFormatRule = createRule({ name: "arm-resource-invalid-version-format", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-invalid-version-format.md"), severity: "warning", description: "Check for valid versions.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-invalid-version-format", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-key-invalid-chars.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-key-invalid-chars.md similarity index 71% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-key-invalid-chars.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-key-invalid-chars.md index 7fd8c96c59..3aba89c433 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-key-invalid-chars.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-key-invalid-chars.md @@ -1,11 +1,3 @@ ---- -title: "arm-resource-key-invalid-chars" ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-resource-key-invalid-chars -``` - ARM resource key must contain only alphanumeric characters or dashes, starting with a lowercase letter. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-resource-key-invalid-chars.ts b/packages/typespec-azure-resource-manager/src/rules/arm-resource-key-invalid-chars.ts index a42409a588..08b12ab8f6 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-resource-key-invalid-chars.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-key-invalid-chars.ts @@ -1,9 +1,17 @@ -import { Model, ModelProperty, createRule, getKeyName, paramMessage } from "@typespec/compiler"; +import { + Model, + ModelProperty, + createRule, + fileRef, + getKeyName, + paramMessage, +} from "@typespec/compiler"; import { getDecoratorParam, isInternalTypeSpec, isResource, isValidKey } from "./utils.js"; export const armResourceKeyInvalidCharsRule = createRule({ name: "arm-resource-key-invalid-chars", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-key-invalid-chars.md"), severity: "warning", description: "Arm resource key must contain only alphanumeric characters.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-key-invalid-chars", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/resource-name-pattern.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-name-pattern.md similarity index 72% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/resource-name-pattern.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-name-pattern.md index 5cccefc235..00d6cc92f5 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/resource-name-pattern.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-name-pattern.md @@ -1,11 +1,3 @@ ---- -title: resource-name-pattern ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-resource-name-pattern -``` - Resource names must specify a pattern string using `@pattern`, providing a regular expression that the name must match. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-resource-name-pattern.ts b/packages/typespec-azure-resource-manager/src/rules/arm-resource-name-pattern.ts index efa266596e..23335e4dbc 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-resource-name-pattern.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-name-pattern.ts @@ -4,6 +4,7 @@ import { Program, createAddDecoratorCodeFix, createRule, + fileRef, getPattern, } from "@typespec/compiler"; @@ -18,8 +19,9 @@ function createPatternCodeFix(diagnosticTarget: DiagnosticTarget) { */ export const armResourceNamePatternRule = createRule({ name: "arm-resource-name-pattern", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-name-pattern.md"), severity: "warning", - url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/resource-name-pattern", + url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-name-pattern", description: "The resource name parameter should be defined with a 'pattern' restriction.", messages: { default: `The resource name parameter should be defined with a 'pattern' restriction. Please use 'ResourceNameParameter' to specify the name parameter with options to override default pattern RegEx expression.`, diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-operation-response.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-operation-response.md similarity index 83% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-operation-response.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-operation-response.md index 1d856d1936..c666ae1e4d 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-operation-response.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-operation-response.md @@ -1,11 +1,3 @@ ---- -title: "arm-resource-operation-response" ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-resource-operation-response -``` - PUT, GET, PATCH & LIST must return the same resource schema. Operations on a resource such as read, create, update, and list must all return the resource type itself (or a collection of the resource type for list operations). :::note diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-resource-operation-response.ts b/packages/typespec-azure-resource-manager/src/rules/arm-resource-operation-response.ts index a8b7d061d3..91eb977d69 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-resource-operation-response.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-operation-response.ts @@ -4,6 +4,7 @@ import { Model, Operation, createRule, + fileRef, getEffectiveModelType, isErrorType, isType, @@ -15,6 +16,7 @@ import { isInternalTypeSpec } from "./utils.js"; export const armResourceOperationsRule = createRule({ name: "arm-resource-operation-response", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-operation-response.md"), severity: "warning", description: "[RPC 008]: PUT, GET, PATCH & LIST must return the same resource schema.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-operation-response", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-operation.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-operation.md similarity index 86% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-operation.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-operation.md index 6f1f23b930..e9fa469ffc 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-operation.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-operation.md @@ -1,11 +1,3 @@ ---- -title: "arm-resource-operation" ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-resource-operation -``` - Validate that all ARM Resource operations are defined inside an interface, include an `api-version` parameter, and use the correct decorator for the HTTP verb. #### ❌ Incorrect diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-patch.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-patch.md similarity index 83% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-patch.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-patch.md index 86a7c8aefb..361612a071 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-patch.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-patch.md @@ -1,11 +1,3 @@ ---- -title: "arm-resource-patch" ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-resource-patch -``` - Validate ARM PATCH operations. The request body of a PATCH must be a model with a subset of the resource properties. The PATCH body must not contain properties that do not exist on the resource. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-resource-patch.ts b/packages/typespec-azure-resource-manager/src/rules/arm-resource-patch.ts index fbbcccc311..53bf3344da 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-resource-patch.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-patch.ts @@ -6,6 +6,7 @@ import { Operation, Program, createRule, + fileRef, getEffectiveModelType, getProperty, isErrorType, @@ -26,6 +27,7 @@ import { getSourceModel, isInternalTypeSpec } from "./utils.js"; export const patchOperationsRule = createRule({ name: "arm-resource-patch", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-patch.md"), severity: "warning", description: "Validate ARM PATCH operations.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-patch", diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-resource-path-invalid-chars.ts b/packages/typespec-azure-resource-manager/src/rules/arm-resource-path-invalid-chars.ts index 312461d0cd..6a5a39d775 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-resource-path-invalid-chars.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-path-invalid-chars.ts @@ -1,10 +1,11 @@ -import { Model, ModelProperty, createRule, paramMessage } from "@typespec/compiler"; +import { Model, ModelProperty, createRule, fileRef, paramMessage } from "@typespec/compiler"; import { getSegment } from "@typespec/rest"; import { getDecoratorParam, isInternalTypeSpec, isResource, isValidKey } from "./utils.js"; export const armResourcePathInvalidCharsRule = createRule({ name: "arm-resource-path-segment-invalid-chars", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-path-segment-invalid-chars.md"), severity: "warning", description: "Arm resource name must contain only alphanumeric characters.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-path-segment-invalid-chars", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-path-segment-invalid-chars.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-path-segment-invalid-chars.md similarity index 68% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-path-segment-invalid-chars.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-path-segment-invalid-chars.md index 58b10c74c1..9ae15345c7 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-path-segment-invalid-chars.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-path-segment-invalid-chars.md @@ -1,11 +1,3 @@ ---- -title: "arm-resource-path-segment-invalid-chars" ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/arm-resource-path-segment-invalid-chars -``` - ARM resource path segments must contain only alphanumeric characters or dashes, starting with a lowercase letter. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/arm-resource-provisioning-state-rule.ts b/packages/typespec-azure-resource-manager/src/rules/arm-resource-provisioning-state-rule.ts index 41bab4ba89..2e1bbb02c5 100644 --- a/packages/typespec-azure-resource-manager/src/rules/arm-resource-provisioning-state-rule.ts +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-provisioning-state-rule.ts @@ -1,4 +1,4 @@ -import { Enum, Model, createRule, getProperty, paramMessage } from "@typespec/compiler"; +import { Enum, Model, createRule, fileRef, getProperty, paramMessage } from "@typespec/compiler"; import { getUnionAsEnum } from "@azure-tools/typespec-azure-core"; import { getArmResource } from "../resource.js"; @@ -7,6 +7,7 @@ import { getSourceProperty } from "./utils.js"; export const armResourceProvisioningStateRule = createRule({ name: "arm-resource-provisioning-state", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-provisioning-state.md"), severity: "warning", description: "Check for properly configured provisioningState property.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-provisioning-state", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-provisioning-state.md b/packages/typespec-azure-resource-manager/src/rules/arm-resource-provisioning-state.md similarity index 91% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-provisioning-state.md rename to packages/typespec-azure-resource-manager/src/rules/arm-resource-provisioning-state.md index 520d82b0a9..7d0eea8561 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/arm-resource-provisioning-state.md +++ b/packages/typespec-azure-resource-manager/src/rules/arm-resource-provisioning-state.md @@ -1,7 +1,3 @@ ---- -title: arm-resource-provisioning-state ---- - ```text title=- Full name- @azure-tools/typespec-azure-resource-manager/arm-resource-provisioning-state ``` diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/beyond-nesting-levels.md b/packages/typespec-azure-resource-manager/src/rules/beyond-nesting-levels.md similarity index 87% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/beyond-nesting-levels.md rename to packages/typespec-azure-resource-manager/src/rules/beyond-nesting-levels.md index 30b7932974..8810304ef1 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/beyond-nesting-levels.md +++ b/packages/typespec-azure-resource-manager/src/rules/beyond-nesting-levels.md @@ -1,11 +1,3 @@ ---- -title: "beyond-nesting-levels" ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/beyond-nesting-levels -``` - Tracked Resources must use 3 or fewer levels of nesting. Deeply nested resources make the API harder to use and are discouraged by ARM guidelines. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/beyond-nesting-levels.ts b/packages/typespec-azure-resource-manager/src/rules/beyond-nesting-levels.ts index 7c782e2273..3384d389f0 100644 --- a/packages/typespec-azure-resource-manager/src/rules/beyond-nesting-levels.ts +++ b/packages/typespec-azure-resource-manager/src/rules/beyond-nesting-levels.ts @@ -1,4 +1,4 @@ -import { Model, createRule } from "@typespec/compiler"; +import { Model, createRule, fileRef } from "@typespec/compiler"; import { getParentResource } from "@typespec/rest"; import { isTrackedResource } from "./utils.js"; @@ -9,6 +9,7 @@ import { isTrackedResource } from "./utils.js"; export const beyondNestingRule = createRule({ name: "beyond-nesting-levels", + docs: fileRef.fromPackageRoot("src/rules/beyond-nesting-levels.md"), severity: "warning", description: "Tracked Resources must use 3 or fewer levels of nesting.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/beyond-nesting-levels", diff --git a/packages/typespec-azure-resource-manager/src/rules/core-operations.ts b/packages/typespec-azure-resource-manager/src/rules/core-operations.ts index 25a2236f31..8b53c56ad1 100644 --- a/packages/typespec-azure-resource-manager/src/rules/core-operations.ts +++ b/packages/typespec-azure-resource-manager/src/rules/core-operations.ts @@ -4,6 +4,7 @@ import { Operation, Program, createRule, + fileRef, isTemplateInstance, paramMessage, } from "@typespec/compiler"; @@ -19,6 +20,7 @@ import { export const coreOperationsRule = createRule({ name: "arm-resource-operation", + docs: fileRef.fromPackageRoot("src/rules/arm-resource-operation.md"), severity: "warning", description: "Validate ARM Resource operations.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/arm-resource-operation", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/empty-updateable-properties.md b/packages/typespec-azure-resource-manager/src/rules/empty-updateable-properties.md similarity index 82% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/empty-updateable-properties.md rename to packages/typespec-azure-resource-manager/src/rules/empty-updateable-properties.md index 97f19dee59..9470e1726a 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/empty-updateable-properties.md +++ b/packages/typespec-azure-resource-manager/src/rules/empty-updateable-properties.md @@ -1,11 +1,3 @@ ---- -title: "empty-updateable-properties" ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/empty-updateable-properties -``` - Resources with update operations should have updateable properties. The RP-specific properties of the resource (as defined in the `properties` property) should have at least one updateable property. Properties are updateable if they do not have a `@visibility` decorator, or if they include `Lifecycle.Update` in the `@visibility` decorator arguments. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/envelope-properties.ts b/packages/typespec-azure-resource-manager/src/rules/envelope-properties.ts index e1e561d5e5..e55182d68f 100644 --- a/packages/typespec-azure-resource-manager/src/rules/envelope-properties.ts +++ b/packages/typespec-azure-resource-manager/src/rules/envelope-properties.ts @@ -1,4 +1,4 @@ -import { Model, createRule, getProperty } from "@typespec/compiler"; +import { Model, createRule, fileRef, getProperty } from "@typespec/compiler"; import { getArmResources } from "../resource.js"; import { getProperties } from "./utils.js"; @@ -8,6 +8,7 @@ import { getProperties } from "./utils.js"; */ export const envelopePropertiesRules = createRule({ name: "empty-updateable-properties", + docs: fileRef.fromPackageRoot("src/rules/empty-updateable-properties.md"), severity: "warning", description: "Should have updateable properties.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/empty-updateable-properties", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/improper-subscription-list-operation.md b/packages/typespec-azure-resource-manager/src/rules/improper-subscription-list-operation.md similarity index 80% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/improper-subscription-list-operation.md rename to packages/typespec-azure-resource-manager/src/rules/improper-subscription-list-operation.md index 05e2d1a451..a67a66b471 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/improper-subscription-list-operation.md +++ b/packages/typespec-azure-resource-manager/src/rules/improper-subscription-list-operation.md @@ -1,11 +1,3 @@ ---- -title: "improper-subscription-list-operation" ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/improper-subscription-list-operation -``` - Tenant and Extension resources should not define a list by subscription operation. These resource types are not scoped to a subscription, so listing them by subscription is not appropriate. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/improper-subscription-list-operation.ts b/packages/typespec-azure-resource-manager/src/rules/improper-subscription-list-operation.ts index bc08fcb9d3..25ed637bd1 100644 --- a/packages/typespec-azure-resource-manager/src/rules/improper-subscription-list-operation.ts +++ b/packages/typespec-azure-resource-manager/src/rules/improper-subscription-list-operation.ts @@ -1,4 +1,4 @@ -import { createRule, Program } from "@typespec/compiler"; +import { createRule, fileRef, Program } from "@typespec/compiler"; import { getArmResources, getResourceBaseType, ResourceBaseType } from "../resource.js"; import { getInterface } from "./utils.js"; @@ -7,6 +7,7 @@ import { getInterface } from "./utils.js"; */ export const improperSubscriptionListOperationRule = createRule({ name: "improper-subscription-list-operation", + docs: fileRef.fromPackageRoot("src/rules/improper-subscription-list-operation.md"), severity: "warning", description: `Tenant and Extension resources should not define a list by subscription operation.`, url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/improper-subscription-list-operation", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/lro-location-header.md b/packages/typespec-azure-resource-manager/src/rules/lro-location-header.md similarity index 93% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/lro-location-header.md rename to packages/typespec-azure-resource-manager/src/rules/lro-location-header.md index 47de4045be..ef28a768a8 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/lro-location-header.md +++ b/packages/typespec-azure-resource-manager/src/rules/lro-location-header.md @@ -1,7 +1,3 @@ ---- -title: lro-location-header ---- - ```text title=- Full name- @azure-tools/typespec-azure-resource-manager/lro-location-header ``` diff --git a/packages/typespec-azure-resource-manager/src/rules/lro-location-header.ts b/packages/typespec-azure-resource-manager/src/rules/lro-location-header.ts index 94349e0b41..9cb4bd5147 100644 --- a/packages/typespec-azure-resource-manager/src/rules/lro-location-header.ts +++ b/packages/typespec-azure-resource-manager/src/rules/lro-location-header.ts @@ -1,4 +1,4 @@ -import { ModelProperty, Operation, createRule } from "@typespec/compiler"; +import { ModelProperty, Operation, createRule, fileRef } from "@typespec/compiler"; import { getHttpOperation } from "@typespec/http"; function getCaseInsensitiveHeader( @@ -21,6 +21,7 @@ function getCaseInsensitiveHeader( */ export const lroLocationHeaderRule = createRule({ name: "lro-location-header", + docs: fileRef.fromPackageRoot("src/rules/lro-location-header.md"), severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/lro-location-header", description: "A 202 response should include a Location response header.", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/missing-operations-endpoint.md b/packages/typespec-azure-resource-manager/src/rules/missing-operations-endpoint.md similarity index 73% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/missing-operations-endpoint.md rename to packages/typespec-azure-resource-manager/src/rules/missing-operations-endpoint.md index 52e421eb05..3eeca2688e 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/missing-operations-endpoint.md +++ b/packages/typespec-azure-resource-manager/src/rules/missing-operations-endpoint.md @@ -1,11 +1,3 @@ ---- -title: "missing-operations-endpoint" ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/missing-operations-endpoint -``` - Check for missing Operations interface. All Azure Resource Manager services must expose the operations endpoint. Add the Operations interface to your service namespace. #### ❌ Incorrect diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/missing-x-ms-identifiers.md b/packages/typespec-azure-resource-manager/src/rules/missing-x-ms-identifiers.md similarity index 91% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/missing-x-ms-identifiers.md rename to packages/typespec-azure-resource-manager/src/rules/missing-x-ms-identifiers.md index eee69646ee..27109e747d 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/missing-x-ms-identifiers.md +++ b/packages/typespec-azure-resource-manager/src/rules/missing-x-ms-identifiers.md @@ -1,7 +1,3 @@ ---- -title: missing-x-ms-identifiers ---- - ```text title=- Full name- @azure-tools/typespec-azure-resource-manager/missing-x-ms-identifiers ``` diff --git a/packages/typespec-azure-resource-manager/src/rules/missing-x-ms-identifiers.ts b/packages/typespec-azure-resource-manager/src/rules/missing-x-ms-identifiers.ts index 5d60502b02..01c5e2d075 100644 --- a/packages/typespec-azure-resource-manager/src/rules/missing-x-ms-identifiers.ts +++ b/packages/typespec-azure-resource-manager/src/rules/missing-x-ms-identifiers.ts @@ -4,6 +4,7 @@ import { Program, createAddDecoratorCodeFix, createRule, + fileRef, getProperty, isArrayModelType, paramMessage, @@ -13,6 +14,7 @@ import { getArmIdentifiers, getArmKeyIdentifiers } from "../resource.js"; export const missingXmsIdentifiersRule = createRule({ name: "missing-x-ms-identifiers", + docs: fileRef.fromPackageRoot("src/rules/missing-x-ms-identifiers.md"), description: `Array properties should describe their identifying properties with x-ms-identifiers. Decorate the property with @OpenAPI.extension("x-ms-identifiers", #[id-prop]) where "id-prop" is a list of the names of identifying properties in the item type.`, severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/missing-x-ms-identifiers", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-empty-model.md b/packages/typespec-azure-resource-manager/src/rules/no-empty-model.md similarity index 95% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-empty-model.md rename to packages/typespec-azure-resource-manager/src/rules/no-empty-model.md index c2b30eda06..3090c92efd 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-empty-model.md +++ b/packages/typespec-azure-resource-manager/src/rules/no-empty-model.md @@ -1,7 +1,3 @@ ---- -title: no-empty-model ---- - ```text title=- Full name- @azure-tools/typespec-azure-resource-manager/no-empty-model ``` diff --git a/packages/typespec-azure-resource-manager/src/rules/no-empty-model.ts b/packages/typespec-azure-resource-manager/src/rules/no-empty-model.ts index 9190578eb0..6df79f7627 100644 --- a/packages/typespec-azure-resource-manager/src/rules/no-empty-model.ts +++ b/packages/typespec-azure-resource-manager/src/rules/no-empty-model.ts @@ -1,7 +1,8 @@ -import { createRule, isRecordModelType, Model } from "@typespec/compiler"; +import { createRule, fileRef, isRecordModelType, Model } from "@typespec/compiler"; export const noEmptyModel = createRule({ name: "no-empty-model", + docs: fileRef.fromPackageRoot("src/rules/no-empty-model.md"), severity: "warning", description: "ARM Properties with type:object that don't reference a model definition are not allowed. ARM doesn't allow generic type definitions as this leads to bad customer experience.", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-override-props.md b/packages/typespec-azure-resource-manager/src/rules/no-override-props.md similarity index 93% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-override-props.md rename to packages/typespec-azure-resource-manager/src/rules/no-override-props.md index 7205bfb21f..f4770c24af 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-override-props.md +++ b/packages/typespec-azure-resource-manager/src/rules/no-override-props.md @@ -1,11 +1,3 @@ ---- -title: no-override-props ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/no-override-props -``` - Warns when a model redefines a property that is already defined in one of its base models. Repeating inherited properties in a child model is an anti-pattern for Azure APIs and can cause problems with OpenAPI tooling and some language representations of the models. Overriding an inherited property is allowed when: diff --git a/packages/typespec-azure-resource-manager/src/rules/no-override-props.ts b/packages/typespec-azure-resource-manager/src/rules/no-override-props.ts index 44e40ed4ba..98da2e1647 100644 --- a/packages/typespec-azure-resource-manager/src/rules/no-override-props.ts +++ b/packages/typespec-azure-resource-manager/src/rules/no-override-props.ts @@ -1,6 +1,7 @@ import { getUnionAsEnum } from "@azure-tools/typespec-azure-core"; import { createRule, + fileRef, ignoreDiagnostics, Model, paramMessage, @@ -75,6 +76,7 @@ function getScalarFamily(type: Type): ScalarFamily | undefined { export const noOverridePropsRule = createRule({ name: "no-override-props", + docs: fileRef.fromPackageRoot("src/rules/no-override-props.md"), severity: "warning", description: "Disallow redefining properties already defined in a base type.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/no-override-props", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-reserved-resource-property.md b/packages/typespec-azure-resource-manager/src/rules/no-reserved-resource-property.md similarity index 89% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-reserved-resource-property.md rename to packages/typespec-azure-resource-manager/src/rules/no-reserved-resource-property.md index e02d60842d..f8aff8e0e1 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-reserved-resource-property.md +++ b/packages/typespec-azure-resource-manager/src/rules/no-reserved-resource-property.md @@ -1,11 +1,3 @@ ---- -title: no-reserved-resource-property ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/no-reserved-resource-property -``` - Certain property names are reserved and must not be present in a resource's property bag (the model referenced by the `properties` property of an ARM resource). For example, `billingData` is reserved for platform billing integration and is being standardized through Common Types, so resource providers must not declare it. The property name is matched case-insensitively (`billingData`, `BillingData`, `billingdata`, etc.) and is disallowed regardless of its type (named model reference, inline model, or primitive). The set of reserved names is maintained by the rule. diff --git a/packages/typespec-azure-resource-manager/src/rules/no-reserved-resource-property.ts b/packages/typespec-azure-resource-manager/src/rules/no-reserved-resource-property.ts index fe89ae617a..7acdb49d85 100644 --- a/packages/typespec-azure-resource-manager/src/rules/no-reserved-resource-property.ts +++ b/packages/typespec-azure-resource-manager/src/rules/no-reserved-resource-property.ts @@ -1,4 +1,4 @@ -import { Model, createRule, getProperty, paramMessage } from "@typespec/compiler"; +import { Model, createRule, fileRef, getProperty, paramMessage } from "@typespec/compiler"; import { getArmResource } from "../resource.js"; import { getProperties } from "./utils.js"; @@ -23,6 +23,7 @@ const reservedPropertiesByLowerName = new Map( export const noReservedResourcePropertyRule = createRule({ name: "no-reserved-resource-property", + docs: fileRef.fromPackageRoot("src/rules/no-reserved-resource-property.md"), description: "Reserved property names (for example 'billingData') must not be present in a resource's property bag. The property name is matched case-insensitively.", severity: "warning", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-resource-delete-operation.md b/packages/typespec-azure-resource-manager/src/rules/no-resource-delete-operation.md similarity index 94% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-resource-delete-operation.md rename to packages/typespec-azure-resource-manager/src/rules/no-resource-delete-operation.md index f97e564bce..b4eb609124 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-resource-delete-operation.md +++ b/packages/typespec-azure-resource-manager/src/rules/no-resource-delete-operation.md @@ -1,7 +1,3 @@ ---- -title: no-resource-delete-operation ---- - ```text title=- Full name- @azure-tools/typespec-azure-resource-manager/no-resource-delete-operation ``` diff --git a/packages/typespec-azure-resource-manager/src/rules/no-resource-delete-operation.ts b/packages/typespec-azure-resource-manager/src/rules/no-resource-delete-operation.ts index c855861c24..3dc35e17a7 100644 --- a/packages/typespec-azure-resource-manager/src/rules/no-resource-delete-operation.ts +++ b/packages/typespec-azure-resource-manager/src/rules/no-resource-delete-operation.ts @@ -1,4 +1,4 @@ -import { Model, createRule, paramMessage } from "@typespec/compiler"; +import { Model, createRule, fileRef, paramMessage } from "@typespec/compiler"; import { getArmResources } from "../resource.js"; import { getInterface } from "./utils.js"; @@ -7,6 +7,7 @@ import { getInterface } from "./utils.js"; */ export const deleteOperationMissingRule = createRule({ name: "no-resource-delete-operation", + docs: fileRef.fromPackageRoot("src/rules/no-resource-delete-operation.md"), severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/no-resource-delete-operation", description: "Check for resources that must have a delete operation.", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-response-body.md b/packages/typespec-azure-resource-manager/src/rules/no-response-body.md similarity index 97% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-response-body.md rename to packages/typespec-azure-resource-manager/src/rules/no-response-body.md index 887605ea81..58e3772bd5 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/no-response-body.md +++ b/packages/typespec-azure-resource-manager/src/rules/no-response-body.md @@ -1,7 +1,3 @@ ---- -title: no-response-body ---- - ```text title=- Full name- @azure-tools/typespec-azure-resource-manager/no-response-body diff --git a/packages/typespec-azure-resource-manager/src/rules/no-response-body.ts b/packages/typespec-azure-resource-manager/src/rules/no-response-body.ts index 33f39743db..23ed98835b 100644 --- a/packages/typespec-azure-resource-manager/src/rules/no-response-body.ts +++ b/packages/typespec-azure-resource-manager/src/rules/no-response-body.ts @@ -1,4 +1,4 @@ -import { createRule, isTemplateInstance, Operation } from "@typespec/compiler"; +import { createRule, fileRef, isTemplateInstance, Operation } from "@typespec/compiler"; import { getHttpOperation, getResponsesForOperation, HttpOperationResponse } from "@typespec/http"; import { isTemplatedInterfaceOperation } from "./utils.js"; /** @@ -7,6 +7,7 @@ import { isTemplatedInterfaceOperation } from "./utils.js"; */ export const noResponseBodyRule = createRule({ name: "no-response-body", + docs: fileRef.fromPackageRoot("src/rules/no-response-body.md"), description: "Check that the body is empty for 202 and 204 responses, and not empty for other success (2xx) responses.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/no-response-body", diff --git a/packages/typespec-azure-resource-manager/src/rules/operations-interface-missing.ts b/packages/typespec-azure-resource-manager/src/rules/operations-interface-missing.ts index d732f846cd..afe32684fa 100644 --- a/packages/typespec-azure-resource-manager/src/rules/operations-interface-missing.ts +++ b/packages/typespec-azure-resource-manager/src/rules/operations-interface-missing.ts @@ -1,4 +1,4 @@ -import { createRule, isService, paramMessage } from "@typespec/compiler"; +import { createRule, fileRef, isService, paramMessage } from "@typespec/compiler"; import { getArmProviderNamespace } from "../namespace.js"; import { isArmOperationsListInterface } from "../private.decorators.js"; @@ -8,6 +8,7 @@ import { isArmOperationsListInterface } from "../private.decorators.js"; */ export const operationsInterfaceMissingRule = createRule({ name: "missing-operations-endpoint", + docs: fileRef.fromPackageRoot("src/rules/missing-operations-endpoint.md"), severity: "warning", description: "Check for missing Operations interface.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/missing-operations-endpoint", diff --git a/packages/typespec-azure-resource-manager/src/rules/patch-envelope-properties.ts b/packages/typespec-azure-resource-manager/src/rules/patch-envelope-properties.ts index 609c6aafa2..98b6145360 100644 --- a/packages/typespec-azure-resource-manager/src/rules/patch-envelope-properties.ts +++ b/packages/typespec-azure-resource-manager/src/rules/patch-envelope-properties.ts @@ -1,9 +1,10 @@ -import { Model, Type, createRule, getProperty, paramMessage } from "@typespec/compiler"; +import { Model, Type, createRule, fileRef, getProperty, paramMessage } from "@typespec/compiler"; import { getArmResources } from "../resource.js"; export const patchEnvelopePropertiesRules = createRule({ name: "patch-envelope", + docs: fileRef.fromPackageRoot("src/rules/patch-envelope.md"), severity: "warning", description: "Patch envelope properties should match the resource properties.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/patch-envelope", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/patch-envelope.md b/packages/typespec-azure-resource-manager/src/rules/patch-envelope.md similarity index 89% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/patch-envelope.md rename to packages/typespec-azure-resource-manager/src/rules/patch-envelope.md index 2b50a944c6..f26000fecc 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/patch-envelope.md +++ b/packages/typespec-azure-resource-manager/src/rules/patch-envelope.md @@ -1,11 +1,3 @@ ---- -title: "patch-envelope" ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/patch-envelope -``` - Patch envelope properties should match the resource properties. If a resource defines envelope properties such as `identity`, `managedBy`, `plan`, `sku`, or `tags`, these properties must also be present in the PATCH request body so they can be updated. #### ❌ Incorrect diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/resource-name.md b/packages/typespec-azure-resource-manager/src/rules/resource-name.md similarity index 83% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/resource-name.md rename to packages/typespec-azure-resource-manager/src/rules/resource-name.md index 55f61fc591..4510e55b75 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/resource-name.md +++ b/packages/typespec-azure-resource-manager/src/rules/resource-name.md @@ -1,11 +1,3 @@ ---- -title: "resource-name" ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/resource-name -``` - Check the resource name. ARM resource model names must contain only alphanumeric characters (starting with an uppercase letter), and the `name` property must be a read-only `@path` parameter. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/resource-name.ts b/packages/typespec-azure-resource-manager/src/rules/resource-name.ts index 59e4696e2e..788e672dc2 100644 --- a/packages/typespec-azure-resource-manager/src/rules/resource-name.ts +++ b/packages/typespec-azure-resource-manager/src/rules/resource-name.ts @@ -3,6 +3,7 @@ import { ModelProperty, SemanticNodeListener, createRule, + fileRef, getProperty, } from "@typespec/compiler"; import * as http from "@typespec/http"; @@ -15,6 +16,7 @@ import { isReadonlyProperty } from "../utils.js"; */ export const resourceNameRule = createRule({ name: "resource-name", + docs: fileRef.fromPackageRoot("src/rules/resource-name.md"), severity: "warning", description: "Check the resource name.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/resource-name", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/retry-after.md b/packages/typespec-azure-resource-manager/src/rules/retry-after.md similarity index 90% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/retry-after.md rename to packages/typespec-azure-resource-manager/src/rules/retry-after.md index 3011fd8ff2..013666c512 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/retry-after.md +++ b/packages/typespec-azure-resource-manager/src/rules/retry-after.md @@ -1,11 +1,3 @@ ---- -title: "retry-after" ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/retry-after -``` - Check if the `Retry-After` header appears in the response for long-running operations. For long-running operations, the `Retry-After` header indicates how long the client should wait before polling the operation status. This header should be included in 201 or 202 responses. #### ❌ Incorrect diff --git a/packages/typespec-azure-resource-manager/src/rules/retry-after.ts b/packages/typespec-azure-resource-manager/src/rules/retry-after.ts index 69a6ab618b..9221266953 100644 --- a/packages/typespec-azure-resource-manager/src/rules/retry-after.ts +++ b/packages/typespec-azure-resource-manager/src/rules/retry-after.ts @@ -1,4 +1,4 @@ -import { Operation, Program, createRule } from "@typespec/compiler"; +import { Operation, Program, createRule, fileRef } from "@typespec/compiler"; import { getResponsesForOperation } from "@typespec/http"; // import { getExtensions } from "@typespec/openapi"; import { getLroMetadata } from "@azure-tools/typespec-azure-core"; @@ -9,6 +9,7 @@ import { isTemplatedInterfaceOperation } from "./utils.js"; */ export const retryAfterRule = createRule({ name: "retry-after", + docs: fileRef.fromPackageRoot("src/rules/retry-after.md"), severity: "warning", description: "Check if retry-after header appears in response body.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/retry-after", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/secret-prop.md b/packages/typespec-azure-resource-manager/src/rules/secret-prop.md similarity index 96% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/secret-prop.md rename to packages/typespec-azure-resource-manager/src/rules/secret-prop.md index 0df8c8b779..bf57d3622d 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/secret-prop.md +++ b/packages/typespec-azure-resource-manager/src/rules/secret-prop.md @@ -1,7 +1,3 @@ ---- -title: secret-prop ---- - ```text title=- Full name- @azure-tools/typespec-azure-resource-manager/secret-prop ``` diff --git a/packages/typespec-azure-resource-manager/src/rules/secret-prop.ts b/packages/typespec-azure-resource-manager/src/rules/secret-prop.ts index 252a1dd7b4..7231838a54 100644 --- a/packages/typespec-azure-resource-manager/src/rules/secret-prop.ts +++ b/packages/typespec-azure-resource-manager/src/rules/secret-prop.ts @@ -3,6 +3,7 @@ import { UsageFlags, createAddDecoratorCodeFix, createRule, + fileRef, isSecret, paramMessage, resolveUsages, @@ -18,6 +19,7 @@ function isKeyValuePairKeyProp(property: ModelProperty): boolean { } export const secretProprule = createRule({ name: "secret-prop", + docs: fileRef.fromPackageRoot("src/rules/secret-prop.md"), description: `RPC-v1-13: Check that property with names indicating sensitive information(e.g. contains auth, password, token, secret, etc.) are marked with @secret decorator.`, severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/secret-prop", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/unsupported-type.md b/packages/typespec-azure-resource-manager/src/rules/unsupported-type.md similarity index 71% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/unsupported-type.md rename to packages/typespec-azure-resource-manager/src/rules/unsupported-type.md index 86abd7502f..66b3f138e7 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/unsupported-type.md +++ b/packages/typespec-azure-resource-manager/src/rules/unsupported-type.md @@ -1,11 +1,3 @@ ---- -title: unsupported-type ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/unsupported-type -``` - Check the ARM specification is not using types not supported in ARM. Primitive types currently unsupported in ARM: diff --git a/packages/typespec-azure-resource-manager/src/rules/unsupported-type.ts b/packages/typespec-azure-resource-manager/src/rules/unsupported-type.ts index 2414070c4a..a12bedf226 100644 --- a/packages/typespec-azure-resource-manager/src/rules/unsupported-type.ts +++ b/packages/typespec-azure-resource-manager/src/rules/unsupported-type.ts @@ -1,4 +1,11 @@ -import { DiagnosticTarget, Type, createRule, isType, paramMessage } from "@typespec/compiler"; +import { + DiagnosticTarget, + Type, + createRule, + fileRef, + isType, + paramMessage, +} from "@typespec/compiler"; const UnsupportedIntrinsicModel = new Set(["int8", "int16", "uint8", "uint16", "uint32", "uint64"]); /** @@ -6,6 +13,7 @@ const UnsupportedIntrinsicModel = new Set(["int8", "int16", "uint8", "uint16", " */ export const unsupportedTypeRule = createRule({ name: "unsupported-type", + docs: fileRef.fromPackageRoot("src/rules/unsupported-type.md"), severity: "warning", description: "Check for unsupported ARM types.", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-resource-manager/rules/unsupported-type", diff --git a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/version-progression.md b/packages/typespec-azure-resource-manager/src/rules/version-progression.md similarity index 92% rename from website/src/content/docs/docs/libraries/azure-resource-manager/rules/version-progression.md rename to packages/typespec-azure-resource-manager/src/rules/version-progression.md index bb71d8209a..2bbe77da4b 100644 --- a/website/src/content/docs/docs/libraries/azure-resource-manager/rules/version-progression.md +++ b/packages/typespec-azure-resource-manager/src/rules/version-progression.md @@ -1,11 +1,3 @@ ---- -title: version-progression ---- - -```text title="Full name" -@azure-tools/typespec-azure-resource-manager/version-progression -``` - ARM service api-versions must: 1. Use a **unique date** — every entry's `YYYY-MM-DD` must differ from every other entry's date in the same `Versions` enum. A preview version and a stable version cannot share the same date (for example, `2026-04-28` and `2026-04-28-preview` together is not allowed). diff --git a/packages/typespec-azure-resource-manager/src/rules/version-progression.ts b/packages/typespec-azure-resource-manager/src/rules/version-progression.ts index b6a6f62f80..180dec1f39 100644 --- a/packages/typespec-azure-resource-manager/src/rules/version-progression.ts +++ b/packages/typespec-azure-resource-manager/src/rules/version-progression.ts @@ -1,4 +1,4 @@ -import { EnumMember, Namespace, createRule, paramMessage } from "@typespec/compiler"; +import { EnumMember, Namespace, createRule, fileRef, paramMessage } from "@typespec/compiler"; import { getVersion } from "@typespec/versioning"; @@ -29,6 +29,7 @@ function parseVersionDate(value: string): string | undefined { */ export const versionProgressionRule = createRule({ name: "version-progression", + docs: fileRef.fromPackageRoot("src/rules/version-progression.md"), severity: "warning", description: "Validate that ARM service versions all use unique dates and are declared in strictly increasing chronological order.", diff --git a/packages/typespec-client-generator-core/package.json b/packages/typespec-client-generator-core/package.json index fcb8103803..20936165aa 100644 --- a/packages/typespec-client-generator-core/package.json +++ b/packages/typespec-client-generator-core/package.json @@ -47,7 +47,7 @@ "test:ci": "vitest run --coverage --reporter=junit --reporter=default", "lint": "oxlint . --deny-warnings", "lint:fix": "oxlint . --fix", - "regen-docs": "tspd doc . --enable-experimental --llmstxt --output-dir ../../website/src/content/docs/docs/libraries/typespec-client-generator-core/reference" + "regen-docs": "tspd doc . --enable-experimental --llmstxt --rules-dir ../rules --output-dir ../../website/src/content/docs/docs/libraries/typespec-client-generator-core/reference" }, "files": [ "lib/*.tsp", diff --git a/website/src/content/docs/docs/libraries/typespec-client-generator-core/rules/csharp-no-url-suffix.md b/packages/typespec-client-generator-core/src/rules/csharp-no-url-suffix.md similarity index 78% rename from website/src/content/docs/docs/libraries/typespec-client-generator-core/rules/csharp-no-url-suffix.md rename to packages/typespec-client-generator-core/src/rules/csharp-no-url-suffix.md index 940b781ebc..6427f884dd 100644 --- a/website/src/content/docs/docs/libraries/typespec-client-generator-core/rules/csharp-no-url-suffix.md +++ b/packages/typespec-client-generator-core/src/rules/csharp-no-url-suffix.md @@ -1,11 +1,3 @@ ---- -title: "csharp-no-url-suffix" ---- - -```text title="Full name" -@azure-tools/typespec-client-generator-core/csharp-no-url-suffix -``` - Properties ending with `Url` should use `Uri` suffix instead to follow .NET SDK naming conventions. The rule checks the C#-resolved name (respecting `@clientName` overrides). diff --git a/packages/typespec-client-generator-core/src/rules/csharp-no-url-suffix.ts b/packages/typespec-client-generator-core/src/rules/csharp-no-url-suffix.ts index dee76854b7..a60fa1e71c 100644 --- a/packages/typespec-client-generator-core/src/rules/csharp-no-url-suffix.ts +++ b/packages/typespec-client-generator-core/src/rules/csharp-no-url-suffix.ts @@ -1,10 +1,11 @@ -import { ModelProperty, createRule, paramMessage } from "@typespec/compiler"; +import { ModelProperty, createRule, fileRef, paramMessage } from "@typespec/compiler"; import { createTCGCContext } from "../context.js"; import { getLibraryName } from "../public-utils.js"; import { createClientTspAugmentDecoratorCodeFix } from "./codefix-helpers.js"; export const csharpNoUrlSuffixRule = createRule({ name: "csharp-no-url-suffix", + docs: fileRef.fromPackageRoot("src/rules/csharp-no-url-suffix.md"), description: "Properties ending with 'Url' should use 'Uri' suffix instead to follow .NET naming conventions.", severity: "warning", diff --git a/website/src/content/docs/docs/libraries/typespec-client-generator-core/rules/no-unnamed-types.md b/packages/typespec-client-generator-core/src/rules/no-unnamed-types.md similarity index 87% rename from website/src/content/docs/docs/libraries/typespec-client-generator-core/rules/no-unnamed-types.md rename to packages/typespec-client-generator-core/src/rules/no-unnamed-types.md index 2c8bce66e1..f8bc779380 100644 --- a/website/src/content/docs/docs/libraries/typespec-client-generator-core/rules/no-unnamed-types.md +++ b/packages/typespec-client-generator-core/src/rules/no-unnamed-types.md @@ -1,11 +1,3 @@ ---- -title: no-unnamed-types ---- - -```text title="Full name" -@azure-tools/typespec-client-generator-core/no-unnamed-types -``` - Types used in the public client surface should be named explicitly rather than defined anonymously or inline. Anonymous types receive a generated name in emitted SDKs, which hurts readability and makes the type hard to diff --git a/packages/typespec-client-generator-core/src/rules/no-unnamed-types.rule.ts b/packages/typespec-client-generator-core/src/rules/no-unnamed-types.rule.ts index 2f9ef828e2..850b16bd83 100644 --- a/packages/typespec-client-generator-core/src/rules/no-unnamed-types.rule.ts +++ b/packages/typespec-client-generator-core/src/rules/no-unnamed-types.rule.ts @@ -1,4 +1,4 @@ -import { createRule, Model, paramMessage, Union } from "@typespec/compiler"; +import { createRule, fileRef, Model, paramMessage, Union } from "@typespec/compiler"; import { createTCGCContext } from "../context.js"; import { isSdkBuiltInKind, @@ -13,6 +13,7 @@ import { handleAllTypes } from "../types.js"; export const noUnnamedTypesRule = createRule({ name: "no-unnamed-types", + docs: fileRef.fromPackageRoot("src/rules/no-unnamed-types.md"), description: "Requires types to be named rather than defined anonymously or inline.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/typespec-client-generator-core/rules/no-unnamed-types", diff --git a/website/src/content/docs/docs/libraries/typespec-client-generator-core/rules/property-name-conflict.md b/packages/typespec-client-generator-core/src/rules/property-name-conflict.md similarity index 79% rename from website/src/content/docs/docs/libraries/typespec-client-generator-core/rules/property-name-conflict.md rename to packages/typespec-client-generator-core/src/rules/property-name-conflict.md index 3cb3ed43bb..715edd812d 100644 --- a/website/src/content/docs/docs/libraries/typespec-client-generator-core/rules/property-name-conflict.md +++ b/packages/typespec-client-generator-core/src/rules/property-name-conflict.md @@ -1,11 +1,3 @@ ---- -title: property-name-conflict ---- - -```text title="Full name" -@azure-tools/typespec-client-generator-core/property-name-conflict -``` - A property whose name matches its enclosing model's name causes problems with some language emitters (notably C#), where the generated property would collide with the type name. Rename the property, or use `@clientName` to diff --git a/packages/typespec-client-generator-core/src/rules/property-name-conflict.rule.ts b/packages/typespec-client-generator-core/src/rules/property-name-conflict.rule.ts index bbd3031117..76e5ce24fb 100644 --- a/packages/typespec-client-generator-core/src/rules/property-name-conflict.rule.ts +++ b/packages/typespec-client-generator-core/src/rules/property-name-conflict.rule.ts @@ -1,9 +1,10 @@ -import { ModelProperty, createRule, paramMessage } from "@typespec/compiler"; +import { ModelProperty, createRule, fileRef, paramMessage } from "@typespec/compiler"; import { createTCGCContext } from "../context.js"; import { getLibraryName } from "../public-utils.js"; export const propertyNameConflictRule = createRule({ name: "property-name-conflict", + docs: fileRef.fromPackageRoot("src/rules/property-name-conflict.md"), description: "Avoid naming conflicts between a property and a model of the same name.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/typespec-client-generator-core/rules/property-name-conflict", diff --git a/website/src/content/docs/docs/libraries/typespec-client-generator-core/rules/require-client-suffix.md b/packages/typespec-client-generator-core/src/rules/require-client-suffix.md similarity index 81% rename from website/src/content/docs/docs/libraries/typespec-client-generator-core/rules/require-client-suffix.md rename to packages/typespec-client-generator-core/src/rules/require-client-suffix.md index 800ee4d0e6..51af9a8da2 100644 --- a/website/src/content/docs/docs/libraries/typespec-client-generator-core/rules/require-client-suffix.md +++ b/packages/typespec-client-generator-core/src/rules/require-client-suffix.md @@ -1,11 +1,3 @@ ---- -title: require-client-suffix ---- - -```text title="Full name" -@azure-tools/typespec-client-generator-core/require-client-suffix -``` - Top-level client names should end with the `Client` suffix. This convention makes it clear that a namespace or interface represents a generated SDK client and provides a consistent experience across emitted languages. diff --git a/packages/typespec-client-generator-core/src/rules/require-client-suffix.rule.ts b/packages/typespec-client-generator-core/src/rules/require-client-suffix.rule.ts index 004be75ad3..51e636c07f 100644 --- a/packages/typespec-client-generator-core/src/rules/require-client-suffix.rule.ts +++ b/packages/typespec-client-generator-core/src/rules/require-client-suffix.rule.ts @@ -1,9 +1,10 @@ -import { createRule, Interface, Namespace, paramMessage } from "@typespec/compiler"; +import { createRule, fileRef, Interface, Namespace, paramMessage } from "@typespec/compiler"; import { createTCGCContext } from "../context.js"; import { getClient } from "../decorators.js"; export const requireClientSuffixRule = createRule({ name: "require-client-suffix", + docs: fileRef.fromPackageRoot("src/rules/require-client-suffix.md"), description: "Client names should end with 'Client'.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/typespec-client-generator-core/rules/require-client-suffix", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index c879366e3a..398d5cd29f 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -1591,6 +1591,9 @@ importers: '@typespec/compiler': specifier: workspace:^ version: link:../compiler + '@typespec/events': + specifier: workspace:^ + version: link:../events '@typespec/http': specifier: workspace:^ version: link:../http @@ -1603,6 +1606,9 @@ importers: '@typespec/spector': specifier: workspace:^ version: link:../spector + '@typespec/sse': + specifier: workspace:^ + version: link:../sse '@typespec/versioning': specifier: workspace:^ version: link:../versioning diff --git a/website/astro.config.mjs b/website/astro.config.mjs index aa9c6fb8f8..5a07e7be25 100644 --- a/website/astro.config.mjs +++ b/website/astro.config.mjs @@ -25,6 +25,13 @@ const rawRedirects = { "/docs/howtos/arm/versioning/": `/docs/howtos/versioning/06-evolving-apis/`, "/docs/howtos/versioning/arm/uncommon-scenarios/01-converting-specs/": `/docs/howtos/versioning/uncommon-scenarios/01-converting-specs/`, "/docs/howtos/versioning/arm/uncommon-scenarios/02-perpetual-preview/": `/docs/howtos/versioning/uncommon-scenarios/02-perpetual-preview/`, + // Linter rule pages are now generated by tspd using the rule name. A few rules + // were historically documented under a different slug than their rule name. + "/docs/libraries/azure-core/rules/prevent-format/": `/docs/libraries/azure-core/rules/no-format/`, + "/docs/libraries/azure-resource-manager/rules/delete-operation-response-codes/": `/docs/libraries/azure-resource-manager/rules/arm-delete-operation-response-codes/`, + "/docs/libraries/azure-resource-manager/rules/post-operation-response-codes/": `/docs/libraries/azure-resource-manager/rules/arm-post-operation-response-codes/`, + "/docs/libraries/azure-resource-manager/rules/put-operation-response-codes/": `/docs/libraries/azure-resource-manager/rules/arm-put-operation-response-codes/`, + "/docs/libraries/azure-resource-manager/rules/resource-name-pattern/": `/docs/libraries/azure-resource-manager/rules/arm-resource-name-pattern/`, }; const normalizedRedirects = Object.fromEntries( diff --git a/website/src/content/docs/docs/howtos/contributing/creating-linter-rules.md b/website/src/content/docs/docs/howtos/contributing/creating-linter-rules.md index ceb0fc3364..42c7714d1a 100644 --- a/website/src/content/docs/docs/howtos/contributing/creating-linter-rules.md +++ b/website/src/content/docs/docs/howtos/contributing/creating-linter-rules.md @@ -35,7 +35,7 @@ A complete rule usually touches **7+ files across 3+ packages**: 2. Linter registration in `packages//src/linter.ts` 3. Tests in `packages//test/rules/.test.ts` 4. Ruleset registration in `packages/typespec-azure-rulesets` -5. Rule documentation in `website/src/content/docs/docs/libraries//rules/` +5. Rule documentation in `packages//src/rules/.md` (referenced from the rule via `docs`) 6. Regenerated reference docs 7. A changeset in `.chronus/changes/` @@ -123,7 +123,7 @@ Concretely, expect changes like: - `packages//src/rules/.ts` - `packages//test/rules/.test.ts` -- `website/src/content/docs/docs/libraries//rules/.md` +- `packages//src/rules/.md` - `packages//src/linter.ts` ### Step 3: Write Tests First (TDD) @@ -238,6 +238,7 @@ import { Namespace, createRule, defineCodeFix, + fileRef, getService, getSourceLocation, paramMessage, @@ -262,6 +263,7 @@ export const myNewRule = createRule({ description: "Require a specific Azure shape.", severity: "warning", url: "https://azure.github.io/typespec-azure/docs/libraries/azure-core/rules/my-new-rule", + docs: fileRef.fromPackageRoot("src/rules/my-new-rule.md"), messages: { default: "This type violates the rule.", withName: paramMessage`Property '${"propertyName"}' must meet the Azure guideline.`, @@ -392,29 +394,26 @@ pnpm --filter "@azure-tools/typespec-azure-rulesets..." test ### Step 7: Write Documentation -Each rule needs its own rule page: +Each rule's extended documentation lives in a markdown file next to the rule +implementation and is referenced from the rule via the `docs` field +(`docs: fileRef.fromPackageRoot("src/rules/.md")`): -- `website/src/content/docs/docs/libraries//rules/.md` +- `packages//src/rules/.md` -That page should include: +`tspd` renders one reference page per rule at +`website/src/content/docs/docs/libraries//rules/.md`. +The generated page starts with the rule id and its `description`, followed by +the content of the `docs` markdown file. The `docs` file therefore contains only +the **extended** documentation (no frontmatter and no `Full name` code block — +those are generated): -- Frontmatter with a `title` -- A `Full name` code block -- A plain-language description +- A plain-language explanation - `#### ❌ Incorrect` examples - `#### ✅ Correct` examples -Example rule doc shape: +Example `docs` markdown (`packages//src/rules/my-new-rule.md`): ````markdown ---- -title: "my-new-rule" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/my-new-rule -``` - Brief description of the rule. #### ❌ Incorrect @@ -555,7 +554,8 @@ packages/ │ ├── src/ │ │ ├── linter.ts │ │ └── rules/ -│ │ └── .ts +│ │ ├── .ts +│ │ └── .md │ └── test/ │ ├── tester.ts │ └── rules/ @@ -564,7 +564,8 @@ packages/ │ ├── src/ │ │ ├── linter.ts │ │ └── rules/ -│ │ └── .ts +│ │ ├── .ts +│ │ └── .md │ └── test/ │ ├── test-host.ts │ └── rules/ @@ -573,7 +574,8 @@ packages/ │ ├── src/ │ │ ├── linter.ts │ │ └── rules/ -│ │ └── .ts +│ │ ├── .ts +│ │ └── .md │ └── test/ │ ├── tester.ts │ └── rules/ @@ -583,9 +585,7 @@ packages/ │ └── src/rulesets/resource-manager.ts website/ └── src/content/docs/docs/libraries/ - ├── azure-core/rules/.md - ├── azure-resource-manager/rules/.md - └── typespec-client-generator-core/rules/.md + └── /rules/.md # generated by `regen-docs` ``` ### Test Hosts diff --git a/website/src/content/docs/docs/libraries/azure-core/rules/no-order-by.md b/website/src/content/docs/docs/libraries/azure-core/rules/no-order-by.md deleted file mode 100644 index ab7270d6a0..0000000000 --- a/website/src/content/docs/docs/libraries/azure-core/rules/no-order-by.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -title: "no-order-by" ---- - -```text title="Full name" -@azure-tools/typespec-azure-core/no-order-by -``` - -List operations with an `orderBy` parameter are uncommon. Support should only be added after large collection sorting performance concerns are considered. - -:::note -This rule specifically targets `Azure.Core.ResourceList` operations. Standard operations using `orderBy` are not affected. -::: - -#### ❌ Incorrect - -Using `OrderByQueryParameter` in a `ResourceList`: - -```tsp -alias MyTraits = Azure.Core.Traits.QueryParametersTrait; - -op list is Azure.Core.ResourceList; -``` - -Inline `orderBy` query parameter in a `ResourceList`: - -```tsp -alias MyTraits = Azure.Core.Traits.QueryParametersTrait<{ - @query orderBy: string; -}>; - -op list is Azure.Core.ResourceList; -``` - -#### ✅ Correct - -`ResourceList` without `orderBy`: - -```tsp -op list is Azure.Core.ResourceList; -```