Merge pull request #17360 from IgniteUI/dpetev/migrations-dynamic-import-fix-22

fix(migrations): restore dynamic import helper as cjs

Author: ChronosSF

package-lock.json

@@ -18,7 +18,7 @@
     "test:lib:pgrid": "ng test igniteui-angular --watch=false --no-progress --code-coverage --karma-config=./projects/igniteui-angular/karma.pivot-grid.conf.js",
     "test:lib:others": "ng test igniteui-angular --watch=false --no-progress --code-coverage --karma-config=./projects/igniteui-angular/karma.non-grid.conf.js",
     "test:lib:watch": "ng test igniteui-angular --karma-config=./projects/igniteui-angular/karma.watch.conf.js",
-    "test:schematics": "gulp copySchematics && tsc --project ./projects/igniteui-angular/schematics/tsconfig.json && gulp copyMigrations && tsc --project ./projects/igniteui-angular/migrations/tsconfig.spec.json && node ./node_modules/jasmine/bin/jasmine.js \"dist/igniteui-angular/migrations/**/*.spec.js\" \"dist/igniteui-angular/schematics/**/*.spec.js\"",
+    "test:schematics": "gulp copySchematics && tsc --project ./projects/igniteui-angular/schematics/tsconfig.json && gulp copyMigrations && tsc --project ./projects/igniteui-angular/migrations/tsconfig.spec.json && node -r ./projects/igniteui-angular/migrations/tsconfig-paths-bootstrap.js ./node_modules/jasmine/bin/jasmine.js \"dist/igniteui-angular/migrations/**/*.spec.js\" \"dist/igniteui-angular/schematics/**/*.spec.js\"",
     "test:styles": "ts-node --skip-project ./node_modules/jasmine/bin/jasmine.js ./projects/igniteui-angular/core/src/core/styles/spec/tests.mjs",
     "test:i18n": "ts-node --skip-project ./projects/igniteui-angular/core/src/core/i18n/tests/tests.mjs",
     "test:elements": "ng test igniteui-angular-elements --watch=false --no-progress --code-coverage --source-map=false",
@@ -163,6 +163,7 @@
     "stylelint-prettier": "^5.0.2",
     "stylelint-scss": "^6.9.0",
     "ts-node": "^10.8.1",
+    "tsconfig-paths": "^4.2.0",
     "typedoc": "^0.28.14",
     "typedoc-plugin-localization": "^3.1.0",
     "typescript": "6.0.3"

package.json

@@ -0,0 +1,79 @@
+# Ignite UI for Angular — `ng update` Migrations
+
+This directory hosts the migration schematics that run when consumers execute
+`ng update igniteui-angular`. Each `update-*` folder is a versioned migration
+listed in [`migration-collection.json`](./migration-collection.json) and
+implemented in `update-*/index.ts`. Shared helpers live in
+[`common/`](./common).
+
+See [Wiki pages under Migrations & Schematics](https://github.com/IgniteUI/igniteui-angular/wiki#migrations--schematics)
+for authoring and testing guidance. 
+
+## Encapsulation and external ESM like `@angular/compiler`
+The collection has `"encapsulation": true` so every
+migration is loaded in its own isolated VM context by the Angular
+schematics tooling. That also restricts some API access/functionality.
+
+See the description of [#13712 — fix(migrations,ng-add): turn on encapsulation for devkit/schematics deps](https://github.com/IgniteUI/igniteui-angular/pull/13712) when encapsulation was first enabled for mechanism details.
+
+### Dynamic `@angular/compiler` import via `nativeImport`
+
+`@angular/compiler` is an ES module. The migrations themselves are emitted and consumed
+(`require()`-d) by the Angular schematics as CommonJS, so they cannot statically `import` it;
+they have to use a runtime dynamic `import()`.
+
+- [`common/import-helper.cts`](./common/import-helper.cts) — authored as
+  a TypeScript CJS module. The dynamic `import()` is preserved in the emitted.
+- Migrations call it via:
+  ```ts
+  import { nativeImport } from 'igniteui-angular/migrations/common/import-helper.cjs';
+  // ...
+  const { HtmlParser } = await nativeImport('@angular/compiler');
+  ```
+
+### Why the bare `igniteui-angular/...` specifier
+
+Schematics encapsulation being a VM execution is affected by the
+[Support of dynamic import() in compilation APIs](https://nodejs.org/api/vm.html#support-of-dynamic-import-in-compilation-apis)
+and at this time Angular schematics do not implement [importModuleDynamically](https://github.com/angular/angular-cli/blob/e5eb3e37c9756669b3b91b5b681a73cc9b616cb9/packages/angular/cli/src/command-builder/utilities/schematic-engine-host.ts#L50).
+
+A **bare package specifier** effectively passes through the schematics host encapsulation again and escapes [the relative wrapping ](https://github.com/angular/angular-cli/blob/e5eb3e37c9756669b3b91b5b681a73cc9b616cb9/packages/angular/cli/src/command-builder/utilities/schematic-engine-host.ts#L177-L178) out into [the original schematic require](https://github.com/angular/angular-cli/blob/e5eb3e37c9756669b3b91b5b681a73cc9b616cb9/packages/angular/cli/src/command-builder/utilities/schematic-engine-host.ts#L203-L204).
+This means just the `import-helper.cjs` script is ran outside of encapsulation and as such can perform dynamic imports.
+
+Every migration that needs `@angular/compiler` follows the same pattern.
+
+To keep TypeScript happy with the bare specifier at compile time,
+[`tsconfig.json`](./tsconfig.json) maps it back to the source:
+
+```jsonc
+"paths": {
+    "igniteui-angular/*": ["../*"],
+    "@infragistics/igniteui-angular/*": ["../*"]
+}
+```
+
+At consumer install time the specifier resolves naturally through their
+`node_modules/igniteui-angular/migrations/common/import-helper.cjs`.
+
+### Tests setup for the bare specifier
+
+`npm run test:schematics` compiles the migrations with
+[`tsconfig.spec.json`](./tsconfig.spec.json) into `dist/igniteui-angular/...`
+and runs the compiled `*.spec.js` files through Jasmine. In this repo there is
+no `node_modules/igniteui-angular` (the library is the workspace itself), so
+the bare `igniteui-angular/migrations/common/import-helper.cjs` specifier
+would not resolve at runtime.
+
+[`tsconfig-paths-bootstrap.js`](./tsconfig-paths-bootstrap.js) fixes that. It
+is loaded with `node --require` before Jasmine starts and installs a runtime
+path map (via the `tsconfig-paths` package) that points
+`igniteui-angular/*` at `./dist/igniteui-angular/*`.
+
+The wiring in [`package.json`](../../../package.json) looks like:
+
+```text
+node -r ./projects/igniteui-angular/migrations/tsconfig-paths-bootstrap.js \
+     ./node_modules/jasmine/bin/jasmine.js \
+     "dist/igniteui-angular/migrations/**/*.spec.js" \
+     "dist/igniteui-angular/schematics/**/*.spec.js"
+```

projects/igniteui-angular/migrations/README.md

@@ -0,0 +1,15 @@
+/** Explicit module map, as generic T can't be resolved to a direct string literal via inference */
+type ModuleMap = {
+  '@angular/compiler': typeof import('@angular/compiler', { with: { "resolution-mode": "import" }});
+};
+
+/**
+ * Native Node dynamic import helper
+ * @remarks
+ * NB: Import this via a bare specifier (igniteui-angular/migrations/common/import-helper.cjs)
+ * to escape the schematics encapsulation for this file and thus the dynamic import inside.
+ * This allows to dynamically import ESM modules from outside the schematics host context.
+ */
+export function nativeImport<T extends keyof ModuleMap>(name: T): Promise<ModuleMap[T]> {
+    return import(name);
+};

projects/igniteui-angular/migrations/common/import-helper.cts

@@ -0,0 +1,23 @@
+/**
+ * Test-time bootstrap. Registered via `node --require` before jasmine runs so
+ * the `igniteui-angular/...` bare specifier used by migrations (to escape the
+ * schematic encapsulation for the dynamic import helper) resolves against the
+ * built migrations in dist instead of `node_modules` (which has no
+ * igniteui-angular install in this repo).
+ *
+ * The compile-time path map in ./tsconfig.json points at the sources under
+ * ../*; at runtime we point at the compiled output under
+ * <repo>/dist/igniteui-angular/* so the require resolves to the emitted .cjs.
+ */
+const path = require("path");
+const tsConfigPaths = require("tsconfig-paths");
+
+const distRoot = path.resolve(__dirname, "../../../dist/igniteui-angular");
+
+tsConfigPaths.register({
+    baseUrl: distRoot,
+    paths: {
+        "igniteui-angular/*": ["./*"],
+        "@infragistics/igniteui-angular/*": ["./*"],
+    },
+});

projects/igniteui-angular/migrations/tsconfig-paths-bootstrap.js

@@ -2,15 +2,16 @@ import type { Element } from '@angular/compiler' with { "resolution-mode": "impo
 import type { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
 import { UpdateChanges } from '../common/UpdateChanges';
 import { FileChange, findElementNodes, getAttribute, getSourceOffset, hasAttribute, parseFile, serializeNodes } from '../common/util';
+// use bare specifier to escape the schematics encapsulation for the dynamic import:
+import { nativeImport } from 'igniteui-angular/migrations/common/import-helper.cjs';
 
 const version = '11.0.0';
 
 export default (): Rule => async (host: Tree, context: SchematicContext) => {
     context.logger.info(
         `Applying migration for Ignite UI for Angular to version ${version}`
     );
-    // bare specifier escapes schematics encapsulation for the compiler dynamic import:
-    const { HtmlParser, getHtmlTagDefinition } = await import('@angular/compiler');
+    const { HtmlParser, getHtmlTagDefinition } = await nativeImport('@angular/compiler');
 
     const update = new UpdateChanges(__dirname, host, context);
 

projects/igniteui-angular/migrations/update-11_0_0/index.ts

@@ -2,6 +2,8 @@ import type { Element } from '@angular/compiler' with { "resolution-mode": "impo
 import type { Rule, SchematicContext, Tree } from '@angular-devkit/schematics';
 import { UpdateChanges } from '../common/UpdateChanges';
 import { FileChange, getAttribute, findElementNodes, getSourceOffset, hasAttribute, parseFile } from '../common/util';
+// use bare specifier to escape the schematics encapsulation for the dynamic import:
+import { nativeImport } from 'igniteui-angular/migrations/common/import-helper.cjs';
 import type { Options } from '../../schematics/interfaces/options';
 
 const version = '12.0.0';
@@ -12,8 +14,7 @@ export default (options: Options): Rule =>
             `Applying migration for Ignite UI for Angular to version ${version}`
         );
 
-        // bare specifier escapes schematics encapsulation for the compiler dynamic import:
-        const { HtmlParser } = await import('@angular/compiler');
+        const { HtmlParser } = await nativeImport('@angular/compiler');
 
         // eslint-disable-next-line max-len
         const UPDATE_NOTE = `<!--NOTE: This component has been updated by Infragistics migration: v${version}\nPlease check your template whether all bindings/event handlers are correct.-->\n`;

projects/igniteui-angular/migrations/update-12_0_0/index.ts

@@ -5,14 +5,15 @@ import {
   FileChange, findElementNodes, getAttribute, getSourceOffset, hasAttribute, parseFile,
   serializeNodes, makeNgIf, stringifyAttributes
 } from '../common/util';
+// use bare specifier to escape the schematics encapsulation for the dynamic import:
+import { nativeImport } from 'igniteui-angular/migrations/common/import-helper.cjs';
 
 const version = '12.1.0';
 
 export default (): Rule => async (host: Tree, context: SchematicContext) => {
   context.logger.info(`Applying migration for Ignite UI for Angular to version ${version}`);
 
-  // bare specifier escapes schematics encapsulation for the compiler dynamic import:
-  const { HtmlParser, getHtmlTagDefinition } = await import('@angular/compiler');
+  const { HtmlParser, getHtmlTagDefinition } = await nativeImport('@angular/compiler');
 
   const update = new UpdateChanges(__dirname, host, context);
   const TAGS = ['igx-grid', 'igx-tree-grid', 'igx-hierarchical-grid'];

projects/igniteui-angular/migrations/update-12_1_0/index.ts

@@ -7,6 +7,8 @@ import type {
 import type { Options } from '../../schematics/interfaces/options';
 import { UpdateChanges } from '../common/UpdateChanges';
 import { FileChange, findElementNodes, getAttribute, getSourceOffset, hasAttribute, parseFile } from '../common/util';
+// use bare specifier to escape the schematics encapsulation for the dynamic import:
+import { nativeImport } from 'igniteui-angular/migrations/common/import-helper.cjs';
 
 const version = '13.0.0';
 
@@ -25,8 +27,7 @@ export default (options: Options): Rule =>
         '[exportExcel]', 'exportExcel', '[exportExcelText]', 'exportExcelText',
         '[exportCsv]', 'exportCsv', '[exportCsvText]', 'exportCsvText', '[exportText]', 'exportText'];
         const actionsLeft = ['igx-grid-toolbar-advanced-filtering'];
-        // bare specifier escapes schematics encapsulation for the compiler dynamic import:
-        const { HtmlParser } = await import('@angular/compiler');
+        const { HtmlParser } = await nativeImport('@angular/compiler');
 
         const moduleTsFiles = tsFiles.filter(x => x.endsWith('.module.ts'));
         for (const path of moduleTsFiles) {

projects/igniteui-angular/migrations/update-13_0_0/index.ts

@@ -4,15 +4,16 @@ import type {
   Tree
 } from '@angular-devkit/schematics';
 import type { Element } from '@angular/compiler' with { "resolution-mode": "import" };
+// use bare specifier to escape the schematics encapsulation for the dynamic import:
+import { nativeImport } from 'igniteui-angular/migrations/common/import-helper.cjs';
 import { UpdateChanges } from '../common/UpdateChanges';
 import { FileChange, findElementNodes, getAttribute, getSourceOffset, hasAttribute, parseFile } from '../common/util';
 
 const version = '13.1.0';
 
 export default (): Rule => async (host: Tree, context: SchematicContext) => {
   context.logger.info(`Applying migration for Ignite UI for Angular to version ${version}`);
-  // bare specifier escapes schematics encapsulation for the compiler dynamic import:
-  const { HtmlParser } = await import('@angular/compiler');
+  const { HtmlParser } = await nativeImport('@angular/compiler');
 
   const update = new UpdateChanges(__dirname, host, context);
   const GRID_TAGS = ['igx-grid', 'igx-tree-grid', 'igx-hierarchical-grid', 'igx-row-island'];