@angular/cli 20.2.0-next.2 → 20.2.0-rc.0

package/src/commands/version/cli.js

@@ -6,104 +6,74 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.dev/license
  */
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-const node_module_1 = __importDefault(require("node:module"));
-const node_path_1 = require("node:path");
 const command_module_1 = require("../../command-builder/command-module");
 const color_1 = require("../../utilities/color");
 const command_config_1 = require("../command-config");
+const version_info_1 = require("./version-info");
 /**
- * Major versions of Node.js that are officially supported by Angular.
+ * The Angular CLI logo, displayed as ASCII art.
+ */
+const ASCII_ART = `
+     _                      _                 ____ _     ___
+    / \\   _ __   __ _ _   _| | __ _ _ __     / ___| |   |_ _|
+   / △ \\ | '_ \\ / _\` | | | | |/ _\` | '__|   | |   | |    | |
+  / ___ \\| | | | (_| | |_| | | (_| | |      | |___| |___ | |
+ /_/   \\_\\_| |_|\\__, |\\__,_|_|\\__,_|_|       \\____|_____|___|
+                |___/
+    `
+    .split('\n')
+    .map((x) => color_1.colors.red(x))
+    .join('\n');
+/**
+ * The command-line module for the `ng version` command.
  */
-const SUPPORTED_NODE_MAJORS = [20, 22, 24];
-const PACKAGE_PATTERNS = [
-    /^@angular\/.*/,
-    /^@angular-devkit\/.*/,
-    /^@ngtools\/.*/,
-    /^@schematics\/.*/,
-    /^rxjs$/,
-    /^typescript$/,
-    /^ng-packagr$/,
-    /^webpack$/,
-    /^zone\.js$/,
-];
 class VersionCommandModule extends command_module_1.CommandModule {
     command = 'version';
     aliases = command_config_1.RootCommands['version'].aliases;
     describe = 'Outputs Angular CLI version.';
     longDescriptionPath;
+    /**
+     * Builds the command-line options for the `ng version` command.
+     * @param localYargs The `yargs` instance to configure.
+     * @returns The configured `yargs` instance.
+     */
     builder(localYargs) {
         return localYargs;
     }
+    /**
+     * The main execution logic for the `ng version` command.
+     */
     async run() {
-        const { packageManager, logger, root } = this.context;
-        const localRequire = node_module_1.default.createRequire((0, node_path_1.resolve)(__filename, '../../../'));
-        // Trailing slash is used to allow the path to be treated as a directory
-        const workspaceRequire = node_module_1.default.createRequire(root + '/');
-        const cliPackage = localRequire('./package.json');
-        let workspacePackage;
-        try {
-            workspacePackage = workspaceRequire('./package.json');
-        }
-        catch { }
-        const [nodeMajor] = process.versions.node.split('.').map((part) => Number(part));
-        const unsupportedNodeVersion = !SUPPORTED_NODE_MAJORS.includes(nodeMajor);
-        const packageNames = new Set(Object.keys({
-            ...cliPackage.dependencies,
-            ...cliPackage.devDependencies,
-            ...workspacePackage?.dependencies,
-            ...workspacePackage?.devDependencies,
-        }));
-        const versions = {};
-        for (const name of packageNames) {
-            if (PACKAGE_PATTERNS.some((p) => p.test(name))) {
-                versions[name] = this.getVersion(name, workspaceRequire, localRequire);
-            }
+        const { logger } = this.context;
+        const versionInfo = (0, version_info_1.gatherVersionInfo)(this.context);
+        const { ngCliVersion, nodeVersion, unsupportedNodeVersion, packageManagerName, packageManagerVersion, os, arch, versions, } = versionInfo;
+        const header = `
+      Angular CLI: ${ngCliVersion}
+      Node: ${nodeVersion}${unsupportedNodeVersion ? ' (Unsupported)' : ''}
+      Package Manager: ${packageManagerName} ${packageManagerVersion ?? '<error>'}
+      OS: ${os} ${arch}
+    `.replace(/^ {6}/gm, '');
+        const angularPackages = this.formatAngularPackages(versionInfo);
+        const packageTable = this.formatPackageTable(versions);
+        logger.info([ASCII_ART, header, angularPackages, packageTable].join('\n\n'));
+        if (unsupportedNodeVersion) {
+            logger.warn(`Warning: The current version of Node (${nodeVersion}) is not supported by Angular.`);
         }
-        const ngCliVersion = cliPackage.version;
-        let angularCoreVersion = '';
-        const angularSameAsCore = [];
-        if (workspacePackage) {
-            // Filter all angular versions that are the same as core.
-            angularCoreVersion = versions['@angular/core'];
-            if (angularCoreVersion) {
-                for (const [name, version] of Object.entries(versions)) {
-                    if (version === angularCoreVersion && name.startsWith('@angular/')) {
-                        angularSameAsCore.push(name.replace(/^@angular\//, ''));
-                        delete versions[name];
-                    }
-                }
-                // Make sure we list them in alphabetical order.
-                angularSameAsCore.sort();
-            }
+    }
+    /**
+     * Formats the Angular packages section of the version output.
+     * @param versionInfo An object containing the version information.
+     * @returns A string containing the formatted Angular packages information.
+     */
+    formatAngularPackages(versionInfo) {
+        const { angularCoreVersion, angularSameAsCore } = versionInfo;
+        if (!angularCoreVersion) {
+            return 'Angular: <error>';
         }
-        const namePad = ' '.repeat(Object.keys(versions).sort((a, b) => b.length - a.length)[0].length + 3);
-        const asciiArt = `
-     _                      _                 ____ _     ___
-    / \\   _ __   __ _ _   _| | __ _ _ __     / ___| |   |_ _|
-   / △ \\ | '_ \\ / _\` | | | | |/ _\` | '__|   | |   | |    | |
-  / ___ \\| | | | (_| | |_| | | (_| | |      | |___| |___ | |
- /_/   \\_\\_| |_|\\__, |\\__,_|_|\\__,_|_|       \\____|_____|___|
-                |___/
-    `
-            .split('\n')
-            .map((x) => color_1.colors.red(x))
-            .join('\n');
-        logger.info(asciiArt);
-        logger.info(`
-      Angular CLI: ${ngCliVersion}
-      Node: ${process.versions.node}${unsupportedNodeVersion ? ' (Unsupported)' : ''}
-      Package Manager: ${packageManager.name} ${packageManager.version ?? '<error>'}
-      OS: ${process.platform} ${process.arch}
-
-      Angular: ${angularCoreVersion}
-      ... ${angularSameAsCore
+        const wrappedPackages = angularSameAsCore
             .reduce((acc, name) => {
-            // Perform a simple word wrap around 60.
-            if (acc.length == 0) {
+            if (acc.length === 0) {
                 return [name];
             }
             const line = acc[acc.length - 1] + ', ' + name;
@@ -115,43 +85,32 @@ class VersionCommandModule extends command_module_1.CommandModule {
             }
             return acc;
         }, [])
-            .join('\n... ')}
-
-      Package${namePad.slice(7)}Version
-      -------${namePad.replace(/ /g, '-')}------------------
-      ${Object.keys(versions)
-            .map((module) => `${module}${namePad.slice(module.length)}${versions[module]}`)
-            .sort()
-            .join('\n')}
-    `.replace(/^ {6}/gm, ''));
-        if (unsupportedNodeVersion) {
-            logger.warn(`Warning: The current version of Node (${process.versions.node}) is not supported by Angular.`);
-        }
+            .join('\n... ');
+        return `Angular: ${angularCoreVersion}\n... ${wrappedPackages}`;
     }
-    getVersion(moduleName, workspaceRequire, localRequire) {
-        let packageInfo;
-        let cliOnly = false;
-        // Try to find the package in the workspace
-        try {
-            packageInfo = workspaceRequire(`${moduleName}/package.json`);
-        }
-        catch { }
-        // If not found, try to find within the CLI
-        if (!packageInfo) {
-            try {
-                packageInfo = localRequire(`${moduleName}/package.json`);
-                cliOnly = true;
-            }
-            catch { }
+    /**
+     * Formats the package table section of the version output.
+     * @param versions A map of package names to their versions.
+     * @returns A string containing the formatted package table.
+     */
+    formatPackageTable(versions) {
+        const versionKeys = Object.keys(versions);
+        if (versionKeys.length === 0) {
+            return '';
         }
-        // If found, attempt to get the version
-        if (packageInfo) {
-            try {
-                return packageInfo.version + (cliOnly ? ' (cli-only)' : '');
-            }
-            catch { }
-        }
-        return '<error>';
+        const header = 'Package';
+        const maxNameLength = Math.max(...versionKeys.map((key) => key.length));
+        const namePad = ' '.repeat(Math.max(0, maxNameLength - header.length) + 3);
+        const tableHeader = `${header}${namePad}Version`;
+        const separator = '-'.repeat(tableHeader.length);
+        const tableRows = versionKeys
+            .map((module) => {
+            const padding = ' '.repeat(maxNameLength - module.length + 3);
+            return `${module}${padding}${versions[module]}`;
+        })
+            .sort()
+            .join('\n');
+        return `${tableHeader}\n${separator}\n${tableRows}`;
     }
 }
 exports.default = VersionCommandModule;

package/src/commands/version/version-info.d.ts

@@ -0,0 +1,33 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+/**
+ * An object containing all the version information that will be displayed by the command.
+ */
+export interface VersionInfo {
+    ngCliVersion: string;
+    angularCoreVersion: string;
+    angularSameAsCore: string[];
+    versions: Record<string, string>;
+    unsupportedNodeVersion: boolean;
+    nodeVersion: string;
+    packageManagerName: string;
+    packageManagerVersion: string | undefined;
+    os: string;
+    arch: string;
+}
+/**
+ * Gathers all the version information from the environment and workspace.
+ * @returns An object containing all the version information.
+ */
+export declare function gatherVersionInfo(context: {
+    packageManager: {
+        name: string;
+        version: string | undefined;
+    };
+    root: string;
+}): VersionInfo;

package/src/commands/version/version-info.js

@@ -0,0 +1,122 @@
+"use strict";
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.gatherVersionInfo = gatherVersionInfo;
+const node_module_1 = require("node:module");
+const node_path_1 = require("node:path");
+/**
+ * Major versions of Node.js that are officially supported by Angular.
+ * @see https://angular.dev/reference/versions#supported-node-js-versions
+ */
+const SUPPORTED_NODE_MAJORS = [20, 22, 24];
+/**
+ * A list of regular expression patterns that match package names that should be included in the
+ * version output.
+ */
+const PACKAGE_PATTERNS = [
+    /^@angular\/.*/,
+    /^@angular-devkit\/.*/,
+    /^@ngtools\/.*/,
+    /^@schematics\/.*/,
+    /^rxjs$/,
+    /^typescript$/,
+    /^ng-packagr$/,
+    /^webpack$/,
+    /^zone\.js$/,
+];
+/**
+ * Gathers all the version information from the environment and workspace.
+ * @returns An object containing all the version information.
+ */
+function gatherVersionInfo(context) {
+    const localRequire = (0, node_module_1.createRequire)((0, node_path_1.resolve)(__filename, '../../../'));
+    // Trailing slash is used to allow the path to be treated as a directory
+    const workspaceRequire = (0, node_module_1.createRequire)(context.root + '/');
+    const cliPackage = localRequire('./package.json');
+    let workspacePackage;
+    try {
+        workspacePackage = workspaceRequire('./package.json');
+    }
+    catch { }
+    const [nodeMajor] = process.versions.node.split('.').map((part) => Number(part));
+    const unsupportedNodeVersion = !SUPPORTED_NODE_MAJORS.includes(nodeMajor);
+    const packageNames = new Set(Object.keys({
+        ...cliPackage.dependencies,
+        ...cliPackage.devDependencies,
+        ...workspacePackage?.dependencies,
+        ...workspacePackage?.devDependencies,
+    }));
+    const versions = {};
+    for (const name of packageNames) {
+        if (PACKAGE_PATTERNS.some((p) => p.test(name))) {
+            versions[name] = getVersion(name, workspaceRequire, localRequire);
+        }
+    }
+    const ngCliVersion = cliPackage.version;
+    let angularCoreVersion = '';
+    const angularSameAsCore = [];
+    if (workspacePackage) {
+        // Filter all angular versions that are the same as core.
+        angularCoreVersion = versions['@angular/core'];
+        if (angularCoreVersion) {
+            for (const [name, version] of Object.entries(versions)) {
+                if (version === angularCoreVersion && name.startsWith('@angular/')) {
+                    angularSameAsCore.push(name.replace(/^@angular\//, ''));
+                    delete versions[name];
+                }
+            }
+            // Make sure we list them in alphabetical order.
+            angularSameAsCore.sort();
+        }
+    }
+    return {
+        ngCliVersion,
+        angularCoreVersion,
+        angularSameAsCore,
+        versions,
+        unsupportedNodeVersion,
+        nodeVersion: process.versions.node,
+        packageManagerName: context.packageManager.name,
+        packageManagerVersion: context.packageManager.version,
+        os: process.platform,
+        arch: process.arch,
+    };
+}
+/**
+ * Gets the version of a package.
+ * @param moduleName The name of the package.
+ * @param workspaceRequire A `require` function for the workspace.
+ * @param localRequire A `require` function for the CLI.
+ * @returns The version of the package, or `<error>` if it could not be found.
+ */
+function getVersion(moduleName, workspaceRequire, localRequire) {
+    let packageInfo;
+    let cliOnly = false;
+    // Try to find the package in the workspace
+    try {
+        packageInfo = workspaceRequire(`${moduleName}/package.json`);
+    }
+    catch { }
+    // If not found, try to find within the CLI
+    if (!packageInfo) {
+        try {
+            packageInfo = localRequire(`${moduleName}/package.json`);
+            cliOnly = true;
+        }
+        catch { }
+    }
+    // If found, attempt to get the version
+    if (packageInfo) {
+        try {
+            return packageInfo.version + (cliOnly ? ' (cli-only)' : '');
+        }
+        catch { }
+    }
+    return '<error>';
+}

package/src/utilities/config.js

@@ -220,6 +220,9 @@ async function getWorkspaceRaw(level = 'local') {
 }
 async function validateWorkspace(data, isGlobal) {
     const schema = (0, json_file_1.readAndParseJson)(exports.workspaceSchemaPath);
+    if (!isJsonObject(schema)) {
+        throw new Error('Workspace schema is not a JSON object.');
+    }
     // We should eventually have a dedicated global config schema and use that to validate.
     const schemaToValidate = isGlobal
         ? {

package/src/utilities/environment-options.d.ts

@@ -5,8 +5,21 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.dev/license
  */
+/** Disables all analytics reporting when the `NG_CLI_ANALYTICS` environment variable is set to '0' or 'false'. */
 export declare const analyticsDisabled: boolean;
+/** Identifies when the CLI is running in a Continuous Integration environment. */
 export declare const isCI: boolean;
+/** Disables the automatic version check when the `NG_DISABLE_VERSION_CHECK` environment variable is enabled. */
 export declare const disableVersionCheck: boolean;
+/** Enables debugging messages when the `NG_DEBUG` environment variable is enabled. */
 export declare const ngDebug: boolean;
+/**
+ * Forces the autocomplete script to be generated.
+ * The `NG_FORCE_AUTOCOMPLETE` environment variable can be 'true', 'false', or undefined (for default behavior).
+ */
 export declare const forceAutocomplete: boolean | undefined;
+/**
+ * When enabled, forces TTY mode.
+ * The `NG_FORCE_TTY` environment variable can be 'true', 'false', or undefined (for default behavior).
+ */
+export declare const forceTty: boolean | undefined;

package/src/utilities/environment-options.js

@@ -7,24 +7,53 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.forceAutocomplete = exports.ngDebug = exports.disableVersionCheck = exports.isCI = exports.analyticsDisabled = void 0;
+exports.forceTty = exports.forceAutocomplete = exports.ngDebug = exports.disableVersionCheck = exports.isCI = exports.analyticsDisabled = void 0;
+/** A set of strings that are considered "truthy" when parsing environment variables. */
+const TRUTHY_VALUES = new Set(['1', 'true']);
+/** A set of strings that are considered "falsy" when parsing environment variables. */
+const FALSY_VALUES = new Set(['0', 'false']);
+/**
+ * Checks if an environment variable is present and has a non-empty value.
+ * @param variable The environment variable to check.
+ * @returns `true` if the variable is a non-empty string.
+ */
 function isPresent(variable) {
     return typeof variable === 'string' && variable !== '';
 }
-function isDisabled(variable) {
-    return isPresent(variable) && (variable === '0' || variable.toLowerCase() === 'false');
-}
-function isEnabled(variable) {
-    return isPresent(variable) && (variable === '1' || variable.toLowerCase() === 'true');
-}
-function optional(variable) {
+/**
+ * Parses an environment variable into a boolean or undefined.
+ * @returns `true` if the variable is truthy ('1', 'true').
+ * @returns `false` if the variable is falsy ('0', 'false').
+ * @returns `undefined` if the variable is not present or has an unknown value.
+ */
+function parseTristate(variable) {
     if (!isPresent(variable)) {
         return undefined;
     }
-    return isEnabled(variable);
+    const value = variable.toLowerCase();
+    if (TRUTHY_VALUES.has(value)) {
+        return true;
+    }
+    if (FALSY_VALUES.has(value)) {
+        return false;
+    }
+    return undefined;
 }
-exports.analyticsDisabled = isDisabled(process.env['NG_CLI_ANALYTICS']);
-exports.isCI = isEnabled(process.env['CI']);
-exports.disableVersionCheck = isEnabled(process.env['NG_DISABLE_VERSION_CHECK']);
-exports.ngDebug = isEnabled(process.env['NG_DEBUG']);
-exports.forceAutocomplete = optional(process.env['NG_FORCE_AUTOCOMPLETE']);
+/** Disables all analytics reporting when the `NG_CLI_ANALYTICS` environment variable is set to '0' or 'false'. */
+exports.analyticsDisabled = parseTristate(process.env['NG_CLI_ANALYTICS']) === false;
+/** Identifies when the CLI is running in a Continuous Integration environment. */
+exports.isCI = parseTristate(process.env['CI']) === true;
+/** Disables the automatic version check when the `NG_DISABLE_VERSION_CHECK` environment variable is enabled. */
+exports.disableVersionCheck = parseTristate(process.env['NG_DISABLE_VERSION_CHECK']) === true;
+/** Enables debugging messages when the `NG_DEBUG` environment variable is enabled. */
+exports.ngDebug = parseTristate(process.env['NG_DEBUG']) === true;
+/**
+ * Forces the autocomplete script to be generated.
+ * The `NG_FORCE_AUTOCOMPLETE` environment variable can be 'true', 'false', or undefined (for default behavior).
+ */
+exports.forceAutocomplete = parseTristate(process.env['NG_FORCE_AUTOCOMPLETE']);
+/**
+ * When enabled, forces TTY mode.
+ * The `NG_FORCE_TTY` environment variable can be 'true', 'false', or undefined (for default behavior).
+ */
+exports.forceTty = parseTristate(process.env['NG_FORCE_TTY']);

package/src/utilities/eol.d.ts

@@ -5,4 +5,16 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.dev/license
  */
+/**
+ * Gets the end-of-line sequence from a string.
+ *
+ * This function analyzes the given string to determine the most frequent end-of-line (EOL)
+ * sequence. It counts the occurrences of carriage return line feed (`\r\n`) and
+ * line feed (`\n`).
+ *
+ * @param content The string to process.
+ * @returns The most frequent EOL sequence. If `\r\n` is more frequent, it returns `\r\n`.
+ * Otherwise (including ties), it returns `\n`. If no newlines are found, it falls back
+ * to the operating system's default EOL sequence.
+ */
 export declare function getEOL(content: string): string;

package/src/utilities/eol.js

@@ -11,6 +11,18 @@ exports.getEOL = getEOL;
 const node_os_1 = require("node:os");
 const CRLF = '\r\n';
 const LF = '\n';
+/**
+ * Gets the end-of-line sequence from a string.
+ *
+ * This function analyzes the given string to determine the most frequent end-of-line (EOL)
+ * sequence. It counts the occurrences of carriage return line feed (`\r\n`) and
+ * line feed (`\n`).
+ *
+ * @param content The string to process.
+ * @returns The most frequent EOL sequence. If `\r\n` is more frequent, it returns `\r\n`.
+ * Otherwise (including ties), it returns `\n`. If no newlines are found, it falls back
+ * to the operating system's default EOL sequence.
+ */
 function getEOL(content) {
     const newlines = content.match(/(?:\r?\n)/g);
     if (newlines?.length) {

package/src/utilities/error.d.ts

@@ -5,6 +5,14 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.dev/license
  */
+/**
+ * Asserts that a given value is an Error-like object.
+ *
+ * If the value is not an `Error` or an object with `name` and `message` properties,
+ * this function will throw an `AssertionError` with a descriptive message.
+ *
+ * @param value The value to check.
+ */
 export declare function assertIsError(value: unknown): asserts value is Error & {
     code?: string;
 };

package/src/utilities/error.js

@@ -12,9 +12,29 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.assertIsError = assertIsError;
 const node_assert_1 = __importDefault(require("node:assert"));
+const node_util_1 = require("node:util");
+/**
+ * Checks if a given value is an Error-like object.
+ *
+ * This type guard checks if the value is an instance of `Error` or if it's an object
+ * with `name` and `message` properties. This is useful for identifying error-like
+ * objects that may not be direct instances of `Error` (e.g., from RxJs).
+ *
+ * @param value The value to check.
+ * @returns `true` if the value is an Error-like object, `false` otherwise.
+ */
+function isError(value) {
+    return (value instanceof Error ||
+        (typeof value === 'object' && value !== null && 'name' in value && 'message' in value));
+}
+/**
+ * Asserts that a given value is an Error-like object.
+ *
+ * If the value is not an `Error` or an object with `name` and `message` properties,
+ * this function will throw an `AssertionError` with a descriptive message.
+ *
+ * @param value The value to check.
+ */
 function assertIsError(value) {
-    const isError = value instanceof Error ||
-        // The following is needing to identify errors coming from RxJs.
-        (typeof value === 'object' && value && 'name' in value && 'message' in value);
-    (0, node_assert_1.default)(isError, 'catch clause variable is not an Error instance');
+    (0, node_assert_1.default)(isError(value), `Expected a value to be an Error-like object, but received: ${(0, node_util_1.inspect)(value)}`);
 }

package/src/utilities/json-file.d.ts

@@ -5,7 +5,20 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.dev/license
  */
+import { JsonValue } from '@angular-devkit/core';
+/** A function that returns an index to insert a new property in a JSON object. */
 export type InsertionIndex = (properties: string[]) => number;
+/** A JSON path. */
 export type JSONPath = (string | number)[];
-export declare function readAndParseJson(path: string): any;
-export declare function parseJson(content: string): any;
+/**
+ * Reads and parses a JSON file, supporting comments and trailing commas.
+ * @param path The path to the JSON file.
+ * @returns The parsed JSON object.
+ */
+export declare function readAndParseJson<T extends JsonValue>(path: string): T;
+/**
+ * Parses a JSON string, supporting comments and trailing commas.
+ * @param content The JSON string to parse.
+ * @returns The parsed JSON object.
+ */
+export declare function parseJson<T extends JsonValue>(content: string): T;