@angular/cli 14.0.0-next.2 → 14.0.0-next.5

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

@@ -0,0 +1,85 @@
+/**
+ * @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 { 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;
+    logger: logging.Logger;
+    /** Arguments parsed in free-from without parser configuration. */
+    args: {
+        positional: string[];
+        options: {
+            help: 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 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>;
+    private _analytics;
+    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,185 @@
+"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;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (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 __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");
+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'),
+                    }
+                    : {}),
+            };
+    }
+    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: [],
+        });
+    }
+    async getAnalytics() {
+        if (this._analytics) {
+            return this._analytics;
+        }
+        return (this._analytics = await (0, analytics_1.createAnalytics)(!!this.context.workspace, this.commandName === 'update'));
+    }
+    /**
+     * 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;
+    }
+}
+exports.CommandModule = CommandModule;
+CommandModule.scope = CommandScope.Both;
+/**
+ * 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/src/command-builder/command-runner.d.ts

@@ -0,0 +1,10 @@
+/**
+ * @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 { logging } from '@angular-devkit/core';
+import { AngularWorkspace } from '../utilities/config';
+export declare function runCommand(args: string[], logger: logging.Logger, workspace: AngularWorkspace | undefined): Promise<number>;

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

@@ -0,0 +1,146 @@
+"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/config/cli");
+const cli_5 = require("../commands/deploy/cli");
+const cli_6 = require("../commands/doc/cli");
+const cli_7 = require("../commands/e2e/cli");
+const cli_8 = require("../commands/extract-i18n/cli");
+const cli_9 = require("../commands/generate/cli");
+const cli_10 = require("../commands/lint/cli");
+const cli_11 = require("../commands/make-this-awesome/cli");
+const cli_12 = require("../commands/new/cli");
+const cli_13 = require("../commands/run/cli");
+const cli_14 = require("../commands/serve/cli");
+const cli_15 = require("../commands/test/cli");
+const cli_16 = require("../commands/update/cli");
+const cli_17 = require("../commands/version/cli");
+const color_1 = require("../utilities/color");
+const command_module_1 = require("./command-module");
+const json_help_1 = require("./utilities/json-help");
+const COMMANDS = [
+    cli_17.VersionCommandModule,
+    cli_6.DocCommandModule,
+    cli_11.AwesomeCommandModule,
+    cli_4.ConfigCommandModule,
+    cli_2.AnalyticsCommandModule,
+    cli_1.AddCommandModule,
+    cli_9.GenerateCommandModule,
+    cli_3.BuildCommandModule,
+    cli_7.E2eCommandModule,
+    cli_15.TestCommandModule,
+    cli_14.ServeCommandModule,
+    cli_8.ExtractI18nCommandModule,
+    cli_5.DeployCommandModule,
+    cli_10.LintCommandModule,
+    cli_12.NewCommandModule,
+    cli_16.UpdateCommandModule,
+    cli_13.RunCommandModule,
+];
+const yargsParser = helpers_1.Parser;
+async function runCommand(args, logger, workspace) {
+    var _a, _b;
+    const { $0, _: positional, help = false, jsonHelp = false, ...rest } = yargsParser(args, { boolean: ['help', 'json-help'], alias: { 'collection': 'c' } });
+    const context = {
+        workspace,
+        logger,
+        currentDirectory: process.cwd(),
+        root: (_a = workspace === null || workspace === void 0 ? void 0 : workspace.basePath) !== null && _a !== void 0 ? _a : process.cwd(),
+        args: {
+            positional: positional.map((v) => v.toString()),
+            options: {
+                help,
+                ...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;
+            }
+        }
+        const commandModule = new CommandModule(context);
+        const describe = jsonHelp ? commandModule.fullDescribe : commandModule.describe;
+        localYargs = localYargs.command({
+            command: commandModule.command,
+            aliases: 'aliases' in commandModule ? commandModule.aliases : undefined,
+            describe: 
+            // We cannot add custom fields in help, such as long command description which is used in AIO.
+            // Therefore, we get around this by adding a complex object as a string which we later parse when generating the help files.
+            describe !== undefined && typeof describe === 'object'
+                ? JSON.stringify(describe)
+                : describe,
+            deprecated: 'deprecated' in commandModule ? commandModule.deprecated : undefined,
+            builder: (argv) => commandModule.builder(argv),
+            // eslint-disable-next-line @typescript-eslint/no-explicit-any
+            handler: (args) => commandModule.handler(args),
+        });
+    }
+    if (jsonHelp) {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        localYargs.getInternalMethods().getUsageInstance().help = () => (0, json_help_1.jsonHelpUsage)();
+    }
+    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()
+        .recommendCommands()
+        .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,31 @@
+/**
+ * @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 } from './command-module';
+import { Option } from './utilities/json-schema';
+export interface SchematicsCommandArgs {
+    interactive: boolean;
+    force: boolean;
+    'dry-run': boolean;
+    defaults: boolean;
+}
+export declare abstract class SchematicsCommandModule extends CommandModule<SchematicsCommandArgs> implements CommandModuleImplementation<SchematicsCommandArgs> {
+    static scope: CommandScope;
+    protected readonly schematicName: string | undefined;
+    builder(argv: Argv): Promise<Argv<SchematicsCommandArgs>>;
+    /** Get schematic schema options.*/
+    protected getSchematicOptions(collection: Collection<FileSystemCollectionDescription, FileSystemSchematicDescription>, schematicName: string, workflow: NodeWorkflow): Promise<Option[]>;
+    protected getCollectionName(): Promise<string>;
+    private _workflow;
+    protected getOrCreateWorkflow(collectionName: string): NodeWorkflow;
+    private _defaultSchematicCollection;
+    protected getDefaultSchematicCollection(): Promise<string>;
+    protected parseSchematicInfo(schematic: string | undefined): [collectionName: string | undefined, schematicName: string | undefined];
+}

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

@@ -0,0 +1,117 @@
+"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
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SchematicsCommandModule = void 0;
+const tools_1 = require("@angular-devkit/schematics/tools");
+const schematic_engine_host_1 = require("../../models/schematic-engine-host");
+const config_1 = require("../utilities/config");
+const command_module_1 = require("./command-module");
+const json_schema_1 = require("./utilities/json-schema");
+const DEFAULT_SCHEMATICS_COLLECTION = '@schematics/angular';
+class SchematicsCommandModule extends command_module_1.CommandModule {
+    async builder(argv) {
+        const localYargs = argv
+            .option('interactive', {
+            describe: 'Enable interactive input prompts.',
+            type: 'boolean',
+            default: true,
+        })
+            .option('dry-run', {
+            describe: 'Run through and reports activity without writing out results.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('defaults', {
+            describe: 'Disable interactive input prompts for options with a default.',
+            type: 'boolean',
+            default: false,
+        })
+            .option('force', {
+            describe: 'Force overwriting of existing files.',
+            type: 'boolean',
+            default: false,
+        })
+            .strict();
+        if (this.schematicName) {
+            const collectionName = await this.getCollectionName();
+            const workflow = this.getOrCreateWorkflow(collectionName);
+            const collection = workflow.engine.createCollection(collectionName);
+            const options = await this.getSchematicOptions(collection, this.schematicName, workflow);
+            return this.addSchemaOptionsToCommand(localYargs, options);
+        }
+        return localYargs;
+    }
+    /** Get schematic schema options.*/
+    async getSchematicOptions(collection, schematicName, workflow) {
+        const schematic = collection.createSchematic(schematicName, true);
+        const { schemaJson } = schematic.description;
+        if (!schemaJson) {
+            return [];
+        }
+        return (0, json_schema_1.parseJsonSchemaToOptions)(workflow.registry, schemaJson);
+    }
+    async getCollectionName() {
+        var _a, _b;
+        const { options: { collection }, positional, } = this.context.args;
+        return ((_b = (_a = (typeof collection === 'string' ? collection : undefined)) !== null && _a !== void 0 ? _a : 
+        // positional = [generate, lint] or [new, collection-package]
+        this.parseSchematicInfo(positional[1])[0]) !== null && _b !== void 0 ? _b : (await this.getDefaultSchematicCollection()));
+    }
+    getOrCreateWorkflow(collectionName) {
+        if (this._workflow) {
+            return this._workflow;
+        }
+        const { root, workspace } = this.context;
+        return new tools_1.NodeWorkflow(root, {
+            resolvePaths: workspace
+                ? // Workspace
+                    collectionName === DEFAULT_SCHEMATICS_COLLECTION
+                        ? // Favor __dirname for @schematics/angular to use the build-in version
+                            [__dirname, process.cwd(), root]
+                        : [process.cwd(), root, __dirname]
+                : // Global
+                    [__dirname, process.cwd()],
+            engineHostCreator: (options) => new schematic_engine_host_1.SchematicEngineHost(options.resolvePaths),
+        });
+    }
+    async getDefaultSchematicCollection() {
+        if (this._defaultSchematicCollection) {
+            return this._defaultSchematicCollection;
+        }
+        let workspace = await (0, config_1.getWorkspace)('local');
+        if (workspace) {
+            const project = (0, config_1.getProjectByCwd)(workspace);
+            if (project) {
+                const value = workspace.getProjectCli(project)['defaultCollection'];
+                if (typeof value == 'string') {
+                    return (this._defaultSchematicCollection = value);
+                }
+            }
+            const value = workspace.getCli()['defaultCollection'];
+            if (typeof value === 'string') {
+                return (this._defaultSchematicCollection = value);
+            }
+        }
+        workspace = await (0, config_1.getWorkspace)('global');
+        const value = workspace === null || workspace === void 0 ? void 0 : workspace.getCli()['defaultCollection'];
+        if (typeof value === 'string') {
+            return (this._defaultSchematicCollection = value);
+        }
+        return (this._defaultSchematicCollection = DEFAULT_SCHEMATICS_COLLECTION);
+    }
+    parseSchematicInfo(schematic) {
+        if (schematic === null || schematic === void 0 ? void 0 : schematic.includes(':')) {
+            const [collectionName, schematicName] = schematic.split(':', 2);
+            return [collectionName, schematicName];
+        }
+        return [undefined, schematic];
+    }
+}
+exports.SchematicsCommandModule = SchematicsCommandModule;
+SchematicsCommandModule.scope = command_module_1.CommandScope.In;

package/src/command-builder/utilities/json-help.d.ts

@@ -0,0 +1,34 @@
+/**
+ * @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
+ */
+export interface JsonHelp {
+    name: string;
+    shortDescription?: string;
+    command: string;
+    longDescription?: string;
+    longDescriptionRelativePath?: string;
+    options: JsonHelpOption[];
+    subcommands?: {
+        name: string;
+        description: string;
+        aliases: string[];
+        deprecated: string | boolean;
+    }[];
+}
+interface JsonHelpOption {
+    name: string;
+    type?: string;
+    deprecated: boolean | string;
+    aliases?: string[];
+    default?: string;
+    required?: boolean;
+    positional?: number;
+    enum?: string[];
+    description?: string;
+}
+export declare function jsonHelpUsage(): string;
+export {};