nx 23.3.0 → 24.0.0-beta.1

package/dist/src/command-line/run/executor-utils.js

@@ -44,6 +44,7 @@ projects) {
         const batchImplementationFactory = executorConfig.batchImplementation
             ? (0, schema_utils_1.getImplementationFactory)(executorConfig.batchImplementation, executorsDir, nodeModule, projects)
             : null;
+        // TODO(v25): remove custom hasher support.
         const hasherFactory = executorConfig.hasher
             ? (0, schema_utils_1.getImplementationFactory)(executorConfig.hasher, executorsDir, nodeModule, projects)
             : null;

package/dist/src/command-line/run/run-one.d.ts

@@ -1,5 +1,5 @@
 import { NxJsonConfiguration } from '../../config/nx-json';
-import { ProjectGraph } from '../../config/project-graph';
+import { ProjectGraph, ProjectGraphProjectNode } from '../../config/project-graph';
 import { TargetDependencyConfig } from '../../config/workspace-json-project-json';
 export declare function runOne(cwd: string, args: {
     [k: string]: any;
@@ -7,6 +7,25 @@ export declare function runOne(cwd: string, args: {
     excludeTaskDependencies: boolean;
     loadDotEnvFiles: boolean;
 }): Promise<void>;
+/**
+ * Builds the error shown when the project itself can't be found. Matches the
+ * attempted `project:target[:configuration]` against every runnable task id so
+ * a project typo (e.g. `webpai:build`) still surfaces the intended task
+ * (`webapi:build`).
+ */
+export declare function getCannotFindProjectError(projectGraph: ProjectGraph, projectName: string, target: string, configuration?: string): {
+    title: string;
+    bodyLines: string[];
+};
+/**
+ * Validates that `target` exists on the resolved project. When it does not,
+ * returns an error describing the available targets (and the closest match, if
+ * any) so the user can recover from a typo or discover what they can run.
+ */
+export declare function getRunOneTargetError(project: ProjectGraphProjectNode, target: string, configuration?: string): {
+    title: string;
+    bodyLines: string[];
+} | null;
 export declare function parseRunOneOptions(cwd: string, parsedArgs: {
     [k: string]: any;
 }, projectGraph: ProjectGraph, nxJson: NxJsonConfiguration): {

package/dist/src/command-line/run/run-one.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.runOne = runOne;
+exports.getCannotFindProjectError = getCannotFindProjectError;
+exports.getRunOneTargetError = getRunOneTargetError;
 exports.parseRunOneOptions = parseRunOneOptions;
 const calculate_default_project_name_1 = require("../../config/calculate-default-project-name");
 const configuration_1 = require("../../config/configuration");
@@ -11,6 +13,7 @@ const command_line_utils_1 = require("../../utils/command-line-utils");
 const find_matching_projects_1 = require("../../utils/find-matching-projects");
 const output_1 = require("../../utils/output");
 const split_target_1 = require("../../utils/split-target");
+const string_similarity_1 = require("../../utils/string-similarity");
 const workspace_root_1 = require("../../utils/workspace-root");
 const graph_1 = require("../graph/graph");
 const connect_to_nx_cloud_1 = require("../nx-cloud/connect/connect-to-nx-cloud");
@@ -28,7 +31,12 @@ async function runOne(cwd, args, extraTargetDependencies = {}, extraOptions = {
         configuration: opts.configuration,
         targets: [opts.target],
     }, 'run-one', { printWarnings: args.graph !== 'stdout' }, nxJson);
-    const { projects, projectName } = getProjects(projectGraph, opts.project);
+    const { projects, projectName } = getProjects(projectGraph, opts.project, opts.target, opts.configuration);
+    const targetError = getRunOneTargetError(projects[0], opts.target, opts.configuration);
+    if (targetError) {
+        output_1.output.error(targetError);
+        process.exit(1);
+    }
     if (nxArgs.help) {
         await (await (0, handle_import_1.handleImport)('./run.js', __dirname)).printTargetRunHelp({
             ...opts,
@@ -59,7 +67,7 @@ async function runOne(cwd, args, extraTargetDependencies = {}, extraOptions = {
         process.exit(status);
     }
 }
-function getProjects(projectGraph, projectName) {
+function getProjects(projectGraph, projectName, target, configuration) {
     if (projectGraph.nodes[projectName]) {
         return {
             projectName: projectName,
@@ -90,11 +98,151 @@ function getProjects(projectGraph, projectName) {
             process.exit(1);
         }
     }
-    output_1.output.error({
-        title: `Cannot find project '${projectName}'`,
-    });
+    output_1.output.error(getCannotFindProjectError(projectGraph, projectName, target, configuration));
     process.exit(1);
 }
+// Keep error output scannable: only show a handful of targets/suggestions.
+const MAX_LISTED_TARGETS = 5;
+const MAX_SUGGESTIONS = 3;
+/**
+ * Builds the list of all runnable `project:target` task ids in the workspace,
+ * used to suggest the right invocation when a project or target can't be found.
+ */
+function getProjectTargetIds(projectGraph) {
+    const ids = [];
+    for (const projectName of Object.keys(projectGraph.nodes)) {
+        const targets = projectGraph.nodes[projectName].data.targets ?? {};
+        for (const targetName of Object.keys(targets)) {
+            ids.push(`${projectName}:${targetName}`);
+        }
+    }
+    return ids;
+}
+/**
+ * A target (and even a configuration) name can legally contain ':'. When the
+ * user typos such a name, `splitTarget` splits on every ':' and parses the
+ * trailing segment(s) as separate parts (e.g. `nx:zzcustom:variantt` becomes
+ * project `nx`, target `zzcustom`, configuration `variantt`).
+ *
+ * To match the real name we therefore score the fully-rejoined specifier and
+ * every progressively shorter form, and keep whichever produced the closest
+ * candidate. Rejoining wins for colon-containing names, while the shorter forms
+ * keep matching genuine `target` + `configuration` typos (where the real target
+ * name does not carry the configuration suffix). Ties go to the longer form,
+ * which is the one that reproduces the name the user actually typed.
+ */
+function findClosestSpecifier(parts, candidates, limit = 1) {
+    const present = parts.filter((part) => !!part);
+    let best = [];
+    for (let end = present.length; end >= 1; end--) {
+        const matches = (0, string_similarity_1.rankSuggestions)(present.slice(0, end).join(':'), candidates);
+        if (matches.length &&
+            (!best.length || matches[0].distance < best[0].distance)) {
+            best = matches;
+        }
+    }
+    return best.slice(0, limit).map(({ candidate }) => candidate);
+}
+/**
+ * Finds the closest available target to what the user typed, staying
+ * config-aware. When a configuration was parsed off the specifier, the rejoined
+ * `target:configuration` is scored too, so a colon-containing real target name
+ * (e.g. `zzcustom:variant`) still matches. Both forms are scored and the closest
+ * candidate wins, ties going to the rejoined form -- mirroring
+ * `findClosestSpecifier`'s preference order. The bare-`target` tier reuses the
+ * precomputed `ranked` list (its head, gated by the suggestion threshold)
+ * instead of recomputing distances.
+ */
+function findClosestTarget(target, configuration, availableTargets, ranked) {
+    let best;
+    if (configuration) {
+        [best] = (0, string_similarity_1.rankSuggestions)(`${target}:${configuration}`, availableTargets);
+    }
+    const nearest = ranked[0];
+    if (nearest &&
+        (0, string_similarity_1.isWithinSuggestionThreshold)(target, nearest.candidate, nearest.distance) &&
+        (!best || nearest.distance < best.distance)) {
+        best = nearest;
+    }
+    return best?.candidate;
+}
+/**
+ * Lists up to `MAX_LISTED_TARGETS` targets from a list already ranked by how
+ * closely they resemble the target the user typed (closest first, ties broken
+ * alphabetically) so the most likely intended targets surface first.
+ * `closestMatch` is dropped because it is already surfaced separately as the
+ * "Did you mean" suggestion. Appends a "...and N more" line when the project has
+ * more targets than we show, and returns no lines at all when the suggestion was
+ * the project's only target -- a bare "Available targets:" header reads as "this
+ * project has none".
+ */
+function formatAvailableTargets(ranked, closestMatch) {
+    const targets = ranked
+        .map(({ candidate }) => candidate)
+        .filter((candidate) => candidate !== closestMatch);
+    if (!targets.length) {
+        return [];
+    }
+    const shown = targets.slice(0, MAX_LISTED_TARGETS);
+    const lines = ['Available targets:', ...shown.map((t) => `  - ${t}`)];
+    if (targets.length > shown.length) {
+        lines.push(`  ...and ${targets.length - shown.length} more`);
+    }
+    return lines;
+}
+/**
+ * Builds the error shown when the project itself can't be found. Matches the
+ * attempted `project:target[:configuration]` against every runnable task id so
+ * a project typo (e.g. `webpai:build`) still surfaces the intended task
+ * (`webapi:build`).
+ */
+function getCannotFindProjectError(projectGraph, projectName, target, configuration) {
+    const bodyLines = [];
+    const suggestions = findClosestSpecifier([projectName, target, configuration], getProjectTargetIds(projectGraph), MAX_SUGGESTIONS);
+    if (suggestions.length) {
+        bodyLines.push('Did you mean one of these?', ...suggestions.map((id) => `  - ${id}`));
+    }
+    return {
+        title: `Cannot find project '${projectName}'`,
+        bodyLines,
+    };
+}
+/**
+ * Validates that `target` exists on the resolved project. When it does not,
+ * returns an error describing the available targets (and the closest match, if
+ * any) so the user can recover from a typo or discover what they can run.
+ */
+function getRunOneTargetError(project, target, configuration) {
+    const availableTargets = Object.keys(project.data.targets ?? {});
+    if (availableTargets.includes(target)) {
+        return null;
+    }
+    const bodyLines = [];
+    // Rank the available targets by distance to the bare target ONCE. This drives
+    // the ordered "Available targets" block and doubles as the bare-target tier of
+    // the closest-match lookup, so distances are not computed twice.
+    const ranked = (0, string_similarity_1.rankByDistance)(target, availableTargets);
+    const closestMatch = findClosestTarget(target, configuration, availableTargets, ranked);
+    if (closestMatch) {
+        bodyLines.push(`Did you mean "${closestMatch}"?`);
+    }
+    if (!availableTargets.length) {
+        bodyLines.push(`The project "${project.name}" does not have any targets configured.`);
+    }
+    else {
+        const targetLines = formatAvailableTargets(ranked, closestMatch);
+        if (targetLines.length) {
+            if (bodyLines.length) {
+                bodyLines.push('');
+            }
+            bodyLines.push(...targetLines);
+        }
+    }
+    return {
+        title: `Cannot find target "${target}" for project "${project.name}"`,
+        bodyLines,
+    };
+}
 const targetAliases = {
     b: 'build',
     e: 'e2e',

package/dist/src/command-line/show/show-target/info.js

@@ -126,7 +126,7 @@ function resolveTaskGraphDependencies(graph, extraTargetDeps, projectName, targe
         const directDeps = [
             ...(taskGraph.dependencies[rootId] ?? []),
             ...(taskGraph.continuousDependencies[rootId] ?? []),
-        ];
+        ].map((edge) => edge.id);
         const directDepSet = new Set(directDeps);
         const depSourceIndices = directDeps.map((depTaskId) => {
             const task = taskGraph.tasks[depTaskId];

package/dist/src/command-line/show/show-target/utils.js

@@ -142,6 +142,7 @@ function validateConfiguration(projectName, targetName, configuration, targetCon
     }
 }
 // ── Custom hasher detection ──────────────────────────────────────────
+// TODO(v25): remove custom hasher support.
 /**
  * Checks whether a target's executor defines a custom hasher.
  * Returns true if the executor has a hasherFactory — meaning the

package/dist/src/command-line/watch/command-object.js

@@ -13,7 +13,7 @@ exports.yargsWatchCommand = {
     },
 };
 function withWatchOptions(yargs) {
-    return ((0, shared_options_1.withVerbose)(yargs)
+    return (0, shared_options_1.withVerbose)(yargs)
         .parserConfiguration({
         'strip-dashed': true,
         'populate--': true,
@@ -32,12 +32,6 @@ function withWatchOptions(yargs) {
         type: 'boolean',
         description: 'When watching selected projects, also include the projects they depend on.',
         alias: 'd',
-    })
-        // TODO(v24): remove the deprecated --includeDependentProjects alias
-        .option('includeDependentProjects', {
-        type: 'boolean',
-        hidden: true,
-        describe: "Deprecated in favor of --includeDependencies; will be removed in Nx 24. The flag name was misleading since it includes the watched project's dependencies, not its dependents. The new flag is functionally identical.",
     })
         .option('includeGlobalWorkspaceFiles', {
         type: 'boolean',
@@ -59,6 +53,7 @@ function withWatchOptions(yargs) {
         .conflicts({
         all: 'projects',
     })
+        .strictOptions()
         .check((args) => {
         if (!args.all && !args.projects) {
             throw Error('Please specify either --all or --projects');
@@ -73,19 +68,5 @@ function withWatchOptions(yargs) {
         else {
             throw Error('No command specified for watch mode.');
         }
-        // --includeDependentProjects was renamed to --includeDependencies in
-        // Nx 23 because the original name was misleading: it includes the
-        // watched project's *dependencies*, not its dependents. The new flag
-        // is functionally identical — only the name changed. Map the legacy
-        // name through so existing scripts keep working during the
-        // deprecation window.
-        // TODO(v24): remove the legacy includeDependentProjects pass-through
-        const a = args;
-        if (a.includeDependentProjects !== undefined &&
-            a.includeDependencies === undefined) {
-            a.includeDependencies = a.includeDependentProjects;
-            // eslint-disable-next-line no-console
-            console.warn("--includeDependentProjects is deprecated in favor of --includeDependencies and will be removed in Nx 24. The flag name was misleading since it includes the watched project's dependencies, not its dependents. The new flag is functionally identical.");
-        }
-    }, true));
+    }, true);
 }

package/dist/src/command-line/watch/watch.d.ts

@@ -3,13 +3,6 @@ export interface WatchArguments {
     projects?: string[];
     all?: boolean;
     includeDependencies?: boolean;
-    /**
-     * @deprecated Renamed to {@link WatchArguments.includeDependencies}; will be
-     * removed in Nx 24. The original name was misleading: this flag includes
-     * the watched project's dependencies, not its dependents. The new property
-     * is functionally identical — only the name changed.
-     */
-    includeDependentProjects?: boolean;
     includeGlobalWorkspaceFiles?: boolean;
     verbose?: boolean;
     command?: string;

package/dist/src/command-line/watch/watch.js

@@ -149,7 +149,7 @@ async function watch(args) {
     }
     await client_1.daemonClient.registerFileWatcher({
         watchProjects: whatToWatch,
-        includeDependencies: args.includeDependencies ?? args.includeDependentProjects,
+        includeDependencies: args.includeDependencies,
         includeGlobalWorkspaceFiles: args.includeGlobalWorkspaceFiles,
     }, async (err, data) => {
         if (err === 'reconnecting') {

package/dist/src/config/misc-interfaces.d.ts

@@ -32,6 +32,9 @@ export interface ExecutorJsonEntryConfig {
     batchImplementation?: string;
     preferBatch?: boolean;
     description?: string;
+    /**
+     * @deprecated Use target inputs instead. This will be removed in Nx 25.
+     */
     hasher?: string;
 }
 export type ExecutorsJsonEntry = string | ExecutorJsonEntryConfig;
@@ -143,6 +146,9 @@ export interface ExecutorConfig {
         outputCapture?: OutputCaptureMethod;
         continuous?: boolean;
     } & Schema;
+    /**
+     * @deprecated Use target inputs instead. This will be removed in Nx 25.
+     */
     hasherFactory?: () => CustomHasher;
     implementationFactory: () => Executor;
     batchImplementationFactory?: () => TaskGraphExecutor;
@@ -172,6 +178,9 @@ options: T, context: ExecutorContext) => AsyncIterableIterator<{
  * Implementation of a target of a project
  */
 export type Executor<T = any> = PromiseExecutor<T> | AsyncIteratorExecutor<T>;
+/**
+ * @deprecated Use target inputs instead. This will be removed in Nx 25.
+ */
 export interface HasherContext {
     hasher: TaskHasher;
     projectGraph: ProjectGraph;
@@ -179,6 +188,9 @@ export interface HasherContext {
     projectsConfigurations: ProjectsConfigurations;
     nxJsonConfiguration: NxJsonConfiguration;
 }
+/**
+ * @deprecated Use target inputs instead. This will be removed in Nx 25.
+ */
 export type CustomHasher = (task: Task, context: HasherContext) => Promise<Hash>;
 export type TaskResult = {
     success: boolean;

package/dist/src/config/task-graph.d.ts

@@ -3,4 +3,4 @@
  * `packages/nx/src/native/tasks/types.rs` and exposed to TypeScript via NAPI.
  * This file re-exports them so existing imports keep working.
  */
-export type { Task, TaskGraph, TaskTarget, TaskHashDetails, TaskUltracacheSettings, } from '../native';
+export type { Task, TaskGraph, TaskGraphEdge, TaskTarget, TaskHashDetails, TaskUltracacheSettings, } from '../native';

package/dist/src/config/workspace-json-project-json.d.ts

@@ -163,6 +163,54 @@ export type Spreadable<T> = T & {
  * permits `'...'`, which target merging resolves away.
  */
 export type TargetUltracacheSettings = Spreadable<TaskUltracacheSettings>;
+export interface ReadyWhenOptions {
+    /**
+     * Milliseconds to wait for readiness before failing dependents that wait
+     * for it. Default is 60000.
+     */
+    timeout?: number;
+    /**
+     * Milliseconds between probe attempts. By default attempts back off from
+     * 100 to 1000 milliseconds. Unused by `logMatches`.
+     */
+    interval?: number;
+}
+/**
+ * Readiness probe of a continuous target. Exactly one of `url`, `port`,
+ * `command` or `logMatches` must be set. Strings may use the `{workspaceRoot}`,
+ * `{projectRoot}`, `{projectName}` and `{options.*}` placeholders, resolved
+ * against the options the task runs with.
+ */
+export type ReadyWhen = ({
+    /**
+     * Ready when an HTTP or HTTPS GET gets a status from 200 to 403. A
+     * redirect counts as ready and is not followed.
+     */
+    url: string;
+} & ReadyWhenOptions) | ({
+    /**
+     * Ready when a TCP connection to the port succeeds. A string must
+     * resolve to a port number through a placeholder such as
+     * `{options.port}`.
+     */
+    port: number | string;
+    /**
+     * Host to connect to. By default 127.0.0.1 and ::1 are both tried.
+     */
+    host?: string;
+} & ReadyWhenOptions) | ({
+    /**
+     * Ready when the command, run through the shell at the workspace root,
+     * exits with code 0.
+     */
+    command: string;
+} & ReadyWhenOptions) | ({
+    /**
+     * Ready when every one of these substrings has appeared in the task's
+     * output.
+     */
+    logMatches: string | string[];
+} & ReadyWhenOptions);
 export interface TargetDependencyConfig {
     /**
      * A list of projects that have `target`.
@@ -187,6 +235,17 @@ export interface TargetDependencyConfig {
      * Whether to forward task options to the dependency target.
      */
     options?: 'ignore' | 'forward';
+    /**
+     * Set to `false` to keep a continuous dependency's inputs out of this
+     * target's hash. It still runs first. Has no effect on other dependencies.
+     */
+    inputs?: boolean;
+    /**
+     * When the dependency is a continuous task, whether this target waits for
+     * it to have started (default) or to be ready per its `readyWhen`.
+     * Ignored when the dependency is not continuous or declares no `readyWhen`.
+     */
+    waitFor?: 'started' | 'ready';
 }
 export type InputDefinition = {
     input: string;
@@ -277,6 +336,12 @@ export interface TargetConfiguration<T = any> {
      * Whether this target runs continuously
      */
     continuous?: boolean;
+    /**
+     * How Nx detects that this continuous target is ready. Only honored when
+     * `continuous` is true; dependents opt in with `waitFor: 'ready'` on their
+     * `dependsOn` entry.
+     */
+    readyWhen?: ReadyWhen;
     /**
      * List of generators to run before the target to ensure the workspace
      * is up to date.