parser-lr 0.3.1 → 0.4.0

package/bin/parser-lr.js

@@ -3781,7 +3781,7 @@ const {
   Help,
 } = commander;
 
-var version$1 = "0.3.1";
+var version$1 = "0.4.0";
 var packageDefinition = {
 	version: version$1};
 
@@ -7240,6 +7240,8 @@ class ParseTable {
     algorithm;
     parserStateCount;
     conflicts;
+    astSchema;
+    transformSchema;
     actionByState;
     gotoByState;
     productionById;
@@ -7258,8 +7260,10 @@ class ParseTable {
      * @param actions - ACTION entries keyed by state and terminal symbol.
      * @param gotos - GOTO entries keyed by state and non-terminal name.
      * @param conflicts - Shift/reduce and reduce/reduce conflicts resolved during construction.
+     * @param astSchema - AST types from the `ast` section, or null when absent.
+     * @param transformSchema - CST-to-AST rules from the `transform` section, or null when absent.
      */
-    constructor(grammarName, startSymbol, tokens, tokenRules, skipRules, states, algorithm, parserStateCount = 0, productions = [], actions = new Map(), gotos = new Map(), conflicts = []) {
+    constructor(grammarName, startSymbol, tokens, tokenRules, skipRules, states, algorithm, parserStateCount = 0, productions = [], actions = new Map(), gotos = new Map(), conflicts = [], astSchema = null, transformSchema = null) {
         this.grammarName = grammarName;
         this.startSymbol = startSymbol;
         this.tokens = tokens;
@@ -7269,6 +7273,8 @@ class ParseTable {
         this.algorithm = algorithm;
         this.parserStateCount = parserStateCount;
         this.conflicts = conflicts;
+        this.astSchema = astSchema;
+        this.transformSchema = transformSchema;
         this.actionByState = actions;
         this.gotoByState = gotos;
         const productionById = new Map();
@@ -7321,7 +7327,13 @@ class ParseTable {
         if (!isParseTableJsonV2(json)) {
             return new ParseTable(json.grammarName, json.startSymbol, [...json.tokens], [...json.tokenRules], [...json.skipRules], [...json.states], json.algorithm);
         }
-        return new ParseTable(json.grammarName, json.startSymbol, [...json.tokens], [...json.tokenRules], [...json.skipRules], [...json.states], json.algorithm, json.parserStateCount, [...json.productions], ParseTable.actionsFromJson(json.actions), ParseTable.gotosFromJson(json.gotos));
+        const astSchema = json.ast === undefined
+            ? null
+            : new AstSchema([...json.ast]);
+        const transformSchema = json.transform === undefined
+            ? null
+            : new TransformSchema([...json.transform]);
+        return new ParseTable(json.grammarName, json.startSymbol, [...json.tokens], [...json.tokenRules], [...json.skipRules], [...json.states], json.algorithm, json.parserStateCount, [...json.productions], ParseTable.actionsFromJson(json.actions), ParseTable.gotosFromJson(json.gotos), [], astSchema, transformSchema);
     }
     /**
      * Parses a parse table from a JSON string.
@@ -7379,16 +7391,18 @@ class ParseTable {
             productions: [...this.productionById.values()].sort((left, right) => left.id - right.id),
             actions: ParseTable.actionsToJson(this.actionByState),
             gotos: ParseTable.gotosToJson(this.gotoByState),
+            ...(this.astSchema === null ? {} : { ast: [...this.astSchema.types] }),
+            ...(this.transformSchema === null ? {} : { transform: [...this.transformSchema.rules] }),
         };
         return json;
     }
     /**
-     * Builds a grammar containing lexer metadata from this table.
+     * Builds a grammar from this table, including AST and transform schemas when present.
      *
-     * @returns A grammar suitable for lexing; productions are empty.
+     * @returns A grammar suitable for lexing and CST-to-AST transforms.
      */
     toGrammar() {
-        return new Grammar(this.grammarName, this.tokenRules, this.skipRules, this.states, this.startSymbol, []);
+        return new Grammar(this.grammarName, this.tokenRules, this.skipRules, this.states, this.startSymbol, [], this.astSchema, this.transformSchema);
     }
     /**
      * Returns the ACTION entry for a parser state and terminal symbol key.
@@ -7430,7 +7444,7 @@ class ParseTable {
             variant: production.variant,
             origin: production.origin,
         }));
-        return new ParseTable(grammar.name, grammar.startSymbol, tokenInventory(grammar), [...grammar.tokenRules], [...grammar.skipRules], [...grammar.states], lrTable.algorithm, lrTable.stateCount, productions, lrTable.actions, lrTable.gotos, [...lrTable.conflicts]);
+        return new ParseTable(grammar.name, grammar.startSymbol, tokenInventory(grammar), [...grammar.tokenRules], [...grammar.skipRules], [...grammar.states], lrTable.algorithm, lrTable.stateCount, productions, lrTable.actions, lrTable.gotos, [...lrTable.conflicts], grammar.astSchema, grammar.transformSchema);
     }
     /**
      * Converts ACTION maps into JSON rows.
@@ -15501,6 +15515,1074 @@ var gotos = [
 		target: 129
 	}
 ];
+var ast = [
+	{
+		name: "grammar_file",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "name_decl"
+				},
+				{
+					kind: "repeat",
+					element: {
+						kind: "reference",
+						name: "section"
+					}
+				},
+				{
+					kind: "reference",
+					name: "start_decl"
+				},
+				{
+					kind: "reference",
+					name: "grammar_section"
+				},
+				{
+					kind: "optional",
+					element: {
+						kind: "reference",
+						name: "ast_section"
+					}
+				},
+				{
+					kind: "optional",
+					element: {
+						kind: "reference",
+						name: "transform_section"
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "name_decl",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "name_kw"
+				},
+				{
+					kind: "reference",
+					name: "grammar_name"
+				},
+				{
+					kind: "reference",
+					name: "semicolon"
+				}
+			]
+		}
+	},
+	{
+		name: "grammar_name",
+		expression: {
+			kind: "choice",
+			alternatives: [
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "identifier"
+					}
+				},
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "string_literal"
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "section",
+		expression: {
+			kind: "choice",
+			alternatives: [
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "token_section"
+					}
+				},
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "skip_section"
+					}
+				},
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "states_section"
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "token_section",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "tokens_kw"
+				},
+				{
+					kind: "reference",
+					name: "token_def"
+				},
+				{
+					kind: "repeat",
+					element: {
+						kind: "reference",
+						name: "token_def"
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "skip_section",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "skip_kw"
+				},
+				{
+					kind: "reference",
+					name: "token_def"
+				},
+				{
+					kind: "repeat",
+					element: {
+						kind: "reference",
+						name: "token_def"
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "states_section",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "states_kw"
+				},
+				{
+					kind: "reference",
+					name: "state_name"
+				},
+				{
+					kind: "repeat",
+					element: {
+						kind: "sequence",
+						elements: [
+							{
+								kind: "reference",
+								name: "comma"
+							},
+							{
+								kind: "reference",
+								name: "state_name"
+							}
+						]
+					}
+				},
+				{
+					kind: "reference",
+					name: "semicolon"
+				}
+			]
+		}
+	},
+	{
+		name: "token_def",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "identifier"
+				},
+				{
+					kind: "reference",
+					name: "equal"
+				},
+				{
+					kind: "reference",
+					name: "regex_literal"
+				},
+				{
+					kind: "reference",
+					name: "semicolon"
+				}
+			]
+		}
+	},
+	{
+		name: "state_name",
+		expression: {
+			kind: "reference",
+			name: "identifier"
+		}
+	},
+	{
+		name: "start_decl",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "start_kw"
+				},
+				{
+					kind: "reference",
+					name: "identifier"
+				},
+				{
+					kind: "reference",
+					name: "semicolon"
+				}
+			]
+		}
+	},
+	{
+		name: "grammar_section",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "grammar_kw"
+				},
+				{
+					kind: "reference",
+					name: "production"
+				},
+				{
+					kind: "repeat",
+					element: {
+						kind: "reference",
+						name: "production"
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "ast_section",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "ast_kw"
+				},
+				{
+					kind: "reference",
+					name: "ast_type"
+				},
+				{
+					kind: "repeat",
+					element: {
+						kind: "reference",
+						name: "ast_type"
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "transform_section",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "transform_kw"
+				},
+				{
+					kind: "reference",
+					name: "transform_rule"
+				},
+				{
+					kind: "repeat",
+					element: {
+						kind: "reference",
+						name: "transform_rule"
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "production",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "identifier"
+				},
+				{
+					kind: "reference",
+					name: "equal"
+				},
+				{
+					kind: "reference",
+					name: "expression"
+				},
+				{
+					kind: "reference",
+					name: "semicolon"
+				}
+			]
+		}
+	},
+	{
+		name: "ast_type",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "identifier"
+				},
+				{
+					kind: "reference",
+					name: "equal"
+				},
+				{
+					kind: "reference",
+					name: "expression"
+				},
+				{
+					kind: "reference",
+					name: "semicolon"
+				}
+			]
+		}
+	},
+	{
+		name: "transform_rule",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "identifier"
+				},
+				{
+					kind: "reference",
+					name: "arrow"
+				},
+				{
+					kind: "reference",
+					name: "labeled_transform"
+				},
+				{
+					kind: "repeat",
+					element: {
+						kind: "sequence",
+						elements: [
+							{
+								kind: "reference",
+								name: "bar"
+							},
+							{
+								kind: "reference",
+								name: "labeled_transform"
+							}
+						]
+					}
+				},
+				{
+					kind: "reference",
+					name: "semicolon"
+				}
+			]
+		}
+	},
+	{
+		name: "labeled_transform",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "hash"
+				},
+				{
+					kind: "reference",
+					name: "identifier"
+				},
+				{
+					kind: "reference",
+					name: "transform_expr"
+				}
+			]
+		}
+	},
+	{
+		name: "transform_expr",
+		expression: {
+			kind: "choice",
+			alternatives: [
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "drop_kw"
+					}
+				},
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "pass_expr"
+					}
+				},
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "fold_left_expr"
+					}
+				},
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "fold_right_expr"
+					}
+				},
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "flatten_expr"
+					}
+				},
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "build_expr"
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "pass_expr",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "pass_kw"
+				},
+				{
+					kind: "reference",
+					name: "lpar"
+				},
+				{
+					kind: "reference",
+					name: "reference"
+				},
+				{
+					kind: "reference",
+					name: "rpar"
+				}
+			]
+		}
+	},
+	{
+		name: "fold_left_expr",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "fold_left_kw"
+				},
+				{
+					kind: "reference",
+					name: "lpar"
+				},
+				{
+					kind: "reference",
+					name: "build_target"
+				},
+				{
+					kind: "reference",
+					name: "comma"
+				},
+				{
+					kind: "reference",
+					name: "reference_list"
+				},
+				{
+					kind: "reference",
+					name: "rpar"
+				}
+			]
+		}
+	},
+	{
+		name: "fold_right_expr",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "fold_right_kw"
+				},
+				{
+					kind: "reference",
+					name: "lpar"
+				},
+				{
+					kind: "reference",
+					name: "build_target"
+				},
+				{
+					kind: "reference",
+					name: "comma"
+				},
+				{
+					kind: "reference",
+					name: "reference_list"
+				},
+				{
+					kind: "reference",
+					name: "rpar"
+				}
+			]
+		}
+	},
+	{
+		name: "flatten_expr",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "flatten_kw"
+				},
+				{
+					kind: "reference",
+					name: "lpar"
+				},
+				{
+					kind: "reference",
+					name: "build_target"
+				},
+				{
+					kind: "reference",
+					name: "comma"
+				},
+				{
+					kind: "reference",
+					name: "reference"
+				},
+				{
+					kind: "reference",
+					name: "comma"
+				},
+				{
+					kind: "reference",
+					name: "reference"
+				},
+				{
+					kind: "reference",
+					name: "rpar"
+				}
+			]
+		}
+	},
+	{
+		name: "build_expr",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "build_target"
+				},
+				{
+					kind: "optional",
+					element: {
+						kind: "sequence",
+						elements: [
+							{
+								kind: "reference",
+								name: "lpar"
+							},
+							{
+								kind: "reference",
+								name: "reference_list"
+							},
+							{
+								kind: "reference",
+								name: "rpar"
+							}
+						]
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "build_target",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "identifier"
+				},
+				{
+					kind: "reference",
+					name: "dot"
+				},
+				{
+					kind: "reference",
+					name: "hash"
+				},
+				{
+					kind: "reference",
+					name: "identifier"
+				}
+			]
+		}
+	},
+	{
+		name: "reference_list",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "reference"
+				},
+				{
+					kind: "repeat",
+					element: {
+						kind: "sequence",
+						elements: [
+							{
+								kind: "reference",
+								name: "comma"
+							},
+							{
+								kind: "reference",
+								name: "reference"
+							}
+						]
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "reference",
+		expression: {
+			kind: "reference",
+			name: "identifier"
+		}
+	},
+	{
+		name: "expression",
+		expression: {
+			kind: "reference",
+			name: "choice"
+		}
+	},
+	{
+		name: "choice",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "alternative"
+				},
+				{
+					kind: "repeat",
+					element: {
+						kind: "sequence",
+						elements: [
+							{
+								kind: "reference",
+								name: "bar"
+							},
+							{
+								kind: "reference",
+								name: "alternative"
+							}
+						]
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "alternative",
+		expression: {
+			kind: "reference",
+			name: "labeled_alternative"
+		}
+	},
+	{
+		name: "labeled_alternative",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "optional",
+					element: {
+						kind: "sequence",
+						elements: [
+							{
+								kind: "reference",
+								name: "hash"
+							},
+							{
+								kind: "reference",
+								name: "identifier"
+							}
+						]
+					}
+				},
+				{
+					kind: "reference",
+					name: "sequence"
+				}
+			]
+		}
+	},
+	{
+		name: "sequence",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "factor"
+				},
+				{
+					kind: "repeat",
+					element: {
+						kind: "reference",
+						name: "factor"
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "factor",
+		expression: {
+			kind: "choice",
+			alternatives: [
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "bracketed"
+					}
+				},
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "repeat"
+					}
+				},
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "group"
+					}
+				},
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "primary"
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "bracketed",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "lbracket"
+				},
+				{
+					kind: "reference",
+					name: "expression"
+				},
+				{
+					kind: "reference",
+					name: "rbracket"
+				},
+				{
+					kind: "optional",
+					element: {
+						kind: "sequence",
+						elements: [
+							{
+								kind: "reference",
+								name: "colon"
+							},
+							{
+								kind: "reference",
+								name: "identifier"
+							}
+						]
+					}
+				}
+			]
+		}
+	},
+	{
+		name: "repeat",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "lbrace"
+				},
+				{
+					kind: "reference",
+					name: "expression"
+				},
+				{
+					kind: "reference",
+					name: "rbrace"
+				}
+			]
+		}
+	},
+	{
+		name: "group",
+		expression: {
+			kind: "sequence",
+			elements: [
+				{
+					kind: "reference",
+					name: "lpar"
+				},
+				{
+					kind: "reference",
+					name: "expression"
+				},
+				{
+					kind: "reference",
+					name: "rpar"
+				}
+			]
+		}
+	},
+	{
+		name: "primary",
+		expression: {
+			kind: "choice",
+			alternatives: [
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "string_literal"
+					}
+				},
+				{
+					label: null,
+					expression: {
+						kind: "reference",
+						name: "identifier"
+					}
+				}
+			]
+		}
+	}
+];
+var transform = [
+	{
+		production: "grammar_file$repeat_0",
+		alternatives: [
+			{
+				label: "main",
+				expression: {
+					kind: "flatten",
+					typeName: "grammar_file",
+					variant: "sections",
+					head: "section",
+					tail: "grammar_file$repeat_0"
+				}
+			}
+		]
+	},
+	{
+		production: "token_section$repeat_1",
+		alternatives: [
+			{
+				label: "main",
+				expression: {
+					kind: "flatten",
+					typeName: "token_section",
+					variant: "definitions",
+					head: "token_def",
+					tail: "token_section$repeat_1"
+				}
+			}
+		]
+	},
+	{
+		production: "skip_section$repeat_2",
+		alternatives: [
+			{
+				label: "main",
+				expression: {
+					kind: "flatten",
+					typeName: "skip_section",
+					variant: "definitions",
+					head: "token_def",
+					tail: "skip_section$repeat_2"
+				}
+			}
+		]
+	},
+	{
+		production: "grammar_section$repeat_4",
+		alternatives: [
+			{
+				label: "main",
+				expression: {
+					kind: "flatten",
+					typeName: "grammar_section",
+					variant: "productions",
+					head: "production",
+					tail: "grammar_section$repeat_4"
+				}
+			}
+		]
+	},
+	{
+		production: "ast_section$repeat_5",
+		alternatives: [
+			{
+				label: "main",
+				expression: {
+					kind: "flatten",
+					typeName: "ast_section",
+					variant: "types",
+					head: "ast_type",
+					tail: "ast_section$repeat_5"
+				}
+			}
+		]
+	},
+	{
+		production: "transform_section$repeat_6",
+		alternatives: [
+			{
+				label: "main",
+				expression: {
+					kind: "flatten",
+					typeName: "transform_section",
+					variant: "rules",
+					head: "transform_rule",
+					tail: "transform_section$repeat_6"
+				}
+			}
+		]
+	},
+	{
+		production: "transform_rule$repeat_7",
+		alternatives: [
+			{
+				label: "main",
+				expression: {
+					kind: "flatten",
+					typeName: "transform_rule",
+					variant: "alternatives",
+					head: "labeled_transform",
+					tail: "transform_rule$repeat_7"
+				}
+			}
+		]
+	},
+	{
+		production: "reference_list$repeat_8",
+		alternatives: [
+			{
+				label: "main",
+				expression: {
+					kind: "flatten",
+					typeName: "reference_list",
+					variant: "references",
+					head: "reference",
+					tail: "reference_list$repeat_8"
+				}
+			}
+		]
+	},
+	{
+		production: "choice$repeat_9",
+		alternatives: [
+			{
+				label: "main",
+				expression: {
+					kind: "flatten",
+					typeName: "choice",
+					variant: "alternatives",
+					head: "alternative",
+					tail: "choice$repeat_9"
+				}
+			}
+		]
+	},
+	{
+		production: "sequence$repeat_10",
+		alternatives: [
+			{
+				label: "main",
+				expression: {
+					kind: "flatten",
+					typeName: "sequence",
+					variant: "factors",
+					head: "factor",
+					tail: "sequence$repeat_10"
+				}
+			}
+		]
+	}
+];
 var bootstrapTableJson = {
 	version: version,
 	algorithm: algorithm,
@@ -15513,7 +16595,9 @@ var bootstrapTableJson = {
 	parserStateCount: parserStateCount,
 	productions: productions,
 	actions: actions,
-	gotos: gotos
+	gotos: gotos,
+	ast: ast,
+	transform: transform
 };
 
 const bootstrapTable = bootstrapTableJson;
@@ -16104,8 +17188,8 @@ class ParserLr {
     /**
      * Creates a parser from a serialized parse table.
      *
-     * @param table - Parse table containing lexer metadata and parser entries.
-     * @returns A parser that can lex and parse using the table.
+     * @param table - Parse table containing lexer metadata, parser entries, and optional AST transforms.
+     * @returns A parser that lexes, parses, and applies transforms from the table JSON.
      */
     static fromParseTable(table) {
         return new ParserLr(table.toGrammar(), table);
@@ -16252,8 +17336,8 @@ class ParseContext {
     /**
      * Builds a parse context from serialized parse table JSON.
      *
-     * @param json - Serialized parse table JSON.
-     * @returns Parser and parse table ready for lexing or parsing.
+     * @param json - Serialized parse table JSON including `ast` and `transform` when present.
+     * @returns Parser and parse table ready for lexing and full AST parsing.
      */
     static fromTableJson(json) {
         const table = ParseTable.fromJsonString(json);
@@ -16329,19 +17413,19 @@ class ParseContext {
         return this.parser.lexChunkStreamAsync(chunks);
     }
     /**
-     * Parses a token stream into a concrete syntax tree.
+     * Parses a token stream into an AST, applying transforms from the grammar or table when present.
      *
      * @param tokens - Token stream ending with `$eof`.
-     * @returns Parse tree rooted at the grammar start symbol, or null on syntax error.
+     * @returns Transformed AST, CST when no transform rules exist, or null on syntax error.
      */
     parse(tokens) {
         return this.parser.parse(tokens);
     }
     /**
-     * Lexes and parses source text into a concrete syntax tree.
+     * Lexes and parses source text into an AST, applying transforms when present.
      *
      * @param source - Input text to parse.
-     * @returns Parse tree rooted at the grammar start symbol, or null on syntax error.
+     * @returns Transformed AST, CST when no transform rules exist, or null on syntax error.
      */
     parseSource(source) {
         return this.parser.parseSource(source);