Add Transformer Library to TypeSpec Compiler Package

packages/compiler/src/config/config-schema.ts

@@ -103,5 +103,30 @@ export const TypeSpecConfigJsonSchema: JSONSchemaType<TypeSpecRawConfig> = {
         },
       },
     } as any, // ajv type system doesn't like the string templates
+    transformer: {
+      type: "object",
+      nullable: true,
+      required: [],
+      additionalProperties: false,
+      properties: {
+        extends: {
+          type: "array",
+          nullable: true,
+          items: { type: "string" },
+        },
+        enable: {
+          type: "object",
+          required: [],
+          nullable: true,
+          additionalProperties: { type: "boolean" },
+        },
+        disable: {
+          type: "object",
+          required: [],
+          nullable: true,
+          additionalProperties: { type: "string" },
+        },
+      },
+    } as any, // ajv type system doesn't like the string templates
   },
 };

packages/compiler/src/config/types.ts

@@ -1,4 +1,4 @@
-import type { Diagnostic, RuleRef } from "../core/types.js";
+import type { Diagnostic, RuleRef, TransformSetRef } from "../core/types.js";
 import type { YamlScript } from "../yaml/types.js";
 
 /**
@@ -69,6 +69,8 @@ export interface TypeSpecConfig {
   options?: Record<string, EmitterOptions>;
 
   linter?: LinterConfig;
+
+  transformer?: TransformerConfig;
 }
 
 /**
@@ -88,6 +90,7 @@ export interface TypeSpecRawConfig {
   options?: Record<string, EmitterOptions>;
 
   linter?: LinterConfig;
+  transformer?: TransformerConfig;
 }
 
 export interface ConfigEnvironmentVariable {
@@ -107,3 +110,9 @@ export interface LinterConfig {
   enable?: Record<RuleRef, boolean>;
   disable?: Record<RuleRef, string>;
 }
+
+export interface TransformerConfig {
+  extends?: TransformSetRef[];
+  enable?: Record<TransformSetRef, boolean>;
+  disable?: Record<TransformSetRef, string>;
+}

packages/compiler/src/core/library.ts

@@ -9,6 +9,8 @@ import {
   LinterRuleDefinition,
   PackageFlags,
   StateDef,
+  TransformDefinition,
+  TransformerDefinition,
   TypeSpecLibrary,
   TypeSpecLibraryDef,
 } from "./types.js";
@@ -116,6 +118,16 @@ export function createLinterRule<const N extends string, const T extends Diagnos
   return definition;
 }
 
+export function defineTransformer(def: TransformerDefinition): TransformerDefinition {
+  return def;
+}
+
+/** Create a new transform. */
+export function createTransform<const N extends string>(definition: TransformDefinition<N>) {
+  compilerAssert(!definition.name.includes("/"), "Transform name cannot contain a '/'.");
+  return definition;
+}
+
 /**
  * Set the TypeSpec namespace for that function.
  * @param namespace Namespace string (e.g. "Foo.Bar")

packages/compiler/src/core/messages.ts

@@ -761,6 +761,40 @@ const diagnostics = {
     },
   },
 
+  /**
+   * Transformer
+   */
+  "invalid-transform-ref": {
+    severity: "error",
+    messages: {
+      default: paramMessage`Reference "${"ref"}" is not a valid reference to a transform or transform set. It must be in the following format: "<library-name>/<transform-name>"`,
+    },
+  },
+  "unknown-transform": {
+    severity: "warning",
+    messages: {
+      default: paramMessage`Transform "${"transformName"}" is not found in library "${"libraryName"}"`,
+    },
+  },
+  "unknown-transform-set": {
+    severity: "warning",
+    messages: {
+      default: paramMessage`Transform set "${"transformSetName"}" is not found in library "${"libraryName"}"`,
+    },
+  },
+  "transform-enabled-disabled": {
+    severity: "warning",
+    messages: {
+      default: paramMessage`Transform "${"transformName"}" has been enabled and disabled in the same transform set.`,
+    },
+  },
+  "transform-engine-error": {
+    severity: "error",
+    messages: {
+      default: paramMessage`Failed to create mutation engine for transform "${"transformId"}": ${"error"}`,
+    },
+  },
+
   /**
    * Formatter
    */

packages/compiler/src/core/options.ts

@@ -1,5 +1,5 @@
 import { EmitterOptions, TypeSpecConfig } from "../config/types.js";
-import { LinterRuleSet, ParseOptions } from "./types.js";
+import { LinterRuleSet, ParseOptions, TransformSet } from "./types.js";
 
 export interface CompilerOptions {
   miscOptions?: Record<string, unknown>;
@@ -68,6 +68,9 @@ export interface CompilerOptions {
   /** Ruleset to enable for linting. */
   linterRuleSet?: LinterRuleSet;
 
+  /** Transform set to enable for transformation. */
+  transformSet?: TransformSet;
+
   /** @internal */
   readonly configFile?: TypeSpecConfig;
 }

packages/compiler/src/core/program.ts

@@ -43,6 +43,12 @@ import {
 } from "./source-loader.js";
 import { createStateAccessors } from "./state-accessors.js";
 import { ComplexityStats, RuntimeStats, Stats, startTimer, time, timeAsync } from "./stats.js";
+import {
+  builtInTransformerLibraryName,
+  createBuiltInTransformerLibrary,
+  createTransformer,
+  resolveTransformerDefinition,
+} from "./transformer.js";
 import {
   CompilerHost,
   Diagnostic,
@@ -52,8 +58,8 @@ import {
   EmitterFunc,
   Entity,
   JsSourceFileNode,
-  LibraryInstance,
   LibraryMetadata,
+  LinterLibraryInstance,
   LiteralType,
   LocationContext,
   LogSink,
@@ -68,6 +74,7 @@ import {
   SyntaxKind,
   TemplateInstanceTarget,
   Tracer,
+  TransformerLibraryInstance,
   Type,
   TypeSpecLibrary,
   TypeSpecScriptNode,
@@ -136,13 +143,20 @@ export interface Program {
   readonly projectRoot: string;
 }
 
+export interface TransformedProgram extends Program {
+  /**
+   * Result from running transformers, including mutation engines for accessing transformed types.
+   */
+  readonly transformerResult?: import("./transformer.js").TransformerResult;
+}
+
 interface EmitterRef {
   emitFunction: EmitterFunc;
   main: string;
   metadata: LibraryMetadata;
   emitterOutputDir: string;
   options: Record<string, unknown>;
-  readonly library: LibraryInstance;
+  readonly library: LinterLibraryInstance & TransformerLibraryInstance;
 }
 
 interface Validator {
@@ -207,7 +221,7 @@ async function createProgram(
   mainFile: string,
   options: CompilerOptions = {},
   oldProgram?: Program,
-): Promise<{ program: Program; shouldAbort: boolean }> {
+): Promise<{ program: TransformedProgram; shouldAbort: boolean }> {
   const runtimeStats: Partial<RuntimeStats> = {};
   const validateCbs: Validator[] = [];
   const stateMaps = new Map<symbol, Map<Type, unknown>>();
@@ -303,6 +317,16 @@ async function createProgram(
     program.reportDiagnostics(await linter.extendRuleSet(options.linterRuleSet));
   }
 
+  const transformer = createTransformer(program, (name) => loadLibrary(basedir, name));
+  // Register built-in transformer library (currently empty placeholder)
+  transformer.registerTransformLibrary(
+    builtInTransformerLibraryName,
+    createBuiltInTransformerLibrary(),
+  );
+  if (options.transformSet) {
+    program.reportDiagnostics(await transformer.extendTransformSet(options.transformSet));
+  }
+
   program.checker = createChecker(program, resolver);
   runtimeStats.checker = time(() => program.checker.checkProgram());
 
@@ -329,7 +353,17 @@ async function createProgram(
   runtimeStats.linter = lintResult.stats.runtime;
   program.reportDiagnostics(lintResult.diagnostics);
 
-  return { program, shouldAbort: false };
+  // Transform stage
+  const transformResult = transformer.transform();
+  runtimeStats.transformer = transformResult.stats.runtime;
+  program.reportDiagnostics(transformResult.diagnostics);
+
+  // Attach transformer result to the program so consumers can access mutation engines
+  const transformedProgram: TransformedProgram = Object.assign(transformResult.program, {
+    transformerResult: transformResult,
+  });
+
+  return { program: transformedProgram, shouldAbort: false };
 
   /**
    * Validate the libraries loaded during the compilation process are compatible.
@@ -507,7 +541,7 @@ async function createProgram(
   async function loadLibrary(
     basedir: string,
     libraryNameOrPath: string,
-  ): Promise<LibraryInstance | undefined> {
+  ): Promise<(LinterLibraryInstance & TransformerLibraryInstance) | undefined> {
     const [resolution, diagnostics] = await resolveEmitterModuleAndEntrypoint(
       basedir,
       libraryNameOrPath,
@@ -522,11 +556,14 @@ async function createProgram(
     const libDefinition: TypeSpecLibrary<any> | undefined = entrypoint?.esmExports.$lib;
     const metadata = computeLibraryMetadata(module, libDefinition);
     const linterDef = entrypoint?.esmExports.$linter;
+    const transformerDef = entrypoint?.esmExports.$transformer;
     return {
       ...resolution,
       metadata,
       definition: libDefinition,
       linter: linterDef && resolveLinterDefinition(libraryNameOrPath, linterDef),
+      transformer:
+        transformerDef && resolveTransformerDefinition(libraryNameOrPath, transformerDef),
     };
   }
 

packages/compiler/src/core/stats.ts

@@ -25,6 +25,13 @@ export interface RuntimeStats {
       [rule: string]: number;
     };
   };
+  transformer: {
+    enabledTransforms: readonly string[];
+    total: number;
+    engineCreation: {
+      [transformId: string]: number;
+    };
+  };
   emit: {
     total: number;
     emitters: {