Deprecate Program in v1 AST

Author: chancancode

packages/@glimmer/syntax/lib/generation/printer.ts

@@ -113,8 +113,6 @@ export default class Printer {
       case 'PathExpression':
       case 'SubExpression':
         return this.Expression(node);
-      case 'Program':
-        return this.Block(node);
       case 'ConcatStatement':
         // should have an AttrNode parent
         return this.ConcatStatement(node);
@@ -174,15 +172,20 @@ export default class Printer {
       case 'ElementNode':
         return this.ElementNode(statement);
       case 'Block':
-      case 'Template':
         return this.Block(statement);
+      case 'Template':
+        return this.Template(statement);
       case 'AttrNode':
         // should have element
         return this.AttrNode(statement);
     }
   }
 
-  Block(block: ASTv1.Block | ASTv1.Program | ASTv1.Template): void {
+  Template(template: ASTv1.Template): void {
+    this.TopLevelStatements(template.body);
+  }
+
+  Block(block: ASTv1.Block): void {
     /*
       When processing a template like:
 

packages/@glimmer/syntax/lib/parser/handlebars-node-visitors.ts

@@ -35,7 +35,6 @@ export abstract class HandlebarsNodeVisitors extends Parser {
     if (this.isTopLevel) {
       node = b.template({
         body,
-        blockParams: program.blockParams,
         loc: this.source.spanFor(program.loc),
       });
     } else {

packages/@glimmer/syntax/lib/parser/tokenizer-event-handlers.ts

@@ -461,21 +461,17 @@ export function preprocess(
     end: offsets.endPosition,
   };
 
-  let program = new TokenizerEventHandlers(source, entityParser, mode).acceptTemplate(ast);
-
-  if (options.strictMode) {
-    program.blockParams = options.locals ?? [];
-  }
+  let template = new TokenizerEventHandlers(source, entityParser, mode).acceptTemplate(ast);
 
   if (options && options.plugins && options.plugins.ast) {
     for (const transform of options.plugins.ast) {
       let env: ASTPluginEnvironment = assign({}, options, { syntax }, { plugins: undefined });
 
       let pluginResult = transform(env);
 
-      traverse(program, pluginResult.visitor);
+      traverse(template, pluginResult.visitor);
     }
   }
 
-  return program;
+  return template;
 }

packages/@glimmer/syntax/lib/traversal/traverse.ts

@@ -67,8 +67,11 @@ function getNodeHandler<N extends ASTv1.Node>(
   visitor: NodeVisitor,
   nodeType: N['type']
 ): NodeTraversal<ASTv1.Node> | undefined {
-  if (nodeType === 'Template' || nodeType === 'Block') {
-    if (visitor.Program) {
+  if (visitor.Program) {
+    if (
+      (nodeType === 'Template' && !visitor.Template) ||
+      (nodeType === 'Block' && !visitor.Block)
+    ) {
       deprecate(
         `The 'Program' visitor node is deprecated. Use 'Template' or 'Block' instead (node was '${nodeType}') `
       );

packages/@glimmer/syntax/lib/traversal/visitor.ts

@@ -13,6 +13,11 @@ export type NodeTraversal<N extends ASTv1.Node> = FullNodeTraversal<N> | NodeHan
 
 export type NodeVisitor = { [P in keyof ASTv1.Nodes]?: NodeTraversal<ASTv1.Nodes[P]> } & {
   All?: NodeTraversal<ASTv1.Node>;
+
+  /**
+   * @deprecated use Template or Block instead
+   */
+  Program?: NodeTraversal<ASTv1.Template | ASTv1.Block>;
 };
 
 export interface FullKeyTraversal<N extends ASTv1.Node, K extends string> {
@@ -27,4 +32,9 @@ export type KeyTraversal<N extends ASTv1.Node, K extends VisitorKey<N>> =
 
 export type KeysVisitor<N extends ASTv1.Node> = { [P in VisitorKey<N>]?: KeyTraversal<N, P> } & {
   All?: KeyTraversal<N, VisitorKey<N>>;
+
+  /**
+   * @deprecated use Template or Block instead
+   */
+  Program?: KeyTraversal<ASTv1.Template | ASTv1.Block, 'body'>;
 };

packages/@glimmer/syntax/lib/traversal/walker.ts

@@ -33,40 +33,21 @@ export default class Walker {
     switch (node.type) {
       case 'Block':
       case 'Template':
-        return visitors.Program(this, node as unknown as ASTv1.Program, callback);
+        walkBody(this, node.body, callback);
+        return;
       case 'ElementNode':
-        return visitors.ElementNode(this, node, callback);
+        walkBody(this, node.children, callback);
+        return;
       case 'BlockStatement':
-        return visitors.BlockStatement(this, node, callback);
+        this.visit(node.program, callback);
+        this.visit(node.inverse || null, callback);
+        return;
       default:
         return;
     }
   }
 }
 
-const visitors = {
-  Program(walker: Walker, node: ASTv1.Program, callback: NodeCallback<ASTv1.Statement>) {
-    walkBody(walker, node.body, callback);
-  },
-
-  Template(walker: Walker, node: ASTv1.Template, callback: NodeCallback<ASTv1.Node>) {
-    walkBody(walker, node.body, callback);
-  },
-
-  Block(walker: Walker, node: ASTv1.Block, callback: NodeCallback<ASTv1.Node>) {
-    walkBody(walker, node.body, callback);
-  },
-
-  ElementNode(walker: Walker, node: ASTv1.ElementNode, callback: NodeCallback<ASTv1.Node>) {
-    walkBody(walker, node.children, callback);
-  },
-
-  BlockStatement(walker: Walker, node: ASTv1.BlockStatement, callback: NodeCallback<ASTv1.Block>) {
-    walker.visit(node.program, callback);
-    walker.visit(node.inverse || null, callback);
-  },
-} as const;
-
 function walkBody(
   walker: Walker,
   body: ASTv1.Statement[],

packages/@glimmer/syntax/lib/v1/nodes-v1.ts

@@ -12,26 +12,30 @@ export interface BaseNode {
 
 export interface CommonProgram extends BaseNode {
   body: Statement[];
-  blockParams: string[];
-  chained?: boolean;
-}
-
-export interface Program extends CommonProgram {
-  type: 'Program';
 }
 
 export interface Block extends CommonProgram {
   type: 'Block';
+  blockParams: string[];
   blockParamNodes: BlockParam[];
+  chained?: boolean;
 }
 
 export type EntityEncodingState = 'transformed' | 'raw';
 
 export interface Template extends CommonProgram {
   type: 'Template';
+
+  /**
+   * @deprecated Template can never have block params
+   */
+  blockParams: never[];
 }
 
-export type PossiblyDeprecatedBlock = Block | Template;
+/**
+ * @deprecated use Template or Block instead
+ */
+export type Program = Template | Block;
 
 export interface CallParts {
   path: Expression;
@@ -320,7 +324,6 @@ export type Nodes = SharedNodes & {
   ElementStartNode: ElementStartNode;
   ElementPartNode: ElementPartNode;
   ElementNameNode: ElementNameNode;
-  Program: Program;
   Template: Template;
   Block: Block;
   BlockStatement: BlockStatement;

packages/@glimmer/syntax/lib/v1/parser-builders.ts

@@ -1,5 +1,5 @@
 import type { Dict, Nullable, PresentArray } from '@glimmer/interfaces';
-import { assert } from '@glimmer/util';
+import { assert, deprecate } from '@glimmer/util';
 
 import type { ParserNodeBuilder } from '../parser';
 import type { SourceLocation } from '../source/location';
@@ -50,19 +50,16 @@ class Builders {
     };
   }
 
-  template({
-    body,
-    blockParams,
-    loc,
-  }: {
-    body?: ASTv1.Statement[];
-    blockParams?: string[];
-    loc: SourceSpan;
-  }): ASTv1.Template {
+  template({ body, loc }: { body?: ASTv1.Statement[]; loc: SourceSpan }): ASTv1.Template {
     return {
       type: 'Template',
       body: body || [],
-      blockParams: blockParams || [],
+      get blockParams() {
+        deprecate(
+          `Template nodes can never have block params. This array is always empty and will be removed in the future.`
+        );
+        return [];
+      },
       loc,
     };
   }

packages/@glimmer/syntax/lib/v1/public-builders.ts

@@ -50,12 +50,14 @@ function buildMustache(
   };
 }
 
+type PossiblyDeprecatedBlock = ASTv1.Block | ASTv1.Template;
+
 function buildBlock(
   path: BuilderHead,
   params: Nullable<ASTv1.Expression[]>,
   hash: Nullable<ASTv1.Hash>,
-  _defaultBlock: ASTv1.PossiblyDeprecatedBlock,
-  _elseBlock?: Nullable<ASTv1.PossiblyDeprecatedBlock>,
+  _defaultBlock: PossiblyDeprecatedBlock,
+  _elseBlock?: Nullable<PossiblyDeprecatedBlock>,
   loc?: SourceLocation,
   openStrip?: ASTv1.StripFlags,
   inverseStrip?: ASTv1.StripFlags,
@@ -454,13 +456,14 @@ function buildProgram(
   body?: ASTv1.Statement[],
   blockParams?: string[],
   loc?: SourceLocation
-): ASTv1.Template {
-  return {
-    type: 'Template',
-    body: body || [],
-    blockParams: blockParams || [],
-    loc: buildLoc(loc || null),
-  };
+): ASTv1.Template | ASTv1.Block {
+  deprecate(`b.program is deprecated. Use b.template or b.blockItself instead.`);
+
+  if (blockParams && blockParams.length) {
+    return buildBlockItself(body, blockParams, false, loc);
+  } else {
+    return buildTemplate(body, loc);
+  }
 }
 
 function buildBlockItself(
@@ -480,15 +483,58 @@ function buildBlockItself(
   };
 }
 
+type BuildTemplateRestArgs =
+  | [loc?: SourceLocation | undefined]
+  | [blockParams?: string[] | never[] | undefined, loc?: SourceLocation | undefined];
+
+function buildTemplate(body?: ASTv1.Statement[], loc?: SourceLocation): ASTv1.Template;
+function buildTemplate(
+  body?: ASTv1.Statement[],
+  blockParams?: never[],
+  loc?: SourceLocation
+): ASTv1.Template;
 function buildTemplate(
   body?: ASTv1.Statement[],
   blockParams?: string[],
   loc?: SourceLocation
-): ASTv1.Template {
+): never;
+function buildTemplate(body?: ASTv1.Statement[], ...args: BuildTemplateRestArgs): ASTv1.Template {
+  let blockParams: string[] | undefined;
+  let loc: SourceLocation | undefined;
+
+  if (args.length === 1) {
+    let [arg] = args;
+
+    if (Array.isArray(arg)) {
+      blockParams = arg;
+    } else {
+      loc = arg;
+    }
+  } else if (args.length > 1) {
+    // force this to be an empty array to trigger the deprecation message
+    blockParams = (args[0] || []) as string[];
+    loc = args[1];
+  }
+
+  if (blockParams) {
+    if (blockParams.length === 0) {
+      deprecate(
+        `Template nodes can never have block params, you may omit the second argument to b.template`
+      );
+    } else {
+      throw new Error('Template nodes can never have block params');
+    }
+  }
+
   return {
     type: 'Template',
     body: body || [],
-    blockParams: blockParams || [],
+    get blockParams() {
+      deprecate(
+        `Template nodes can never have block params. This array is always empty and will be removed in the future.`
+      );
+      return [];
+    },
     loc: buildLoc(loc || null),
   };
 }

packages/@glimmer/syntax/lib/v1/visitor-keys.ts

@@ -3,7 +3,6 @@ import type * as ASTv1 from './api';
 // ensure stays in sync with typing
 // ParentNode and ChildKey types are derived from VisitorKeysMap
 const visitorKeys = {
-  Program: ['body'],
   Template: ['body'],
   Block: ['body'],
 
@@ -35,11 +34,6 @@ const visitorKeys = {
   Hash: ['pairs'],
   HashPair: ['value'],
   BlockParam: [],
-
-  // v2 new nodes
-  NamedBlock: ['attributes', 'modifiers', 'children', 'comments'],
-  SimpleElement: ['attributes', 'modifiers', 'children', 'comments'],
-  Component: ['head', 'attributes', 'modifiers', 'children', 'comments'],
 } as const;
 
 type VisitorKeysMap = typeof visitorKeys;