Proof of concept for Transformers

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

@@ -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?: RuleRef[];
+  enable?: Record<RuleRef, boolean>;
+  disable?: Record<RuleRef, 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/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,
@@ -133,13 +140,15 @@ export interface Program {
   readonly projectRoot: string;
 }
 
+export interface TransformedProgram extends Program {}
+
 interface EmitterRef {
   emitFunction: EmitterFunc;
   main: string;
   metadata: LibraryMetadata;
   emitterOutputDir: string;
   options: Record<string, unknown>;
-  readonly library: LibraryInstance;
+  readonly library: LinterLibraryInstance & TransformerLibraryInstance;
 }
 
 interface Validator {
@@ -204,7 +213,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>>();
@@ -299,6 +308,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());
 
@@ -325,7 +344,12 @@ 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);
+
+  return { program: transformResult.program, shouldAbort: false };
 
   /**
    * Validate the libraries loaded during the compilation process are compatible.
@@ -503,7 +527,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,
@@ -518,11 +542,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,12 @@ export interface RuntimeStats {
       [rule: string]: number;
     };
   };
+  transformer: {
+    total: number;
+    transforms: {
+      [transform: string]: number;
+    };
+  };
   emit: {
     total: number;
     emitters: {