Merge branch 'main' into bug/escape-characters-in-docblock

.chronus/changes/json-schema-reftype-fix-2024-4-23-16-41-33.md

@@ -0,0 +1,7 @@
+---
+changeKind: fix
+packages:
+  - "@typespec/json-schema"
+---
+
+The emitted JSON Schema now doesn't make root schemas for TypeSpec types which do not have the @jsonSchema decorator or are contained in a namespace with that decorator. Instead, such schemas are put into the $defs of any root schema which references them, and are referenced using JSON Pointers.

.chronus/changes/playground-storybook-2024-4-22-18-10-6.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: internal
+packages:
+  - "@typespec/playground"
+---
+
+Add storybook for playground library

.chronus/changes/versioning-library-cleanup-2024-4-9-22-35-15.md

@@ -0,0 +1,8 @@
+---
+# Change versionKind to one of: internal, fix, dependencies, feature, deprecation, breaking
+changeKind: internal
+packages:
+  - "@typespec/versioning"
+---
+
+Organize versioning library

.devcontainer/Dockerfile

@@ -0,0 +1,4 @@
+FROM mcr.microsoft.com/devcontainers/javascript-node:20
+
+RUN corepack enable pnpm && \
+  echo 'alias pnpm="corepack pnpm"' >> /home/node/.bash_aliases

.devcontainer/devcontainer.json

@@ -0,0 +1,18 @@
+{
+  "name": "Standard",
+  "build": {
+    "dockerfile": "Dockerfile"
+  },
+  "customizations": {
+    // Configure properties specific to VS Code.
+    "vscode": {
+      // Add the IDs of extensions you want installed when the container is created.
+      "extensions": [
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "streetsidesoftware.code-spell-checker",
+        "vitest.explorer"
+      ]
+    }
+  }
+}

.github/policies/issues.needs-info.yml

@@ -15,8 +15,6 @@ configuration:
         filters:
           - isIssue
           - isOpen
-          - hasLabel:
-              label: No-Recent-Activity
           - hasLabel:
               label: needs-info
           - noActivitySince:

.npmrc

@@ -1 +1,2 @@
 auto-install-peers=true
+package-manager-strict=false

.prettierignore

@@ -6,8 +6,6 @@
 **/obj/
 **/.vs/
 **/.docusaurus/
-common/temp/
-common/scripts/
 .chronus/changes/
 
 # Pnpm lock file

CONTRIBUTING.md

@@ -297,17 +297,6 @@ TypeSpec repo use labels to help categorize and manage issues and PRs. The follo
 
 ### Labels reference
 
-#### issue_kinds
-
-Issue kinds
-
-| Name      | Color   | Description                                |
-| --------- | ------- | ------------------------------------------ |
-| `bug`     | #d93f0b | Something isn't working                    |
-| `feature` | #cccccc | New feature or request                     |
-| `docs`    | #cccccc | Improvements or additions to documentation |
-| `epic`    | #cccccc |                                            |
-
 #### area
 
 Area of the codebase
@@ -332,6 +321,17 @@ Area of the codebase
 | `emitter:service:js`         | #967200 |                                       |
 | `eng`                        | #65bfff |                                       |
 
+#### issue_kinds
+
+Issue kinds
+
+| Name      | Color   | Description                                |
+| --------- | ------- | ------------------------------------------ |
+| `bug`     | #d93f0b | Something isn't working                    |
+| `feature` | #cccccc | New feature or request                     |
+| `docs`    | #cccccc | Improvements or additions to documentation |
+| `epic`    | #cccccc |                                            |
+
 #### breaking-change
 
 Labels around annotating issues and PR if they contain breaking change or deprecation

cspell.yaml

@@ -26,18 +26,21 @@ words:
   - createsorreplacesresource
   - createsorupdatesresource
   - CRUDL
+  - dbaeumer
   - debouncer
   - devdiv
   - dogfood
   - eastus
   - ecmarkup
+  - esbenp
   - esbuild
   - espt
   - ESRP
   - fluentui
   - genproto
   - globby
   - Infima
+  - inlines
   - inmemory
   - instanceid
   - interner

docker/Dockerfile

@@ -8,7 +8,7 @@ COPY . /app
 
 WORKDIR /app
 ENV TYPESPEC_SKIP_VS_BUILD=1
-RUN npm install -g pnpm@8.13.1
+RUN corepack enable && corepack prepare
 RUN pnpm install --frozen-lockfile
 RUN pnpm --filter "@typespec/compiler..." run build
 

docs/emitters/json-schema/guide.md

@@ -0,0 +1,37 @@
+---
+title: Guide
+---
+
+# JSON Schema files and references
+
+When a TypeSpec data type has the `@jsonSchema` decorator or is declared inside a namespace with that decorator, it is considered a _JSON Schema type_.
+
+By default, this emitter will produce one JSON Schema file per JSON Schema type. The file defines an `$id` metadata keyword based on the TypeSpec type name and the file format of the schema (for example, `Widget.yaml`). The `$id` can be overridden by using the `@id` decorator.
+
+:::note
+The base URI of a schema is the reference point for resolving relative URIs within the schema, such as those inside `$ref`s. When the `$id` metadata keyword of a schema is an absolute URI, the `$id` is the base URI. When the `$id` is a relative reference, then the base URI is determined by resolving the relative reference against the URI used to retrieve the schema.
+
+The default behavior of this emitter for a model named `Widget` is to produce a schema with a `$id` of `Widget.yaml`, which allows the actual base URI of the document to differ depending on where it is retrieved from, and therefore should allow resolving relative references to other schemas whether loaded from disk or retrieved over HTTP.
+:::
+
+When JSON Schema types reference other JSON Schema types, those references are created using a `$ref` with a relative reference (see the note above for how this works in JSON Schema).
+
+How this emitter handles data types which aren't JSON Schema types can be controlled using the `emitAllModels` and `emitAllRefs` options.
+
+By default, this emitter does not define schemas for such data types. Instead, the schemas for them are placed in the `$defs` of any JSON Schema types that reference them. The schemas do not define either `$id` or `$schema` metadata keywords. The `$defs` are referenced using a `$ref` with URI fragment containing a JSON Pointer, which uses the syntax of the following form:
+
+```json
+{ "$ref": "#/$defs/{TypeNameHere}" }
+```
+
+If you want to treat all TypeSpec types as JSON Schema types (even if they don't have the `@jsonSchema` decorator), you can set the `emitAllModels` option to true. With this set, every data type in your TypeSpec program will get its own schema file, and all references will be relative URIs.
+
+If you want to treat all TypeSpec types referenced from JSON Schema types as JSON Schema types (even if they don't have the `@jsonSchema` decorator), you can set the `emitAllRefs` option to true. With this set, data types which are referenced from JSON Schema types will get their own schema file, and all references to them will be relative URIs.
+
+## Bundling behavior
+
+By default, this emitter will produce separate schema files for each JSON Schema type in your program. However, if you prefer to bundle all of your schemas into a single file, you can set the `bundleId` option to the id you want to use for your bundle. You will now get a single file containing all of your schemas.
+
+Note that bundling does not affect any references within the bundled schemas. In particular, references between JSON Schema types still use relative URIs. As such, correctly resolving these references to the local file requires JSON Schema implementations to support bundling as defined in the JSON Schema 2020-12 specification.
+
+Note also that this does not affect the behavior of non-JSON Schema data types. In particular, by default, non-JSON Schema data types are inlined into each referencing schema's `$defs` object. The `emitAllModels` and `emitAllRefs` options can be used to turn these inlined `$defs` into `$defs` in the bundle.

eng/common/config/labels.ts

@@ -1,4 +1,6 @@
 // cspell:ignore bfff
+import { repo } from "../scripts/common.js";
+import { defineConfig, defineLabels } from "../scripts/labels/config.js";
 
 /**
  * Labels that are used to categorize issue for which area they belong to.
@@ -74,10 +76,10 @@ export const AreaLabels = defineLabels({
   },
 });
 
-export default {
+export const CommonLabels = {
   issue_kinds: {
     description: "Issue kinds",
-    labels: {
+    labels: defineLabels({
       bug: {
         color: "d93f0b",
         description: "Something isn't working",
@@ -94,11 +96,7 @@ export default {
         color: "cccccc",
         description: "",
       },
-    },
-  },
-  area: {
-    description: "Area of the codebase",
-    labels: AreaLabels,
+    }),
   },
   "breaking-change": {
     description:
@@ -150,23 +148,52 @@ export default {
       },
     },
   },
-  misc: {
-    description: "Misc labels",
-    labels: {
-      "Client Emitter Migration": {
-        color: "FD92F0",
-        description: "",
-      },
-      "good first issue": {
-        color: "7057ff",
-        description: "Good for newcomers",
+};
+
+/**
+ * Set the paths that each area applies to.
+ */
+export const AreaPaths: Record<keyof typeof AreaLabels, string[]> = {
+  "compiler:core": ["packages/compiler/"],
+  "compiler:emitter-framework": [],
+  ide: ["packages/typespec-vscode/", "packages/typespec-vs/"],
+  "lib:http": ["packages/http/"],
+  "lib:openapi": ["packages/openapi/"],
+  "lib:rest": ["packages/rest/"],
+  "lib:versioning": ["packages/versioning/"],
+  "meta:blog": ["blog/"],
+  "meta:website": ["website/"],
+  tspd: ["packages/tspd/"],
+  "emitter:client:csharp": ["packages/http-client-csharp/"],
+  "emitter:json-schema": ["packages/json-schema/"],
+  "emitter:protobuf": ["packages/protobuf/"],
+  "emitter:openapi3": ["packages/openapi3/"],
+  "emitter:service:csharp": [],
+  "emitter:service:js": [],
+  eng: ["eng/", ".github/"],
+};
+
+export default defineConfig({
+  repo,
+  labels: {
+    area: {
+      description: "Area of the codebase",
+      labels: AreaLabels,
+    },
+    ...CommonLabels,
+    misc: {
+      description: "Misc labels",
+      labels: {
+        "Client Emitter Migration": {
+          color: "FD92F0",
+          description: "",
+        },
+        "good first issue": {
+          color: "7057ff",
+          description: "Good for newcomers",
+        },
       },
     },
   },
-} as const;
-
-function defineLabels<const T extends string>(
-  labels: Record<T, { color: string; description: string }>
-) {
-  return labels;
-}
+  areaPaths: AreaPaths,
+});