@ng-doc/add 22.0.0-beta.1 → 22.0.0

package/schematics/ng-add/utils/get-main-path.js

@@ -2,12 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.getMainPath = getMainPath;
 const schematics_1 = require("@angular/cdk/schematics");
+const get_build_options_target_1 = require("./get-build-options-target");
 /**
- *
- * @param project
+ * Returns the browser entry of the application (`browser`, or `main` of older builders).
+ * @param project - The application project.
  */
 function getMainPath(project) {
-    const buildOptions = (0, schematics_1.getProjectTargetOptions)(project, 'build');
+    const buildOptions = (0, schematics_1.getProjectTargetOptions)(project, (0, get_build_options_target_1.getBuildOptionsTarget)(project));
     return (buildOptions['main'] ?? buildOptions['browser']);
 }
 //# sourceMappingURL=get-main-path.js.map

package/schematics/ng-add/utils/get-main-path.js.map

@@ -1 +1 @@
-{"version":3,"file":"get-main-path.js","sourceRoot":"","sources":["../../../../../../libs/add/schematics/ng-add/utils/get-main-path.ts"],"names":[],"mappings":";;AAQA,kCAOC;AAfD,wDAAkE;AAIlE;;;GAGG;AACH,SAAgB,WAAW,CAAC,OAA0B;IACrD,MAAM,YAAY,GAA0C,IAAA,oCAAuB,EAClF,OAAO,EACP,OAAO,CACP,CAAC;IAEF,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,SAAS,CAAC,CAAW,CAAC;AACpE,CAAC"}
+{"version":3,"file":"get-main-path.js","sourceRoot":"","sources":["../../../../../../libs/add/schematics/ng-add/utils/get-main-path.ts"],"names":[],"mappings":";;AAUA,kCAOC;AAjBD,wDAAkE;AAIlE,yEAAmE;AAEnE;;;GAGG;AACH,SAAgB,WAAW,CAAC,OAA0B;IACpD,MAAM,YAAY,GAA0C,IAAA,oCAAuB,EACjF,OAAO,EACP,IAAA,gDAAqB,EAAC,OAAO,CAAC,CAC/B,CAAC;IAEF,OAAO,CAAC,YAAY,CAAC,MAAM,CAAC,IAAI,YAAY,CAAC,SAAS,CAAC,CAAW,CAAC;AACrE,CAAC"}

package/schematics/ng-add/utils/get-root-module.d.ts

@@ -0,0 +1,14 @@
+import { CallExpression, ClassDeclaration } from 'ng-morph';
+/**
+ * Finds the `bootstrapModule(...)` call of an NgModule application.
+ *
+ * The platform is not checked: Angular 22 applications call `platformBrowser().bootstrapModule`,
+ * older ones `platformBrowserDynamic().bootstrapModule`, and both must be found.
+ * @param mainPath - Path of the application's main file.
+ */
+export declare function getBootstrapModuleFn(mainPath: string): CallExpression | undefined;
+/**
+ * Returns the class of the module passed to `bootstrapModule`.
+ * @param mainPath - Path of the application's main file.
+ */
+export declare function getRootModule(mainPath: string): ClassDeclaration | undefined;

package/schematics/ng-add/utils/get-root-module.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getBootstrapModuleFn = getBootstrapModuleFn;
+exports.getRootModule = getRootModule;
+const ng_morph_1 = require("ng-morph");
+/**
+ * Finds the `bootstrapModule(...)` call of an NgModule application.
+ *
+ * The platform is not checked: Angular 22 applications call `platformBrowser().bootstrapModule`,
+ * older ones `platformBrowserDynamic().bootstrapModule`, and both must be found.
+ * @param mainPath - Path of the application's main file.
+ */
+function getBootstrapModuleFn(mainPath) {
+    const [sourceFile] = (0, ng_morph_1.getSourceFiles)(mainPath);
+    return sourceFile
+        ?.getDescendantsOfKind(ng_morph_1.SyntaxKind.CallExpression)
+        .find((call) => {
+        const expression = call.getExpression();
+        return (ng_morph_1.Node.isPropertyAccessExpression(expression) && expression.getName() === 'bootstrapModule');
+    });
+}
+/**
+ * Returns the class of the module passed to `bootstrapModule`.
+ * @param mainPath - Path of the application's main file.
+ */
+function getRootModule(mainPath) {
+    const [module] = getBootstrapModuleFn(mainPath)?.getArguments() ?? [];
+    const [definition] = ng_morph_1.Node.isIdentifier(module) ? module.getDefinitionNodes() : [];
+    return ng_morph_1.Node.isClassDeclaration(definition) ? definition : undefined;
+}
+//# sourceMappingURL=get-root-module.js.map

package/schematics/ng-add/utils/get-root-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"get-root-module.js","sourceRoot":"","sources":["../../../../../../libs/add/schematics/ng-add/utils/get-root-module.ts"],"names":[],"mappings":";;AAgBA,oDAYC;AAMD,sCAKC;AAvCD,uCAOkB;AAElB;;;;;;GAMG;AACH,SAAgB,oBAAoB,CAAC,QAAgB;IACnD,MAAM,CAAC,UAAU,CAAC,GAAiB,IAAA,yBAAc,EAAC,QAAQ,CAAC,CAAC;IAE5D,OAAO,UAAU;QACf,EAAE,oBAAoB,CAAC,qBAAU,CAAC,cAAc,CAAC;SAChD,IAAI,CAAC,CAAC,IAAoB,EAAE,EAAE;QAC7B,MAAM,UAAU,GAAG,IAAI,CAAC,aAAa,EAAE,CAAC;QAExC,OAAO,CACL,eAAI,CAAC,0BAA0B,CAAC,UAAU,CAAC,IAAI,UAAU,CAAC,OAAO,EAAE,KAAK,iBAAiB,CAC1F,CAAC;IACJ,CAAC,CAAC,CAAC;AACP,CAAC;AAED;;;GAGG;AACH,SAAgB,aAAa,CAAC,QAAgB;IAC5C,MAAM,CAAC,MAAM,CAAC,GAAG,oBAAoB,CAAC,QAAQ,CAAC,EAAE,YAAY,EAAE,IAAI,EAAE,CAAC;IACtE,MAAM,CAAC,UAAU,CAAC,GAAG,eAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAElF,OAAO,eAAI,CAAC,kBAAkB,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,SAAS,CAAC;AACtE,CAAC"}

package/schematics/ng-add/utils/select-engine.d.ts

@@ -0,0 +1,38 @@
+import { logging } from '@angular-devkit/core';
+import { ProjectDefinition } from '@angular-devkit/core/src/workspace';
+import { Tree } from '@angular-devkit/schematics';
+import { NgDocEngine } from '../schema';
+/** The command that moves a project from the legacy builders to the Vite engine. */
+export declare const MIGRATE_TO_VITE = "ng g @ng-doc/builder:migrate-to-vite";
+/** The engine `ng add` sets up, and whether the project already had it. */
+export interface EngineChoice {
+    engine: NgDocEngine;
+    /** The project already builds with NgDoc: its builders are kept as they are. */
+    existing: boolean;
+    /**
+     * Whether the legacy setup sets its builders on `build` and `serve`. An existing project whose
+     * NgDoc builder is on another target keeps `build` and `serve` as they are.
+     */
+    replaceBuilders: boolean;
+}
+/** Angular's application builders, whose options the Vite setup reads. */
+export declare const ANGULAR_APPLICATION_BUILDERS: string[];
+/**
+ * Whether the application bootstraps an NgModule (`bootstrapModule`) instead of a standalone
+ * component.
+ * @param tree - The workspace tree.
+ * @param project - The application project.
+ */
+export declare function isNgModuleApp(tree: Tree, project: ProjectDefinition): boolean;
+/**
+ * Chooses the engine to set up. A project that already builds with NgDoc keeps its engine: `ng add`
+ * never switches it (the legacy builders move to the Vite engine with `migrate-to-vite`). A new
+ * standalone application gets the Vite engine unless `--engine legacy` is passed; an NgModule
+ * application, or one whose `build` target does not use Angular's application builder, gets the
+ * legacy builders; `--engine vite` is refused for an NgModule application.
+ * @param tree - The workspace tree.
+ * @param project - The application project.
+ * @param requested - The `--engine` option, if any.
+ * @param logger - Where the choice is explained.
+ */
+export declare function selectEngine(tree: Tree, project: ProjectDefinition, requested: NgDocEngine | undefined, logger: logging.LoggerApi): EngineChoice;

package/schematics/ng-add/utils/select-engine.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ANGULAR_APPLICATION_BUILDERS = exports.MIGRATE_TO_VITE = void 0;
+exports.isNgModuleApp = isNgModuleApp;
+exports.selectEngine = selectEngine;
+const schematics_1 = require("@angular-devkit/schematics");
+const ng_morph_1 = require("ng-morph");
+const get_build_options_target_1 = require("./get-build-options-target");
+const get_main_path_1 = require("./get-main-path");
+const get_root_module_1 = require("./get-root-module");
+/** The command that moves a project from the legacy builders to the Vite engine. */
+exports.MIGRATE_TO_VITE = 'ng g @ng-doc/builder:migrate-to-vite';
+/** Angular's application builders, whose options the Vite setup reads. */
+exports.ANGULAR_APPLICATION_BUILDERS = [
+    '@angular/build:application',
+    '@angular-devkit/build-angular:application',
+];
+const NG_DOC_BUILDER_PREFIX = '@ng-doc/builder:';
+/**
+ * Whether the application bootstraps an NgModule (`bootstrapModule`) instead of a standalone
+ * component.
+ * @param tree - The workspace tree.
+ * @param project - The application project.
+ */
+function isNgModuleApp(tree, project) {
+    // Without a build target there is no entry to look at; the setup reports the missing target.
+    const mainPath = project.targets.has('build')
+        ? (0, get_main_path_1.getMainPath)(project)
+        : undefined;
+    if (!mainPath || !tree.exists(mainPath)) {
+        return false;
+    }
+    try {
+        (0, ng_morph_1.setActiveProject)((0, ng_morph_1.createProject)(tree, '/', [mainPath]));
+        return !!(0, get_root_module_1.getBootstrapModuleFn)(mainPath);
+    }
+    finally {
+        (0, ng_morph_1.resetActiveProject)();
+    }
+}
+/**
+ * Chooses the engine to set up. A project that already builds with NgDoc keeps its engine: `ng add`
+ * never switches it (the legacy builders move to the Vite engine with `migrate-to-vite`). A new
+ * standalone application gets the Vite engine unless `--engine legacy` is passed; an NgModule
+ * application, or one whose `build` target does not use Angular's application builder, gets the
+ * legacy builders; `--engine vite` is refused for an NgModule application.
+ * @param tree - The workspace tree.
+ * @param project - The application project.
+ * @param requested - The `--engine` option, if any.
+ * @param logger - Where the choice is explained.
+ */
+function selectEngine(tree, project, requested, logger) {
+    const build = project.targets.get('build')?.builder;
+    const serve = project.targets.get('serve')?.builder;
+    if (build === get_build_options_target_1.VITE_APPLICATION_BUILDER) {
+        if (requested === 'legacy') {
+            logger.warn(`⚠️ The project already builds with the Vite engine (${get_build_options_target_1.VITE_APPLICATION_BUILDER}); "--engine legacy" was ignored and the builders were kept.`);
+        }
+        return { engine: 'vite', existing: true, replaceBuilders: false };
+    }
+    // Any NgDoc builder, not only on `build` and `serve`, means the project already uses NgDoc.
+    const ngDocTarget = [...project.targets.entries()]
+        .map(([name, target]) => [name, target.builder ?? ''])
+        .find(([, builder]) => builder.startsWith(NG_DOC_BUILDER_PREFIX));
+    if (ngDocTarget) {
+        const message = `The project already uses the NgDoc builders ("${ngDocTarget[0]}" runs ${ngDocTarget[1]}); they were kept. To move it to the Vite engine, run "${exports.MIGRATE_TO_VITE}".`;
+        if (requested === 'vite') {
+            logger.warn(`⚠️ "--engine vite" was ignored. ${message}`);
+        }
+        else {
+            logger.info(`ℹ️ ${message}`);
+        }
+        return {
+            engine: 'legacy',
+            existing: true,
+            replaceBuilders: !!build?.startsWith(NG_DOC_BUILDER_PREFIX) || !!serve?.startsWith(NG_DOC_BUILDER_PREFIX),
+        };
+    }
+    if (isNgModuleApp(tree, project)) {
+        if (requested === 'vite') {
+            throw new schematics_1.SchematicsException(`[NGDOC_ADD_ENGINE] "ng add" sets up the Vite engine for standalone applications (bootstrapApplication), and this application bootstraps an NgModule. Run "ng add @ng-doc/add --engine legacy", then "${exports.MIGRATE_TO_VITE}" if you want the Vite engine.`);
+        }
+        if (requested === undefined) {
+            logger.info(`ℹ️ The application bootstraps an NgModule, so NgDoc uses the legacy builders. "${exports.MIGRATE_TO_VITE}" moves it to the Vite engine later.`);
+        }
+        return { engine: 'legacy', existing: false, replaceBuilders: true };
+    }
+    // The Vite setup reads the options of Angular's application builder. Without `--engine`, another
+    // builder (a browser builder, an Nx or custom executor) gets the legacy builders, as before; an
+    // explicit `--engine vite` goes on to the Vite setup, which refuses it and says why.
+    if (requested === undefined && !exports.ANGULAR_APPLICATION_BUILDERS.includes(build ?? '')) {
+        logger.info(`ℹ️ The "build" target uses ${build ? `"${build}"` : 'no builder'}, not Angular's application builder, so NgDoc uses the legacy builders.`);
+        return { engine: 'legacy', existing: false, replaceBuilders: true };
+    }
+    return { engine: requested ?? 'vite', existing: false, replaceBuilders: true };
+}
+//# sourceMappingURL=select-engine.js.map

package/schematics/ng-add/utils/select-engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"select-engine.js","sourceRoot":"","sources":["../../../../../../libs/add/schematics/ng-add/utils/select-engine.ts"],"names":[],"mappings":"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"}