Create a new @typespec-autorest-canonical emitter (#351)

Create a new emitter to generate canonical version swagger file. This
emitter works similar to the @typespec-autorest emitter, but it will
generate canonical swagger file instead of versioned swagger files.

---------

Co-authored-by: Mark Cowlishaw <[email protected]>

.chronus/changes/add_new_emitter_autorest-canonical-2024-3-5-11-26-18.md

@@ -0,0 +1,7 @@
+---
+changeKind: internal
+packages:
+  - "@azure-tools/typespec-autorest-canonical"
+---
+
+add new emitter typespec-autorest-canonical

docs/emitters/typespec-autorest-canonical/reference/emitter.md

@@ -0,0 +1,68 @@
+---
+title: "Emitter usage"
+toc_min_heading_level: 2
+toc_max_heading_level: 3
+---
+
+# Emitter
+
+## Usage
+
+1. Via the command line
+
+```bash
+tsp compile . --emit=@azure-tools/typespec-autorest-canonical
+```
+
+2. Via the config
+
+```yaml
+emit:
+  - "@azure-tools/typespec-autorest-canonical"
+```
+
+## Emitter options
+
+### `output-file`
+
+**Type:** `string`
+
+Name of the output file.
+Output file will interpolate the following values:
+
+- service-name: Name of the service if multiple
+- azure-resource-provider-folder: Value of the azure-resource-provider-folder option
+
+Default: `{azure-resource-provider-folder}/{service-name}/{version}/openapi.json`
+
+Example: Single service
+
+- `canonical.openapi.json`
+
+Example: Multiple services
+
+- `Service1.canonical.openapi.json`
+- `Service2.canonical.openapi.json`
+
+### `azure-resource-provider-folder`
+
+**Type:** `string`
+
+### `new-line`
+
+**Type:** `"crlf" | "lf"`
+
+Set the newline character for emitting files.
+
+### `omit-unreachable-types`
+
+**Type:** `boolean`
+
+Omit unreachable types. By default all types declared under the service namespace will be included. With this flag on only types references in an operation will be emitted.
+
+### `include-x-typespec-name`
+
+**Type:** `"inline-only" | "never"`
+
+If the generated openapi types should have the `x-typespec-name` extension set with the name of the TypeSpec type that created it.
+This extension is meant for debugging and should not be depended on.

docs/emitters/typespec-autorest-canonical/reference/index.mdx

@@ -0,0 +1,36 @@
+---
+title: Overview
+sidebar_position: 0
+toc_min_heading_level: 2
+toc_max_heading_level: 3
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+
+# Overview
+
+TypeSpec library for emitting canonical swagger
+
+## Install
+
+<Tabs>
+<TabItem value="spec" label="In a spec" default>
+
+```bash
+npm install @azure-tools/typespec-autorest-canonical
+```
+
+</TabItem>
+<TabItem value="library" label="In a library" default>
+
+```bash
+npm install --save-peer @azure-tools/typespec-autorest-canonical
+```
+
+</TabItem>
+</Tabs>
+
+## Emitter usage
+
+[See documentation](./emitter.md)

packages/typespec-autorest-canonical/.eslintrc.cjs

@@ -0,0 +1,7 @@
+require("@typespec/eslint-config-typespec/patch/modern-module-resolution");
+
+module.exports = {
+  plugins: ["@typespec/eslint-plugin"],
+  extends: ["@typespec/eslint-config-typespec", "plugin:@typespec/eslint-plugin/recommended"],
+  parserOptions: { tsconfigRootDir: __dirname, project: "tsconfig.config.json" },
+};

packages/typespec-autorest-canonical/.scripts/schema-json-to-js.js

@@ -0,0 +1,21 @@
+// @ts-check
+
+import { readFile, writeFile } from "fs/promises";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+const jsonFilename = resolve(__dirname, "../schema/dist/schema.json");
+const jsFilename = resolve(__dirname, "../schema/dist/schema.js");
+console.log("Reading json schema at:", jsonFilename);
+const content = await readFile(jsonFilename);
+
+const json = JSON.parse(content.toString());
+
+const jsContent = `
+const schema = ${JSON.stringify(json)};
+export default schema;
+`;
+console.log("Writing json schema in js file:", jsonFilename);
+await writeFile(jsFilename, jsContent);

packages/typespec-autorest-canonical/LICENSE

@@ -0,0 +1,21 @@
+    MIT License
+
+    Copyright (c) Microsoft Corporation. All rights reserved.
+
+    Permission is hereby granted, free of charge, to any person obtaining a copy
+    of this software and associated documentation files (the "Software"), to deal
+    in the Software without restriction, including without limitation the rights
+    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+    copies of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be included in all
+    copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+    OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+    SOFTWARE

packages/typespec-autorest-canonical/README.md

@@ -0,0 +1,72 @@
+# @azure-tools/typespec-autorest-canonical
+
+TypeSpec library for emitting canonical swagger
+
+## Install
+
+```bash
+npm install @azure-tools/typespec-autorest-canonical
+```
+
+## Emitter
+
+### Usage
+
+1. Via the command line
+
+```bash
+tsp compile . --emit=@azure-tools/typespec-autorest-canonical
+```
+
+2. Via the config
+
+```yaml
+emit:
+  - "@azure-tools/typespec-autorest-canonical"
+```
+
+### Emitter options
+
+#### `output-file`
+
+**Type:** `string`
+
+Name of the output file.
+Output file will interpolate the following values:
+
+- service-name: Name of the service if multiple
+- azure-resource-provider-folder: Value of the azure-resource-provider-folder option
+
+Default: `{azure-resource-provider-folder}/{service-name}/{version}/openapi.json`
+
+Example: Single service
+
+- `canonical.openapi.json`
+
+Example: Multiple services
+
+- `Service1.canonical.openapi.json`
+- `Service2.canonical.openapi.json`
+
+#### `azure-resource-provider-folder`
+
+**Type:** `string`
+
+#### `new-line`
+
+**Type:** `"crlf" | "lf"`
+
+Set the newline character for emitting files.
+
+#### `omit-unreachable-types`
+
+**Type:** `boolean`
+
+Omit unreachable types. By default all types declared under the service namespace will be included. With this flag on only types references in an operation will be emitted.
+
+#### `include-x-typespec-name`
+
+**Type:** `"inline-only" | "never"`
+
+If the generated openapi types should have the `x-typespec-name` extension set with the name of the TypeSpec type that created it.
+This extension is meant for debugging and should not be depended on.

packages/typespec-autorest-canonical/lib/autorest-canonical.tsp

@@ -0,0 +1 @@
+import "../dist/src/index.js";

packages/typespec-autorest-canonical/package.json

@@ -0,0 +1,84 @@
+{
+  "name": "@azure-tools/typespec-autorest-canonical",
+  "version": "0.1.0",
+  "author": "Microsoft Corporation",
+  "description": "TypeSpec library for emitting canonical swagger",
+  "homepage": "https://azure.github.io/typespec-azure",
+  "readme": "https://github.com/Azure/typespec-azure/blob/main/README.md",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Azure/typespec-azure.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Azure/typespec-azure/issues"
+  },
+  "keywords": [
+    "typespec",
+    "autorestcanonical"
+  ],
+  "type": "module",
+  "main": "dist/src/index.js",
+  "tspMain": "lib/autorest-canonical.tsp",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./testing": {
+      "types": "./dist/src/testing/index.d.ts",
+      "default": "./dist/src/testing/index.js"
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "clean": "rimraf ./dist ./temp",
+    "build": "npm run regen-autorest-canonical-openapi-schema && tsc -p . && npm run lint-typespec-library",
+    "watch": "tsc -p . --watch",
+    "lint-typespec-library": "tsp compile . --warn-as-error --import @typespec/library-linter --no-emit",
+    "regen-autorest-canonical-openapi-schema": "tsp compile ./schema/autorest-canonical-openapi-schema.tsp --warn-as-error && node ./.scripts/schema-json-to-js.js",
+    "test": "vitest run",
+    "test:watch": "vitest -w",
+    "test:ui": "vitest --ui",
+    "test-official": "vitest run --coverage --reporter=junit --reporter=default --no-file-parallelism",
+    "lint": "eslint . --ext .ts --max-warnings=0",
+    "lint:fix": "eslint . --fix --ext .ts",
+    "regen-docs": "tspd doc .  --enable-experimental  --output-dir ../../docs/emitters/typespec-autorest-canonical/reference"
+  },
+  "files": [
+    "lib/*.tsp",
+    "schema/dist/schema.js",
+    "dist/**",
+    "!dist/test/**"
+  ],
+  "peerDependencies": {
+    "@azure-tools/typespec-azure-core": "workspace:~",
+    "@azure-tools/typespec-client-generator-core": "workspace:~",
+    "@typespec/versioning": "workspace:~"
+  },
+  "devDependencies": {
+    "@azure-tools/typespec-azure-core": "workspace:~",
+    "@azure-tools/typespec-client-generator-core": "workspace:~",
+    "@types/node": "~18.11.19",
+    "@typespec/compiler": "workspace:~",
+    "@typespec/eslint-config-typespec": "workspace:~",
+    "@typespec/eslint-plugin": "workspace:~",
+    "@typespec/http": "workspace:~",
+    "@typespec/json-schema": "workspace:~",
+    "@typespec/library-linter": "workspace:~",
+    "@typespec/openapi": "workspace:~",
+    "@typespec/rest": "workspace:~",
+    "@typespec/tspd": "workspace:~",
+    "@typespec/versioning": "workspace:~",
+    "@vitest/coverage-v8": "^1.4.0",
+    "@vitest/ui": "^1.4.0",
+    "c8": "^9.1.0",
+    "change-case": "~5.4.3",
+    "eslint": "^8.57.0",
+    "rimraf": "~5.0.5",
+    "typescript": "~5.4.2",
+    "vitest": "^1.4.0"
+  }
+}

packages/typespec-autorest-canonical/schema/.gitignore

@@ -0,0 +1 @@
+out/