@nx/plugin 0.0.0-pr-22179-271588f

package/src/generators/executor/executor.js

@@ -0,0 +1,126 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.executorGeneratorInternal = exports.executorGenerator = exports.createExecutorsJson = void 0;
+const devkit_1 = require("@nx/devkit");
+const path = require("path");
+const generator_1 = require("../lint-checks/generator");
+const versions_1 = require("../../utils/versions");
+const artifact_name_and_directory_utils_1 = require("@nx/devkit/src/generators/artifact-name-and-directory-utils");
+const path_1 = require("path");
+function addFiles(host, options) {
+    (0, devkit_1.generateFiles)(host, path.join(__dirname, './files/executor'), options.directory, {
+        ...options,
+    });
+    if (options.unitTestRunner === 'none') {
+        host.delete((0, devkit_1.joinPathFragments)(options.directory, `executor.spec.ts`));
+    }
+}
+function addHasherFiles(host, options) {
+    (0, devkit_1.generateFiles)(host, path.join(__dirname, './files/hasher'), options.directory, {
+        ...options,
+    });
+    if (options.unitTestRunner === 'none') {
+        host.delete((0, devkit_1.joinPathFragments)(options.directory, 'hasher.spec.ts'));
+    }
+}
+async function createExecutorsJson(host, projectRoot, projectName, skipLintChecks) {
+    (0, devkit_1.updateJson)(host, (0, devkit_1.joinPathFragments)(projectRoot, 'package.json'), (json) => {
+        json.executors ??= './executors.json';
+        return json;
+    });
+    (0, devkit_1.writeJson)(host, (0, devkit_1.joinPathFragments)(projectRoot, 'executors.json'), {
+        executors: {},
+    });
+    if (!skipLintChecks) {
+        await (0, generator_1.default)(host, {
+            projectName,
+        });
+    }
+}
+exports.createExecutorsJson = createExecutorsJson;
+async function updateExecutorJson(host, options) {
+    const packageJson = (0, devkit_1.readJson)(host, (0, devkit_1.joinPathFragments)(options.projectRoot, 'package.json'));
+    const packageJsonExecutors = packageJson.executors ?? packageJson.builders;
+    let executorsPath = packageJsonExecutors
+        ? (0, devkit_1.joinPathFragments)(options.projectRoot, packageJsonExecutors)
+        : null;
+    if (!executorsPath) {
+        executorsPath = (0, devkit_1.joinPathFragments)(options.projectRoot, 'executors.json');
+    }
+    if (!host.exists(executorsPath)) {
+        await createExecutorsJson(host, options.projectRoot, options.project, options.skipLintChecks);
+    }
+    // add dependencies
+    (0, devkit_1.updateJson)(host, (0, devkit_1.joinPathFragments)(options.projectRoot, 'package.json'), (json) => {
+        json.dependencies = {
+            '@nx/devkit': versions_1.nxVersion,
+            ...json.dependencies,
+        };
+        return json;
+    });
+    return (0, devkit_1.updateJson)(host, executorsPath, (json) => {
+        let executors = json.executors ?? json.builders;
+        executors ||= {};
+        executors[options.name] = {
+            implementation: `./${(0, devkit_1.joinPathFragments)((0, path_1.relative)(options.projectRoot, options.directory), 'executor')}`,
+            schema: `./${(0, devkit_1.joinPathFragments)((0, path_1.relative)(options.projectRoot, options.directory), 'schema.json')}`,
+            description: options.description,
+        };
+        if (options.includeHasher) {
+            executors[options.name].hasher = `./${(0, devkit_1.joinPathFragments)((0, path_1.relative)(options.projectRoot, options.directory), 'hasher')}`;
+        }
+        json.executors = executors;
+        return json;
+    });
+}
+async function normalizeOptions(tree, options) {
+    const { project, artifactName, filePath, directory } = await (0, artifact_name_and_directory_utils_1.determineArtifactNameAndDirectoryOptions)(tree, {
+        artifactType: 'executor',
+        callingGenerator: '@nx/plugin:executor',
+        name: options.name,
+        nameAndDirectoryFormat: options.nameAndDirectoryFormat,
+        project: options.project,
+        directory: options.directory,
+        fileName: 'executor',
+        derivedDirectory: 'executors',
+    });
+    const { className, propertyName } = (0, devkit_1.names)(artifactName);
+    const { root: projectRoot } = (0, devkit_1.readProjectConfiguration)(tree, project);
+    let description;
+    if (options.description) {
+        description = options.description;
+    }
+    else {
+        description = `${options.name} executor`;
+    }
+    return {
+        ...options,
+        filePath,
+        project,
+        directory,
+        className,
+        propertyName,
+        description,
+        projectRoot,
+    };
+}
+async function executorGenerator(tree, rawOptions) {
+    await executorGeneratorInternal(tree, {
+        nameAndDirectoryFormat: 'derived',
+        ...rawOptions,
+    });
+}
+exports.executorGenerator = executorGenerator;
+async function executorGeneratorInternal(host, schema) {
+    const options = await normalizeOptions(host, schema);
+    addFiles(host, options);
+    if (options.includeHasher) {
+        addHasherFiles(host, options);
+    }
+    await updateExecutorJson(host, options);
+    if (!schema.skipFormat) {
+        await (0, devkit_1.formatFiles)(host);
+    }
+}
+exports.executorGeneratorInternal = executorGeneratorInternal;
+exports.default = executorGenerator;

package/src/generators/executor/files/executor/executor.spec.ts.template

@@ -0,0 +1,11 @@
+import { <%= className %>ExecutorSchema } from './schema';
+import executor from './executor';
+
+const options: <%= className %>ExecutorSchema = {};
+
+describe('<%= className %> Executor', () => {
+  it('can run', async () => {
+    const output = await executor(options);
+    expect(output.success).toBe(true);
+  });
+});

package/src/generators/executor/files/executor/executor.ts.template

@@ -0,0 +1,11 @@
+import { <%= className %>ExecutorSchema } from './schema';
+
+export default async function runExecutor(
+  options: <%= className %>ExecutorSchema,
+) {
+  console.log('Executor ran for <%= className %>', options);
+  return {
+    success: true
+  };
+}
+

package/src/generators/executor/files/executor/schema.d.ts.template

@@ -0,0 +1 @@
+export interface <%= className %>ExecutorSchema {} // eslint-disable-line

package/src/generators/executor/files/executor/schema.json.template

@@ -0,0 +1,9 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "version": 2,
+  "title": "<%= className %> executor",
+  "description": "",
+  "type": "object",
+  "properties": {},
+  "required": []
+}

package/src/generators/executor/files/hasher/hasher.spec.ts.template

@@ -0,0 +1,23 @@
+import { TaskHasher, HasherContext } from '@nx/devkit';
+
+import { <%=propertyName%>Hasher } from './hasher';
+
+describe('<%=propertyName%>Hasher', () => {
+    it('should generate hash', async () => {
+        const mockHasher: TaskHasher = {
+            hashTask: jest.fn().mockReturnValue({value: 'hashed-task'})
+        } as unknown as TaskHasher
+        const hash = await <%=propertyName%>Hasher({
+            id: 'my-task-id',
+            target: {
+                project: 'proj',
+                target: 'target'
+            },
+            overrides: {},
+            outputs: []
+        }, {
+            hasher: mockHasher
+        } as unknown as HasherContext)
+        expect(hash).toEqual({value: 'hashed-task'})
+    })
+})

package/src/generators/executor/files/hasher/hasher.ts.template

@@ -0,0 +1,12 @@
+import { CustomHasher } from '@nx/devkit';
+
+/**
+ * This is a boilerplate custom hasher that matches
+ * the default Nx hasher. If you need to extend the behavior,
+ * you can consume workspace details from the context.
+ */
+export const <%=propertyName%>Hasher: CustomHasher = async (task, context) => {
+    return context.hasher.hashTask(task, context.taskGraph);
+};
+
+export default <%=propertyName%>Hasher;

package/src/generators/executor/schema.d.ts

@@ -0,0 +1,17 @@
+import type { NameAndDirectoryFormat } from '@nx/devkit/src/generators/artifact-name-and-directory-utils';
+
+export interface Schema {
+  name: string;
+  directory?: string;
+  description?: string;
+  unitTestRunner: 'jest' | 'none';
+  includeHasher: boolean;
+  nameAndDirectoryFormat?: NameAndDirectoryFormat;
+  skipLintChecks?: boolean;
+  skipFormat?: boolean;
+
+  /**
+   * @deprecated Provide the `directory` option instead. The project will be determined from the directory provided. It will be removed in Nx v19.
+   */
+  project?: string;
+}

package/src/generators/executor/schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "$id": "NxPluginExecutor",
+  "title": "Create an Executor for an Nx Plugin",
+  "description": "Create an Executor for an Nx Plugin.",
+  "examplesFile": "../../../docs/generators/executor-examples.md",
+  "type": "object",
+  "examples": [
+    {
+      "command": "nx g executor my-executor --project=my-plugin",
+      "description": "Generate `libs/my-plugin/src/executors/my-executor`"
+    }
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Executor name.",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use for the executor?",
+      "x-priority": "important"
+    },
+    "directory": {
+      "type": "string",
+      "description": "The directory at which to create the executor file. When `--nameAndDirectoryFormat=as-provided`, it will be relative to the current working directory. Otherwise, it will be relative to the workspace root.",
+      "aliases": ["dir"],
+      "x-priority": "important"
+    },
+    "description": {
+      "type": "string",
+      "description": "Executor description.",
+      "x-priority": "important"
+    },
+    "unitTestRunner": {
+      "type": "string",
+      "enum": ["jest", "none"],
+      "description": "Test runner to use for unit tests.",
+      "default": "jest"
+    },
+    "includeHasher": {
+      "type": "boolean",
+      "default": false,
+      "description": "Should the boilerplate for a custom hasher be generated?"
+    },
+    "skipLintChecks": {
+      "type": "boolean",
+      "default": false,
+      "description": "Do not add an eslint configuration for plugin json files."
+    },
+    "nameAndDirectoryFormat": {
+      "description": "Whether to generate the executor in the directory as provided, relative to the current working directory and ignoring the project (`as-provided`) or generate it using the project and directory relative to the workspace root (`derived`).",
+      "type": "string",
+      "enum": ["as-provided", "derived"]
+    },
+    "project": {
+      "type": "string",
+      "description": "The name of the project.",
+      "alias": "p",
+      "$default": {
+        "$source": "projectName"
+      },
+      "x-deprecated": "Provide the `directory` option instead and use the `as-provided` format. The project will be determined from the directory provided. It will be removed in Nx v19."
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "description": "Skip formatting files.",
+      "default": false,
+      "x-priority": "internal"
+    }
+  },
+  "required": ["name"],
+  "additionalProperties": false
+}

package/src/generators/generator/files/generator/generator.spec.ts.template

@@ -0,0 +1,20 @@
+import { createTreeWithEmptyWorkspace } from '@nx/devkit/testing';
+import { Tree, readProjectConfiguration } from '@nx/devkit';
+
+import { <%= generatorFnName %> } from './generator';
+import { <%= schemaInterfaceName %> } from './schema';
+
+describe('<%= name %> generator', () => {
+  let tree: Tree;
+  const options: <%= schemaInterfaceName %> = { name: 'test' };
+
+  beforeEach(() => {
+    tree = createTreeWithEmptyWorkspace();
+  });
+
+  it('should run successfully', async () => {
+    await <%= generatorFnName %>(tree, options);
+    const config = readProjectConfiguration(tree, 'test');
+    expect(config).toBeDefined();
+  });
+});

package/src/generators/generator/files/generator/generator.ts.template

@@ -0,0 +1,26 @@
+import {
+  addProjectConfiguration,
+  formatFiles,
+  generateFiles,
+  Tree,
+} from '@nx/devkit';
+import * as path from 'path';
+import { <%= className %>GeneratorSchema } from './schema';
+
+export async function <%= generatorFnName %> (tree: Tree, options: <%= schemaInterfaceName %>) {
+  const projectRoot = `libs/${options.name}`;
+  addProjectConfiguration(
+    tree,
+    options.name,
+    {
+      root: projectRoot,
+      projectType: 'library',
+      sourceRoot: `${projectRoot}/src`,
+      targets: {}
+    }
+  );
+  generateFiles(tree, path.join(__dirname, 'files'), projectRoot, options);
+  await formatFiles(tree);
+}
+
+export default <%= generatorFnName %>;

package/src/generators/generator/files/generator/schema.d.ts.template

@@ -0,0 +1,3 @@
+export interface <%= className %>GeneratorSchema {
+    name: string;
+}

package/src/generators/generator/files/generator/schema.json.template

@@ -0,0 +1,18 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "$id": "<%= className %>",
+  "title": "",
+  "type": "object",
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use?"
+    }
+  },
+  "required": ["name"]
+}

package/src/generators/generator/generator.d.ts

@@ -0,0 +1,6 @@
+import { Tree } from '@nx/devkit';
+import type { Schema } from './schema';
+export declare function createGeneratorsJson(host: Tree, projectRoot: string, projectName: string, skipLintChecks?: boolean, skipFormat?: boolean): Promise<void>;
+export declare function generatorGenerator(tree: Tree, rawOptions: Schema): Promise<void>;
+export declare function generatorGeneratorInternal(host: Tree, schema: Schema): Promise<void>;
+export default generatorGenerator;

package/src/generators/generator/generator.js

@@ -0,0 +1,127 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generatorGeneratorInternal = exports.generatorGenerator = exports.createGeneratorsJson = void 0;
+const devkit_1 = require("@nx/devkit");
+const has_generator_1 = require("../../utils/has-generator");
+const generator_1 = require("../lint-checks/generator");
+const versions_1 = require("../../utils/versions");
+const artifact_name_and_directory_utils_1 = require("@nx/devkit/src/generators/artifact-name-and-directory-utils");
+const path_1 = require("path");
+async function normalizeOptions(tree, options) {
+    const { project, fileName, artifactName, filePath, directory } = await (0, artifact_name_and_directory_utils_1.determineArtifactNameAndDirectoryOptions)(tree, {
+        artifactType: 'generator',
+        callingGenerator: '@nx/plugin:generator',
+        name: options.name,
+        nameAndDirectoryFormat: options.nameAndDirectoryFormat,
+        project: options.project,
+        directory: options.directory,
+        fileName: 'generator',
+        derivedDirectory: 'generators',
+    });
+    const { className, propertyName } = (0, devkit_1.names)(artifactName);
+    const { root: projectRoot, sourceRoot: projectSourceRoot } = (0, devkit_1.readProjectConfiguration)(tree, project);
+    let description;
+    if (options.description) {
+        description = options.description;
+    }
+    else {
+        description = `${options.name} generator`;
+    }
+    return {
+        ...options,
+        project,
+        directory,
+        fileName,
+        className,
+        propertyName,
+        description,
+        projectRoot,
+        projectSourceRoot,
+    };
+}
+function addFiles(host, options) {
+    const indexPath = (0, path_1.join)(options.directory, 'files/src/index.ts.template');
+    if (!host.exists(indexPath)) {
+        host.write(indexPath, 'const variable = "<%= name %>";');
+    }
+    (0, devkit_1.generateFiles)(host, (0, path_1.join)(__dirname, './files/generator'), options.directory, {
+        ...options,
+        generatorFnName: `${options.propertyName}Generator`,
+        schemaInterfaceName: `${options.className}GeneratorSchema`,
+    });
+    if (options.unitTestRunner === 'none') {
+        host.delete((0, path_1.join)(options.directory, `generator.spec.ts`));
+    }
+}
+async function createGeneratorsJson(host, projectRoot, projectName, skipLintChecks, skipFormat) {
+    (0, devkit_1.updateJson)(host, (0, devkit_1.joinPathFragments)(projectRoot, 'package.json'), (json) => {
+        json.generators ??= './generators.json';
+        return json;
+    });
+    (0, devkit_1.writeJson)(host, (0, devkit_1.joinPathFragments)(projectRoot, 'generators.json'), {
+        generators: {},
+    });
+    if (!skipLintChecks) {
+        await (0, generator_1.default)(host, {
+            projectName,
+            skipFormat,
+        });
+    }
+}
+exports.createGeneratorsJson = createGeneratorsJson;
+async function updateGeneratorJson(host, options) {
+    const packageJson = (0, devkit_1.readJson)(host, (0, devkit_1.joinPathFragments)(options.projectRoot, 'package.json'));
+    const packageJsonGenerators = packageJson.generators ?? packageJson.schematics;
+    let generatorsPath = packageJsonGenerators
+        ? (0, devkit_1.joinPathFragments)(options.projectRoot, packageJsonGenerators)
+        : null;
+    if (!generatorsPath) {
+        generatorsPath = (0, devkit_1.joinPathFragments)(options.projectRoot, 'generators.json');
+    }
+    if (!host.exists(generatorsPath)) {
+        await createGeneratorsJson(host, options.projectRoot, options.project, options.skipLintChecks, options.skipFormat);
+    }
+    // add dependencies
+    (0, devkit_1.updateJson)(host, (0, devkit_1.joinPathFragments)(options.projectRoot, 'package.json'), (json) => {
+        json.dependencies = {
+            '@nx/devkit': versions_1.nxVersion,
+            ...json.dependencies,
+        };
+        return json;
+    });
+    (0, devkit_1.updateJson)(host, generatorsPath, (json) => {
+        let generators = json.generators ?? json.schematics;
+        generators = generators || {};
+        generators[options.name] = {
+            factory: `./${(0, devkit_1.joinPathFragments)((0, path_1.relative)(options.projectRoot, options.directory), 'generator')}`,
+            schema: `./${(0, devkit_1.joinPathFragments)((0, path_1.relative)(options.projectRoot, options.directory), 'schema.json')}`,
+            description: options.description,
+        };
+        // @todo(v17): Remove this, prop is defunct.
+        if (options.name === 'preset') {
+            generators[options.name]['x-use-standalone-layout'] = true;
+        }
+        json.generators = generators;
+        return json;
+    });
+}
+async function generatorGenerator(tree, rawOptions) {
+    await generatorGeneratorInternal(tree, {
+        nameAndDirectoryFormat: 'derived',
+        ...rawOptions,
+    });
+}
+exports.generatorGenerator = generatorGenerator;
+async function generatorGeneratorInternal(host, schema) {
+    const options = await normalizeOptions(host, schema);
+    if ((0, has_generator_1.hasGenerator)(host, options.project, options.name)) {
+        throw new Error(`Generator ${options.name} already exists.`);
+    }
+    addFiles(host, options);
+    await updateGeneratorJson(host, options);
+    if (!options.skipFormat) {
+        await (0, devkit_1.formatFiles)(host);
+    }
+}
+exports.generatorGeneratorInternal = generatorGeneratorInternal;
+exports.default = generatorGenerator;

package/src/generators/generator/schema.d.ts

@@ -0,0 +1,16 @@
+import { NameAndDirectoryFormat } from '@nx/devkit/src/generators/artifact-name-and-directory-utils';
+
+export interface Schema {
+  directory?: string;
+  name: string;
+  description?: string;
+  unitTestRunner: 'jest' | 'none';
+  skipLintChecks?: boolean;
+  skipFormat?: boolean;
+  nameAndDirectoryFormat?: NameAndDirectoryFormat;
+
+  /**
+   * @deprecated Provide the `directory` option instead. The project will be determined from the directory provided. It will be removed in Nx v19.
+   */
+  project?: string;
+}

package/src/generators/generator/schema.json

@@ -0,0 +1,70 @@
+{
+  "$schema": "https://json-schema.org/schema",
+  "cli": "nx",
+  "$id": "NxPluginGenerator",
+  "title": "Create a Generator for an Nx Plugin",
+  "description": "Create a Generator for an Nx Plugin.",
+  "type": "object",
+  "examples": [
+    {
+      "command": "nx g generator my-generator --project=my-plugin",
+      "description": "Generate `libs/my-plugin/src/generators/my-generator`"
+    }
+  ],
+  "properties": {
+    "name": {
+      "type": "string",
+      "description": "Generator name.",
+      "$default": {
+        "$source": "argv",
+        "index": 0
+      },
+      "x-prompt": "What name would you like to use for the generator?",
+      "x-priority": "important"
+    },
+    "directory": {
+      "type": "string",
+      "description": "The directory at which to create the generator file. When `--nameAndDirectoryFormat=as-provided`, it will be relative to the current working directory. Otherwise, it will be relative to the workspace root.",
+      "aliases": ["dir"],
+      "x-priority": "important"
+    },
+    "description": {
+      "type": "string",
+      "description": "Generator description.",
+      "x-priority": "important"
+    },
+    "unitTestRunner": {
+      "type": "string",
+      "enum": ["jest", "none"],
+      "description": "Test runner to use for unit tests.",
+      "default": "jest"
+    },
+    "skipLintChecks": {
+      "type": "boolean",
+      "default": false,
+      "description": "Do not add an eslint configuration for plugin json files."
+    },
+    "project": {
+      "type": "string",
+      "description": "The name of the project.",
+      "alias": "p",
+      "$default": {
+        "$source": "projectName"
+      },
+      "x-deprecated": "Provide the `directory` option instead and use the `as-provided` format. The project will be determined from the directory provided. It will be removed in Nx v19."
+    },
+    "skipFormat": {
+      "type": "boolean",
+      "default": false,
+      "description": "Do not format files with prettier.",
+      "x-priority": "internal"
+    },
+    "nameAndDirectoryFormat": {
+      "description": "Whether to generate the generator in the directory as provided, relative to the current working directory and ignoring the project (`as-provided`) or generate it using the project and directory relative to the workspace root (`derived`).",
+      "type": "string",
+      "enum": ["as-provided", "derived"]
+    }
+  },
+  "required": ["name"],
+  "additionalProperties": false
+}

package/src/generators/lint-checks/generator.d.ts

@@ -0,0 +1,7 @@
+import { ProjectConfiguration, TargetConfiguration, Tree } from '@nx/devkit';
+import type { Schema as EsLintExecutorOptions } from '@nx/eslint/src/executors/lint/schema';
+import { PluginLintChecksGeneratorSchema } from './schema';
+import { PackageJson } from 'nx/src/utils/package-json';
+export default function pluginLintCheckGenerator(host: Tree, options: PluginLintChecksGeneratorSchema): Promise<void>;
+export declare function addMigrationJsonChecks(host: Tree, options: PluginLintChecksGeneratorSchema, packageJson: PackageJson): void;
+export declare function getEsLintOptions(project: ProjectConfiguration): [target: string, configuration: TargetConfiguration<EsLintExecutorOptions>];