@nx/js 24.0.0-beta.2 → 24.0.0-canary.20261016-5ef7804

package/dist/src/plugins/scripts/create-script-nodes.d.ts

@@ -1,6 +1,10 @@
 import { type CreateNodes, type TargetConfiguration } from '@nx/devkit';
 import { type Shebang } from './shebang';
-export interface ScriptPluginDefinition<T> {
+export interface ScriptPluginOptions {
+    /** Runs claimed scripts in watch mode as continuous targets. */
+    watch?: boolean;
+}
+export interface ScriptPluginDefinition<T extends ScriptPluginOptions> {
     /** Prefix of the plugin's cache file. */
     cacheName: string;
     technology: string;
@@ -12,7 +16,7 @@ export interface ScriptPluginDefinition<T> {
     extraTargets?(projectRoot: string, workspaceRoot: string, options: T): Promise<ScriptTargets>;
 }
 export type ScriptTargets = Record<string, TargetConfiguration>;
-export declare function createScriptNodes<T extends object>(definition: ScriptPluginDefinition<T>): CreateNodes<T>;
+export declare function createScriptNodes<T extends ScriptPluginOptions>(definition: ScriptPluginDefinition<T>): CreateNodes<T>;
 /**
  * Quotes a path for a shell command when the shell would split or expand it.
  * Double quotes keep spaces intact in sh and cmd.exe; cmd.exe still expands `%VAR%`.

package/dist/src/plugins/scripts/create-script-nodes.js

@@ -2,14 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createScriptNodes = createScriptNodes;
 exports.quoteShellArg = quoteShellArg;
-const devkit_1 = require("@nx/devkit");
 const internal_1 = require("@nx/devkit/internal");
-const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const frontmatter_1 = require("./frontmatter");
 const shebang_1 = require("./shebang");
-// Frontmatter keys the plugin interprets; any other key merges into the target.
-const RESERVED_KEYS = ['name', 'description', 'disable', 'watch', 'cwd'];
+const target_name_1 = require("./target-name");
 const SCRIPT_GLOB = '**/*.{js,cjs,mjs,ts,cts,mts}';
 const PROJECT_MARKERS = ['package.json', 'project.json'];
 function createScriptNodes(definition) {
@@ -36,7 +32,7 @@ function createScriptNodes(definition) {
                     if (!cache.has(key)) {
                         cache.set(key, {
                             ...(await definition.extraTargets?.(projectRoot, context.workspaceRoot, options)),
-                            ...createTargets(definition, context.workspaceRoot, projectRoot, scripts),
+                            ...createTargets(definition, context.workspaceRoot, projectRoot, scripts, options?.watch === true),
                         });
                     }
                     const targets = cache.get(key);
@@ -91,31 +87,23 @@ function groupScriptsByProjectRoot(files, includeAllRoots) {
     }
     return byRoot;
 }
-function createTargets(definition, workspaceRoot, projectRoot, scripts) {
+function createTargets(definition, workspaceRoot, projectRoot, scripts, watch) {
     const claimed = [];
     for (const script of scripts) {
-        const absolutePath = (0, node_path_1.join)(workspaceRoot, script);
-        const line = (0, shebang_1.readShebangLine)(absolutePath);
-        const shebang = line === null ? null : (0, shebang_1.parseShebang)(line);
+        const header = (0, shebang_1.readScriptHeader)((0, node_path_1.join)(workspaceRoot, script));
+        const shebang = header === null ? null : (0, shebang_1.parseShebang)((0, shebang_1.getShebangLine)(header));
         if (!shebang || !definition.claims(shebang)) {
             continue;
         }
-        let frontmatter = {};
-        try {
-            frontmatter = (0, frontmatter_1.parseFrontmatter)((0, node_fs_1.readFileSync)(absolutePath, 'utf-8'));
-        }
-        catch (e) {
-            devkit_1.logger.warn(`Ignoring the nx frontmatter in ${script}: ${e.message}`);
-        }
-        frontmatter = dropInvalidKeys(frontmatter, script);
-        if (frontmatter.disable === true) {
-            continue;
+        const { name, warnings } = (0, target_name_1.parseTargetName)(header);
+        for (const warning of warnings) {
+            (0, internal_1.emitPluginWorkerLog)('warn', `${script}: ${warning}.`);
         }
         claimed.push({
             path: script,
             relativePath: node_path_1.posix.relative(projectRoot, script),
             shebang,
-            frontmatter,
+            targetName: name,
         });
     }
     const baseNameCounts = new Map();
@@ -126,67 +114,26 @@ function createTargets(definition, workspaceRoot, projectRoot, scripts) {
     const targets = {};
     for (const script of claimed) {
         const baseName = withoutExtension((0, node_path_1.basename)(script.relativePath));
-        const name = typeof script.frontmatter.name === 'string'
-            ? script.frontmatter.name
-            : baseNameCounts.get(baseName) > 1
+        const name = script.targetName ??
+            (baseNameCounts.get(baseName) > 1
                 ? withoutExtension(script.relativePath)
-                : baseName;
-        targets[name] = createTarget(definition, projectRoot, script);
+                : baseName);
+        targets[name] = createTarget(definition, projectRoot, script, watch);
     }
     return targets;
 }
-function createTarget(definition, projectRoot, { path, relativePath, shebang, frontmatter }) {
-    const { description, watch, cwd, options, metadata } = frontmatter;
-    const rest = { ...frontmatter };
-    for (const key of [...RESERVED_KEYS, 'options', 'metadata']) {
-        delete rest[key];
-    }
-    const targetCwd = cwd ?? (typeof options?.cwd === 'string' ? options.cwd : projectRoot);
+function createTarget(definition, projectRoot, { path, relativePath, shebang }, watch) {
     return {
-        command: definition.command(quoteShellArg(node_path_1.posix.relative(targetCwd, path)), shebang, watch === true),
-        options: { ...options, cwd: targetCwd },
+        command: definition.command(quoteShellArg(node_path_1.posix.relative(projectRoot, path)), shebang, watch),
+        options: { cwd: projectRoot },
         cache: false,
-        ...(watch === true && { continuous: true }),
+        ...(watch && { continuous: true }),
         metadata: {
             technologies: [definition.technology],
-            description: description ?? `Runs ${relativePath}`,
-            ...metadata,
+            description: `Runs ${relativePath}`,
         },
-        ...rest,
     };
 }
-const EXPECTED_TYPES = {
-    name: 'string',
-    description: 'string',
-    cwd: 'string',
-    cache: 'boolean',
-    continuous: 'boolean',
-    watch: 'boolean',
-    disable: 'boolean',
-    dependsOn: 'array',
-    inputs: 'array',
-    outputs: 'array',
-    options: 'object',
-    metadata: 'object',
-};
-/** Drops known keys with the wrong type so they cannot break the project graph. */
-function dropInvalidKeys(frontmatter, script) {
-    const valid = {};
-    for (const [key, value] of Object.entries(frontmatter)) {
-        const expected = EXPECTED_TYPES[key];
-        const actual = Array.isArray(value)
-            ? 'array'
-            : value === null
-                ? 'null'
-                : typeof value;
-        if (expected && actual !== expected) {
-            devkit_1.logger.warn(`Ignoring nx frontmatter key "${key}" in ${script}: expected ${expected}, got ${actual}.`);
-            continue;
-        }
-        valid[key] = value;
-    }
-    return valid;
-}
 /**
  * Quotes a path for a shell command when the shell would split or expand it.
  * Double quotes keep spaces intact in sh and cmd.exe; cmd.exe still expands `%VAR%`.

package/dist/src/plugins/scripts/node-plugin.d.ts

@@ -1,4 +1,5 @@
-export interface NodeScriptsPluginOptions {
+import { type ScriptPluginOptions } from './create-script-nodes';
+export interface NodeScriptsPluginOptions extends ScriptPluginOptions {
     /**
      * `dependsOn` for `bin` targets whose file is build output (not a tracked
      * workspace file). Defaults to `["build"]`.

package/dist/src/plugins/scripts/shebang.d.ts

@@ -4,8 +4,13 @@ export interface Shebang {
     /** Arguments that follow the interpreter on the shebang line. */
     args: string[];
 }
-/** Returns the shebang line without `#!`, or `null` when the file has none. */
-export declare function readShebangLine(absolutePath: string): string | null;
+/**
+ * Returns the first bytes of a script that starts with `#!`, or `null` when it
+ * has no shebang or cannot be read (e.g. a tracked broken symlink).
+ */
+export declare function readScriptHeader(absolutePath: string): string | null;
+/** The shebang line of a header from `readScriptHeader`, without `#!`. */
+export declare function getShebangLine(header: string): string;
 /**
  * Handles `/usr/bin/env node`, `/usr/bin/env -S node --flags`,
  * `/usr/bin/env -S npx tsx` and direct paths such as `/usr/local/bin/node`.

package/dist/src/plugins/scripts/shebang.js

@@ -1,29 +1,46 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.readShebangLine = readShebangLine;
+exports.readScriptHeader = readScriptHeader;
+exports.getShebangLine = getShebangLine;
 exports.parseShebang = parseShebang;
 exports.stripBom = stripBom;
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const SNIFF_BYTES = 512;
 const PACKAGE_RUNNERS = new Set(['npx', 'pnpx', 'bunx']);
-/** Returns the shebang line without `#!`, or `null` when the file has none. */
-function readShebangLine(absolutePath) {
+/**
+ * Returns the first bytes of a script that starts with `#!`, or `null` when it
+ * has no shebang or cannot be read (e.g. a tracked broken symlink).
+ */
+function readScriptHeader(absolutePath) {
     const buffer = Buffer.alloc(SNIFF_BYTES);
-    const fd = (0, node_fs_1.openSync)(absolutePath, 'r');
     let bytesRead;
     try {
-        bytesRead = (0, node_fs_1.readSync)(fd, buffer, 0, SNIFF_BYTES, 0);
+        const fd = (0, node_fs_1.openSync)(absolutePath, 'r');
+        try {
+            bytesRead = (0, node_fs_1.readSync)(fd, buffer, 0, SNIFF_BYTES, 0);
+        }
+        finally {
+            (0, node_fs_1.closeSync)(fd);
+        }
     }
-    finally {
-        (0, node_fs_1.closeSync)(fd);
+    catch {
+        return null;
     }
-    const text = stripBom(buffer.toString('utf8', 0, bytesRead));
+    let text = stripBom(buffer.toString('utf8', 0, bytesRead));
     if (!text.startsWith('#!')) {
         return null;
     }
-    const end = text.search(/\r?\n/);
-    return (end === -1 ? text : text.slice(0, end)).slice(2).trim();
+    // Drop a line the sniff cut off, so a directive is never read truncated.
+    if (bytesRead === SNIFF_BYTES && text.includes('\n')) {
+        text = text.slice(0, text.lastIndexOf('\n'));
+    }
+    return text;
+}
+/** The shebang line of a header from `readScriptHeader`, without `#!`. */
+function getShebangLine(header) {
+    const end = header.search(/\r?\n/);
+    return (end === -1 ? header : header.slice(0, end)).slice(2).trim();
 }
 /**
  * Handles `/usr/bin/env node`, `/usr/bin/env -S node --flags`,

package/dist/src/plugins/scripts/target-name.d.ts

@@ -0,0 +1,9 @@
+export interface TargetNameDirective {
+    name?: string;
+    warnings: string[];
+}
+/**
+ * Reads `@nx-target-name: <name>` from the comment block that opens the
+ * script. Only the first directive counts; problems come back as warnings.
+ */
+export declare function parseTargetName(header: string): TargetNameDirective;

package/dist/src/plugins/scripts/target-name.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseTargetName = parseTargetName;
+const internal_1 = require("@nx/devkit/internal");
+/**
+ * Reads `@nx-target-name: <name>` from the comment block that opens the
+ * script. Only the first directive counts; problems come back as warnings.
+ */
+function parseTargetName(header) {
+    const [value, ...extra] = (0, internal_1.parseNxDirectives)(header).get('target-name') ?? [];
+    const warnings = extra.map((v) => `ignoring the extra "@nx-target-name: ${v}" directive`);
+    if (value === undefined) {
+        return { warnings };
+    }
+    if (!value) {
+        return { warnings: ['"@nx-target-name" is empty', ...warnings] };
+    }
+    return { name: value, warnings };
+}

package/dist/src/plugins/scripts/tsx-plugin.d.ts

@@ -1,2 +1,3 @@
-export declare const createNodes: import("@nx/devkit").CreateNodes<Record<string, never>>;
-export declare const createNodesV2: import("@nx/devkit").CreateNodes<Record<string, never>>;
+import { type ScriptPluginOptions } from './create-script-nodes';
+export declare const createNodes: import("@nx/devkit").CreateNodes<ScriptPluginOptions>;
+export declare const createNodesV2: import("@nx/devkit").CreateNodes<ScriptPluginOptions>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nx/js",
-  "version": "24.0.0-beta.2",
+  "version": "24.0.0-canary.20261016-5ef7804",
   "private": false,
   "type": "commonjs",
   "files": [
@@ -154,8 +154,8 @@
     "@babel/preset-env": "^7.23.2",
     "@babel/preset-typescript": "^7.22.5",
     "@babel/runtime": "^7.22.6",
-    "@nx/devkit": "24.0.0-beta.2",
-    "@nx/workspace": "24.0.0-beta.2",
+    "@nx/devkit": "24.0.0-canary.20261016-5ef7804",
+    "@nx/workspace": "24.0.0-canary.20261016-5ef7804",
     "@zkochan/js-yaml": "0.0.7",
     "babel-plugin-const-enum": "^1.0.1",
     "babel-plugin-macros": "^3.1.0",
@@ -175,14 +175,14 @@
     "tslib": "^2.3.0"
   },
   "devDependencies": {
-    "@nx/esbuild": "24.0.0-beta.2",
-    "@nx/eslint": "24.0.0-beta.2",
-    "@nx/jest": "24.0.0-beta.2",
-    "@nx/oxlint": "24.0.0-beta.2",
-    "@nx/rollup": "24.0.0-beta.2",
-    "@nx/vite": "24.0.0-beta.2",
-    "@nx/vitest": "24.0.0-beta.2",
-    "nx": "24.0.0-beta.2"
+    "@nx/esbuild": "24.0.0-canary.20261016-5ef7804",
+    "@nx/eslint": "24.0.0-canary.20261016-5ef7804",
+    "@nx/jest": "24.0.0-canary.20261016-5ef7804",
+    "@nx/oxlint": "24.0.0-canary.20261016-5ef7804",
+    "@nx/rollup": "24.0.0-canary.20261016-5ef7804",
+    "@nx/vite": "24.0.0-canary.20261016-5ef7804",
+    "@nx/vitest": "24.0.0-canary.20261016-5ef7804",
+    "nx": "24.0.0-canary.20261016-5ef7804"
   },
   "peerDependencies": {
     "@swc/cli": ">=0.6.0 <0.9.0",

package/dist/src/plugins/scripts/frontmatter.d.ts

@@ -1,6 +0,0 @@
-export type Frontmatter = Record<string, unknown>;
-/**
- * Reads the YAML in a `/** @nx ... *\/` block comment after the shebang. Any other
- * first comment yields `{}`. Throws on malformed YAML or an unterminated `@nx` block.
- */
-export declare function parseFrontmatter(source: string): Frontmatter;

package/dist/src/plugins/scripts/frontmatter.js

@@ -1,52 +0,0 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.parseFrontmatter = parseFrontmatter;
-const js_yaml_1 = require("@zkochan/js-yaml");
-const shebang_1 = require("./shebang");
-/**
- * Reads the YAML in a `/** @nx ... *\/` block comment after the shebang. Any other
- * first comment yields `{}`. Throws on malformed YAML or an unterminated `@nx` block.
- */
-function parseFrontmatter(source) {
-    const lines = (0, shebang_1.stripBom)(source).split(/\r?\n/);
-    // lines[0] is the shebang; blank lines may follow it.
-    let start = 1;
-    while (start < lines.length && !lines[start].trim()) {
-        start++;
-    }
-    if (!lines[start]?.trim().startsWith('/*')) {
-        return {};
-    }
-    const block = [];
-    let terminated = false;
-    for (let i = start; i < lines.length; i++) {
-        let line = i === start ? lines[i].trim().replace(/^\/\*\*?/, '') : lines[i];
-        const end = line.indexOf('*/');
-        if (end !== -1) {
-            line = line.slice(0, end);
-            terminated = true;
-        }
-        // Tolerate JSDoc-style ` * ` line prefixes.
-        block.push(line.replace(/^\s*\* ?/, ''));
-        if (terminated) {
-            break;
-        }
-    }
-    const firstContent = block.findIndex((line) => line.trim());
-    const marker = (block[firstContent] ?? '').match(/^\s*@nx(?=\s|$)(.*)$/);
-    if (!marker) {
-        return {};
-    }
-    if (!terminated) {
-        throw new Error('Unterminated "@nx" frontmatter block.');
-    }
-    const body = [marker[1].trim(), ...block.slice(firstContent + 1)];
-    const parsed = (0, js_yaml_1.load)(body.join('\n'));
-    if (parsed == null) {
-        return {};
-    }
-    if (typeof parsed !== 'object' || Array.isArray(parsed)) {
-        throw new Error('The "@nx" frontmatter block must be a YAML mapping.');
-    }
-    return parsed;
-}