Document transform hook timing for parameter decorators

Author: jtenner

cli/index.d.ts

@@ -276,7 +276,10 @@ export abstract class Transform {
   /** Called when parsing is complete, before a program is instantiated from the AST. */
   afterParse?(parser: Parser): void | Promise<void>;
 
-  /** Called after the program is instantiated. */
+  /**
+   * Called after the program is instantiated and before compilation-time validation runs.
+   * This is the last hook where transforms can rewrite preserved AST-only syntax before it is rejected.
+   */
   afterInitialize?(program: Program): void | Promise<void>;
 
   /** Called when compilation is complete, before the module is being validated. */

cli/index.js

@@ -718,7 +718,7 @@ export async function main(argv, options) {
     stats.initializeTime += stats.end(begin);
   }
 
-  // Call afterInitialize transform hook
+  // Call afterInitialize transform hook, the last AST rewrite point before compilation-time validation.
   {
     let error = await applyTransform("afterInitialize", program);
     if (error) return prepareResult(error);

src/index-wasm.ts

@@ -347,7 +347,7 @@ export function getDependee(program: Program, file: string): string | null {
 
 // Compiler
 
-/** Initializes the program pre-emptively for transform hooks. */
+/** Initializes the program pre-emptively so `afterInitialize` transforms can rewrite the AST before compilation. */
 export function initializeProgram(program: Program): void {
   program.initialize();
 }

tests/transform/cjs/remove-parameter-decorators.js

@@ -1,3 +1,5 @@
+// Example transform proving that preserved parameter decorators can be stripped
+// during afterInitialize before compilation rejects them.
 console.log("CommonJS parameter decorator removal transform loaded");
 
 const NodeKind = {

tests/transform/remove-parameter-decorators.js

@@ -1,3 +1,5 @@
+// Example transform proving that preserved parameter decorators can be stripped
+// during afterInitialize before compilation rejects them.
 console.log("Parameter decorator removal transform loaded");
 
 const NodeKind = {