nx 20.8.4 → 22.7.7

package/dist/src/utils/plugins/output.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listPlugins = listPlugins;
+exports.listAlsoAvailableCorePlugins = listAlsoAvailableCorePlugins;
+exports.listPowerpackPlugins = listPowerpackPlugins;
+exports.listPluginCapabilities = listPluginCapabilities;
+exports.formatPluginCapabilitiesAsJson = formatPluginCapabilitiesAsJson;
+exports.formatPluginsAsJson = formatPluginsAsJson;
+const tslib_1 = require("tslib");
+const path_1 = require("path");
+const pc = tslib_1.__importStar(require("picocolors"));
+const output_1 = require("../output");
+const package_manager_1 = require("../package-manager");
+const workspace_root_1 = require("../workspace-root");
+const core_plugins_1 = require("./core-plugins");
+const plugin_capabilities_1 = require("./plugin-capabilities");
+const package_json_1 = require("../package-json");
+function listPlugins(plugins, title) {
+    package_json_1.readModulePackageJson;
+    const bodyLines = [];
+    for (const [, p] of plugins) {
+        const capabilities = [];
+        if (hasElements(p.executors)) {
+            capabilities.push('executors');
+        }
+        if (hasElements(p.generators)) {
+            capabilities.push('generators');
+        }
+        if (p.projectGraphExtension) {
+            capabilities.push('graph-extension');
+        }
+        if (p.projectInference) {
+            capabilities.push('project-inference');
+        }
+        bodyLines.push(`${pc.bold(p.name)} ${capabilities.length >= 1 ? `(${capabilities.join()})` : ''}`);
+    }
+    output_1.output.log({
+        title: title,
+        bodyLines: bodyLines,
+    });
+}
+function listAlsoAvailableCorePlugins(installedPlugins) {
+    const alsoAvailable = core_plugins_1.CORE_PLUGINS.filter((p) => !installedPlugins.has(p.name));
+    if (alsoAvailable.length) {
+        output_1.output.log({
+            title: `Also available:`,
+            bodyLines: alsoAvailable.map((p) => {
+                return `${pc.bold(p.name)} (${p.capabilities})`;
+            }),
+        });
+    }
+}
+function listPowerpackPlugins() {
+    const powerpackLink = 'https://nx.dev/plugin-registry#powerpack';
+    output_1.output.log({
+        title: `Available Powerpack Plugins: ${powerpackLink}`,
+    });
+}
+async function listPluginCapabilities(pluginName, projects, json = false) {
+    const plugin = await (0, plugin_capabilities_1.getPluginCapabilities)(workspace_root_1.workspaceRoot, pluginName, projects);
+    if (!plugin) {
+        if (json) {
+            console.log(JSON.stringify({ error: `${pluginName} is not installed` }));
+            return;
+        }
+        const pmc = (0, package_manager_1.getPackageManagerCommand)();
+        output_1.output.note({
+            title: `${pluginName} is not currently installed`,
+            bodyLines: [
+                `Use "${pmc.addDev} ${pluginName}" to install the plugin.`,
+                `After that, use "${pmc.exec} nx g ${pluginName}:init" to add the required peer deps and initialize the plugin.`,
+            ],
+        });
+        return;
+    }
+    const hasBuilders = hasElements(plugin.executors);
+    const hasGenerators = hasElements(plugin.generators);
+    const hasProjectGraphExtension = !!plugin.projectGraphExtension;
+    const hasProjectInference = !!plugin.projectInference;
+    if (!hasBuilders &&
+        !hasGenerators &&
+        !hasProjectGraphExtension &&
+        !hasProjectInference) {
+        if (json) {
+            console.log(JSON.stringify({
+                name: plugin.name,
+                path: plugin.path,
+                generators: {},
+                executors: {},
+                projectGraphExtension: false,
+                projectInference: false,
+            }));
+            return;
+        }
+        output_1.output.warn({ title: `No capabilities found in ${pluginName}` });
+        return;
+    }
+    if (json) {
+        console.log(JSON.stringify(formatPluginCapabilitiesAsJson(plugin), null, 2));
+        return;
+    }
+    const bodyLines = [];
+    if (plugin.path) {
+        bodyLines.push(`${pc.bold('Path:')} ${plugin.path}`);
+        bodyLines.push('');
+    }
+    if (hasGenerators) {
+        bodyLines.push(pc.bold(pc.green('GENERATORS')));
+        bodyLines.push('');
+        bodyLines.push(...Object.keys(plugin.generators).map((name) => `${pc.bold(name)} : ${plugin.generators[name].description}`));
+        if (hasBuilders) {
+            bodyLines.push('');
+        }
+    }
+    if (hasBuilders) {
+        bodyLines.push(pc.bold(pc.green('EXECUTORS/BUILDERS')));
+        bodyLines.push('');
+        bodyLines.push(...Object.keys(plugin.executors).map((name) => {
+            const definition = plugin.executors[name];
+            return typeof definition === 'string'
+                ? pc.bold(name)
+                : `${pc.bold(name)} : ${definition.description}`;
+        }));
+    }
+    if (hasProjectGraphExtension) {
+        bodyLines.push(`✔️  Project Graph Extension`);
+    }
+    if (hasProjectInference) {
+        bodyLines.push(`✔️  Project Inference`);
+    }
+    output_1.output.log({
+        title: `Capabilities in ${plugin.name}:`,
+        bodyLines,
+    });
+}
+function formatPluginCapabilitiesAsJson(plugin) {
+    const generators = {};
+    for (const [name, entry] of Object.entries(plugin.generators ?? {})) {
+        generators[name] = {
+            description: entry.description ?? '',
+            path: resolveCapabilityPath(plugin.path, entry.factory ?? entry.implementation),
+            schema: resolveCapabilityPath(plugin.path, entry.schema),
+        };
+    }
+    const executors = {};
+    for (const [name, entry] of Object.entries(plugin.executors ?? {})) {
+        if (typeof entry === 'string') {
+            executors[name] = { description: '', path: null, schema: null };
+        }
+        else {
+            executors[name] = {
+                description: entry.description ?? '',
+                path: resolveCapabilityPath(plugin.path, entry.implementation),
+                schema: resolveCapabilityPath(plugin.path, entry.schema),
+            };
+        }
+    }
+    return {
+        name: plugin.name,
+        path: plugin.path ?? null,
+        generators,
+        executors,
+        projectGraphExtension: !!plugin.projectGraphExtension,
+        projectInference: !!plugin.projectInference,
+    };
+}
+function formatPluginsAsJson(localPlugins, installedPlugins) {
+    function formatPluginSummary(plugin) {
+        const capabilities = [];
+        if (hasElements(plugin.executors)) {
+            capabilities.push('executors');
+        }
+        if (hasElements(plugin.generators)) {
+            capabilities.push('generators');
+        }
+        if (plugin.projectGraphExtension) {
+            capabilities.push('graph-extension');
+        }
+        if (plugin.projectInference) {
+            capabilities.push('project-inference');
+        }
+        return {
+            name: plugin.name,
+            path: plugin.path ?? null,
+            capabilities,
+        };
+    }
+    return {
+        localWorkspacePlugins: Array.from(localPlugins.values()).map(formatPluginSummary),
+        installedPlugins: Array.from(installedPlugins.values()).map(formatPluginSummary),
+    };
+}
+function resolveCapabilityPath(pluginPath, relativePath) {
+    if (!pluginPath || !relativePath) {
+        return null;
+    }
+    return (0, path_1.join)(pluginPath, relativePath);
+}
+function hasElements(obj) {
+    return obj && Object.values(obj).length > 0;
+}

package/dist/src/utils/plugins/plugin-capabilities.d.ts

@@ -0,0 +1,15 @@
+import { ExecutorsJsonEntry, GeneratorsJsonEntry } from '../../config/misc-interfaces';
+import { ProjectConfiguration } from '../../config/workspace-json-project-json';
+export interface PluginCapabilities {
+    name: string;
+    path?: string;
+    executors?: {
+        [name: string]: ExecutorsJsonEntry;
+    };
+    generators?: {
+        [name: string]: GeneratorsJsonEntry;
+    };
+    projectInference?: boolean;
+    projectGraphExtension?: boolean;
+}
+export declare function getPluginCapabilities(workspaceRoot: string, pluginName: string, projects: Record<string, ProjectConfiguration>, includeRuntimeCapabilities?: boolean): Promise<PluginCapabilities | null>;

package/dist/src/utils/plugins/plugin-capabilities.js

@@ -0,0 +1,78 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getPluginCapabilities = getPluginCapabilities;
+const path_1 = require("path");
+const fileutils_1 = require("../fileutils");
+const installation_directory_1 = require("../installation-directory");
+const plugins_1 = require("../../project-graph/plugins");
+const in_process_loader_1 = require("../../project-graph/plugins/in-process-loader");
+function tryGetCollection(packageJsonPath, collectionFile, propName) {
+    if (!collectionFile) {
+        return null;
+    }
+    try {
+        const collectionFilePath = (0, path_1.join)((0, path_1.dirname)(packageJsonPath), collectionFile);
+        return (0, fileutils_1.readJsonFile)(collectionFilePath)[propName];
+    }
+    catch {
+        return null;
+    }
+}
+async function getPluginCapabilities(workspaceRoot, pluginName, projects, includeRuntimeCapabilities = false) {
+    try {
+        const { json: packageJson, path: packageJsonPath } = (0, plugins_1.readPluginPackageJson)(pluginName, projects, (0, installation_directory_1.getNxRequirePaths)(workspaceRoot));
+        const pluginModule = includeRuntimeCapabilities
+            ? await tryGetModule(packageJson, workspaceRoot)
+            : {};
+        const pluginPath = (0, path_1.relative)(workspaceRoot, (0, path_1.dirname)(packageJsonPath)) || '.';
+        return {
+            name: pluginName,
+            path: pluginPath,
+            generators: {
+                ...tryGetCollection(packageJsonPath, packageJson.schematics, 'schematics'),
+                ...tryGetCollection(packageJsonPath, packageJson.generators, 'schematics'),
+                ...tryGetCollection(packageJsonPath, packageJson.schematics, 'generators'),
+                ...tryGetCollection(packageJsonPath, packageJson.generators, 'generators'),
+            },
+            executors: {
+                ...tryGetCollection(packageJsonPath, packageJson.builders, 'builders'),
+                ...tryGetCollection(packageJsonPath, packageJson.executors, 'builders'),
+                ...tryGetCollection(packageJsonPath, packageJson.builders, 'executors'),
+                ...tryGetCollection(packageJsonPath, packageJson.executors, 'executors'),
+            },
+            projectGraphExtension: pluginModule &&
+                ('processProjectGraph' in pluginModule ||
+                    'createNodes' in pluginModule ||
+                    'createNodesV2' in pluginModule ||
+                    'createMetadata' in pluginModule ||
+                    'createDependencies' in pluginModule),
+            projectInference: pluginModule &&
+                ('projectFilePatterns' in pluginModule ||
+                    'createNodes' in pluginModule ||
+                    'createNodesV2' in pluginModule),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+async function tryGetModule(packageJson, workspaceRoot) {
+    try {
+        if (packageJson.generators ??
+            packageJson.executors ??
+            packageJson['nx-migrations'] ??
+            packageJson['schematics'] ??
+            packageJson['builders']) {
+            const [pluginPromise] = (0, in_process_loader_1.loadNxPlugin)(packageJson.name, workspaceRoot);
+            return await pluginPromise;
+        }
+        else {
+            return {
+                name: packageJson.name,
+            };
+        }
+    }
+    catch {
+        return null;
+    }
+}

package/dist/src/utils/pnpm-workspace.d.ts

@@ -0,0 +1,8 @@
+export interface PnpmCatalogEntry {
+    [packageName: string]: string;
+}
+export interface PnpmWorkspaceYaml {
+    packages?: string[];
+    catalog?: PnpmCatalogEntry;
+    catalogs?: Record<string, PnpmCatalogEntry>;
+}

package/dist/src/utils/pnpm-workspace.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/src/utils/print-help.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.printHelp = printHelp;
+const tslib_1 = require("tslib");
+const pc = tslib_1.__importStar(require("picocolors"));
+const string_width_1 = tslib_1.__importDefault(require("string-width"));
+const logger_1 = require("./logger");
+const output_1 = require("./output");
+const versions_1 = require("./versions");
+const package_json_1 = require("./package-json");
+// cliui is the CLI layout engine developed by, and used within, yargs
+// the typings for cliui do not play nice with our tsconfig, it either
+// works in build or in test but not both.
+const cliui = require('cliui');
+function printHelp(header, schema, meta) {
+    const allPositional = Object.keys(schema.properties).filter((key) => {
+        const p = schema.properties[key];
+        return p['$default'] && p['$default']['$source'] === 'argv';
+    });
+    const positional = allPositional.length > 0 ? ` [${allPositional[0]}]` : '';
+    logger_1.logger.info(`
+${output_1.output.applyNxPrefix('cyan', pc.bold(`${`${header + pc.cyan(positional)} ${pc.cyan('[options,...]')}`}`))}
+
+${generateOverviewOutput({
+        pluginName: meta.plugin,
+        name: meta.entity,
+        description: schema.description,
+        mode: meta.mode,
+        aliases: meta.mode === 'generate' ? meta.aliases : [],
+    })}
+${generateOptionsOutput(schema)}
+${generateExamplesOutput(schema)}
+${generateLinkOutput({
+        pluginName: meta.plugin,
+        name: meta.entity,
+        type: meta.mode === 'generate' ? 'generators' : 'executors',
+    })}
+`);
+}
+function generateOverviewOutput({ pluginName, name, description, mode, aliases, }) {
+    switch (mode) {
+        case 'generate':
+            return generateGeneratorOverviewOutput({
+                pluginName,
+                name,
+                description,
+                aliases,
+            });
+        case 'run':
+            return generateExecutorOverviewOutput({
+                pluginName,
+                name,
+                description,
+            });
+        default:
+            throw new Error(`Unexpected mode ${mode}`);
+    }
+}
+function generateGeneratorOverviewOutput({ pluginName, name, description, aliases, }) {
+    const ui = cliui(null);
+    const overviewItemsLabelWidth = 
+    // Chars in labels "From" and "Name"
+    4 +
+        // The `:` char
+        1;
+    let installedVersion;
+    try {
+        installedVersion = (0, package_json_1.readModulePackageJson)(pluginName).packageJson.version;
+    }
+    catch { }
+    ui.div(...[
+        {
+            text: pc.bold('From:'),
+            padding: [1, 0, 0, 0],
+            width: overviewItemsLabelWidth,
+        },
+        {
+            text: pluginName +
+                (installedVersion ? pc.dim(` (v${installedVersion})`) : ''),
+            padding: [1, 0, 0, 2],
+        },
+    ]);
+    ui.div(...[
+        {
+            text: pc.bold('Name:'),
+            padding: [0, 0, 0, 0],
+            width: overviewItemsLabelWidth,
+        },
+        {
+            text: `${name}${aliases.length ? pc.dim(` (aliases: ${aliases.join(', ')})`) : ''}`,
+            padding: [0, 0, 0, 2],
+        },
+    ]);
+    ui.div(...[
+        {
+            text: description,
+            padding: [2, 0, 1, 2],
+        },
+    ]);
+    return ui.toString();
+}
+function generateExecutorOverviewOutput({ pluginName, name, description, }) {
+    const ui = cliui(null);
+    const overviewItemsLeftPadding = 2;
+    const overviewItemsLabelWidth = overviewItemsLeftPadding + 'Executor:'.length;
+    ui.div(...[
+        {
+            text: pc.bold('Executor:'),
+            padding: [1, 0, 0, 0],
+            width: overviewItemsLabelWidth,
+        },
+        {
+            text: `${pluginName}:${name}` +
+                (pluginName.startsWith('@nx/') ? pc.dim(` (v${versions_1.nxVersion})`) : ''),
+            padding: [1, 0, 0, 0],
+        },
+    ]);
+    ui.div(...[
+        {
+            text: description,
+            padding: [2, 0, 1, 2],
+        },
+    ]);
+    return ui.toString();
+}
+const formatOptionVal = (maybeStr) => typeof maybeStr === 'string' ? `"${maybeStr}"` : JSON.stringify(maybeStr);
+// From our JSON schemas an option could possibly have more than one valid type
+const formatOptionType = (optionConfig) => {
+    if (Array.isArray(optionConfig.oneOf)) {
+        return optionConfig.oneOf
+            .map((typeConfig) => formatOptionType(typeConfig))
+            .join(' OR ');
+    }
+    return `[${optionConfig.type}]`;
+};
+function generateOptionsOutput(schema) {
+    const ui = cliui(null);
+    const flagAndAliasLeftPadding = 4;
+    const flagAndAliasRightPadding = 4;
+    // Construct option flags (including optional aliases) and descriptions and track the required space to render them
+    const optionsToRender = new Map();
+    let requiredSpaceToRenderAllFlagsAndAliases = 0;
+    const sorted = Object.entries(schema.properties).sort((a, b) => compareByPriority(a, b, schema));
+    for (const [optionName, optionConfig] of sorted) {
+        const renderedFlagAndAlias = `--${optionName}` +
+            (optionConfig.alias ? `, -${optionConfig.alias}` : '');
+        const renderedFlagAndAliasTrueWidth = (0, string_width_1.default)(renderedFlagAndAlias);
+        if (renderedFlagAndAliasTrueWidth > requiredSpaceToRenderAllFlagsAndAliases) {
+            requiredSpaceToRenderAllFlagsAndAliases = renderedFlagAndAliasTrueWidth;
+        }
+        const renderedDescription = optionConfig.description;
+        const renderedTypesAndDefault = `${formatOptionType(optionConfig)}${optionConfig.enum
+            ? ` [choices: ${optionConfig.enum
+                .map((e) => formatOptionVal(e))
+                .join(', ')}]`
+            : ''}${optionConfig.default
+            ? ` [default: ${formatOptionVal(optionConfig.default)}]`
+            : ''}`;
+        optionConfig.hidden ??= optionConfig.visible === false;
+        if (!optionConfig.hidden)
+            optionsToRender.set(optionName, {
+                renderedFlagAndAlias,
+                renderedDescription,
+                renderedTypesAndDefault,
+            });
+    }
+    ui.div({
+        text: 'Options:',
+        padding: [1, 0, 0, 0],
+    });
+    for (const { renderedFlagAndAlias, renderedDescription, renderedTypesAndDefault, } of optionsToRender.values()) {
+        const cols = [
+            {
+                text: renderedFlagAndAlias,
+                width: requiredSpaceToRenderAllFlagsAndAliases +
+                    flagAndAliasLeftPadding +
+                    flagAndAliasRightPadding,
+                padding: [0, flagAndAliasRightPadding, 0, flagAndAliasLeftPadding],
+            },
+            {
+                text: renderedDescription,
+                padding: [0, 0, 0, 0],
+            },
+            {
+                text: renderedTypesAndDefault,
+                padding: [0, 0, 0, 0],
+                align: 'right',
+            },
+        ];
+        ui.div(...cols);
+    }
+    return ui.toString();
+}
+function generateExamplesOutput(schema) {
+    if (!schema.examples || schema.examples.length === 0) {
+        return '';
+    }
+    const ui = cliui(null);
+    const xPadding = 4;
+    ui.div({
+        text: 'Examples:',
+        padding: [1, 0, 0, 0],
+    });
+    for (const { command, description } of schema.examples) {
+        const cols = [
+            {
+                text: command,
+                padding: [0, xPadding, 0, xPadding],
+            },
+            {
+                text: description || '',
+                padding: [0, 2, 0, 0],
+            },
+        ];
+        ui.div(...cols);
+    }
+    return ui.toString();
+}
+// TODO: generalize link generation so it works for non @nx plugins as well
+function generateLinkOutput({ pluginName, name, type, }) {
+    const nxPackagePrefix = '@nx/';
+    if (!pluginName.startsWith(nxPackagePrefix)) {
+        return '';
+    }
+    const link = `https://nx.dev/nx-api/${pluginName.substring(nxPackagePrefix.length)}/${type}/${name}`;
+    return `\n\n${pc.dim('Find more information and examples at:')} ${pc.bold(link)}`;
+}
+/**
+ * sorts properties in the following order
+ * - required
+ * - x-priority: important
+ * - everything else
+ * - x-priority: internal
+ * - deprecated
+ * if two properties have equal priority, they are sorted by name
+ */
+function compareByPriority(a, b, schema) {
+    function getPriority([name, property]) {
+        if (schema.required?.includes(name)) {
+            return 0;
+        }
+        if (property['x-priority'] === 'important') {
+            return 1;
+        }
+        if (property['x-deprecated']) {
+            return 4;
+        }
+        if (property['x-priority'] === 'internal') {
+            return 3;
+        }
+        return 2;
+    }
+    const aPriority = getPriority(a);
+    const bPriority = getPriority(b);
+    if (aPriority === bPriority) {
+        return a[0].localeCompare(b[0]);
+    }
+    return aPriority - bPriority;
+}

package/dist/src/utils/progress-topics.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Named channels that daemon clients can subscribe to in order to
+ * receive streaming progress/log output produced by a long-running
+ * daemon operation. A handler subscribes the requesting socket to the
+ * topics it will produce output for, and broadcast helpers fan out to
+ * every currently-subscribed socket for that topic.
+ *
+ * Topics are the contract between the code producing progress (usually
+ * through a {@link DelayedSpinner}) and the daemon subscriber registry
+ * that routes those messages to connected clients, so they live next
+ * to the spinner rather than inside the daemon implementation.
+ *
+ * Add new topics here as other long-running daemon operations grow
+ * their own streaming surfaces.
+ */
+export declare const ProgressTopics: {
+    readonly GraphConstruction: "graph-construction";
+};
+export type ProgressTopic = (typeof ProgressTopics)[keyof typeof ProgressTopics];

package/dist/src/utils/progress-topics.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ProgressTopics = void 0;
+/**
+ * Named channels that daemon clients can subscribe to in order to
+ * receive streaming progress/log output produced by a long-running
+ * daemon operation. A handler subscribes the requesting socket to the
+ * topics it will produce output for, and broadcast helpers fan out to
+ * every currently-subscribed socket for that topic.
+ *
+ * Topics are the contract between the code producing progress (usually
+ * through a {@link DelayedSpinner}) and the daemon subscriber registry
+ * that routes those messages to connected clients, so they live next
+ * to the spinner rather than inside the daemon implementation.
+ *
+ * Add new topics here as other long-running daemon operations grow
+ * their own streaming surfaces.
+ */
+exports.ProgressTopics = {
+    GraphConstruction: 'graph-construction',
+};

package/dist/src/utils/project-graph-utils.d.ts

@@ -0,0 +1,18 @@
+import { ProjectGraph, ProjectGraphProjectNode } from '../config/project-graph';
+import type { ProjectConfiguration } from '../config/workspace-json-project-json';
+export declare function projectHasTarget(project: ProjectGraphProjectNode, target: string): boolean;
+export declare function projectHasTargetAndConfiguration(project: ProjectGraphProjectNode, target: string, configuration: string): any;
+export declare function getSourceDirOfDependentProjects(projectName: string, projectGraph?: ProjectGraph): [
+    projectDirs: string[],
+    warnings: string[]
+];
+/**
+ * Find all internal project dependencies.
+ * All the external (npm) dependencies will be filtered out unless includeExternalDependencies is set to true
+ * @param {string} parentNodeName
+ * @param {ProjectGraph} projectGraph
+ * @param includeExternalDependencies
+ * @returns {string[]}
+ */
+export declare function findAllProjectNodeDependencies(parentNodeName: string, projectGraph?: ProjectGraph, includeExternalDependencies?: boolean): string[];
+export declare function getProjectSourceRoot(project: ProjectConfiguration): string | undefined;