Allow AST plugins to manipulate Javascript scope

README.md

@@ -77,6 +77,7 @@ interface NodeOptions extends Options {
   // Options handling rules:
   //
   //  - we add `content`, which is the original string form of the template
+  //  - we add `meta.jsutils: JSUtils`, which gives AST transform plugins access to methods for manipulating the outer Javascript scope. This only works in non-strict-mode templates on Ember 3.28+ because prior to that only strict-mode templates could use lexically scoped values.
   //  - we have special parsing for `scope` which becomes `locals` when passed
   //    to your precompile
   //  - anything else the user passes to `precompileTemplate` will be passed

__tests__/tests.ts

@@ -5,6 +5,8 @@ import TransformTemplateLiterals from '@babel/plugin-transform-template-literals
 import TransformModules from '@babel/plugin-transform-modules-amd';
 import TransformUnicodeEscapes from '@babel/plugin-transform-unicode-escapes';
 import { stripIndent } from 'common-tags';
+import { WithJSUtils } from '../src/js-utils';
+import type { ASTPluginBuilder, ASTPluginEnvironment } from '@glimmer/syntax';
 
 describe('htmlbars-inline-precompile', function () {
   let precompile: NonNullable<Options['precompile']>;
@@ -25,7 +27,8 @@ describe('htmlbars-inline-precompile', function () {
   beforeEach(function () {
     optionsReceived = undefined;
     precompile = (template, options) => {
-      optionsReceived = options;
+      optionsReceived = { ...options };
+      delete optionsReceived.meta;
       return `"precompiled(${template})"`;
     };
 
@@ -93,6 +96,7 @@ describe('htmlbars-inline-precompile', function () {
 
     expect(optionsReceived).toEqual({
       contents: source,
+      locals: [],
     });
   });
 
@@ -106,6 +110,7 @@ describe('htmlbars-inline-precompile', function () {
     expect(optionsReceived).toEqual({
       contents: source,
       isProduction: true,
+      locals: [],
     });
   });
 
@@ -117,6 +122,7 @@ describe('htmlbars-inline-precompile', function () {
 
     expect(optionsReceived).toEqual({
       contents: source,
+      locals: [],
     });
   });
 
@@ -159,6 +165,7 @@ describe('htmlbars-inline-precompile', function () {
       stringifiedThing: {
         foo: 'baz',
       },
+      locals: [],
     });
   });
 
@@ -244,6 +251,7 @@ describe('htmlbars-inline-precompile', function () {
 
     expect(optionsReceived).toEqual({
       contents: source,
+      locals: [],
     });
   });
 
@@ -570,13 +578,9 @@ describe('htmlbars-inline-precompile', function () {
     // eslint-disable-next-line @typescript-eslint/no-var-requires
     const compiler = require('ember-source/dist/ember-template-compiler');
 
-    beforeEach(function () {
-      precompile = (template, options) => {
-        return compiler.precompile(template, options);
-      };
-    });
-
     it('includes the original template content', function () {
+      precompile = (template, options) => compiler.precompile(template, options);
+
       let transformed = transform(stripIndent`
         import { precompileTemplate } from '@ember/template-compilation';
 
@@ -585,6 +589,143 @@ describe('htmlbars-inline-precompile', function () {
 
       expect(transformed).toContain(`hello {{firstName}}`);
     });
+
+    it('allows AST transform to bind a JS expression', function () {
+      precompile = runASTTransform(compiler, function (env) {
+        return {
+          name: 'sample-transform',
+          visitor: {
+            PathExpression(node) {
+              if (node.original === 'onePlusOne') {
+                let name = env.meta.jsutils.bindValue('1+1', { nameHint: 'two' });
+                return env.syntax.builders.path(name);
+              }
+              return undefined;
+            },
+          },
+        };
+      });
+
+      let transformed = transform(stripIndent`
+        import { precompileTemplate } from '@ember/template-compilation';
+        const template = precompileTemplate('<Message @text={{onePlusOne}} />');
+      `);
+
+      expect(transformed).toContain(`@text={{two}}`);
+      expect(transformed).toContain(`locals: [two]`);
+      expect(transformed).toContain(`let two = 1 + 1`);
+    });
+
+    it('adds locals to the compiled output', function () {
+      precompile = compileASTTransform(compiler, function (env) {
+        return {
+          name: 'sample-transform',
+          visitor: {
+            PathExpression(node) {
+              if (node.original === 'onePlusOne') {
+                let name = env.meta.jsutils.bindValue('1+1', { nameHint: 'two' });
+                return env.syntax.builders.path(name);
+              }
+              return undefined;
+            },
+          },
+        };
+      });
+
+      let transformed = transform(stripIndent`
+      import { precompileTemplate } from '@ember/template-compilation';
+      const template = precompileTemplate('<Message @text={{onePlusOne}} />');
+    `);
+      expect(transformed).toContain(`"scope": () => [two]`);
+    });
+
+    it('allows AST transform to bind a JS import', function () {
+      precompile = runASTTransform(compiler, function (env) {
+        return {
+          name: 'sample-transform',
+          visitor: {
+            PathExpression(node) {
+              if (node.original === 'onePlusOne') {
+                let name = env.meta.jsutils.bindImport('my-library', 'default', {
+                  nameHint: 'two',
+                });
+                return env.syntax.builders.path(name);
+              }
+              return undefined;
+            },
+          },
+        };
+      });
+
+      let transformed = transform(stripIndent`
+        import { precompileTemplate } from '@ember/template-compilation';
+        const template = precompileTemplate('<Message @text={{onePlusOne}} />');
+      `);
+
+      expect(transformed).toContain(`@text={{two}}`);
+      expect(transformed).toContain(`locals: [two]`);
+      expect(transformed).toContain(`import two from "my-library"`);
+    });
+
+    it('does not smash existing binding for import', function () {
+      precompile = runASTTransform(compiler, function (env) {
+        return {
+          name: 'sample-transform',
+          visitor: {
+            PathExpression(node) {
+              if (node.original === 'onePlusOne') {
+                let name = env.meta.jsutils.bindImport('my-library', 'default', {
+                  nameHint: 'two',
+                });
+                return env.syntax.builders.path(name);
+              }
+              return undefined;
+            },
+          },
+        };
+      });
+
+      let transformed = transform(stripIndent`
+        import { precompileTemplate } from '@ember/template-compilation';
+        export function inner() {
+          let two = 'twice';
+          const template = precompileTemplate('<Message @text={{onePlusOne}} />');
+        }
+      `);
+
+      expect(transformed).toContain(`@text={{two0}}`);
+      expect(transformed).toContain(`locals: [two0]`);
+      expect(transformed).toContain(`import two0 from "my-library"`);
+    });
+
+    it('does not smash existing binding for expression', function () {
+      precompile = runASTTransform(compiler, function (env) {
+        return {
+          name: 'sample-transform',
+          visitor: {
+            PathExpression(node) {
+              if (node.original === 'onePlusOne') {
+                let name = env.meta.jsutils.bindValue('1+1', { nameHint: 'two' });
+                return env.syntax.builders.path(name);
+              }
+              return undefined;
+            },
+          },
+        };
+      });
+
+      let transformed = transform(stripIndent`
+        import { precompileTemplate } from '@ember/template-compilation';
+        export default function() {
+          let two = 'twice';
+          const template = precompileTemplate('<Message @text={{onePlusOne}} />');
+        }
+      `);
+
+      expect(transformed).toContain(`@text={{two0}}`);
+      expect(transformed).toContain(`locals: [two0]`);
+      expect(transformed).toContain(`let two0 = 1 + 1`);
+    });
   });
 
   describe('scope', function () {
@@ -663,3 +804,34 @@ describe('htmlbars-inline-precompile', function () {
     });
   });
 });
+
+function runASTTransform(
+  compiler: any,
+  customTransform: ASTPluginBuilder<WithJSUtils<ASTPluginEnvironment>>
+) {
+  return (template: string, options: Record<string, unknown>) => {
+    let ast = compiler._preprocess(template, {
+      ...options,
+      plugins: { ast: [customTransform] },
+    });
+    return (
+      '{ transformedHBS: `' +
+      compiler._print(ast) +
+      '`, locals: [' +
+      ((options.locals as string[]) ?? []).join(',') +
+      ']}'
+    );
+  };
+}
+
+function compileASTTransform(
+  compiler: any,
+  customTransform: ASTPluginBuilder<WithJSUtils<ASTPluginEnvironment>>
+) {
+  return (template: string, options: Record<string, unknown>) => {
+    return compiler.precompile(template, {
+      ...options,
+      plugins: { ast: [customTransform] },
+    });
+  };
+}

package.json

@@ -41,12 +41,13 @@
     "@babel/plugin-transform-template-literals": "^7.14.5",
     "@babel/plugin-transform-unicode-escapes": "^7.14.5",
     "@babel/traverse": "^7.14.5",
+    "@glimmer/syntax": "^0.84.2",
     "@types/babel__traverse": "^7.11.1",
     "@types/jest": "^26.0.23",
     "@typescript-eslint/eslint-plugin": "^4.28.4",
     "@typescript-eslint/parser": "^4.28.4",
     "common-tags": "^1.8.0",
-    "ember-source": "^3.27.5",
+    "ember-source": "^3.28.9",
     "eslint": "^6.8.0",
     "eslint-config-prettier": "^6.15.0",
     "eslint-plugin-node": "^11.1.0",

src/js-utils.ts

@@ -0,0 +1,95 @@
+import type { types as t } from '@babel/core';
+import type * as Babel from '@babel/core';
+import type { NodePath } from '@babel/traverse';
+import type { ImportUtil } from 'babel-import-util';
+
+// This exists to give AST plugins a controlled interface for influencing the
+// surrounding Javascript scope
+export class JSUtils {
+  #babel: typeof Babel;
+  #program: NodePath<t.Program>;
+  #template: NodePath<t.Expression>;
+  #locals: string[];
+  #importer: ImportUtil;
+
+  constructor(
+    babel: typeof Babel,
+    program: NodePath<t.Program>,
+    template: NodePath<t.Expression>,
+    locals: string[],
+    importer: ImportUtil
+  ) {
+    this.#babel = babel;
+    this.#program = program;
+    this.#template = template;
+    this.#locals = locals;
+    this.#importer = importer;
+  }
+
+  bindValue(expression: string, opts?: { nameHint?: string }): string {
+    let name = this.#unusedNameLike(opts?.nameHint ?? 'a');
+    let t = this.#babel.types;
+    this.#program.unshiftContainer(
+      'body',
+      t.variableDeclaration('let', [
+        t.variableDeclarator(t.identifier(name), this.#parseExpression(expression)),
+      ])
+    );
+    this.#locals.push(name);
+    return name;
+  }
+
+  bindImport(moduleSpecifier: string, exportedName: string, opts?: { nameHint?: string }): string {
+    let identifier = this.#importer.import(
+      this.#template,
+      moduleSpecifier,
+      exportedName,
+      opts?.nameHint
+    );
+    this.#locals.push(identifier.name);
+    return identifier.name;
+  }
+
+  #parseExpression(expressionString: string): t.Expression {
+    let parsed = this.#babel.parse(expressionString);
+    if (!parsed) {
+      throw new Error(`JSUtils.bindValue could not understand the expression: ${expressionString}`);
+    }
+    let statements = body(parsed);
+    if (statements.length !== 1) {
+      throw new Error(
+        `JSUtils.bindValue expected to find exactly one expression but found ${statements.length} in: ${expressionString}`
+      );
+    }
+    let statement = statements[0];
+    if (statement.type !== 'ExpressionStatement') {
+      throw new Error(
+        `JSUtils.bindValue expected to find an expression but found ${statement.type} in: ${expressionString}`
+      );
+    }
+    return statement.expression;
+  }
+
+  #unusedNameLike(desiredName: string): string {
+    let candidate = desiredName;
+    let counter = 0;
+    while (this.#template.scope.hasBinding(candidate)) {
+      candidate = `${desiredName}${counter++}`;
+    }
+    return candidate;
+  }
+}
+
+// This extends Glimmer's ASTPluginEnvironment type to put our jsutils into
+// meta.
+export type WithJSUtils<T extends { meta?: object }> = {
+  meta: T['meta'] & { jsutils: JSUtils };
+} & T;
+
+function body(node: t.Program | t.File) {
+  if (node.type === 'File') {
+    return node.program.body;
+  } else {
+    return node.body;
+  }
+}