@nx/devkit 24.0.0-pr.37405.acdaf31 → 24.0.0-rc.1

package/dist/src/utils/nx-directives.d.ts

@@ -1,6 +1,7 @@
 /**
  * The `@nx-<name>: <value>` directives in the comment block that opens a file,
- * by name, with their trimmed values in order. Reading stops at the first line
+ * by name, with their trimmed values in order. A bare `@nx-<name>` has the
+ * value `''`. Reading stops at the first line
  * that is not blank, a shebang or a comment.
  */
 export declare function parseNxDirectives(content: string): Map<string, string[]>;

package/dist/src/utils/nx-directives.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.parseNxDirectives = parseNxDirectives;
-const DIRECTIVE = /^@nx-([\w-]+):(.*)$/;
+const DIRECTIVE = /^@nx-([\w-]+)(?::(.*))?$/;
 /**
  * The `@nx-<name>: <value>` directives in the comment block that opens a file,
- * by name, with their trimmed values in order. Reading stops at the first line
+ * by name, with their trimmed values in order. A bare `@nx-<name>` has the
+ * value `''`. Reading stops at the first line
  * that is not blank, a shebang or a comment.
  */
 function parseNxDirectives(content) {
@@ -45,7 +46,7 @@ function parseNxDirectives(content) {
         }
         const match = line.trim().match(DIRECTIVE);
         if (match) {
-            const [, name, value] = match;
+            const [, name, value = ''] = match;
             const values = directives.get(name);
             if (values) {
                 values.push(value.trim());

package/dist/src/utils/readiness.d.ts

@@ -0,0 +1,71 @@
+import { type AddressInfo } from 'net';
+/**
+ * The url of a server listening on `address`, for `emitReadySignal`. A
+ * wildcard address maps to localhost. Undefined for a socket or a pipe.
+ */
+export declare function getListeningUrl(address: AddressInfo | string | null | undefined, https: boolean): string | undefined;
+/**
+ * A `readyWhen` that calls `waitForDevServer` from `module` when the task
+ * runs, with the config's file name, when given, and then `literals` as its
+ * arguments.
+ */
+export declare function getReadyCheckReadyWhen(module: string, configFileName?: string, ...literals: string[]): {
+    command: string;
+    interval: number;
+};
+export type TaskOptions = Record<string, unknown> & {
+    cwd?: string;
+};
+/**
+ * The arguments run-commands passes the task's command, as the command
+ * receives them: built by run-commands' own code, then split the way the shell
+ * splits them. A `{args.*}` command gets them as if appended, which matches a
+ * command that passes each value to the flag of its name.
+ */
+export declare function getForwardedArgs(options: TaskOptions): string[];
+export interface CacArgsOptions {
+    /** Each short flag and the camel-case option it aliases, such as `{ c: 'config' }`. */
+    aliases?: Record<string, string>;
+    /** The flags that take no value, by any of their names. */
+    booleans?: string[];
+}
+/**
+ * The options a cac CLI, such as Rsbuild's or Rspack's, parses from `args`,
+ * before it applies option defaults and types. Ports cac's `mri()` step:
+ * - A flag takes the next argument as its value unless that starts with `-`.
+ * - A repeated flag collects its values in an array, and numeric values
+ *   become numbers.
+ * - Every alias takes the value of the alias given first.
+ * - The kebab-case and camel-case spellings of an option take the value of
+ *   the spelling that first appears last.
+ *
+ * Dotted names stay flat keys, where cac nests them.
+ */
+export declare function parseCacArgs(args: string[], { aliases, booleans }?: CacArgsOptions): Record<string, unknown>;
+/**
+ * The options a commander 12 command, such as the Rsbuild 1.0 and 1.1 CLI's,
+ * parses from `args`, by attribute name, given its option flags such as
+ * `'-o --open [url]'`. The last value of an option wins, and no defaults or
+ * custom argument parsers apply. Throws where the command exits instead: on an
+ * unknown option, `--help` included, or a missing value.
+ */
+export declare function parseCommanderArgs(args: string[], declarations: string[]): Record<string, string | true>;
+export interface ServerAddress {
+    port: number;
+    host?: string;
+}
+/**
+ * Where to probe a server, or null when its port is not a positive integer:
+ * a server that picks its port or listens on a socket can't be probed ahead.
+ */
+export declare function getServerAddress(port: unknown, host: unknown): ServerAddress | null;
+/**
+ * Runs a task-time readiness check. Reads the options the task runs with,
+ * moves to its cwd, where the CLI resolves its config, and waits until every
+ * address `resolveAddresses` returns accepts a TCP connection. Probes nothing
+ * when it returns null.
+ */
+export declare function runReadyCheck(resolveAddresses: (task: {
+    options: TaskOptions;
+    root: string;
+}) => Promise<ServerAddress[] | null>): Promise<void>;

package/dist/src/utils/readiness.js

@@ -0,0 +1,259 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getListeningUrl = getListeningUrl;
+exports.getReadyCheckReadyWhen = getReadyCheckReadyWhen;
+exports.getForwardedArgs = getForwardedArgs;
+exports.parseCacArgs = parseCacArgs;
+exports.parseCommanderArgs = parseCommanderArgs;
+exports.getServerAddress = getServerAddress;
+exports.runReadyCheck = runReadyCheck;
+const net_1 = require("net");
+const devkit_internals_1 = require("nx/src/devkit-internals");
+const path_1 = require("path");
+const split_shell_args_1 = require("./split-shell-args");
+/**
+ * The url of a server listening on `address`, for `emitReadySignal`. A
+ * wildcard address maps to localhost. Undefined for a socket or a pipe.
+ */
+function getListeningUrl(address, https) {
+    if (!address || typeof address === 'string') {
+        return undefined;
+    }
+    const host = address.address === '::' || address.address === '0.0.0.0'
+        ? 'localhost'
+        : address.family === 'IPv6'
+            ? `[${address.address}]`
+            : address.address;
+    return `${https ? 'https' : 'http'}://${host}:${address.port}/`;
+}
+/**
+ * A `readyWhen` that calls `waitForDevServer` from `module` when the task
+ * runs, with the config's file name, when given, and then `literals` as its
+ * arguments.
+ */
+function getReadyCheckReadyWhen(module, configFileName, ...literals) {
+    // Unquoted in the command, as no quoting works in every shell
+    if (configFileName !== undefined && !/^[\w.-]+$/.test(configFileName)) {
+        throw new Error(`Unsupported config file name: ${configFileName}`);
+    }
+    const args = [
+        ...(configFileName === undefined ? [] : ['process.argv[1]']),
+        ...literals.map((literal) => `'${literal}'`),
+    ].join(', ');
+    return {
+        command: `node -e "require('${module}').waitForDevServer(${args})"${configFileName === undefined ? '' : ` ${configFileName}`}`,
+        // Each attempt starts node, and loads the config when there is one
+        interval: 1000,
+    };
+}
+/**
+ * The arguments run-commands passes the task's command, as the command
+ * receives them: built by run-commands' own code, then split the way the shell
+ * splits them. A `{args.*}` command gets them as if appended, which matches a
+ * command that passes each value to the flag of its name.
+ */
+function getForwardedArgs(options) {
+    const commands = options.command
+        ? [{ command: [options.command].flat().join(' ') }]
+        : Array.isArray(options.commands)
+            ? options.commands.map((c) => typeof c === 'string' ? { command: c } : c)
+            : [];
+    // Which of several commands starts the server is unknown
+    const server = commands.length === 1 ? commands[0] : {};
+    const template = server.command?.includes('{args}') && !server.command.includes('{args.')
+        ? '{args}'
+        : '';
+    const forwarded = (0, devkit_internals_1.interpolateArgsIntoCommand)(template, (0, devkit_internals_1.normalizeRunCommandsArgs)({
+        ...options,
+        __unparsed__: Array.isArray(options.__unparsed__)
+            ? options.__unparsed__.map(String)
+            : [],
+    }), server.forwardAllArgs ?? options.forwardAllArgs ?? true);
+    return (0, split_shell_args_1.splitShellArgs)(forwarded);
+}
+/**
+ * The options a cac CLI, such as Rsbuild's or Rspack's, parses from `args`,
+ * before it applies option defaults and types. Ports cac's `mri()` step:
+ * - A flag takes the next argument as its value unless that starts with `-`.
+ * - A repeated flag collects its values in an array, and numeric values
+ *   become numbers.
+ * - Every alias takes the value of the alias given first.
+ * - The kebab-case and camel-case spellings of an option take the value of
+ *   the spelling that first appears last.
+ *
+ * Dotted names stay flat keys, where cac nests them.
+ */
+function parseCacArgs(args, { aliases = {}, booleans = [] } = {}) {
+    const aliasOf = new Map();
+    for (const [short, long] of Object.entries(aliases)) {
+        aliasOf.set(short, long).set(long, short);
+    }
+    const isBoolean = (name) => booleans.includes(name) || booleans.includes(aliasOf.get(name));
+    const parsed = {};
+    const add = (name, value) => {
+        const number = Number(value);
+        const typed = typeof value === 'boolean'
+            ? value
+            : isBoolean(name)
+                ? value !== 'false' && value !== ''
+                : Number.isFinite(number)
+                    ? number
+                    : value;
+        parsed[name] =
+            parsed[name] === undefined ? typed : [parsed[name], typed].flat();
+    };
+    let i = 0;
+    for (; i < args.length && args[i] !== '--'; i++) {
+        const arg = args[i];
+        const dashes = arg.match(/^-*/)[0].length;
+        if (dashes === 0)
+            continue;
+        if (arg.startsWith('no-', dashes)) {
+            parsed[arg.slice(dashes + 3)] = false;
+            continue;
+        }
+        const equals = arg.indexOf('=', dashes + 1);
+        const name = arg.slice(dashes, equals === -1 ? undefined : equals);
+        const value = (equals === -1 ? '' : arg.slice(equals + 1)) ||
+            i + 1 === args.length ||
+            args[i + 1].startsWith('-') ||
+            args[++i];
+        // `-abc` sets `a` and `b` and gives its value to `c`
+        const names = dashes === 2 ? [name] : [...name];
+        names.forEach((n, index) => add(n, index + 1 < names.length || value));
+    }
+    const synced = new Set();
+    for (const name of Object.keys(parsed)) {
+        const alias = aliasOf.get(name);
+        if (alias !== undefined && !synced.has(name)) {
+            parsed[alias] = parsed[name];
+            synced.add(alias);
+        }
+    }
+    const options = { '--': args.slice(i + 1) };
+    for (const [name, value] of Object.entries(parsed)) {
+        options[name.replace(/([a-z])-([a-z])/g, (_, a, b) => a + b.toUpperCase())] = value;
+    }
+    return options;
+}
+/**
+ * The options a commander 12 command, such as the Rsbuild 1.0 and 1.1 CLI's,
+ * parses from `args`, by attribute name, given its option flags such as
+ * `'-o --open [url]'`. The last value of an option wins, and no defaults or
+ * custom argument parsers apply. Throws where the command exits instead: on an
+ * unknown option, `--help` included, or a missing value.
+ */
+function parseCommanderArgs(args, declarations) {
+    const options = declarations.map((flags) => {
+        const names = flags.split(/[ |,]+/).filter((part) => part.startsWith('-'));
+        return {
+            flags,
+            names,
+            key: names
+                .at(-1)
+                .replace(/^-+/, '')
+                .split('-')
+                .reduce((key, word) => key + word[0].toUpperCase() + word.slice(1)),
+            required: flags.includes('<'),
+            optional: flags.includes('['),
+        };
+    });
+    const find = (flag) => options.find((o) => o.names.includes(flag));
+    const isOption = (arg) => arg.length > 1 && arg[0] === '-';
+    const parsed = {};
+    const rest = [...args];
+    while (rest.length > 0 && rest[0] !== '--') {
+        const arg = rest.shift();
+        let option = find(arg);
+        if (option?.required) {
+            if (rest.length === 0) {
+                throw new Error(`option '${option.flags}' argument missing`);
+            }
+            parsed[option.key] = rest.shift();
+        }
+        else if (option) {
+            parsed[option.key] =
+                option.optional && rest.length > 0 && !isOption(rest[0])
+                    ? rest.shift()
+                    : true;
+        }
+        else if (arg.length > 2 &&
+            arg[0] === '-' &&
+            arg[1] !== '-' &&
+            (option = find(arg.slice(0, 2)))) {
+            // `-abc` gives `a` the value `bc`, or sets it and goes on with `-bc`
+            if (option.required || option.optional) {
+                parsed[option.key] = arg.slice(2);
+            }
+            else {
+                parsed[option.key] = true;
+                rest.unshift(`-${arg.slice(2)}`);
+            }
+        }
+        else if (/^--[^=]+=/.test(arg) &&
+            (option = find(arg.slice(0, arg.indexOf('=')))) &&
+            (option.required || option.optional)) {
+            parsed[option.key] = arg.slice(arg.indexOf('=') + 1);
+        }
+        else if (isOption(arg)) {
+            throw new Error(`unknown option '${arg}'`);
+        }
+    }
+    return parsed;
+}
+// The probe reaches these on loopback
+const LOOPBACK_HOSTS = new Set(['', 'localhost', '0.0.0.0', '::']);
+/**
+ * Where to probe a server, or null when its port is not a positive integer:
+ * a server that picks its port or listens on a socket can't be probed ahead.
+ */
+function getServerAddress(port, host) {
+    const number = Number(port);
+    if (!Number.isInteger(number) || number <= 0)
+        return null;
+    return typeof host === 'string' && !LOOPBACK_HOSTS.has(host)
+        ? { port: number, host }
+        : { port: number };
+}
+/**
+ * Runs a task-time readiness check. Reads the options the task runs with,
+ * moves to its cwd, where the CLI resolves its config, and waits until every
+ * address `resolveAddresses` returns accepts a TCP connection. Probes nothing
+ * when it returns null.
+ */
+async function runReadyCheck(resolveAddresses) {
+    const options = readTaskOptions();
+    const root = (0, path_1.resolve)(options.cwd ?? '.');
+    process.chdir(root);
+    const addresses = await resolveAddresses({ options, root });
+    if (addresses) {
+        await Promise.all(addresses.map(waitForAddress));
+    }
+}
+function readTaskOptions() {
+    try {
+        return JSON.parse(process.env.NX_TASK_OPTIONS ?? '{}');
+    }
+    catch {
+        return {};
+    }
+}
+async function waitForAddress({ port, host }) {
+    const hosts = host ? [host] : ['127.0.0.1', '::1'];
+    while (!(await Promise.any(hosts.map((h) => connects(port, h))).catch(() => false))) {
+        await new Promise((r) => setTimeout(r, 250));
+    }
+}
+function connects(port, host) {
+    return new Promise((resolve, reject) => {
+        const socket = (0, net_1.createConnection)({ port, host });
+        socket.once('connect', () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once('error', (e) => {
+            socket.destroy();
+            reject(e);
+        });
+    });
+}

package/dist/src/utils/split-shell-args.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Splits a string into the words a command gets when a shell runs it, as
+ * run-commands does: with POSIX sh rules, or on Windows with cmd.exe and the C
+ * runtime's argv rules. Variables expand from `process.env`; command
+ * substitution and globs stay literal.
+ */
+export declare function splitShellArgs(value: string): string[];

package/dist/src/utils/split-shell-args.js

@@ -0,0 +1,190 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.splitShellArgs = splitShellArgs;
+/**
+ * Splits a string into the words a command gets when a shell runs it, as
+ * run-commands does: with POSIX sh rules, or on Windows with cmd.exe and the C
+ * runtime's argv rules. Variables expand from `process.env`; command
+ * substitution and globs stay literal.
+ */
+function splitShellArgs(value) {
+    return process.platform === 'win32'
+        ? splitWindowsArgs(applyCmdRules(value))
+        : splitPosixArgs(value);
+}
+function splitPosixArgs(value) {
+    const words = [];
+    let word;
+    let quote;
+    // An unquoted expansion splits into words on whitespace
+    const appendUnquoted = (text) => text.split(/[ \t\n]+/).forEach((part, index) => {
+        if (index > 0 && word !== undefined) {
+            words.push(word);
+            word = undefined;
+        }
+        if (part)
+            word = (word ?? '') + part;
+    });
+    for (let i = 0; i < value.length; i++) {
+        const char = value[i];
+        if (quote === "'") {
+            if (char === "'")
+                quote = undefined;
+            else
+                word += char;
+        }
+        else if (char === '\\' && value[i + 1] === '\n') {
+            i++;
+        }
+        else if (char === '$' && expandPosixVariable(value, i)) {
+            const expansion = expandPosixVariable(value, i);
+            if (quote)
+                word += expansion.value;
+            else
+                appendUnquoted(expansion.value);
+            i = expansion.end;
+        }
+        else if (quote === '"') {
+            if (char === '"') {
+                quote = undefined;
+            }
+            else if (char === '\\' && '"\\$`'.includes(value[i + 1])) {
+                word += value[++i];
+            }
+            else {
+                word += char;
+            }
+        }
+        else if (/[ \t\n]/.test(char)) {
+            if (word !== undefined)
+                words.push(word);
+            word = undefined;
+        }
+        else if (char === '"' || char === "'") {
+            quote = char;
+            word ??= '';
+        }
+        else if (char === '\\' && i + 1 < value.length) {
+            word = (word ?? '') + value[++i];
+        }
+        else {
+            word = (word ?? '') + char;
+        }
+    }
+    if (word !== undefined)
+        words.push(word);
+    return words;
+}
+/**
+ * Expands `$NAME`, `${NAME}`, `${NAME-default}` and `${NAME:-default}` at
+ * `start`, returning the value and the index of its last character. Returns
+ * undefined for anything else, which stays literal.
+ */
+function expandPosixVariable(value, start) {
+    const name = value.slice(start + 1).match(/^[A-Za-z_][A-Za-z0-9_]*/)?.[0];
+    if (name) {
+        return { value: process.env[name] ?? '', end: start + name.length };
+    }
+    if (value[start + 1] !== '{')
+        return undefined;
+    let depth = 0;
+    for (let i = start + 1; i < value.length; i++) {
+        if (value[i] === '{')
+            depth++;
+        else if (value[i] === '}' && --depth === 0) {
+            const match = value
+                .slice(start + 2, i)
+                .match(/^([A-Za-z_][A-Za-z0-9_]*)(?:(:?)-(.*))?$/s);
+            if (!match)
+                return undefined;
+            const [, braced, colon, fallback] = match;
+            const env = process.env[braced];
+            const useFallback = fallback !== undefined && (colon ? !env : env === undefined);
+            return {
+                value: useFallback ? expandPosixText(fallback) : (env ?? ''),
+                end: i,
+            };
+        }
+    }
+    return undefined;
+}
+function expandPosixText(text) {
+    let result = '';
+    for (let i = 0; i < text.length; i++) {
+        const expansion = text[i] === '$' && expandPosixVariable(text, i);
+        if (expansion) {
+            result += expansion.value;
+            i = expansion.end;
+        }
+        else {
+            result += text[i];
+        }
+    }
+    return result;
+}
+// cmd.exe expands defined %NAME% variables, then drops each ^ outside double
+// quotes and keeps the character after it
+function applyCmdRules(value) {
+    const expanded = value.replace(/%([^%\s]+)%/g, (match, name) => process.env[name] ?? match);
+    let result = '';
+    let quoted = false;
+    for (let i = 0; i < expanded.length; i++) {
+        const char = expanded[i];
+        if (char === '^' && !quoted && i + 1 < expanded.length) {
+            result += expanded[++i];
+        }
+        else {
+            if (char === '"')
+                quoted = !quoted;
+            result += char;
+        }
+    }
+    return result;
+}
+// Backslashes are literal unless they precede a double quote, and single
+// quotes are literal
+function splitWindowsArgs(value) {
+    const words = [];
+    let word;
+    let quoted = false;
+    for (let i = 0; i < value.length; i++) {
+        const char = value[i];
+        if (char === '\\') {
+            let count = 1;
+            while (value[i + count] === '\\')
+                count++;
+            i += count - 1;
+            if (value[i + 1] === '"') {
+                word = (word ?? '') + '\\'.repeat(Math.floor(count / 2));
+                if (count % 2 === 1) {
+                    word += '"';
+                    i++;
+                }
+            }
+            else {
+                word = (word ?? '') + '\\'.repeat(count);
+            }
+        }
+        else if (char === '"') {
+            if (quoted && value[i + 1] === '"') {
+                word += '"';
+                i++;
+            }
+            else {
+                quoted = !quoted;
+                word ??= '';
+            }
+        }
+        else if (!quoted && (char === ' ' || char === '\t')) {
+            if (word !== undefined)
+                words.push(word);
+            word = undefined;
+        }
+        else {
+            word = (word ?? '') + char;
+        }
+    }
+    if (word !== undefined)
+        words.push(word);
+    return words;
+}

package/dist/src/utils/test-file-depends-on.d.ts

@@ -3,9 +3,9 @@ import type { TargetConfiguration } from 'nx/src/devkit-exports';
 export declare function dependsOnProjects(values: string[]): string[];
 /**
  * `target` narrowed to the projects a test file names: its dependency inputs
- * (`^…`, `dependencies: true`) become one input selecting `projects`, by the
- * first named input among them (else `default`) and kept under ultracache
- * (`always: true`). Its `dependsOn` entries naming projects, the servers the
- * test talks to, get `inputs: false`.
+ * (`^…`, `dependencies: true`) become two inputs selecting `projects` and their
+ * dependencies, by the first named input among them (else `default`) and kept
+ * under ultracache (`always: true`). Its `dependsOn` entries naming projects,
+ * the servers the test talks to, get `inputs: false`.
  */
 export declare function scopeTestTargetToProjects(target: TargetConfiguration, projects: string[]): TargetConfiguration;

package/dist/src/utils/test-file-depends-on.js

@@ -18,10 +18,10 @@ function dependsOnProjects(values) {
 }
 /**
  * `target` narrowed to the projects a test file names: its dependency inputs
- * (`^…`, `dependencies: true`) become one input selecting `projects`, by the
- * first named input among them (else `default`) and kept under ultracache
- * (`always: true`). Its `dependsOn` entries naming projects, the servers the
- * test talks to, get `inputs: false`.
+ * (`^…`, `dependencies: true`) become two inputs selecting `projects` and their
+ * dependencies, by the first named input among them (else `default`) and kept
+ * under ultracache (`always: true`). Its `dependsOn` entries naming projects,
+ * the servers the test talks to, get `inputs: false`.
  */
 function scopeTestTargetToProjects(target, projects) {
     return {
@@ -54,10 +54,7 @@ function scopeDependencyInputs(inputs, projects) {
             }
         }
     }
-    own.splice(position ?? own.length, 0, {
-        input: namedInput ?? 'default',
-        projects,
-        always: true,
-    });
+    const input = namedInput ?? 'default';
+    own.splice(position ?? own.length, 0, { input, projects, always: true }, { input, projects, dependencies: true, always: true });
     return own;
 }

package/dist/src/utils/test-file-directives.d.ts

@@ -1,12 +1,10 @@
 import type { TargetConfiguration } from 'nx/src/devkit-exports';
-declare const TEST_FILE_DIRECTIVES: readonly ['depends-on', 'ultracache'];
-/** An `@nx-<name>` directive a plugin can apply to a test file's target. */
-type TestFileDirective = (typeof TEST_FILE_DIRECTIVES)[number];
 /**
- * `target` with the `@nx-*` directives of a workspace-relative test file
- * applied, for the directives in `supported`. A directive that is not
- * supported, has an unsupported value or lists no projects is skipped with a
- * warning.
+ * `target` with the `@nx-depends-on` and `@nx-ignore-server-inputs`
+ * directives of a workspace-relative test file applied. A directive that lists
+ * no projects, has a value it does not take, or is not supported
+ * (`ignoreServerInputs: false`) is skipped with a warning.
  */
-export declare function applyTestFileDirectives(target: TargetConfiguration, workspaceRoot: string, file: string, supported: readonly TestFileDirective[]): TargetConfiguration;
-export {};
+export declare function applyTestFileDirectives(target: TargetConfiguration, workspaceRoot: string, file: string, options: {
+    ignoreServerInputs: boolean;
+}): TargetConfiguration;