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`, which gives AST transform plugins access to methods for manipulating the surrounding javascript scope. See "JSUtils" below.
   //  - we have special parsing for `scope` which becomes `locals` when passed
   //    to your precompile
   //  - anything else the user passes to `precompileTemplate` will be passed
@@ -98,6 +99,45 @@ import * as babel from '@babel/core';
 babel.transform(someCode, { plugins: [makePlugin(loadTemplateCompiler)] });
 ```
 
+# JSUtils: Manipulating Javascript from within AST transforms
+
+AST transforms are plugins for modifying HBS templates at build time. Because those templates are embedded in Javascript and can access the Javascript scope, an AST plugin may want to introduce some new things into Javascript scope. That is what the JSUtils API is for.
+
+Your AST transform can access the JSUtils API via `env.meta.jsutils`. Here's an example transform.
+
+```js
+function myAstTransform(env) {
+  return {
+    name: 'my-ast-transform',
+    visitor: {
+      PathExpression(node, path) {
+        if (node.original === 'onePlusOne') {
+          let name = env.meta.jsutils.bindExpression('1+1', path, { nameHint: 'two' });
+          return env.syntax.builders.path(name);
+        }
+      },
+    },
+  };
+}
+```
+
+The example transform above would rewrite:
+
+```js
+import { precompileTemplate } from '@ember/template-compilation';
+precompileTemplate('<Counter @value={{onePlusOne}} />>');
+```
+
+To:
+
+```js
+import { precompileTemplate } from '@ember/template-compilation';
+let two = 1 + 1;
+precompileTemplate('<Counter @value={{two}} />', { scope: () => ({ two }) });
+```
+
+See the jsdoc comments in js-utils.js for details on the methods available.
+
 # Acknowledgement / History
 
 This repo derives from https://github.com/ember-cli/babel-plugin-htmlbars-inline-precompile

__tests__/mock-precompile.ts

@@ -1,3 +1,7 @@
 export function precompile(value: string) {
   return `precompiledFromPath(${value})`;
 }
+
+export function _preprocess(...args: unknown[]) {
+  return args;
+}