feat: parse and preserve parameter decorators in AST

Adds support for decorator syntax on function parameters (e.g.
`@decorator value: i32`). Decorators are parsed and stored in
`ParameterNode.decorators` and `FunctionTypeNode.explicitThisDecorators`,
making them available to transformer plugins without affecting compilation.

- Parser: parses leading parameter decorators into AST; emits TS1206
  only for misplaced decorators (e.g. `value @Deco: i32`)
- AST: new `decorators` field on ParameterNode, `explicitThisDecorators`
  on FunctionTypeNode, `decoratedFunctionTypes` index on Source
- Serialization: inline parameter decorator serialization in extra/ast.ts
- Transform API: new `beforeCompile(program)` hook in cli/index.d.ts for
  transformer-owned validation after program init, before WASM compilation
- Tests: parser round-trip, compiler clean-compile, parser error cases,
  and transform example that reads parameter decorators via afterInitialize

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: PaperPrototype

NOTICE

@@ -63,6 +63,7 @@ under the licensing terms detailed in LICENSE:
 * Mopsgamer <79159094+Mopsgamer@users.noreply.github.com>
 * EDM115 <github@edm115.dev>
 * Weixie Cui <cuiweixie@gmail.com>
+* Abdiel Lopez <a.paperprototype@gmail.com>
 
 Portions of this software are derived from third-party works licensed under
 the following terms:

TODO.md

@@ -0,0 +1,20 @@
+Working document of notes/tasks for trying to figure out how to correctly add decorators to AssemblyScript. Will be delete once the PR is complete.
+
+NOTES:
+- AST can be extended without breaking changes, this is perfectly fine and anything that is added will just be ignored by the compiler but at least transformer plugins can then make use of it. No need to validate and throw errors unless it is an AST parse error.
+    - Need to add a transformer hook so transformers can add their own validation. This way AssemblyScript can delegate validation to transformers instead of having to handle it internally, which doesn't make sense because AS shouldn't be in charge of worring about that in the first place.
+
+- "Transformer" refers the to transformers in /tests/transform
+
+- Rather than have a method validate the decorators, they should just be part of the AST. Once the AST can directly handle the decorators then validating decorators syntax will happen automatically. This also means we need actual AST nodes in ast.ts for the different parts of decorators rather than just inlining the decorators.
+- Correction to the above. The method validation was only 1 part of the problem, the compiler of assemblyscript is for outputting WASM binaries not validating valid AST syntax. The compiler.ts will not need to be touched AT ALL for this PR.
+
+TODO:
+<!-- 
+- [ ] Ask claude to explain how the AssemblyScript parser works and try to add a garbage throwaway feature myself manually for learning purposes (eg. `mut` keyword for syntax like `mut myVariable = 10`).
+
+- [ ] After implementing re-read all the stuff dcode and Max have been explaining and try to better understand it -->
+
+- [ ] Need to add a transform hook for valdiating after parse but before compiliation.
+
+- [ ] Need to add a test case for having a transform validate decorators.

cli/index.d.ts

@@ -273,6 +273,11 @@ export abstract class Transform {
   /** Lists all files in a directory. */
   listFiles(dirname: string, baseDir: string): (string[] | null) | Promise<string[] | null>;
 
+  /** Called after program initialization, before WASM compilation. Transformers should use
+   *  this hook to perform custom validation of AST constructs such as parameter decorators
+   *  and emit their own diagnostics. Decorators remain in the AST unchanged. */
+  beforeCompile?(program: Program): void | Promise<void>;
+
   /** Called when parsing is complete, before a program is instantiated from the AST. */
   afterParse?(parser: Parser): void | Promise<void>;
 

eslint.config.js

@@ -25,6 +25,10 @@ export default defineConfig([
 
     // FIXME: Tagged template literal tests with invalid escapes
     "tests/compiler/templateliteral.ts",
+
+    // Decorators on `this` are not allowed typically in TypeScript, but this
+    // fixture exercises that AS-only syntax and is validated by transform tests.
+    "tests/transform/parameter-decorators.ts",
   ]),
 
   js.configs.recommended,

package.json

@@ -85,8 +85,8 @@
     "test:browser": "node --enable-source-maps tests/browser",
     "test:asconfig": "cd tests/asconfig && npm run test",
     "test:transform": "npm run test:transform:esm && npm run test:transform:cjs",
-    "test:transform:esm": "node bin/asc tests/compiler/empty --transform ./tests/transform/index.js --noEmit && node bin/asc tests/compiler/empty --transform ./tests/transform/simple.js --noEmit",
-    "test:transform:cjs": "node bin/asc tests/compiler/empty --transform ./tests/transform/cjs/index.js --noEmit && node bin/asc tests/compiler/empty --transform ./tests/transform/cjs/simple.js --noEmit",
+    "test:transform:esm": "node bin/asc tests/compiler/empty --transform ./tests/transform/index.js --noEmit && node bin/asc tests/compiler/empty --transform ./tests/transform/simple.js --noEmit && node --experimental-strip-types --no-warnings bin/asc tests/transform/parameter-decorators.ts --transform ./tests/transform/remove-parameter-decorators.ts --noEmit",
+    "test:transform:cjs": "node bin/asc tests/compiler/empty --transform ./tests/transform/cjs/index.js --noEmit && node bin/asc tests/compiler/empty --transform ./tests/transform/cjs/simple.js --noEmit && node bin/asc tests/transform/parameter-decorators.ts --transform ./tests/transform/cjs/remove-parameter-decorators.js --noEmit",
     "test:cli": "node tests/cli/options.js",
     "asbuild": "npm run asbuild:debug && npm run asbuild:release",
     "asbuild:debug": "node bin/asc --config src/asconfig.json --target debug",

src/ast.ts

@@ -156,10 +156,11 @@ export abstract class Node {
     parameters: ParameterNode[],
     returnType: TypeNode,
     explicitThisType: NamedTypeNode | null,
+    explicitThisDecorators: DecoratorNode[] | null,
     isNullable: bool,
     range: Range
   ): FunctionTypeNode {
-    return new FunctionTypeNode(parameters, returnType, explicitThisType, isNullable, range);
+    return new FunctionTypeNode(parameters, returnType, explicitThisType, explicitThisDecorators, isNullable, range);
   }
 
   static createTupleType(
@@ -191,9 +192,10 @@ export abstract class Node {
     name: IdentifierExpression,
     type: TypeNode,
     initializer: Expression | null,
+    decorators: DecoratorNode[] | null,
     range: Range
   ): ParameterNode {
-    return new ParameterNode(parameterKind, name, type, initializer, range);
+    return new ParameterNode(parameterKind, name, type, initializer, decorators, range);
   }
 
   // special
@@ -935,6 +937,8 @@ export class FunctionTypeNode extends TypeNode {
     public returnType: TypeNode,
     /** Explicitly provided this type, if any. */
     public explicitThisType: NamedTypeNode | null, // can't be a function
+    /** Decorators on an explicit `this` parameter, if any. Preserved as transform-only syntax. */
+    public explicitThisDecorators: DecoratorNode[] | null,
     /** Whether nullable or not. */
     isNullable: bool,
     /** Source range. */
@@ -997,12 +1001,13 @@ export class ParameterNode extends Node {
     public type: TypeNode,
     /** Initializer expression, if any. */
     public initializer: Expression | null,
+    /** Decorators, if any. Preserved as transform-only syntax so transforms can rewrite or remove them before validation. */
+    public decorators: DecoratorNode[] | null,
     /** Source range. */
     range: Range
   ) {
     super(NodeKind.Parameter, range);
   }
-
   /** Implicit field declaration, if applicable. */
   implicitFieldDeclaration: FieldDeclaration | null = null;
   /** Common flags indicating specific traits. */
@@ -1696,6 +1701,8 @@ export class Source extends Node {
   debugInfoIndex: i32 = -1;
   /** Re-exported sources. */
   exportPaths: string[] | null = null;
+  /** Function types with parameter or this-parameter decorators, revisited after transforms for validation. */
+  decoratedFunctionTypes: FunctionTypeNode[] | null = null;
 
   /** Checks if this source represents native code. */
   get isNative(): bool {

src/extra/ast.ts

@@ -436,6 +436,7 @@ export class ASTBuilder {
     sb.push(isNullable ? "((" : "(");
     let explicitThisType = node.explicitThisType;
     if (explicitThisType) {
+      this.serializeParameterDecorators(node.explicitThisDecorators);
       sb.push("this: ");
       this.visitTypeNode(explicitThisType);
     }
@@ -1189,6 +1190,7 @@ export class ASTBuilder {
       let numParameters = parameters.length;
       let explicitThisType = signature.explicitThisType;
       if (explicitThisType) {
+        this.serializeParameterDecorators(signature.explicitThisDecorators);
         sb.push("this: ");
         this.visitTypeNode(explicitThisType);
       }
@@ -1577,7 +1579,7 @@ export class ASTBuilder {
 
   // other
 
-  serializeDecorator(node: DecoratorNode): void {
+  serializeDecorator(node: DecoratorNode, isInline: bool = false): void {
     let sb = this.sb;
     sb.push("@");
     this.visitNode(node.name);
@@ -1592,16 +1594,28 @@ export class ASTBuilder {
           this.visitNode(args[i]);
         }
       }
-      sb.push(")\n");
+      sb.push(")");
+    }
+    if (isInline) {
+      sb.push(" ");
     } else {
       sb.push("\n");
+      indent(sb, this.indentLevel);
+    }
+  }
+
+  serializeParameterDecorators(decorators: DecoratorNode[] | null): void {
+    if (decorators) {
+      for (let i = 0, k = decorators.length; i < k; ++i) {
+        this.serializeDecorator(decorators[i], true);
+      }
     }
-    indent(sb, this.indentLevel);
   }
 
   serializeParameter(node: ParameterNode): void {
     let sb = this.sb;
     let kind = node.parameterKind;
+    this.serializeParameterDecorators(node.decorators);
     let implicitFieldDeclaration = node.implicitFieldDeclaration;
     if (implicitFieldDeclaration) {
       this.serializeAccessModifiers(implicitFieldDeclaration);