@ohos-ports/nx 23.2.1-beta.0 → 23.3.0-beta.0

package/dist/src/project-graph/plugins/isolation/plugin-worker.js

@@ -0,0 +1,225 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+// Must be the first import — see enable-compile-cache.ts.
+require("../../../utils/enable-compile-cache");
+const node_perf_hooks_1 = require("node:perf_hooks");
+node_perf_hooks_1.performance.mark(`plugin worker ${process.pid} code loading -- start`);
+const consume_messages_from_socket_1 = require("../../../utils/consume-messages-from-socket");
+const logger_1 = require("../../../utils/logger");
+const serializable_error_1 = require("../../../utils/serializable-error");
+const daemon_message_1 = require("../../../daemon/message-types/daemon-message");
+const messaging_1 = require("./messaging");
+const worker_streaming_1 = require("./worker-streaming");
+const fs_1 = require("fs");
+const net_1 = require("net");
+const analytics_1 = require("../../../analytics");
+const daemon_environment_1 = require("../../../daemon/client/daemon-environment");
+const sandbox_socket_hint_1 = require("../../../daemon/sandbox-socket-hint");
+const permission_errors_1 = require("../../../utils/permission-errors");
+const socket_refused_exit_code_1 = require("../../../utils/socket-refused-exit-code");
+const is_sandbox_1 = require("../../../utils/is-sandbox");
+require("../../../utils/perf-logging");
+const environment = process.env;
+(0, analytics_1.startAnalytics)();
+node_perf_hooks_1.performance.mark(`plugin worker ${process.pid} code loading -- end`);
+node_perf_hooks_1.performance.measure(`plugin worker ${process.pid} code loading`, `plugin worker ${process.pid} code loading -- start`, `plugin worker ${process.pid} code loading -- end`);
+global.NX_GRAPH_CREATION = true;
+global.NX_PLUGIN_WORKER = true;
+let plugin;
+const socketPath = process.argv[2];
+const expectedPluginName = process.argv[3];
+// The host's root, passed explicitly rather than re-resolved: a host that set
+// its root at runtime would resolve a different one here and drop every
+// legitimate message as foreign.
+const hostWorkspaceRoot = process.argv[4];
+// Positional, so inserting an argument host-side shifts all of them — and the
+// symptom is silent and total: an undefined hostWorkspaceRoot makes every
+// message look foreign while the host waits out its plugin timeout.
+if (!socketPath || !expectedPluginName || !hostWorkspaceRoot) {
+    console.error(`[plugin-worker] started with an incomplete argument list ` +
+        `(socketPath=${socketPath}, pluginName=${expectedPluginName}, hostWorkspaceRoot=${hostWorkspaceRoot}). ` +
+        `This is an Nx bug — please report it at https://github.com/nrwl/nx/issues.`);
+    process.exit(1);
+}
+const CONNECT_TIMEOUT_MS = 30_000;
+// Runs in this worker's own loop from the moment it accepts, while the host is
+// loading every plugin at once and may sit in a synchronous workspace walk for
+// over ten seconds. A host that has died closes the socket; 'end' covers that.
+const LOAD_TIMEOUT_MS = 60_000;
+let connectErrorTimeout = setErrorTimeout(CONNECT_TIMEOUT_MS, `The plugin worker for ${expectedPluginName} is exiting as it was not connected to within ${CONNECT_TIMEOUT_MS / 1000} seconds. ` +
+    'Plugin workers expect to receive a socket connection from the parent process shortly after being started. ' +
+    'If you are seeing this issue, please report it to the Nx team at https://github.com/nrwl/nx/issues.');
+const server = (0, net_1.createServer)((socket) => {
+    connectErrorTimeout?.clear();
+    // Make the host-facing socket available to plugin code running in this
+    // worker so it can emit log / progress notifications without having
+    // the socket threaded through every call site.
+    (0, worker_streaming_1.setPluginWorkerHostSocket)(socket);
+    logger_1.logger.verbose(`[plugin-worker] "${expectedPluginName}" (pid: ${process.pid}) connected`);
+    // This handles cases where the host process was killed
+    // after the worker connected but before the worker was
+    // instructed to load the plugin.
+    let loadErrorTimeout = setErrorTimeout(LOAD_TIMEOUT_MS, `Plugin Worker for ${expectedPluginName} is exiting as it did not receive a load message within ${LOAD_TIMEOUT_MS / 1000} seconds of connecting. ` +
+        'This likely indicates that the host process was terminated before the worker could be instructed to load the plugin. ' +
+        'If you are seeing this issue, please report it to the Nx team at https://github.com/nrwl/nx/issues.');
+    socket.on('data', (0, consume_messages_from_socket_1.consumeMessagesFromSocket)((raw) => {
+        const message = (0, consume_messages_from_socket_1.parseMessage)(raw);
+        if (!(0, messaging_1.isPluginWorkerMessage)(message)) {
+            return;
+        }
+        // Same check the daemon applies to its own socket. Dropped rather than thrown:
+        // a stray foreign message must not kill a worker serving its host. The daemon
+        // has a response channel and surfaces it to the client instead.
+        try {
+            (0, daemon_message_1.assertNotForeignWorkspaceMessage)(message, hostWorkspaceRoot, `The Nx plugin worker "${expectedPluginName}" (pid: ${process.pid})`);
+        }
+        catch (e) {
+            logger_1.logger.verbose(`[plugin-worker] ignored a "${message.type}" message: ${e instanceof Error ? e.message : e}`);
+            return;
+        }
+        return (0, messaging_1.consumeMessage)(socket, message, {
+            load: async ({ plugin: pluginConfiguration, root, name, pluginPath, shouldRegisterTSTranspiler, }) => {
+                loadErrorTimeout?.clear();
+                process.chdir(root);
+                return withErrorHandling(async () => {
+                    const { loadResolvedNxPluginAsync } = await Promise.resolve(require(require.resolve('../load-resolved-plugin')));
+                    // Register the ts-transpiler if we are pointing to a
+                    // plain ts file that's not part of a plugin project
+                    if (shouldRegisterTSTranspiler) {
+                        require('../transpiler').registerPluginTSTranspiler();
+                    }
+                    plugin = await loadResolvedNxPluginAsync(pluginConfiguration, pluginPath, name);
+                    logger_1.logger.verbose(`[plugin-worker] "${name}" (pid: ${process.pid}) loaded successfully`);
+                    return {
+                        name: plugin.name,
+                        include: plugin.include,
+                        exclude: plugin.exclude,
+                        createNodesPattern: plugin.createNodes?.[0],
+                        hasCreateDependencies: 'createDependencies' in plugin && !!plugin.createDependencies,
+                        hasProcessProjectGraph: 'processProjectGraph' in plugin &&
+                            !!plugin.processProjectGraph,
+                        hasCreateMetadata: 'createMetadata' in plugin && !!plugin.createMetadata,
+                        hasPreTasksExecution: 'preTasksExecution' in plugin && !!plugin.preTasksExecution,
+                        hasPostTasksExecution: 'postTasksExecution' in plugin && !!plugin.postTasksExecution,
+                        success: true,
+                    };
+                });
+            },
+            createNodes: async ({ configFiles, context }) => withErrorHandling(async () => {
+                const result = await plugin.createNodes[1](configFiles, context);
+                return { result, success: true };
+            }),
+            createDependencies: async ({ context }) => withErrorHandling(async () => {
+                const result = await plugin.createDependencies(context);
+                return { dependencies: result, success: true };
+            }),
+            createMetadata: async ({ graph, context }) => withErrorHandling(async () => {
+                const result = await plugin.createMetadata(graph, context);
+                return { metadata: result, success: true };
+            }),
+            preTasksExecution: async ({ context }) => withErrorHandling(async () => {
+                const mutations = await plugin.preTasksExecution?.(context);
+                return { success: true, mutations };
+            }),
+            postTasksExecution: async ({ context }) => withErrorHandling(() => plugin.postTasksExecution?.(context)),
+            setWorkerEnv: (env) => withErrorHandling(() => {
+                (0, daemon_environment_1.applyDaemonEnvFromClient)(env);
+            }),
+        });
+    }, (err) => {
+        // The host link cannot resynchronize. Exit so the host's 'exit' handler
+        // rejects the pending hooks instead of waiting on a reply that the
+        // framing failure guarantees will never arrive.
+        console.error(err.message);
+        socket.destroy();
+        process.exit(1);
+    }));
+    // When the host disconnects, clean up and exit.
+    socket.on('end', () => {
+        socket.destroySoon();
+        try {
+            (0, fs_1.unlinkSync)(socketPath);
+        }
+        catch (e) { }
+        process.exit(0);
+    });
+});
+server.on('error', (err) => {
+    // Without this the host only sees "exited before the connection was
+    // established"; the errno distinguishes a denied bind from EADDRINUSE.
+    console.error(`[plugin-worker] "${expectedPluginName}" (pid: ${process.pid}) failed to listen on ${socketPath}: ${err.message}`);
+    // A bind can fail for reasons permission does not explain (EADDRINUSE from a
+    // leftover socket, ENOENT from a reaped socket dir), so print the hint only
+    // when the errno proves a refusal or the environment says a sandbox is here.
+    const refusedByOs = (0, permission_errors_1.isPermissionDenied)(err);
+    if (refusedByOs || (0, is_sandbox_1.isSandbox)()) {
+        console.error((0, sandbox_socket_hint_1.sandboxSocketHint)({ certain: refusedByOs }).join('\n'));
+    }
+    // The host cannot see this errno, and stderr may be lost with the process, so
+    // the exit code is what tells it a refusal happened rather than a crash.
+    process.exit(refusedByOs ? socket_refused_exit_code_1.SOCKET_REFUSED_EXIT_CODE : 1);
+});
+// A worker killed without its 'end' handler leaves the socket behind. Colliding
+// takes a recycled host pid landing on the same counter *and* the same 4 random
+// bytes; the random component is what this unlink rests on, and on Windows it is
+// the only barrier, since the endpoint is a namespace object and the mode never
+// applies. A failed bind surfaces through the error handler above.
+try {
+    (0, fs_1.unlinkSync)(socketPath);
+}
+catch { }
+server.listen(socketPath, () => {
+    logger_1.logger.verbose(`[plugin-worker] "${expectedPluginName}" (pid: ${process.pid}) listening on ${socketPath}`);
+});
+async function withErrorHandling(cb) {
+    try {
+        const result = await cb();
+        return result ?? { success: true };
+    }
+    catch (e) {
+        return {
+            success: false,
+            error: (0, serializable_error_1.createSerializableError)(e),
+        };
+    }
+}
+function setErrorTimeout(timeoutMs, errorMessage) {
+    if (environment.NX_PLUGIN_NO_TIMEOUTS === 'true') {
+        return;
+    }
+    let cleared = false;
+    const timeout = setTimeout(() => {
+        if (!cleared) {
+            console.error(errorMessage);
+            process.exit(1);
+        }
+    }, timeoutMs).unref();
+    return {
+        clear: () => {
+            cleared = true;
+            clearTimeout(timeout);
+        },
+    };
+}
+const cleanup = () => {
+    server.close();
+    try {
+        (0, fs_1.unlinkSync)(socketPath);
+    }
+    catch (e) { }
+};
+const events = ['SIGINT', 'SIGTERM', 'SIGQUIT'];
+events.forEach((event) => process.once(event, () => {
+    cleanup();
+    process.exit(0);
+}));
+// Cleanup only: process.exit() here would override the real exit code.
+process.once('exit', cleanup);
+const fatalHandler = (error) => {
+    // Registering this handler suppresses Node's default reporting.
+    console.error(error);
+    cleanup();
+    process.exit(1);
+};
+process.once('uncaughtException', fatalHandler);
+process.once('unhandledRejection', fatalHandler);

package/dist/src/project-graph/plugins/isolation/worker-streaming.d.ts

@@ -0,0 +1,14 @@
+import type { Socket } from 'net';
+import { PluginWorkerEmitLogNotification } from './messaging';
+export declare function setPluginWorkerHostSocket(socket: Socket): void;
+/**
+ * Emits a log line from the plugin worker up to its host. The host
+ * decides where it ends up (direct stdout/stderr when running under the
+ * CLI, forwarded to the active daemon client when running under the
+ * daemon).
+ *
+ * When plugin isolation is turned off, or this is otherwise called
+ * outside of a connected plugin worker, the message is written
+ * directly to stdout/stderr so the log line isn't silently dropped.
+ */
+export declare function emitPluginWorkerLog(level: PluginWorkerEmitLogNotification['level'], message: string): void;

package/dist/src/project-graph/plugins/isolation/worker-streaming.js

@@ -0,0 +1,39 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.setPluginWorkerHostSocket = setPluginWorkerHostSocket;
+exports.emitPluginWorkerLog = emitPluginWorkerLog;
+const messaging_1 = require("./messaging");
+// Plugin workers talk to their host process over a single socket that
+// is established when the host connects. Plugin code running anywhere
+// in the worker process needs a way to emit log lines without having
+// that socket threaded through every call frame, so we stash a
+// module-level reference here when the host connects.
+let hostSocket = null;
+function setPluginWorkerHostSocket(socket) {
+    hostSocket = socket;
+    socket.once('close', () => {
+        if (hostSocket === socket)
+            hostSocket = null;
+    });
+}
+/**
+ * Emits a log line from the plugin worker up to its host. The host
+ * decides where it ends up (direct stdout/stderr when running under the
+ * CLI, forwarded to the active daemon client when running under the
+ * daemon).
+ *
+ * When plugin isolation is turned off, or this is otherwise called
+ * outside of a connected plugin worker, the message is written
+ * directly to stdout/stderr so the log line isn't silently dropped.
+ */
+function emitPluginWorkerLog(level, message) {
+    if (!hostSocket) {
+        console[level](message);
+        return;
+    }
+    (0, messaging_1.sendMessageOverSocket)(hostSocket, {
+        type: 'emitLog',
+        level,
+        message,
+    });
+}

package/dist/src/project-graph/plugins/load-resolved-plugin.d.ts

@@ -0,0 +1,3 @@
+import type { PluginConfiguration } from '../../config/nx-json';
+import { LoadedNxPlugin } from './loaded-nx-plugin';
+export declare function loadResolvedNxPluginAsync(pluginConfiguration: PluginConfiguration, pluginPath: string, name: string, index?: number): Promise<LoadedNxPlugin>;

package/dist/src/project-graph/plugins/load-resolved-plugin.js

@@ -0,0 +1,24 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadResolvedNxPluginAsync = loadResolvedNxPluginAsync;
+const loaded_nx_plugin_1 = require("./loaded-nx-plugin");
+const handle_import_1 = require("../../utils/handle-import");
+async function loadResolvedNxPluginAsync(pluginConfiguration, pluginPath, name, index) {
+    // This needs to be spread to create an extensible object.
+    const plugin = { ...(await importPluginModule(pluginPath)) };
+    plugin.name ??= name;
+    return new loaded_nx_plugin_1.LoadedNxPlugin(plugin, pluginConfiguration, index);
+}
+async function importPluginModule(pluginPath) {
+    const m = await (0, handle_import_1.handleImport)(pluginPath);
+    if (m.default &&
+        ('createNodes' in m.default ||
+            'createNodesV2' in m.default ||
+            'createDependencies' in m.default ||
+            'createMetadata' in m.default ||
+            'preTasksExecution' in m.default ||
+            'postTasksExecution' in m.default)) {
+        return m.default;
+    }
+    return m;
+}

package/dist/src/project-graph/plugins/loaded-nx-plugin.d.ts

@@ -0,0 +1,44 @@
+import type { ProjectGraph } from '../../config/project-graph';
+import { type PluginConfiguration } from '../../config/nx-json';
+import type { RawProjectGraphDependency } from '../project-graph-builder';
+import type { CreateDependenciesContext, CreateMetadataContext, CreateNodesContext, CreateNodesResult, NxPlugin, PreTasksExecutionContext, ProjectsMetadata } from './public-api';
+import { type MaybeStubbedPostTasksExecutionContext } from './task-results-stub';
+import type { NxPluginCapabilities } from './nx-plugin-capabilities';
+/**
+ * NOTE: Avoid using `import type` with this class. It causes issues with
+ * jest's module resolution when running tests in projects that import
+ * the devkit-internals
+ */
+export declare class LoadedNxPlugin {
+    readonly index?: number;
+    readonly name: string;
+    readonly createNodes?: [
+        filePattern: string,
+        fn: (matchedFiles: string[], context: CreateNodesContext) => Promise<Array<readonly [plugin: string, file: string, result: CreateNodesResult]>>
+    ];
+    readonly createDependencies?: (context: CreateDependenciesContext) => Promise<RawProjectGraphDependency[]>;
+    readonly createMetadata?: (graph: ProjectGraph, context: CreateMetadataContext) => Promise<ProjectsMetadata>;
+    readonly preTasksExecution?: (context: PreTasksExecutionContext) => Promise<NodeJS.ProcessEnv>;
+    readonly postTasksExecution?: (context: MaybeStubbedPostTasksExecutionContext) => Promise<void>;
+    readonly options?: unknown;
+    readonly include?: string[];
+    readonly exclude?: string[];
+    /**
+     * Notifies the plugin that a phase was aborted mid-flight.
+     * Overridden by IsolatedPlugin to reset lifecycle phase tracking so
+     * the worker can still shut down properly.
+     *
+     * @param phase The phase that was aborted (e.g. 'graph').
+     * @param lastCompletedHook The last hook that was called before the
+     *   abort (e.g. 'createNodes').
+     */
+    notifyPhaseAborted?(phase: string, lastCompletedHook: string): void;
+    /**
+     * Forwards updated environment variables to the plugin worker process.
+     * Only meaningful for isolated plugins; in-process plugins share the
+     * daemon's process.env automatically.
+     */
+    setWorkerEnv?(env: Record<string, string>): Promise<void>;
+    constructor(plugin: NxPlugin, pluginDefinition: PluginConfiguration, index?: number);
+    capabilities(): NxPluginCapabilities;
+}

package/dist/src/project-graph/plugins/loaded-nx-plugin.js

@@ -0,0 +1,117 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LoadedNxPlugin = void 0;
+const analytics_1 = require("../../analytics");
+const error_types_1 = require("../error-types");
+const enabled_1 = require("./isolation/enabled");
+const client_1 = require("../../daemon/client/client");
+const task_results_stub_1 = require("./task-results-stub");
+/**
+ * NOTE: Avoid using `import type` with this class. It causes issues with
+ * jest's module resolution when running tests in projects that import
+ * the devkit-internals
+ */
+class LoadedNxPlugin {
+    constructor(plugin, pluginDefinition, index) {
+        this.index = index;
+        this.name = plugin.name;
+        if (typeof pluginDefinition !== 'string') {
+            this.options = pluginDefinition.options;
+            this.include = pluginDefinition.include;
+            this.exclude = pluginDefinition.exclude;
+        }
+        // Fall back to `createNodesV2` for plugins authored against the old name.
+        const createNodesImpl = plugin.createNodes ??
+            plugin.createNodesV2;
+        if (createNodesImpl) {
+            this.createNodes = [
+                createNodesImpl[0],
+                async (configFiles, context) => {
+                    const result = await createNodesImpl[1](configFiles, this.options, context);
+                    return result.map((r) => [this.name, r[0], r[1]]);
+                },
+            ];
+        }
+        /**
+         * Wraps the plugin-provided createNodes function to provide performance
+         * measurement and error handling.
+         */
+        if (this.createNodes) {
+            const inner = this.createNodes[1];
+            this.createNodes[1] = async (...args) => {
+                performance.mark(`${plugin.name}:createNodes - start`);
+                let projectCount = 0;
+                try {
+                    const result = await inner(...args);
+                    for (const [, , r] of result) {
+                        projectCount += Object.keys(r.projects ?? {}).length;
+                    }
+                    return result;
+                }
+                catch (e) {
+                    if ((0, error_types_1.isAggregateCreateNodesError)(e)) {
+                        throw e;
+                    }
+                    // The underlying plugin errored out. We can't know any partial results.
+                    throw new error_types_1.AggregateCreateNodesError([[null, e]], []);
+                }
+                finally {
+                    performance.mark(`${plugin.name}:createNodes - end`);
+                    performance.measure(`${plugin.name}:createNodes`, {
+                        start: `${plugin.name}:createNodes - start`,
+                        end: `${plugin.name}:createNodes - end`,
+                        detail: {
+                            track: true,
+                            ...(analytics_1.customDimensions && {
+                                [analytics_1.customDimensions.projectCount]: projectCount,
+                                [analytics_1.customDimensions.sampleRate]: analytics_1.PERF_SPAN_SAMPLE_RATE,
+                            }),
+                        },
+                    });
+                }
+            };
+        }
+        if (plugin.createDependencies) {
+            this.createDependencies = async (context) => plugin.createDependencies(this.options, context);
+        }
+        if (plugin.createMetadata) {
+            this.createMetadata = async (graph, context) => plugin.createMetadata(graph, this.options, context);
+        }
+        if (plugin.preTasksExecution) {
+            this.preTasksExecution = async (context) => {
+                const updates = {};
+                let originalEnv = process.env;
+                if ((0, enabled_1.isIsolationEnabled)() || (0, client_1.isDaemonEnabled)()) {
+                    process.env = new Proxy(originalEnv, {
+                        set: (target, key, value) => {
+                            target[key] = value;
+                            updates[key] = value;
+                            return true;
+                        },
+                    });
+                }
+                await plugin.preTasksExecution(this.options, context);
+                // This doesn't revert env changes, as the proxy still updates
+                // originalEnv, rather it removes the proxy.
+                process.env = originalEnv;
+                return updates;
+            };
+        }
+        if (plugin.postTasksExecution) {
+            // The single rehydration point: every transport hands its context
+            // straight here, so a context bound for an isolated plugin stays stubbed
+            // across that second hop rather than being read and re-stubbed.
+            this.postTasksExecution = async (context) => plugin.postTasksExecution(this.options, await (0, task_results_stub_1.rehydrateTerminalOutputs)(context));
+        }
+    }
+    capabilities() {
+        return {
+            createNodesPattern: this.createNodes?.[0],
+            hasCreateDependencies: !!this.createDependencies,
+            hasCreateMetadata: !!this.createMetadata,
+            hasPreTasksExecution: !!this.preTasksExecution,
+            hasPostTasksExecution: !!this.postTasksExecution,
+        };
+    }
+}
+exports.LoadedNxPlugin = LoadedNxPlugin;

package/dist/src/project-graph/plugins/nx-plugin-capabilities.d.ts

@@ -0,0 +1,6 @@
+import { type CachedPluginCapabilities, NxPluginCapabilities as NxPluginCapabilitiesStore } from '../../native';
+export type NxPluginCapabilities = CachedPluginCapabilities;
+export declare function getNxPluginCapabilitiesStore(): NxPluginCapabilitiesStore | null;
+export declare function noteGraphReadFromCache(computedAt: number | undefined): void;
+/** Null means "load them", never "no plugin registers anything". */
+export declare function capabilitiesOfNxPluginsReadFromCache(): NxPluginCapabilities[] | null;

package/dist/src/project-graph/plugins/nx-plugin-capabilities.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getNxPluginCapabilitiesStore = getNxPluginCapabilitiesStore;
+exports.noteGraphReadFromCache = noteGraphReadFromCache;
+exports.capabilitiesOfNxPluginsReadFromCache = capabilitiesOfNxPluginsReadFromCache;
+const native_1 = require("../../native");
+const db_connection_1 = require("../../utils/db-connection");
+let store;
+function getNxPluginCapabilitiesStore() {
+    // The database is not part of the WASM build.
+    if (native_1.IS_WASM) {
+        return null;
+    }
+    // Checkout-local: the rows describe this checkout's graph.
+    store ??= new native_1.NxPluginCapabilities((0, db_connection_1.getLocalDbConnection)());
+    return store;
+}
+let computedAtOfGraphReadFromCache;
+function noteGraphReadFromCache(computedAt) {
+    computedAtOfGraphReadFromCache = computedAt;
+}
+/** Null means "load them", never "no plugin registers anything". */
+function capabilitiesOfNxPluginsReadFromCache() {
+    if (computedAtOfGraphReadFromCache === undefined) {
+        return null;
+    }
+    return (getNxPluginCapabilitiesStore()?.get(computedAtOfGraphReadFromCache) ?? null);
+}

package/dist/src/project-graph/plugins/public-api.d.ts

@@ -0,0 +1,139 @@
+import type { FileMap, ProjectGraph, ProjectGraphExternalNode } from '../../config/project-graph';
+import type { ProjectConfiguration } from '../../config/workspace-json-project-json';
+import type { NxJsonConfiguration } from '../../config/nx-json';
+import type { TaskResults } from '../../tasks-runner/life-cycle';
+import type { RawProjectGraphDependency } from '../project-graph-builder';
+export interface CreateNodesContext {
+    readonly nxJsonConfiguration: NxJsonConfiguration;
+    readonly workspaceRoot: string;
+}
+/**
+ * @deprecated This will be removed in Nx 24. See {@link CreateNodesContext}
+ */
+export type CreateNodesContextV2 = CreateNodesContext;
+export type CreateNodesResultArray = Array<readonly [configFileSource: string, result: CreateNodesResult]>;
+/**
+ * @deprecated This will be removed in Nx 24. See {@link CreateNodesResultArray}
+ */
+export type CreateNodesResultV2 = CreateNodesResultArray;
+export type CreateNodesFunction<T = unknown> = (projectConfigurationFiles: readonly string[], options: T | undefined, context: CreateNodesContext) => CreateNodesResultArray | Promise<CreateNodesResultArray>;
+/**
+ * @deprecated see {@link CreateNodesFunction}
+ */
+export type CreateNodesFunctionV2<T = unknown> = CreateNodesFunction<T>;
+export type Optional<T, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;
+export interface CreateNodesResult {
+    /**
+     * A map of project root -> project configuration
+     */
+    projects?: Record<string, Optional<ProjectConfiguration, 'root'>>;
+    /**
+     * A map of external node name -> external node. External nodes do not have a root, so the key is their name.
+     */
+    externalNodes?: Record<string, ProjectGraphExternalNode>;
+}
+/**
+ * A pair of file patterns and {@link CreateNodesFunction}
+ */
+export type CreateNodes<T = unknown> = readonly [
+    projectFilePattern: string,
+    createNodesFunction: CreateNodesFunction<T>
+];
+/**
+ * @deprecated - use {@link CreateNodes} instead
+ */
+export type CreateNodesV2<T = unknown> = CreateNodes<T>;
+/**
+ * Context for {@link CreateDependencies}
+ */
+export interface CreateDependenciesContext {
+    /**
+     * The external nodes that have been added to the graph.
+     */
+    readonly externalNodes: ProjectGraph['externalNodes'];
+    /**
+     * The configuration of each project in the workspace keyed by project name.
+     */
+    readonly projects: Record<string, ProjectConfiguration>;
+    /**
+     * The `nx.json` configuration from the workspace
+     */
+    readonly nxJsonConfiguration: NxJsonConfiguration;
+    /**
+     * All files in the workspace
+     */
+    readonly fileMap: FileMap;
+    /**
+     * Files changes since last invocation
+     */
+    readonly filesToProcess: FileMap;
+    readonly workspaceRoot: string;
+}
+/**
+ * A function which parses files in the workspace to create dependencies in the {@link ProjectGraph}
+ * Use {@link validateDependency} to validate dependencies
+ */
+export type CreateDependencies<T = unknown> = (options: T | undefined, context: CreateDependenciesContext) => RawProjectGraphDependency[] | Promise<RawProjectGraphDependency[]>;
+export type CreateMetadataContext = {
+    readonly nxJsonConfiguration: NxJsonConfiguration;
+    readonly workspaceRoot: string;
+};
+export type ProjectsMetadata = Record<string, Pick<ProjectConfiguration, 'metadata'>>;
+export type CreateMetadata<T = unknown> = (graph: ProjectGraph, options: T | undefined, context: CreateMetadataContext) => ProjectsMetadata | Promise<ProjectsMetadata>;
+/**
+ * A plugin which enhances the behavior of Nx
+ */
+export type NxPlugin<TOptions = unknown> = {
+    name: string;
+    /**
+     * Provides a file pattern and function that retrieves configuration info from
+     * those files. e.g. { '**\/*.csproj': buildProjectsFromCsProjFile }
+     */
+    createNodes?: CreateNodes<TOptions>;
+    /**
+     * Provides a file pattern and function that retrieves configuration info from
+     * those files. e.g. { '**\/*.csproj': buildProjectsFromCsProjFiles }
+     *
+     * @deprecated Prefer `createNodes` for new plugins
+     */
+    createNodesV2?: CreateNodes<TOptions>;
+    /**
+     * Provides a function to analyze files to create dependencies for the {@link ProjectGraph}
+     */
+    createDependencies?: CreateDependencies<TOptions>;
+    /**
+     * Provides a function to create metadata for the {@link ProjectGraph}
+     */
+    createMetadata?: CreateMetadata<TOptions>;
+    /**
+     * Provides a function to run before the Nx runs tasks
+     */
+    preTasksExecution?: PreTasksExecution<TOptions>;
+    /**
+     * Provides a function to run after the Nx runs tasks
+     */
+    postTasksExecution?: PostTasksExecution<TOptions>;
+};
+export type PreTasksExecutionContext = {
+    readonly id: string;
+    readonly workspaceRoot: string;
+    readonly nxJsonConfiguration: NxJsonConfiguration;
+    readonly argv: string[];
+};
+export type PostTasksExecutionContext = {
+    readonly id: string;
+    readonly workspaceRoot: string;
+    readonly nxJsonConfiguration: NxJsonConfiguration;
+    readonly taskResults: TaskResults;
+    readonly argv: string[];
+    readonly startTime: number;
+    readonly endTime: number;
+};
+export type PreTasksExecution<TOptions = unknown> = (options: TOptions | undefined, context: PreTasksExecutionContext) => void | Promise<void>;
+export type PostTasksExecution<TOptions = unknown> = (options: TOptions | undefined, context: PostTasksExecutionContext) => void | Promise<void>;
+/**
+ * A plugin which enhances the behavior of Nx
+ *
+ * @deprecated See {@link NxPlugin}
+ */
+export type NxPluginV2<TOptions = unknown> = NxPlugin<TOptions>;

package/dist/src/project-graph/plugins/public-api.js

@@ -0,0 +1,4 @@
+"use strict";
+// This file represents the public API for plugins which live in nx.json's plugins array.
+// For methods to interact with plugins from within Nx, see `./internal-api.ts`.
+Object.defineProperty(exports, "__esModule", { value: true });