Add babel plugin for preprocessing templates with ast transforms

PORTING-ADDONS-TO-V2.md

@@ -61,10 +61,7 @@ The steps:
    ```json
    {
      "private": true,
-     "workspaces": [
-       "addon",
-       "test-app"
-     ]
+     "workspaces": ["addon", "test-app"]
    }
    ```
 
@@ -219,6 +216,7 @@ Now that we've separated the test-app and docs app concerns from the addon, we c
    `yarn add --dev @embroider/addon-dev rollup @rollup/plugin-babel @babel/core @babel/plugin-proposal-class-properties @babel/plugin-proposal-decorators`
 
 6. Grab the [example babel config](https://github.com/embroider-build/embroider/blob/main/packages/addon-dev/sample-babel.config.json) and save it as `addon/babel.config.json`
+   - If you addon requires template transforms in order to publish to a shareable format. Apply transforms using the `@embroider/addon-dev/template-transform-plugin`. View how to use this in the [example babel.config.js](https://github.com/embroider-build/embroider/blob/main/packages/addon-dev/sample-babel.config.js)
 7. Grab the [example rollup config](https://github.com/embroider-build/embroider/blob/main/packages/addon-dev/sample-rollup.config.js) and save it as `addon/rollup.config.js`.
 8. Identify your **app reexports**. This is the list of modules from your addon that get reexported by files in the `addon/app` directory.
 9. Delete the `addon/app` directory. You aren't going to need it anymore.
@@ -230,10 +228,12 @@ Now that we've separated the test-app and docs app concerns from the addon, we c
 11. Still editing `addon/rollup.config.js`, customize the `appReexports` to match all your **app reexports** as identified above.
 12. Delete your `addon/index.js` file.
 13. Create a new `addon/addon-main.js` file (this replaces `addon/index.js`) with this exact content:
-   ```js
-   const { addonV1Shim } = require('@embroider/addon-shim');
-   module.exports = addonV1Shim(__dirname);
-   ```
+
+```js
+const { addonV1Shim } = require('@embroider/addon-shim');
+module.exports = addonV1Shim(__dirname);
+```
+
 14. In your `addon/.eslintrc.js`, replace "index.js" with "addon-main.js" so that our new file will lint correctly as Node code.
 15. In your `addon/package.json`, add these things:
     ```js

packages/addon-dev/.gitignore

@@ -4,6 +4,9 @@
 /src/**/*.js
 /src/**/*.d.ts
 /src/**/*.map
+/tests/**/*.js
+/tests/**/*.d.ts
+/tests/**/*.map
 
 # dependencies
 /node_modules/

packages/addon-dev/jest.config.js

@@ -0,0 +1,6 @@
+module.exports = {
+  testEnvironment: 'node',
+  testMatch: [
+    '<rootDir>/tests/**/*.test.js',
+  ],
+};

packages/addon-dev/package.json

@@ -14,6 +14,7 @@
   },
   "exports": {
     "./template-colocation-plugin": "./src/template-colocation-plugin.js",
+    "./template-transform-plugin": "./src/template-transform-plugin.js",
     "./rollup": "./src/rollup.js"
   },
   "files": [
@@ -22,8 +23,12 @@
     "src/**/*.d.ts",
     "src/**/*.js.map"
   ],
+  "scripts": {
+    "prepare": "tsc",
+    "test": "jest"
+  },
   "dependencies": {
-    "@embroider/shared-internals": "^1.7.1",
+    "@embroider/core": "^1.7.1",
     "@rollup/pluginutils": "^4.1.1",
     "assert-never": "^1.2.1",
     "fs-extra": "^10.0.0",
@@ -34,10 +39,21 @@
     "yargs": "^17.0.1"
   },
   "devDependencies": {
+    "@embroider/test-support": "0.36.0",
+    "@glimmer/syntax": "^0.84.2",
     "@types/fs-extra": "^9.0.12",
     "@types/minimatch": "^3.0.4",
     "@types/yargs": "^17.0.3",
-    "rollup": "^2.58.0"
+    "rollup": "^2.58.0",
+    "tmp": "^0.1.0"
+  },
+  "peerDependencies": {
+    "ember-source": "*"
+  },
+  "peerDependenciesMeta": {
+    "ember-source": {
+      "optional": true
+    }
   },
   "engines": {
     "node": "12.* || 14.* || >= 16"

packages/addon-dev/sample-babel.config.js

@@ -0,0 +1,25 @@
+// Some addons need to transform their templates before they have a portable format.
+// In "classic" builds this was done at the application. In embroider it should
+// be done during the addon build.
+const someAstTransformPlugin = require('./some-ast-transform-plugin');
+
+// The `@embroider/addon-dev/template-transform-plugin` has the following options:
+// `options.astTransforms` - an array of functions or paths to preprocess the GlimmerAST
+// `options.compilerPath` - Optional: Defaults to `ember-source/dist/ember-template-compiler`
+
+module.exports = {
+  plugins: [
+    '@embroider/addon-dev/template-colocation-plugin',
+    [
+      '@embroider/addon-dev/template-transform-plugin',
+      {
+        astTransforms: [
+          someAstTransformPlugin,
+          './path/to/another-template-transform-plugin',
+        ],
+      },
+    ],
+    ['@babel/plugin-proposal-decorators', { legacy: true }],
+    '@babel/plugin-proposal-class-properties',
+  ],
+};

packages/addon-dev/src/rollup-addon-dependencies.ts

@@ -5,7 +5,7 @@ import {
   emberVirtualPeerDeps,
   packageName,
   templateCompilationModules,
-} from '@embroider/shared-internals';
+} from '@embroider/core';
 
 const compilationModules = new Set(
   templateCompilationModules.map((m) => m.module)

packages/addon-dev/src/rollup-hbs-plugin.ts

@@ -6,7 +6,7 @@ import type {
   ResolvedId,
 } from 'rollup';
 import { readFileSync } from 'fs';
-import { hbsToJS } from '@embroider/shared-internals';
+import { hbsToJS } from '@embroider/core';
 import assertNever from 'assert-never';
 import { parse as pathParse } from 'path';
 

packages/addon-dev/src/template-colocation-plugin.ts

@@ -1,4 +1,7 @@
-export {
-  default,
-  Options,
-} from '@embroider/shared-internals/src/template-colocation-plugin';
+import {
+  templateColocationPlugin,
+  Options as TemplateColocationPluginOptions,
+} from '@embroider/core';
+
+export { TemplateColocationPluginOptions as Options };
+export default templateColocationPlugin;

packages/addon-dev/src/template-transform-plugin.ts

@@ -0,0 +1,42 @@
+import make from '@embroider/core/src/babel-plugin-stage1-inline-hbs';
+import { TemplateCompiler, TemplateCompilerParams } from '@embroider/core';
+import { getEmberExports } from '@embroider/core/src/load-ember-template-compiler';
+
+export type TemplateTransform = () => { name: string; visitor: {} };
+export type TemplateTransformPlugin = TemplateTransform | string;
+export interface Options {
+  // An array of either Glimmer AST plugins or paths that can be resolved to a plugin.
+  astTransforms?: TemplateTransformPlugin[];
+  // Defaults to 'ember-source/dist/ember-template-compiler'
+  compilerPath?: string;
+}
+
+function resolvePlugins(plugins: TemplateTransformPlugin[]) {
+  return plugins.map((somePlugin: TemplateTransformPlugin) => {
+    // If it's a string attempt to resolve the path to a module.
+    return typeof somePlugin === 'string'
+      ? require(somePlugin) // eslint-disable-line @typescript-eslint/no-require-imports
+      : somePlugin;
+  });
+}
+
+export default make((options: Options) => {
+  let {
+    astTransforms: somePlugins = [],
+    compilerPath = 'ember-source/dist/ember-template-compiler',
+  } = options;
+
+  compilerPath = require.resolve(compilerPath);
+
+  const astTransforms: TemplateTransform[] = resolvePlugins(somePlugins);
+
+  const params: TemplateCompilerParams = {
+    EmberENV: {},
+    loadEmberTemplateCompiler: () => getEmberExports(compilerPath),
+    plugins: {
+      ast: astTransforms,
+    },
+  };
+
+  return new TemplateCompiler(params);
+});

packages/addon-dev/tests/template-transform-plugin.test.ts

@@ -0,0 +1,150 @@
+import {
+  allBabelVersions,
+  emberTemplateCompilerPath,
+} from '@embroider/test-support';
+import {
+  TemplateTransformPlugin,
+  Options,
+} from '../src/template-transform-plugin';
+import { hbsToJS } from '@embroider/core';
+import { AST } from '@glimmer/syntax';
+import { join } from 'path';
+import tmp from 'tmp';
+import { writeFileSync } from 'fs-extra';
+
+describe('template-transform-plugin', () => {
+  jest.setTimeout(120000);
+
+  const templateTransformBabelPlugin = join(
+    __dirname,
+    '../src/template-transform-plugin.js'
+  );
+
+  let plugins: any = [];
+
+  function reverseTransform() {
+    return {
+      name: 'reverse-transform',
+      visitor: {
+        ElementNode(node: AST.ElementNode) {
+          node.tag = node.tag.split('').reverse().join('');
+        },
+      },
+    };
+  }
+
+  function setupPlugins(options?: {
+    astTransforms: TemplateTransformPlugin[];
+  }) {
+    const opts: Options = {
+      astTransforms: options?.astTransforms,
+      compilerPath: emberTemplateCompilerPath(),
+    };
+    plugins = [[templateTransformBabelPlugin, opts]];
+  }
+
+  allBabelVersions({
+    babelConfig() {
+      return {
+        plugins,
+      };
+    },
+    createTests(transform) {
+      afterEach(function () {
+        plugins = undefined;
+      });
+
+      test('no-op', () => {
+        setupPlugins();
+        const code = hbsToJS('Hello {{@phrase}}');
+        let output = transform(code);
+        expect(output).toMatch(
+          /import { hbs } from ['"]ember-cli-htmlbars['"];/
+        );
+        expect(output).toMatch(
+          /export default hbs\(['"]Hello {{@phrase}}['"]\);/
+        );
+      });
+
+      test('options.astTransforms empty array', () => {
+        setupPlugins({
+          astTransforms: [],
+        });
+        const code = hbsToJS('Hello {{@phrase}}');
+        let output = transform(code);
+        expect(output).toMatch(
+          /import { hbs } from ['"]ember-cli-htmlbars['"];/
+        );
+        expect(output).toMatch(
+          /export default hbs\(['"]Hello {{@phrase}}['"]\);/
+        );
+      });
+      test('options.astTransforms function', () => {
+        setupPlugins({
+          astTransforms: [reverseTransform],
+        });
+
+        const code = hbsToJS('<span>{{@phrase}}</span>');
+        let output = transform(code);
+        expect(output).toMatch(
+          /import { hbs } from ['"]ember-cli-htmlbars['"];/
+        );
+        expect(output).toMatch(
+          /export default hbs\(['"]\<naps\>{{@phrase}}\<\/naps\>['"]\);/
+        );
+      });
+
+      test('options.astTransforms path', () => {
+        const someFile = tmp.fileSync();
+
+        const contents = `module.exports = function reverseTransform() {
+        return {
+          name: 'reverse-transform',
+          visitor: {
+            ElementNode(node) {
+              node.tag = node.tag.split('').reverse().join('');
+            },
+          },
+        };
+      }`;
+
+        writeFileSync(someFile.name, contents, 'utf8');
+
+        setupPlugins({
+          astTransforms: [someFile.name],
+        });
+
+        const code = hbsToJS('<span>{{@phrase}}</span>');
+
+        let output = transform(code);
+
+        expect(output).toMatch(
+          /import { hbs } from ['"]ember-cli-htmlbars['"];/
+        );
+        expect(output).toMatch(
+          /export default hbs\(['"]\<naps\>{{@phrase}}\<\/naps\>['"]\);/
+        );
+
+        someFile.removeCallback();
+      });
+
+      test('ember-cli-htmlbars alias import name', () => {
+        setupPlugins({
+          astTransforms: [reverseTransform],
+        });
+
+        const code = `import { hbs as render } from 'ember-cli-htmlbars';
+      export default render('<span>{{@phrase}}</span>');`;
+
+        let output = transform(code);
+
+        expect(output).toMatch(
+          /import { hbs as render } from ['"]ember-cli-htmlbars['"];/
+        );
+        expect(output).toMatch(
+          /export default render\(['"]\<naps\>{{@phrase}}\<\/naps\>['"]\);/
+        );
+      });
+    },
+  });
+});

packages/core/package.json

@@ -18,6 +18,7 @@
     },
     "./src/messages": "./src/messages.js",
     "./src/babel-plugin-inline-hbs": "./src/babel-plugin-inline-hbs.js",
+    "./src/babel-plugin-stage1-inline-hbs": "./src/babel-plugin-stage1-inline-hbs.js",
     "./src/mini-modules-polyfill": "./src/mini-modules-polyfill.js",
     "./src/load-ember-template-compiler": "./src/load-ember-template-compiler.js"
   },

packages/shared-internals/src/index.ts

@@ -9,3 +9,7 @@ export { default as tmpdir } from './tmpdir';
 export * from './ember-cli-models';
 export * from './ember-standard-modules';
 export { hbsToJS } from './hbs-to-js';
+export {
+  default as templateColocationPlugin,
+  Options as TemplateColocationPluginOptions,
+} from './template-colocation-plugin';