refactor(@angular/cli): import markdown files directly for command descriptions

Use TypeScript ambient module declaration for *.md files and register a scoped
markdown require extension hook in CommonJS to allow direct import of command
long descriptions.

Loading markdown directly via module imports prepares the CLI codebase for
ESM bundling, where __dirname and runtime filesystem reads are problematic.
It simplifies unit tests by avoiding filesystem path resolution while bundling
the text content seamlessly during production builds.

This eliminates 12 __dirname references across command modules and removes
the obsolete longDescriptionPath property.

Author: clydin

packages/angular/cli/src/command-builder/command-module.ts

@@ -7,8 +7,6 @@
  */
 
 import { schema } from '@angular-devkit/core';
-import { readFileSync } from 'node:fs';
-import { join, posix, relative } from 'node:path';
 import type { ArgumentsCamelCase, Argv, CommandModule as YargsCommandModule } from 'yargs';
 import { Parser as yargsParser } from 'yargs/helpers';
 import { getAnalyticsUserId } from '../analytics/analytics';
@@ -20,6 +18,7 @@ import { AngularWorkspace } from '../utilities/config';
 import { memoize } from '../utilities/memoize';
 import { CommandContext, CommandScope, Options, OtherOptions } from './definitions';
 import { Option, addSchemaOptionsToCommand } from './utilities/json-schema';
+import '../utilities/markdown-loader';
 
 export { CommandScope };
 export type { CommandContext, Options, OtherOptions };
@@ -31,8 +30,11 @@ export interface CommandModuleImplementation<T extends {} = {}> extends Omit<
   /** Scope in which the command can be executed in. */
   scope: CommandScope;
 
-  /** Path used to load the long description for the command in JSON help text. */
-  longDescriptionPath?: string;
+  /** Long description for the command in JSON help text. */
+  longDescription?: string;
+
+  /** Relative path to the long description file for the command in JSON help text. */
+  longDescriptionRelativePath?: string;
 
   /** Object declaring the options the command accepts, or a function accepting and returning a yargs instance. */
   builder(argv: Argv): Promise<Argv<T>> | Argv<T>;
@@ -50,7 +52,8 @@ export interface FullDescribe {
 export abstract class CommandModule<T extends {} = {}> implements CommandModuleImplementation<T> {
   abstract readonly command: string;
   abstract readonly describe: string | false;
-  abstract readonly longDescriptionPath?: string;
+  readonly longDescription?: string;
+  readonly longDescriptionRelativePath?: string;
   protected readonly shouldReportAnalytics: boolean = true;
   readonly scope: CommandScope = CommandScope.Both;
 
@@ -68,23 +71,22 @@ export abstract class CommandModule<T extends {} = {}> implements CommandModuleI
    * `false` will result in a hidden command.
    */
   public get fullDescribe(): FullDescribe | false {
-    return this.describe === false
-      ? false
-      : {
-          describe: this.describe,
-          ...(this.longDescriptionPath
-            ? {
-                longDescriptionRelativePath: relative(
-                  join(__dirname, '../../../../'),
-                  this.longDescriptionPath,
-                ).replace(/\\/g, posix.sep),
-                longDescription: readFileSync(this.longDescriptionPath, 'utf8').replace(
-                  /\r\n/g,
-                  '\n',
-                ),
-              }
-            : {}),
-        };
+    if (this.describe === false) {
+      return false;
+    }
+
+    const description: FullDescribe = {
+      describe: this.describe,
+    };
+
+    if (this.longDescription) {
+      description.longDescription = this.longDescription.replace(/\r\n/g, '\n');
+      description.longDescriptionRelativePath =
+        this.longDescriptionRelativePath ??
+        `@angular/cli/src/commands/${this.commandName}/long-description.md`;
+    }
+
+    return description;
   }
 
   protected get commandName(): string {

packages/angular/cli/src/commands/add/cli.ts

@@ -29,6 +29,9 @@ import { NgAddSaveDependency, PackageManifest, PackageMetadata } from '../../pac
 import { assertIsError } from '../../utilities/error';
 import { isTTY } from '../../utilities/tty';
 import { VERSION } from '../../utilities/version';
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore strict-deps: Markdown files are asset dependencies bundled/loaded at runtime
+import longDescription from './long-description.md';
 
 class CommandError extends Error {}
 
@@ -100,7 +103,7 @@ export default class AddCommandModule
 {
   command = 'add <collection>';
   describe = 'Adds support for an external library to your project.';
-  longDescriptionPath = join(__dirname, 'long-description.md');
+  override longDescription = longDescription;
   protected override allowPrivateSchematics = true;
   private readonly schematicName = 'ng-add';
   private rootRequire = createRequire(this.context.root + '/');

packages/angular/cli/src/commands/analytics/cli.ts

@@ -6,7 +6,6 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import { join } from 'node:path';
 import { Argv } from 'yargs';
 import {
   CommandModule,
@@ -18,6 +17,9 @@ import {
   demandCommandFailureMessage,
 } from '../../command-builder/utilities/command';
 import { AnalyticsInfoCommandModule } from './info/cli';
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore strict-deps: Markdown files are asset dependencies bundled/loaded at runtime
+import longDescription from './long-description.md';
 import {
   AnalyticsDisableModule,
   AnalyticsEnableModule,
@@ -30,7 +32,7 @@ export default class AnalyticsCommandModule
 {
   command = 'analytics';
   describe = 'Configures the gathering of Angular CLI usage metrics.';
-  longDescriptionPath = join(__dirname, 'long-description.md');
+  override longDescription = longDescription;
 
   builder(localYargs: Argv): Argv {
     const subcommands = [

packages/angular/cli/src/commands/analytics/info/cli.ts

@@ -20,7 +20,6 @@ export class AnalyticsInfoCommandModule
 {
   command = 'info';
   describe = 'Prints analytics gathering and reporting configuration in the console.';
-  longDescriptionPath?: string;
 
   builder(localYargs: Argv): Argv {
     return localYargs.strict();

packages/angular/cli/src/commands/analytics/settings/cli.ts

@@ -26,8 +26,6 @@ abstract class AnalyticsSettingModule
   extends CommandModule<AnalyticsCommandArgs>
   implements CommandModuleImplementation<AnalyticsCommandArgs>
 {
-  longDescriptionPath?: string;
-
   builder(localYargs: Argv): Argv<AnalyticsCommandArgs> {
     return localYargs
       .option('global', {

packages/angular/cli/src/commands/build/cli.ts

@@ -6,10 +6,12 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import { join } from 'node:path';
 import { ArchitectCommandModule } from '../../command-builder/architect-command-module';
 import { CommandModuleImplementation } from '../../command-builder/command-module';
 import { RootCommands } from '../command-config';
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore strict-deps: Markdown files are asset dependencies bundled/loaded at runtime
+import longDescription from './long-description.md';
 
 export default class BuildCommandModule
   extends ArchitectCommandModule
@@ -20,5 +22,5 @@ export default class BuildCommandModule
   aliases = RootCommands['build'].aliases;
   describe =
     'Compiles an Angular application or library into an output directory named dist/ at the given output path.';
-  longDescriptionPath = join(__dirname, 'long-description.md');
+  override longDescription = longDescription;
 }

packages/angular/cli/src/commands/cache/clean/cli.ts

@@ -18,7 +18,6 @@ import { getCacheConfig } from '../utilities';
 export class CacheCleanModule extends CommandModule implements CommandModuleImplementation {
   command = 'clean';
   describe = 'Deletes persistent disk cache from disk.';
-  longDescriptionPath: string | undefined;
   override scope = CommandScope.In;
 
   builder(localYargs: Argv): Argv {

packages/angular/cli/src/commands/cache/cli.ts

@@ -6,7 +6,6 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import { join } from 'node:path';
 import { Argv } from 'yargs';
 import {
   CommandModule,
@@ -20,6 +19,9 @@ import {
 } from '../../command-builder/utilities/command';
 import { CacheCleanModule } from './clean/cli';
 import { CacheInfoCommandModule } from './info/cli';
+// eslint-disable-next-line @typescript-eslint/ban-ts-comment
+// @ts-ignore strict-deps: Markdown files are asset dependencies bundled/loaded at runtime
+import longDescription from './long-description.md';
 import { CacheDisableModule, CacheEnableModule } from './settings/cli';
 
 export default class CacheCommandModule
@@ -28,7 +30,7 @@ export default class CacheCommandModule
 {
   command = 'cache';
   describe = 'Configure persistent disk cache and retrieve cache statistics.';
-  longDescriptionPath = join(__dirname, 'long-description.md');
+  override longDescription = longDescription;
   override scope = CommandScope.In;
 
   builder(localYargs: Argv): Argv {

packages/angular/cli/src/commands/cache/info/cli.ts

@@ -21,7 +21,6 @@ import { getCacheConfig } from '../utilities';
 export class CacheInfoCommandModule extends CommandModule implements CommandModuleImplementation {
   command = 'info';
   describe = 'Prints persistent disk cache configuration and statistics in the console.';
-  longDescriptionPath?: string | undefined;
   override scope = CommandScope.In;
 
   builder(localYargs: Argv): Argv {

packages/angular/cli/src/commands/cache/settings/cli.ts

@@ -18,7 +18,6 @@ export class CacheDisableModule extends CommandModule implements CommandModuleIm
   command = 'disable';
   aliases = 'off';
   describe = 'Disables persistent disk cache for all projects in the workspace.';
-  longDescriptionPath: string | undefined;
   override scope = CommandScope.In;
 
   builder(localYargs: Argv): Argv {
@@ -34,7 +33,6 @@ export class CacheEnableModule extends CommandModule implements CommandModuleImp
   command = 'enable';
   aliases = 'on';
   describe = 'Enables disk cache for all projects in the workspace.';
-  longDescriptionPath: string | undefined;
   override scope = CommandScope.In;
 
   builder(localYargs: Argv): Argv {