feat: parse and preserve parameter decorators in AST

[PaperPrototype]

Made a new PR instead of force pushing (see original #3015)

Claude (with my own modifications):

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. @decorator variableName: 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

Me:

The following syntax is now parsed and included in the AST:

function regular(@first value: i32): void {}
function multiParam(@first huh: string, @second(123, 456) works: i32, @third("can pass a string?") hello: string): void {}
function rest(@rest ...values: i32[]): void {}
function withthis(@self this: i32, value: i32): i32 { return this; }

class Box {
  constructor(@field public value: i32) {}
  method(@arg value: i32): void {}
}

type Callback = (@arg value: i32) => void;
const expression = function(@arg value: i32): void {};
const arrow = (@arg value: i32): void => {};
namespace ns {
  export function nested(@arg value: i32): void {}
}

I also added a beforeCompile hook to the transformer API so transformers can validate decorators if they want to (as per @MaxGraey suggestion)

[PaperPrototype]

I regenerated fixtures as well, there was no difference.

[PaperPrototype]

Oh, do I need to add my name to the contributors list? Er, idk how that all works. EDIT: I already did, i just forgot

[MaxGraey]

You could have just forced a merge of the latest main branch into your branch. But if you've already started a new one you should close the previous one

[PaperPrototype]

I am scared of force pushing, too many nightmares (I almost deleted an entire open source project's main branch once... scary moment) ignore this cough

[PaperPrototype]

You could have just forced a merge of the latest main branch into your branch. But if you've already started a new one you should close the previous one

Oh, I see what you meant... yeah that would have worked 🤣

[MaxGraey]

Transformers should use

This can be cited as an example, not as a requirement. Also, the comment is rather wordy.

[MaxGraey]

Also, I haven't seen any indication that it's been integrated into the pipeline and well tested. For instance afterParse:
https://github.com/search?q=repo%3AAssemblyScript%2Fassemblyscript+afterParse&type=code
for beforeCompile need to do the same

[MaxGraey]

It's even less clear why we need beforeCompile when we have afterInitialize?

validate?(program: Program): Promise<bool> | bool;

Specialized validate would be appropriate more, as I suggested. Because it could optionally interrupt the compilation flow without trigger exception (soft bail)

[PaperPrototype]

It's even less clear why we need afterInitialize when we have afterInitialize?

I'm gonna assume you meant:

It's even less clear why we need beforeCompile when we have afterInitialize?

I think a preliminary discussion on this might be a good idea before I just jump and and start adding stuff 😅. Maybe a change to the transformer API should be delegated to it's own PR? What do you think? That would allow this PR to focus solely on adding decorators to the AST.

[MaxGraey]

I'm gonna assume you meant

Yeah, copy-paste typo

Maybe a change to the transformer API should be delegated to it's own PR? What do you think?

If this is not a blocker then that’s actually how it should be.