Parse and preserve parameter decorators

Extend parameter AST nodes to retain decorators, including explicit-this decorators on function signatures, without forcing a broad constructor API churn.

Teach both parameter parsers to accept stacked decorators on regular, rest, explicit-this, constructor-property, function-type, and parenthesized-arrow parameters.

Update the AST builder to serialize parameter decorators inline so parser fixtures can round-trip the new syntax faithfully.

Add a focused parser fixture covering the preserved syntax surface before deferred validation is introduced.

Author: jtenner

src/ast.ts

@@ -181,9 +181,12 @@ export abstract class Node {
     name: IdentifierExpression,
     type: TypeNode,
     initializer: Expression | null,
-    range: Range
+    range: Range,
+    decorators: DecoratorNode[] | null = null
   ): ParameterNode {
-    return new ParameterNode(parameterKind, name, type, initializer, range);
+    let parameter = new ParameterNode(parameterKind, name, type, initializer, range);
+    parameter.decorators = decorators;
+    return parameter;
   }
 
   // special
@@ -926,6 +929,9 @@ export class FunctionTypeNode extends TypeNode {
   ) {
     super(NodeKind.FunctionType, isNullable, range);
   }
+
+  /** Decorators on an explicit `this` parameter, if any. */
+  explicitThisDecorators: DecoratorNode[] | null = null;
 }
 
 /** Represents a type parameter. */
@@ -971,6 +977,8 @@ export class ParameterNode extends Node {
     super(NodeKind.Parameter, range);
   }
 
+  /** Decorators, if any. */
+  decorators: DecoratorNode[] | null = null;
   /** Implicit field declaration, if applicable. */
   implicitFieldDeclaration: FieldDeclaration | null = null;
   /** Common flags indicating specific traits. */

src/extra/ast.ts

@@ -427,6 +427,7 @@ export class ASTBuilder {
     sb.push(isNullable ? "((" : "(");
     let explicitThisType = node.explicitThisType;
     if (explicitThisType) {
+      this.serializeParameterDecorators(node.explicitThisDecorators);
       sb.push("this: ");
       this.visitTypeNode(explicitThisType);
     }
@@ -1153,6 +1154,7 @@ export class ASTBuilder {
       let numParameters = parameters.length;
       let explicitThisType = signature.explicitThisType;
       if (explicitThisType) {
+        this.serializeParameterDecorators(signature.explicitThisDecorators);
         sb.push("this: ");
         this.visitTypeNode(explicitThisType);
       }
@@ -1563,9 +1565,38 @@ export class ASTBuilder {
     indent(sb, this.indentLevel);
   }
 
+  serializeParameterDecorators(decorators: DecoratorNode[] | null): void {
+    if (decorators) {
+      for (let i = 0, k = decorators.length; i < k; ++i) {
+        this.serializeParameterDecorator(decorators[i]);
+      }
+    }
+  }
+
+  private serializeParameterDecorator(node: DecoratorNode): void {
+    let sb = this.sb;
+    sb.push("@");
+    this.visitNode(node.name);
+    let args = node.args;
+    if (args) {
+      sb.push("(");
+      let numArgs = args.length;
+      if (numArgs) {
+        this.visitNode(args[0]);
+        for (let i = 1; i < numArgs; ++i) {
+          sb.push(", ");
+          this.visitNode(args[i]);
+        }
+      }
+      sb.push(")");
+    }
+    sb.push(" ");
+  }
+
   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);

src/parser.ts

@@ -709,6 +709,7 @@ export class Parser extends DiagnosticEmitter {
     let startPos = tn.tokenPos;
     let parameters: ParameterNode[] | null = null;
     let thisType: NamedTypeNode | null = null;
+    let thisDecorators: DecoratorNode[] | null = null;
     let isSignature: bool = false;
     let firstParamNameNoType: IdentifierExpression | null = null;
     let firstParamKind: ParameterKind = ParameterKind.Default;
@@ -723,6 +724,12 @@ export class Parser extends DiagnosticEmitter {
       do {
         let paramStart = -1;
         let kind = ParameterKind.Default;
+        let decorators = this.parseParameterDecorators(tn);
+        if (decorators) {
+          paramStart = decorators[0].range.start;
+          isSignature = true;
+          tn.discard(state);
+        }
         if (tn.skip(Token.Dot_Dot_Dot)) {
           paramStart = tn.tokenPos;
           isSignature = true;
@@ -745,6 +752,7 @@ export class Parser extends DiagnosticEmitter {
               return null;
             }
             thisType = <NamedTypeNode>type;
+            thisDecorators = decorators;
           } else {
             tn.reset(state);
             this.tryParseSignatureIsSignature = false;
@@ -773,7 +781,7 @@ export class Parser extends DiagnosticEmitter {
               this.tryParseSignatureIsSignature = isSignature;
               return null;
             }
-            let param = Node.createParameter(kind, name, type, null, tn.range(paramStart, tn.pos));
+            let param = Node.createParameter(kind, name, type, null, tn.range(paramStart, tn.pos), decorators);
             if (!parameters) parameters = [ param ];
             else parameters.push(param);
           } else {
@@ -784,7 +792,7 @@ export class Parser extends DiagnosticEmitter {
               }
             }
             if (isSignature) {
-              let param = Node.createParameter(kind, name, Node.createOmittedType(tn.range(tn.pos)), null, tn.range(paramStart, tn.pos));
+              let param = Node.createParameter(kind, name, Node.createOmittedType(tn.range(tn.pos)), null, tn.range(paramStart, tn.pos), decorators);
               if (!parameters) parameters = [ param ];
               else parameters.push(param);
               this.error(
@@ -869,13 +877,15 @@ export class Parser extends DiagnosticEmitter {
 
     if (!parameters) parameters = [];
 
-    return Node.createFunctionType(
+    let functionType = Node.createFunctionType(
       parameters,
       returnType,
       thisType,
       false,
       tn.range(startPos, tn.pos)
     );
+    functionType.explicitThisDecorators = thisDecorators;
+    return functionType;
   }
 
   // statements
@@ -924,6 +934,19 @@ export class Parser extends DiagnosticEmitter {
     return null;
   }
 
+  private parseParameterDecorators(
+    tn: Tokenizer
+  ): DecoratorNode[] | null {
+    let decorators: DecoratorNode[] | null = null;
+    while (tn.skip(Token.At)) {
+      let decorator = this.parseDecorator(tn);
+      if (!decorator) break;
+      if (!decorators) decorators = [decorator];
+      else decorators.push(decorator);
+    }
+    return decorators;
+  }
+
   parseVariable(
     tn: Tokenizer,
     flags: CommonFlags,
@@ -1227,6 +1250,7 @@ export class Parser extends DiagnosticEmitter {
   }
 
   private parseParametersThis: NamedTypeNode | null = null;
+  private parseParametersThisDecorators: DecoratorNode[] | null = null;
 
   parseParameters(
     tn: Tokenizer,
@@ -1243,40 +1267,50 @@ export class Parser extends DiagnosticEmitter {
 
     // check if there is a leading `this` parameter
     this.parseParametersThis = null;
-    if (tn.skip(Token.This)) {
-      if (tn.skip(Token.Colon)) {
-        thisType = this.parseType(tn); // reports
-        if (!thisType) return null;
-        if (thisType.kind == NodeKind.NamedType) {
-          this.parseParametersThis = <NamedTypeNode>thisType;
-        } else {
-          this.error(
-            DiagnosticCode.Identifier_expected,
-            thisType.range
-          );
-        }
-      } else {
-        this.error(
-          DiagnosticCode._0_expected,
-          tn.range(), ":"
-        );
-        return null;
-      }
-      if (!tn.skip(Token.Comma)) {
-        if (tn.skip(Token.CloseParen)) {
-          return parameters;
+    this.parseParametersThisDecorators = null;
+
+    let first = true;
+    while (true) {
+      if (tn.skip(Token.CloseParen)) break;
+
+      let paramDecorators = this.parseParameterDecorators(tn);
+
+      if (first && tn.skip(Token.This)) {
+        if (tn.skip(Token.Colon)) {
+          thisType = this.parseType(tn); // reports
+          if (!thisType) return null;
+          if (thisType.kind == NodeKind.NamedType) {
+            this.parseParametersThis = <NamedTypeNode>thisType;
+            this.parseParametersThisDecorators = paramDecorators;
+          } else {
+            this.error(
+              DiagnosticCode.Identifier_expected,
+              thisType.range
+            );
+          }
         } else {
           this.error(
             DiagnosticCode._0_expected,
-            tn.range(), ")"
+            tn.range(), ":"
           );
           return null;
         }
+        first = false;
+        if (!tn.skip(Token.Comma)) {
+          if (tn.skip(Token.CloseParen)) {
+            break;
+          } else {
+            this.error(
+              DiagnosticCode._0_expected,
+              tn.range(), ")"
+            );
+            return null;
+          }
+        }
+        continue;
       }
-    }
 
-    while (!tn.skip(Token.CloseParen)) {
-      let param = this.parseParameter(tn, isConstructor); // reports
+      let param = this.parseParameter(tn, isConstructor, paramDecorators); // reports
       if (!param) return null;
       if (seenRest && !reportedRest) {
         this.error(
@@ -1305,6 +1339,7 @@ export class Parser extends DiagnosticEmitter {
         }
       }
       parameters.push(param);
+      first = false;
       if (!tn.skip(Token.Comma)) {
         if (tn.skip(Token.CloseParen)) {
           break;
@@ -1322,24 +1357,27 @@ export class Parser extends DiagnosticEmitter {
 
   parseParameter(
     tn: Tokenizer,
-    isConstructor: bool = false
+    isConstructor: bool = false,
+    decorators: DecoratorNode[] | null = null
   ): ParameterNode | null {
 
     // before: ('public' | 'private' | 'protected' | '...')? Identifier '?'? (':' Type)? ('=' Expression)?
 
     let isRest = false;
     let isOptional = false;
-    let startRange: Range | null = null;
+    let startRange: Range | null = decorators
+      ? decorators[0].range
+      : null;
     let accessFlags: CommonFlags = CommonFlags.None;
     if (isConstructor) {
       if (tn.skip(Token.Public)) {
-        startRange = tn.range();
+        if (!startRange) startRange = tn.range();
         accessFlags |= CommonFlags.Public;
       } else if (tn.skip(Token.Protected)) {
-        startRange = tn.range();
+        if (!startRange) startRange = tn.range();
         accessFlags |= CommonFlags.Protected;
       } else if (tn.skip(Token.Private)) {
-        startRange = tn.range();
+        if (!startRange) startRange = tn.range();
         accessFlags |= CommonFlags.Private;
       }
       if (tn.peek() == Token.Readonly) {
@@ -1361,12 +1399,12 @@ export class Parser extends DiagnosticEmitter {
           tn.range()
         );
       } else {
-        startRange = tn.range();
+        if (!startRange) startRange = tn.range();
       }
       isRest = true;
     }
     if (tn.skipIdentifier()) {
-      if (!isRest) startRange = tn.range();
+      if (!isRest && !startRange) startRange = tn.range();
       let identifier = Node.createIdentifierExpression(tn.readIdentifier(), tn.range());
       let type: TypeNode | null = null;
       if (isOptional = tn.skip(Token.Question)) {
@@ -1411,7 +1449,8 @@ export class Parser extends DiagnosticEmitter {
         identifier,
         type,
         initializer,
-        Range.join(assert(startRange), tn.range())
+        Range.join(assert(startRange), tn.range()),
+        decorators
       );
       param.flags |= accessFlags;
       return param;
@@ -1523,6 +1562,7 @@ export class Parser extends DiagnosticEmitter {
       false,
       tn.range(signatureStart, tn.pos)
     );
+    signature.explicitThisDecorators = this.parseParametersThisDecorators;
 
     let body: Statement | null = null;
     if (tn.skip(Token.OpenBrace)) {
@@ -1597,14 +1637,24 @@ export class Parser extends DiagnosticEmitter {
     let parameters = this.parseParameters(tn);
     if (!parameters) return null;
 
-    return this.parseFunctionExpressionCommon(tn, name, parameters, this.parseParametersThis, arrowKind, startPos, signatureStart);
+    return this.parseFunctionExpressionCommon(
+      tn,
+      name,
+      parameters,
+      this.parseParametersThis,
+      this.parseParametersThisDecorators,
+      arrowKind,
+      startPos,
+      signatureStart
+    );
   }
 
   private parseFunctionExpressionCommon(
     tn: Tokenizer,
     name: IdentifierExpression,
     parameters: ParameterNode[],
     explicitThis: NamedTypeNode | null,
+    explicitThisDecorators: DecoratorNode[] | null,
     arrowKind: ArrowKind,
     startPos: i32 = -1,
     signatureStart: i32 = -1
@@ -1637,6 +1687,7 @@ export class Parser extends DiagnosticEmitter {
       false,
       tn.range(signatureStart, tn.pos)
     );
+    signature.explicitThisDecorators = explicitThisDecorators;
 
     let body: Statement | null = null;
     if (arrowKind) {
@@ -2282,6 +2333,7 @@ export class Parser extends DiagnosticEmitter {
         false,
         tn.range(signatureStart, tn.pos)
       );
+      signature.explicitThisDecorators = this.parseParametersThisDecorators;
 
       let body: Statement | null = null;
       if (tn.skip(Token.OpenBrace)) {
@@ -3729,6 +3781,7 @@ export class Parser extends DiagnosticEmitter {
             Node.createEmptyIdentifierExpression(tn.range(startPos)),
             [],
             null,
+            null,
             ArrowKind.Parenthesized
           );
         }
@@ -3738,6 +3791,7 @@ export class Parser extends DiagnosticEmitter {
           switch (tn.next(IdentifierHandling.Prefer)) {
 
             // function expression
+            case Token.At:
             case Token.Dot_Dot_Dot: {
               tn.reset(state);
               return this.parseFunctionExpression(tn);
@@ -3930,6 +3984,7 @@ export class Parser extends DiagnosticEmitter {
               )
             ],
             null,
+            null,
             ArrowKind.Single,
             startPos
           );