Decorator post validator

packages/compiler/src/core/checker.ts

@@ -56,6 +56,7 @@ import {
   DecoratorContext,
   DecoratorDeclarationStatementNode,
   DecoratorExpressionNode,
+  DecoratorPostValidator,
   Diagnostic,
   DiagnosticTarget,
   DocContent,
@@ -368,6 +369,7 @@ export function createChecker(program: Program, resolver: NameResolver): Checker
    * Key is the SymId of a node. It can be retrieved with getNodeSymId(node)
    */
   const pendingResolutions = new PendingResolutions();
+  const postCheckValidators: DecoratorPostValidator[] = [];
 
   const typespecNamespaceBinding = resolver.symbols.global.exports!.get("TypeSpec");
   if (typespecNamespaceBinding) {
@@ -3485,6 +3487,7 @@ export function createChecker(program: Program, resolver: NameResolver): Checker
 
     internalDecoratorValidation();
     assertNoPendingResolutions();
+    runPostValidators(postCheckValidators);
   }
 
   function assertNoPendingResolutions() {
@@ -5956,9 +5959,7 @@ export function createChecker(program: Program, resolver: NameResolver): Checker
 
     if (!options.skipDecorators) {
       if ("decorators" in typeDef) {
-        for (const decApp of typeDef.decorators) {
-          applyDecoratorToType(program, decApp, typeDef);
-        }
+        applyDecoratorsToType(typeDef);
       }
       typeDef.isFinished = true;
       Object.setPrototypeOf(typeDef, typePrototype);
@@ -5968,6 +5969,31 @@ export function createChecker(program: Program, resolver: NameResolver): Checker
     return typeDef;
   }
 
+  function applyDecoratorsToType(typeDef: Type & { decorators: DecoratorApplication[] }) {
+    const postSelfValidators: DecoratorPostValidator[] = [];
+    for (const decApp of typeDef.decorators) {
+      const validator = applyDecoratorToType(program, decApp, typeDef);
+      if (validator) {
+        switch (validator.kind) {
+          case "postSelf":
+            postSelfValidators.push(validator);
+            break;
+          case "post":
+            postCheckValidators.push(validator);
+            break;
+        }
+      }
+    }
+    runPostValidators(postSelfValidators);
+  }
+
+  /** Run a list of post validator */
+  function runPostValidators(validators: DecoratorPostValidator[]) {
+    for (const validator of validators) {
+      program.reportDiagnostics(validator.validator());
+    }
+  }
+
   function markAsChecked<T extends Type>(type: T) {
     if (!type.creating) return;
     delete type.creating;
@@ -6669,7 +6695,11 @@ function reportDeprecation(
   }
 }
 
-function applyDecoratorToType(program: Program, decApp: DecoratorApplication, target: Type) {
+function applyDecoratorToType(
+  program: Program,
+  decApp: DecoratorApplication,
+  target: Type,
+): DecoratorPostValidator | void {
   compilerAssert("decorators" in target, "Cannot apply decorator to non-decoratable type", target);
 
   for (const arg of decApp.args) {
@@ -6697,7 +6727,7 @@ function applyDecoratorToType(program: Program, decApp: DecoratorApplication, ta
     const args = decApp.args.map((x) => x.jsValue);
     const fn = decApp.decorator;
     const context = createDecoratorContext(program, decApp);
-    fn(context, target, ...args);
+    return fn(context, target, ...args);
   } catch (error: any) {
     // do not fail the language server for exceptions in decorators
     if (program.compilerOptions.designTimeBuild) {

packages/compiler/src/core/types.ts

@@ -48,11 +48,27 @@ export interface DecoratorApplication {
   node?: DecoratorExpressionNode | AugmentDecoratorStatementNode;
 }
 
+/**
+ * Signature for a decorator JS implementation function.
+ * Use `@typespec/tspd` to generate an accurate signature from the `extern dec`
+ */
 export interface DecoratorFunction {
-  (program: DecoratorContext, target: any, ...customArgs: any[]): void;
+  (program: DecoratorContext, target: any, ...customArgs: any[]): DecoratorPostValidator | void;
   namespace?: string;
 }
 
+export interface DecoratorPostValidator {
+  /**
+   * When should this validator run.
+   * "postSelf": After all decorators are run on the same type. Useful if trying to validate this decorator is compatible with other decorators without relying on the order they are applied.
+   * "post": After everything is checked in the program. Useful when trying to get an overall view of the program.
+   */
+  readonly kind: "postSelf" | "post";
+
+  /** Validator implementation. This function will be run according to the kind defined above. */
+  readonly validator: () => readonly Diagnostic[];
+}
+
 export interface BaseType {
   readonly entityKind: "Type";
   kind: string;

packages/compiler/src/index.ts

@@ -322,6 +322,7 @@ export type {
   DecoratorContext,
   DecoratorFunction,
   DecoratorImplementations,
+  DecoratorPostValidator,
   DeprecatedDirective,
   Diagnostic,
   DiagnosticCreator,

packages/compiler/test/checker/decorators.test.ts

@@ -3,7 +3,9 @@ import { beforeEach, describe, it } from "vitest";
 import { numericRanges } from "../../src/core/numeric-ranges.js";
 import { Numeric } from "../../src/core/numeric.js";
 import {
+  DecoratorContext,
   DecoratorFunction,
+  Model,
   Namespace,
   PackageFlags,
   setTypeSpecNamespace,
@@ -14,7 +16,9 @@ import {
   createTestHost,
   createTestWrapper,
   expectDiagnostics,
+  mockFile,
 } from "../../src/testing/index.js";
+import { Tester } from "../tester.js";
 
 describe("compiler: checker: decorators", () => {
   let testHost: TestHost;
@@ -546,3 +550,88 @@ describe("compiler: checker: decorators", () => {
     ok(result, "expected Foo to be blue in isBlue decorator");
   });
 });
+
+describe("validators", () => {
+  async function testerForDecorator(fn: DecoratorFunction) {
+    return await Tester.files({
+      "dec.tsp": `
+        import "./dec.js";
+        namespace MyLibrary;
+        extern dec myDecorator(target: unknown);
+      `,
+      "dec.js": mockFile.js({
+        $decorators: {
+          MyLibrary: {
+            myDecorator: fn,
+          },
+        },
+      }),
+    })
+      .import("./dec.tsp")
+      .using("MyLibrary");
+  }
+
+  it("postSelf apply validator after checking the type", async () => {
+    const order: string[] = [];
+    const tester = await testerForDecorator((_: DecoratorContext, target: Model) => {
+      order.push(`apply(${target.name})`);
+      return {
+        kind: "postSelf",
+        validator: () => {
+          order.push(`validate(${target.name})`);
+          return [];
+        },
+      };
+    });
+    await tester.compile(`
+      @myDecorator
+      @myDecorator
+      model A {}  
+      @myDecorator
+      @myDecorator
+      model B {}  
+    `);
+    deepStrictEqual(order, [
+      `apply(A)`,
+      `apply(A)`,
+      `validate(A)`,
+      `validate(A)`,
+      `apply(B)`,
+      `apply(B)`,
+      `validate(B)`,
+      `validate(B)`,
+    ]);
+  });
+
+  it("post apply validator after checking every type", async () => {
+    const order: string[] = [];
+    const tester = await testerForDecorator((_: DecoratorContext, target: Model) => {
+      order.push(`apply(${target.name})`);
+      return {
+        kind: "post",
+        validator: () => {
+          order.push(`validate(${target.name})`);
+          return [];
+        },
+      };
+    });
+    await tester.compile(`
+      @myDecorator
+      @myDecorator
+      model A {}  
+      @myDecorator
+      @myDecorator
+      model B {}  
+    `);
+    deepStrictEqual(order, [
+      `apply(A)`,
+      `apply(A)`,
+      `apply(B)`,
+      `apply(B)`,
+      `validate(A)`,
+      `validate(A)`,
+      `validate(B)`,
+      `validate(B)`,
+    ]);
+  });
+});

packages/events/generated-defs/TypeSpec.Events.ts

@@ -1,4 +1,10 @@
-import type { DecoratorContext, ModelProperty, Union, UnionVariant } from "@typespec/compiler";
+import type {
+  DecoratorContext,
+  DecoratorPostValidator,
+  ModelProperty,
+  Union,
+  UnionVariant,
+} from "@typespec/compiler";
 
 /**
  * Specify that this union describes a set of events.
@@ -13,7 +19,10 @@ import type { DecoratorContext, ModelProperty, Union, UnionVariant } from "@type
  * }
  * ```
  */
-export type EventsDecorator = (context: DecoratorContext, target: Union) => void;
+export type EventsDecorator = (
+  context: DecoratorContext,
+  target: Union,
+) => DecoratorPostValidator | void;
 
 /**
  * Specifies the content type of the event envelope, event body, or event payload.
@@ -41,7 +50,7 @@ export type ContentTypeDecorator = (
   context: DecoratorContext,
   target: UnionVariant | ModelProperty,
   contentType: string,
-) => void;
+) => DecoratorPostValidator | void;
 
 /**
  * Identifies the payload of an event.
@@ -54,7 +63,10 @@ export type ContentTypeDecorator = (
  * }
  * ```
  */
-export type DataDecorator = (context: DecoratorContext, target: ModelProperty) => void;
+export type DataDecorator = (
+  context: DecoratorContext,
+  target: ModelProperty,
+) => DecoratorPostValidator | void;
 
 export type TypeSpecEventsDecorators = {
   events: EventsDecorator;

packages/http-client/generated-defs/TypeSpec.HttpClient.ts

@@ -1,4 +1,4 @@
-import type { DecoratorContext, Type } from "@typespec/compiler";
+import type { DecoratorContext, DecoratorPostValidator, Type } from "@typespec/compiler";
 
 export interface FeatureLifecycleOptions {
   readonly emitterScope?: string;
@@ -8,7 +8,7 @@ export type ExperimentalDecorator = (
   context: DecoratorContext,
   target: Type,
   options?: FeatureLifecycleOptions,
-) => void;
+) => DecoratorPostValidator | void;
 
 export type TypeSpecHttpClientDecorators = {
   experimental: ExperimentalDecorator;

packages/http/generated-defs/TypeSpec.Http.Private.ts

@@ -1,4 +1,10 @@
-import type { DecoratorContext, Model, ModelProperty, Type } from "@typespec/compiler";
+import type {
+  DecoratorContext,
+  DecoratorPostValidator,
+  Model,
+  ModelProperty,
+  Type,
+} from "@typespec/compiler";
 
 export interface HttpPartOptions {
   readonly name?: string;
@@ -8,16 +14,22 @@ export interface ApplyMergePatchOptions {
   readonly visibilityMode: unknown;
 }
 
-export type PlainDataDecorator = (context: DecoratorContext, target: Model) => void;
+export type PlainDataDecorator = (
+  context: DecoratorContext,
+  target: Model,
+) => DecoratorPostValidator | void;
 
-export type HttpFileDecorator = (context: DecoratorContext, target: Model) => void;
+export type HttpFileDecorator = (
+  context: DecoratorContext,
+  target: Model,
+) => DecoratorPostValidator | void;
 
 export type HttpPartDecorator = (
   context: DecoratorContext,
   target: Model,
   type: Type,
   options: HttpPartOptions,
-) => void;
+) => DecoratorPostValidator | void;
 
 /**
  * Performs the canonical merge-patch transformation on the given model and injects its
@@ -29,7 +41,7 @@ export type ApplyMergePatchDecorator = (
   source: Model,
   nameTemplate: string,
   options: ApplyMergePatchOptions,
-) => void;
+) => DecoratorPostValidator | void;
 
 /**
  * Specify if inapplicable metadata should be included in the payload for the given entity.
@@ -40,7 +52,7 @@ export type IncludeInapplicableMetadataInPayloadDecorator = (
   context: DecoratorContext,
   target: Type,
   value: boolean,
-) => void;
+) => DecoratorPostValidator | void;
 
 /**
  * Marks a model that was generated by applying the MergePatch
@@ -50,7 +62,7 @@ export type MergePatchModelDecorator = (
   context: DecoratorContext,
   target: Model,
   source: Model,
-) => void;
+) => DecoratorPostValidator | void;
 
 /**
  * Links a modelProperty mutated as part of a mergePatch transform to
@@ -60,7 +72,7 @@ export type MergePatchPropertyDecorator = (
   context: DecoratorContext,
   target: ModelProperty,
   source: ModelProperty,
-) => void;
+) => DecoratorPostValidator | void;
 
 export type TypeSpecHttpPrivateDecorators = {
   plainData: PlainDataDecorator;