@angular/cli 14.0.0-next.1 → 14.0.0-next.12

package/src/command-builder/command-module.d.ts

@@ -0,0 +1,89 @@
+/**
+ * @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.io/license
+ */
+import { analytics, logging } from '@angular-devkit/core';
+import { ArgumentsCamelCase, Argv, CamelCaseKey, CommandModule as YargsCommandModule } from 'yargs';
+import { AngularWorkspace } from '../utilities/config';
+import { PackageManagerUtils } from '../utilities/package-manager';
+import { Option } from './utilities/json-schema';
+export declare type Options<T> = {
+    [key in keyof T as CamelCaseKey<key>]: T[key];
+};
+export declare enum CommandScope {
+    /** Command can only run inside an Angular workspace. */
+    In = 0,
+    /** Command can only run outside an Angular workspace. */
+    Out = 1,
+    /** Command can run inside and outside an Angular workspace. */
+    Both = 2
+}
+export interface CommandContext {
+    currentDirectory: string;
+    root: string;
+    workspace?: AngularWorkspace;
+    globalConfiguration?: AngularWorkspace;
+    logger: logging.Logger;
+    packageManager: PackageManagerUtils;
+    /** Arguments parsed in free-from without parser configuration. */
+    args: {
+        positional: string[];
+        options: {
+            help: boolean;
+            jsonHelp: boolean;
+            getYargsCompletions: boolean;
+        } & Record<string, unknown>;
+    };
+}
+export declare type OtherOptions = Record<string, unknown>;
+export interface CommandModuleImplementation<T extends {} = {}> extends Omit<YargsCommandModule<{}, T>, 'builder' | 'handler'> {
+    /** Path used to load the long description for the command in JSON help text. */
+    longDescriptionPath?: 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>;
+    /** A function which will be passed the parsed argv. */
+    run(options: Options<T> & OtherOptions): Promise<number | void> | number | void;
+}
+export interface FullDescribe {
+    describe?: string;
+    longDescription?: string;
+    longDescriptionRelativePath?: string;
+}
+export declare abstract class CommandModule<T extends {} = {}> implements CommandModuleImplementation<T> {
+    protected readonly context: CommandContext;
+    abstract readonly command: string;
+    abstract readonly describe: string | false;
+    abstract readonly longDescriptionPath?: string;
+    protected readonly shouldReportAnalytics: boolean;
+    static scope: CommandScope;
+    private readonly optionsWithAnalytics;
+    constructor(context: CommandContext);
+    /**
+     * Description object which contains the long command descroption.
+     * This is used to generate JSON help wich is used in AIO.
+     *
+     * `false` will result in a hidden command.
+     */
+    get fullDescribe(): FullDescribe | false;
+    protected get commandName(): string;
+    abstract builder(argv: Argv): Promise<Argv<T>> | Argv<T>;
+    abstract run(options: Options<T> & OtherOptions): Promise<number | void> | number | void;
+    handler(args: ArgumentsCamelCase<T> & OtherOptions): Promise<void>;
+    reportAnalytics(options: (Options<T> & OtherOptions) | OtherOptions, paths?: string[], dimensions?: (boolean | number | string)[]): Promise<void>;
+    protected getAnalytics(): Promise<analytics.Analytics>;
+    /**
+     * Adds schema options to a command also this keeps track of options that are required for analytics.
+     * **Note:** This method should be called from the command bundler method.
+     */
+    protected addSchemaOptionsToCommand<T>(localYargs: Argv<T>, options: Option[]): Argv<T>;
+    protected getWorkspaceOrThrow(): AngularWorkspace;
+}
+/**
+ * Creates an known command module error.
+ * This is used so during executation we can filter between known validation error and real non handled errors.
+ */
+export declare class CommandModuleError extends Error {
+}

package/src/command-builder/command-module.js

@@ -0,0 +1,198 @@
+"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.io/license
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CommandModuleError = exports.CommandModule = exports.CommandScope = void 0;
+const core_1 = require("@angular-devkit/core");
+const fs_1 = require("fs");
+const path = __importStar(require("path"));
+const helpers_1 = require("yargs/helpers");
+const analytics_1 = require("../analytics/analytics");
+const memoize_1 = require("../utilities/memoize");
+var CommandScope;
+(function (CommandScope) {
+    /** Command can only run inside an Angular workspace. */
+    CommandScope[CommandScope["In"] = 0] = "In";
+    /** Command can only run outside an Angular workspace. */
+    CommandScope[CommandScope["Out"] = 1] = "Out";
+    /** Command can run inside and outside an Angular workspace. */
+    CommandScope[CommandScope["Both"] = 2] = "Both";
+})(CommandScope = exports.CommandScope || (exports.CommandScope = {}));
+class CommandModule {
+    constructor(context) {
+        this.context = context;
+        this.shouldReportAnalytics = true;
+        this.optionsWithAnalytics = new Map();
+    }
+    /**
+     * Description object which contains the long command descroption.
+     * This is used to generate JSON help wich is used in AIO.
+     *
+     * `false` will result in a hidden command.
+     */
+    get fullDescribe() {
+        return this.describe === false
+            ? false
+            : {
+                describe: this.describe,
+                ...(this.longDescriptionPath
+                    ? {
+                        longDescriptionRelativePath: path
+                            .relative(path.join(__dirname, '../../../../'), this.longDescriptionPath)
+                            .replace(/\\/g, path.posix.sep),
+                        longDescription: (0, fs_1.readFileSync)(this.longDescriptionPath, 'utf8').replace(/\r\n/g, '\n'),
+                    }
+                    : {}),
+            };
+    }
+    get commandName() {
+        return this.command.split(' ', 1)[0];
+    }
+    async handler(args) {
+        const { _, $0, ...options } = args;
+        // Camelize options as yargs will return the object in kebab-case when camel casing is disabled.
+        const camelCasedOptions = {};
+        for (const [key, value] of Object.entries(options)) {
+            camelCasedOptions[helpers_1.Parser.camelCase(key)] = value;
+        }
+        // Gather and report analytics.
+        const analytics = await this.getAnalytics();
+        if (this.shouldReportAnalytics) {
+            await this.reportAnalytics(camelCasedOptions);
+        }
+        let exitCode;
+        try {
+            // Run and time command.
+            const startTime = Date.now();
+            exitCode = await this.run(camelCasedOptions);
+            const endTime = Date.now();
+            analytics.timing(this.commandName, 'duration', endTime - startTime);
+            await analytics.flush();
+        }
+        catch (e) {
+            if (e instanceof core_1.schema.SchemaValidationException) {
+                this.context.logger.fatal(`Error: ${e.message}`);
+                exitCode = 1;
+            }
+            else {
+                throw e;
+            }
+        }
+        finally {
+            if (typeof exitCode === 'number' && exitCode > 0) {
+                process.exitCode = exitCode;
+            }
+        }
+    }
+    async reportAnalytics(options, paths = [], dimensions = []) {
+        for (const [name, ua] of this.optionsWithAnalytics) {
+            const value = options[name];
+            if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+                dimensions[ua] = value;
+            }
+        }
+        const analytics = await this.getAnalytics();
+        analytics.pageview('/command/' + [this.commandName, ...paths].join('/'), {
+            dimensions,
+            metrics: [],
+        });
+    }
+    getAnalytics() {
+        return (0, analytics_1.createAnalytics)(!!this.context.workspace, 
+        // Don't prompt for `ng update` and `ng analytics` commands.
+        ['update', 'analytics'].includes(this.commandName));
+    }
+    /**
+     * Adds schema options to a command also this keeps track of options that are required for analytics.
+     * **Note:** This method should be called from the command bundler method.
+     */
+    addSchemaOptionsToCommand(localYargs, options) {
+        const workingDir = (0, core_1.normalize)(path.relative(this.context.root, process.cwd()));
+        for (const option of options) {
+            const { default: defaultVal, positional, deprecated, description, alias, userAnalytics, type, hidden, name, choices, format, } = option;
+            const sharedOptions = {
+                alias,
+                hidden,
+                description,
+                deprecated,
+                choices,
+                // This should only be done when `--help` is used otherwise default will override options set in angular.json.
+                ...(this.context.args.options.help ? { default: defaultVal } : {}),
+            };
+            // Special case for schematics
+            if (workingDir && format === 'path' && name === 'path' && hidden) {
+                sharedOptions.default = workingDir;
+            }
+            if (positional === undefined) {
+                localYargs = localYargs.option(core_1.strings.dasherize(name), {
+                    type,
+                    ...sharedOptions,
+                });
+            }
+            else {
+                localYargs = localYargs.positional(core_1.strings.dasherize(name), {
+                    type: type === 'array' || type === 'count' ? 'string' : type,
+                    ...sharedOptions,
+                });
+            }
+            // Record option of analytics.
+            if (userAnalytics !== undefined) {
+                this.optionsWithAnalytics.set(name, userAnalytics);
+            }
+        }
+        return localYargs;
+    }
+    getWorkspaceOrThrow() {
+        const { workspace } = this.context;
+        if (!workspace) {
+            throw new CommandModuleError('A workspace is required for this command.');
+        }
+        return workspace;
+    }
+}
+CommandModule.scope = CommandScope.Both;
+__decorate([
+    memoize_1.memoize
+], CommandModule.prototype, "getAnalytics", null);
+exports.CommandModule = CommandModule;
+/**
+ * Creates an known command module error.
+ * This is used so during executation we can filter between known validation error and real non handled errors.
+ */
+class CommandModuleError extends Error {
+}
+exports.CommandModuleError = CommandModuleError;

package/{utilities/package-json.js → src/command-builder/command-runner.d.ts}

@@ -1,4 +1,3 @@
-"use strict";
 /**
  * @license
  * Copyright Google LLC All Rights Reserved.
@@ -6,4 +5,5 @@
  * Use of this source code is governed by an MIT-style license that can be
  * found in the LICENSE file at https://angular.io/license
  */
-Object.defineProperty(exports, "__esModule", { value: true });
+import { logging } from '@angular-devkit/core';
+export declare function runCommand(args: string[], logger: logging.Logger): Promise<number>;

package/src/command-builder/command-runner.js

@@ -0,0 +1,168 @@
+"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.io/license
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCommand = void 0;
+const yargs_1 = __importDefault(require("yargs"));
+const helpers_1 = require("yargs/helpers");
+const cli_1 = require("../commands/add/cli");
+const cli_2 = require("../commands/analytics/cli");
+const cli_3 = require("../commands/build/cli");
+const cli_4 = require("../commands/cache/cli");
+const cli_5 = require("../commands/completion/cli");
+const cli_6 = require("../commands/config/cli");
+const cli_7 = require("../commands/deploy/cli");
+const cli_8 = require("../commands/doc/cli");
+const cli_9 = require("../commands/e2e/cli");
+const cli_10 = require("../commands/extract-i18n/cli");
+const cli_11 = require("../commands/generate/cli");
+const cli_12 = require("../commands/lint/cli");
+const cli_13 = require("../commands/make-this-awesome/cli");
+const cli_14 = require("../commands/new/cli");
+const cli_15 = require("../commands/run/cli");
+const cli_16 = require("../commands/serve/cli");
+const cli_17 = require("../commands/test/cli");
+const cli_18 = require("../commands/update/cli");
+const cli_19 = require("../commands/version/cli");
+const color_1 = require("../utilities/color");
+const config_1 = require("../utilities/config");
+const package_manager_1 = require("../utilities/package-manager");
+const command_module_1 = require("./command-module");
+const command_1 = require("./utilities/command");
+const json_help_1 = require("./utilities/json-help");
+const normalize_options_middleware_1 = require("./utilities/normalize-options-middleware");
+const COMMANDS = [
+    cli_19.VersionCommandModule,
+    cli_8.DocCommandModule,
+    cli_13.AwesomeCommandModule,
+    cli_6.ConfigCommandModule,
+    cli_2.AnalyticsCommandModule,
+    cli_1.AddCommandModule,
+    cli_11.GenerateCommandModule,
+    cli_3.BuildCommandModule,
+    cli_9.E2eCommandModule,
+    cli_17.TestCommandModule,
+    cli_16.ServeCommandModule,
+    cli_10.ExtractI18nCommandModule,
+    cli_7.DeployCommandModule,
+    cli_12.LintCommandModule,
+    cli_14.NewCommandModule,
+    cli_18.UpdateCommandModule,
+    cli_15.RunCommandModule,
+    cli_4.CacheCommandModule,
+    cli_5.CompletionCommandModule,
+].sort(); // Will be sorted by class name.
+const yargsParser = helpers_1.Parser;
+async function runCommand(args, logger) {
+    var _a, _b;
+    const { $0, _, help = false, jsonHelp = false, getYargsCompletions = false, ...rest } = yargsParser(args, {
+        boolean: ['help', 'json-help', 'get-yargs-completions'],
+        alias: { 'collection': 'c' },
+    });
+    // When `getYargsCompletions` is true the scriptName 'ng' at index 0 is not removed.
+    const positional = getYargsCompletions ? _.slice(1) : _;
+    let workspace;
+    let globalConfiguration;
+    try {
+        [workspace, globalConfiguration] = await Promise.all([
+            (0, config_1.getWorkspace)('local'),
+            (0, config_1.getWorkspace)('global'),
+        ]);
+    }
+    catch (e) {
+        logger.fatal(e.message);
+        return 1;
+    }
+    const root = (_a = workspace === null || workspace === void 0 ? void 0 : workspace.basePath) !== null && _a !== void 0 ? _a : process.cwd();
+    const context = {
+        globalConfiguration,
+        workspace,
+        logger,
+        currentDirectory: process.cwd(),
+        root,
+        packageManager: new package_manager_1.PackageManagerUtils({ globalConfiguration, workspace, root }),
+        args: {
+            positional: positional.map((v) => v.toString()),
+            options: {
+                help,
+                jsonHelp,
+                getYargsCompletions,
+                ...rest,
+            },
+        },
+    };
+    let localYargs = (0, yargs_1.default)(args);
+    for (const CommandModule of COMMANDS) {
+        if (!jsonHelp) {
+            // Skip scope validation when running with '--json-help' since it's easier to generate the output for all commands this way.
+            const scope = CommandModule.scope;
+            if ((scope === command_module_1.CommandScope.In && !workspace) || (scope === command_module_1.CommandScope.Out && workspace)) {
+                continue;
+            }
+        }
+        localYargs = (0, command_1.addCommandModuleToYargs)(localYargs, CommandModule, context);
+    }
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const usageInstance = localYargs.getInternalMethods().getUsageInstance();
+    if (jsonHelp) {
+        usageInstance.help = () => (0, json_help_1.jsonHelpUsage)();
+    }
+    if (getYargsCompletions) {
+        // When in auto completion mode avoid printing description as it causes a slugish
+        // experience when there are a large set of options.
+        usageInstance.getDescriptions = () => ({});
+    }
+    await localYargs
+        .scriptName('ng')
+        // https://github.com/yargs/yargs/blob/main/docs/advanced.md#customizing-yargs-parser
+        .parserConfiguration({
+        'populate--': true,
+        'unknown-options-as-args': false,
+        'dot-notation': false,
+        'boolean-negation': true,
+        'strip-aliased': true,
+        'strip-dashed': true,
+        'camel-case-expansion': false,
+    })
+        .option('json-help', {
+        describe: 'Show help in JSON format.',
+        implies: ['help'],
+        hidden: true,
+        type: 'boolean',
+    })
+        .help('help', 'Shows a help message for this command in the console.')
+        // A complete list of strings can be found: https://github.com/yargs/yargs/blob/main/locales/en.json
+        .updateStrings({
+        'Commands:': color_1.colors.cyan('Commands:'),
+        'Options:': color_1.colors.cyan('Options:'),
+        'Positionals:': color_1.colors.cyan('Arguments:'),
+        'deprecated': color_1.colors.yellow('deprecated'),
+        'deprecated: %s': color_1.colors.yellow('deprecated:') + ' %s',
+        'Did you mean %s?': 'Unknown command. Did you mean %s?',
+    })
+        .demandCommand(1, command_1.demandCommandFailureMessage)
+        .recommendCommands()
+        .middleware(normalize_options_middleware_1.normalizeOptionsMiddleware)
+        .version(false)
+        .showHelpOnFail(false)
+        .strict()
+        .fail((msg, err) => {
+        throw msg
+            ? // Validation failed example: `Unknown argument:`
+                new command_module_1.CommandModuleError(msg)
+            : // Unknown exception, re-throw.
+                err;
+    })
+        .wrap(yargs_1.default.terminalWidth())
+        .parseAsync();
+    return (_b = process.exitCode) !== null && _b !== void 0 ? _b : 0;
+}
+exports.runCommand = runCommand;

package/src/command-builder/schematics-command-module.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @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.io/license
+ */
+import { Collection } from '@angular-devkit/schematics';
+import { FileSystemCollectionDescription, FileSystemSchematicDescription, NodeWorkflow } from '@angular-devkit/schematics/tools';
+import { Argv } from 'yargs';
+import { CommandModule, CommandModuleImplementation, CommandScope, Options, OtherOptions } from './command-module';
+import { Option } from './utilities/json-schema';
+export declare const DEFAULT_SCHEMATICS_COLLECTION = "@schematics/angular";
+export interface SchematicsCommandArgs {
+    interactive: boolean;
+    force: boolean;
+    'dry-run': boolean;
+    defaults: boolean;
+}
+export interface SchematicsExecutionOptions extends Options<SchematicsCommandArgs> {
+    packageRegistry?: string;
+}
+export declare abstract class SchematicsCommandModule extends CommandModule<SchematicsCommandArgs> implements CommandModuleImplementation<SchematicsCommandArgs> {
+    static scope: CommandScope;
+    protected readonly allowPrivateSchematics: boolean;
+    protected readonly shouldReportAnalytics = false;
+    builder(argv: Argv): Promise<Argv<SchematicsCommandArgs>>;
+    /** Get schematic schema options.*/
+    protected getSchematicOptions(collection: Collection<FileSystemCollectionDescription, FileSystemSchematicDescription>, schematicName: string, workflow: NodeWorkflow): Promise<Option[]>;
+    protected getOrCreateWorkflowForBuilder(collectionName: string): NodeWorkflow;
+    protected getOrCreateWorkflowForExecution(collectionName: string, options: SchematicsExecutionOptions): Promise<NodeWorkflow>;
+    protected getSchematicCollections(): Promise<Set<string>>;
+    protected parseSchematicInfo(schematic: string | undefined): [collectionName: string | undefined, schematicName: string | undefined];
+    protected runSchematic(options: {
+        executionOptions: SchematicsExecutionOptions;
+        schematicOptions: OtherOptions;
+        collectionName: string;
+        schematicName: string;
+    }): Promise<number>;
+    private defaultProjectDeprecationWarningShown;
+    private getProjectName;
+    private getResolvePaths;
+}