Bundle things outside JSON Schema namespace by default (microsoft#2085)

I think it's somewhat unexpected that you might get schemas for types
outside of a JSON Schema namespace merely because they are referenced.
With this PR, by default we will not emit schemas for such types, and
instead bundle them into the referencing schema. As a result, you will
only get schemas for things you have explicitly annotated with
`@jsonSchema`, either on the declaration or on its containing namespace.

For example:

```
@jsonschema 
model Pet { toy: Toy }
model Toy { }
```

will emit a single schema - `Pet.json`, with a `$defs` with Toy.

In order to restore the old behavior, you can pass `emitAllRefs`. This
is technically a breaking change, but I don't expect this is a common
scenario.

It's worth thinking about the behavior here when you are importing a
library of interesting types that you actually WANT to emit as json
schema. There are a few options:

* Pass the `emitAllRefs` option.
* Model-is the things you want into your JSON Schema namespace.
* Use augment decorators on the library's namespace.
* Ask the library to add the necessary JSON Schema metadata.

The latter three options seem like actually good options since it allows
you to provide the namespace/base URI of the schemas, which is
considered a best practice.

In order to implement this change, a new `TypeEmitter` member is
required - `writeOutput` - which lets you customize how you write assets
to disk. For this PR, it is used to skip emitting source files that we
don't actually need on disk. Another scenario this gets used for is when
an emitter composes another emitter and needs to write that emitters
output when its own output is needed. An example is a JSON-RPC emitter
that has an internal JSON Schema emitter and needs to write JSON Schema
to disk.

Additionally, `meta` properties were added to declarations and source
files to allow for arbitrary metadata to be added. This is far more
convenient than establishing maps to maintain this metadata yourself in
your emitter, although at the cost of type safety.

Fixes microsoft#2022

---------

Co-authored-by: Timothee Guerin <tiguerin@microsoft.com>

Author: bterlson

common/changes/@typespec/compiler/json-schema-bundle2_2023-06-16-21-24.json

@@ -0,0 +1,15 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "Emitter Framework: TypeEmitter can now implement `writeOutput` to customize how to write source files to disk.",
+      "type": "none"
+    },
+    {
+      "packageName": "@typespec/compiler",
+      "comment": "Emitter Framework: Source Files and Declarations have a new property `meta` which can store arbitrary metadata about those entities.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/compiler"
+}

common/changes/@typespec/json-schema/json-schema-bundle2_2023-06-16-21-24.json

@@ -0,0 +1,10 @@
+{
+  "changes": [
+    {
+      "packageName": "@typespec/json-schema",
+      "comment": "By default, types that are not marked with @jsonSchema or are within a namespace with @jsonSchema are bundled into the schemas that reference them. Set the `emitAllRefs` option to true to get the previous behavior of emitting all types referenced as JSON Schema.",
+      "type": "none"
+    }
+  ],
+  "packageName": "@typespec/json-schema"
+}

packages/compiler/src/emitter-framework/asset-emitter.ts

@@ -1,7 +1,6 @@
 import {
   compilerAssert,
   EmitContext,
-  emitFile,
   IntrinsicType,
   isTemplateDeclaration,
   joinPaths,
@@ -107,6 +106,7 @@ export function createAssetEmitter<T, TOptions extends object>(
   let programContext: ContextState | null = null;
   let incomingReferenceContext: Record<string, string> | null = null;
   const interner = createInterner();
+
   const assetEmitter: AssetEmitter<T, TOptions> = {
     getContext() {
       return {
@@ -172,6 +172,7 @@ export function createAssetEmitter<T, TOptions extends object>(
         globalScope: undefined as any,
         path: joinPaths(basePath, path),
         imports: new Map(),
+        meta: {},
       };
       sourceFile.globalScope = this.createScope(sourceFile, "");
       sourceFiles.push(sourceFile);
@@ -292,13 +293,7 @@ export function createAssetEmitter<T, TOptions extends object>(
     },
 
     async writeOutput() {
-      for (const file of sourceFiles) {
-        const outputFile = typeEmitter.sourceFile(file);
-        await emitFile(program, {
-          path: outputFile.path,
-          content: outputFile.contents,
-        });
-      }
+      return typeEmitter.writeOutput(sourceFiles);
     },
 
     emitType(type) {
@@ -425,6 +420,10 @@ export function createAssetEmitter<T, TOptions extends object>(
     emitTupleLiteralValues(tuple) {
       return invokeTypeEmitter("tupleLiteralValues", tuple);
     },
+
+    emitSourceFile(sourceFile) {
+      return typeEmitter.sourceFile(sourceFile);
+    },
   };
 
   const typeEmitter = new TypeEmitterClass(assetEmitter);
@@ -445,6 +444,7 @@ export function createAssetEmitter<T, TOptions extends object>(
       | "declarationName"
       | "reference"
       | "emitValue"
+      | "writeOutput"
       | EndingWith<keyof TypeEmitter<T, TOptions>, "Context">
     >
   >(method: TMethod, ...args: Parameters<TypeEmitter<T, TOptions>[TMethod]>): EmitEntity<T> {

packages/compiler/src/emitter-framework/type-emitter.ts

@@ -1,6 +1,7 @@
 import {
   BooleanLiteral,
   compilerAssert,
+  emitFile,
   Enum,
   EnumMember,
   Interface,
@@ -633,6 +634,16 @@ export class TypeEmitter<T, TOptions extends object = Record<string, never>> {
     return emittedSourceFile;
   }
 
+  async writeOutput(sourceFiles: SourceFile<T>[]) {
+    for (const file of sourceFiles) {
+      const outputFile = this.emitter.emitSourceFile(file);
+      await emitFile(this.emitter.getProgram(), {
+        path: outputFile.path,
+        content: outputFile.contents,
+      });
+    }
+  }
+
   reference(
     targetDeclaration: Declaration<T>,
     pathUp: Scope<T>[],

packages/compiler/src/emitter-framework/types.ts

@@ -39,7 +39,7 @@ export interface AssetEmitter<T, TOptions extends object = Record<string, unknow
   emitEnumMembers(en: Enum): EmitEntity<T>;
   emitUnionVariants(union: Union): EmitEntity<T>;
   emitTupleLiteralValues(tuple: Tuple): EmitEntity<T>;
-
+  emitSourceFile(sourceFile: SourceFile<T>): EmittedSourceFile;
   /**
    * Create a source file.
    *
@@ -86,6 +86,7 @@ export interface SourceFile<T> {
   path: string;
   globalScope: Scope<T>;
   imports: Map<string, string[]>;
+  meta: Record<string, any>;
 }
 
 export interface EmittedSourceFile {
@@ -98,6 +99,7 @@ export type EmitEntity<T> = Declaration<T> | RawCode<T> | NoEmit | CircularEmit;
 export class EmitterResult {}
 export class Declaration<T> extends EmitterResult {
   public kind = "declaration" as const;
+  public meta: Record<string, any> = {};
 
   constructor(public name: string, public scope: Scope<T>, public value: T | Placeholder<T>) {
     if (value instanceof Placeholder) {

packages/json-schema/src/index.ts

@@ -74,10 +74,27 @@ export function findBaseUri(
   return baseUrl;
 }
 
+export function isJsonSchemaDeclaration(program: Program, target: JsonSchemaDeclaration) {
+  let current: JsonSchemaDeclaration | Namespace | undefined = target;
+  do {
+    if (getJsonSchema(program, current)) {
+      return true;
+    }
+
+    current = current.namespace;
+  } while (current);
+
+  return false;
+}
+
 export function getJsonSchemaTypes(program: Program): (Namespace | Model)[] {
   return [...(program.stateSet(jsonSchemaKey) || [])] as (Namespace | Model)[];
 }
 
+export function getJsonSchema(program: Program, target: Type) {
+  return program.stateSet(jsonSchemaKey).has(target);
+}
+
 const multipleOfKey = createStateSymbol("JsonSchema.multipleOf");
 export function $multipleOf(context: DecoratorContext, target: Model, value: number) {
   context.program.stateMap(multipleOfKey).set(target, value);