@nx/js 24.0.0-beta.1 → 24.0.0-beta.2

package/dist/node.d.ts

@@ -0,0 +1 @@
+export { createNodes, createNodesV2, type NodeScriptsPluginOptions, } from './src/plugins/scripts/node-plugin';

package/dist/node.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNodesV2 = exports.createNodes = void 0;
+var node_plugin_1 = require("./src/plugins/scripts/node-plugin");
+Object.defineProperty(exports, "createNodes", { enumerable: true, get: function () { return node_plugin_1.createNodes; } });
+Object.defineProperty(exports, "createNodesV2", { enumerable: true, get: function () { return node_plugin_1.createNodesV2; } });

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

@@ -0,0 +1,20 @@
+import { type CreateNodes, type TargetConfiguration } from '@nx/devkit';
+import { type Shebang } from './shebang';
+export interface ScriptPluginDefinition<T> {
+    /** Prefix of the plugin's cache file. */
+    cacheName: string;
+    technology: string;
+    /** Only files whose shebang the plugin claims become targets. */
+    claims(shebang: Shebang): boolean;
+    /** `file` is relative to the target's cwd. */
+    command(file: string, shebang: Shebang, watch: boolean): string;
+    /** Targets not tied to a shebang; claimed scripts win on name clashes. */
+    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>;
+/**
+ * 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%`.
+ */
+export declare function quoteShellArg(arg: string): string;

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

@@ -0,0 +1,202 @@
+"use strict";
+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 SCRIPT_GLOB = '**/*.{js,cjs,mjs,ts,cts,mts}';
+const PROJECT_MARKERS = ['package.json', 'project.json'];
+function createScriptNodes(definition) {
+    return [
+        (0, internal_1.combineGlobPatterns)([
+            SCRIPT_GLOB,
+            ...PROJECT_MARKERS.map((marker) => `**/${marker}`),
+        ]),
+        async (files, options, context) => {
+            const scriptsByRoot = groupScriptsByProjectRoot(files, !!definition.extraTargets);
+            const projectRoots = [...scriptsByRoot.keys()];
+            if (!projectRoots.length) {
+                return [];
+            }
+            const cache = new internal_1.PluginCache((0, node_path_1.join)(internal_1.workspaceDataDirectory, `${definition.cacheName}-${(0, internal_1.hashObject)(options ?? {})}.hash`));
+            try {
+                const hashes = await (0, internal_1.calculateHashesForCreateNodes)(projectRoots, options ?? {}, context);
+                const results = [];
+                for (const [i, projectRoot] of projectRoots.entries()) {
+                    const { marker, scripts } = scriptsByRoot.get(projectRoot);
+                    // include/exclude can change which scripts a project gets without
+                    // changing its contents.
+                    const key = (0, internal_1.hashObject)([hashes[i], [...scripts].sort()]);
+                    if (!cache.has(key)) {
+                        cache.set(key, {
+                            ...(await definition.extraTargets?.(projectRoot, context.workspaceRoot, options)),
+                            ...createTargets(definition, context.workspaceRoot, projectRoot, scripts),
+                        });
+                    }
+                    const targets = cache.get(key);
+                    if (Object.keys(targets).length) {
+                        results.push([
+                            scripts[0] ?? marker,
+                            { projects: { [projectRoot]: { root: projectRoot, targets } } },
+                        ]);
+                    }
+                }
+                return results;
+            }
+            finally {
+                cache.writeToDisk();
+            }
+        },
+    ];
+}
+/**
+ * Assigns each script to its nearest enclosing project root. Roots without
+ * scripts are kept only when `includeAllRoots` is set.
+ */
+function groupScriptsByProjectRoot(files, includeAllRoots) {
+    const markers = new Map();
+    const scripts = [];
+    for (const file of files) {
+        if (PROJECT_MARKERS.includes((0, node_path_1.basename)(file))) {
+            markers.set((0, node_path_1.dirname)(file), file);
+        }
+        else {
+            scripts.push(file);
+        }
+    }
+    const byRoot = new Map();
+    if (includeAllRoots) {
+        for (const [root, marker] of markers) {
+            byRoot.set(root, { marker, scripts: [] });
+        }
+    }
+    for (const script of scripts) {
+        let dir = (0, node_path_1.dirname)(script);
+        while (!markers.has(dir) && dir !== '.') {
+            dir = (0, node_path_1.dirname)(dir);
+        }
+        if (!markers.has(dir)) {
+            continue;
+        }
+        if (!byRoot.has(dir)) {
+            byRoot.set(dir, { marker: markers.get(dir), scripts: [] });
+        }
+        byRoot.get(dir).scripts.push(script);
+    }
+    return byRoot;
+}
+function createTargets(definition, workspaceRoot, projectRoot, scripts) {
+    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);
+        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;
+        }
+        claimed.push({
+            path: script,
+            relativePath: node_path_1.posix.relative(projectRoot, script),
+            shebang,
+            frontmatter,
+        });
+    }
+    const baseNameCounts = new Map();
+    for (const { relativePath } of claimed) {
+        const name = withoutExtension((0, node_path_1.basename)(relativePath));
+        baseNameCounts.set(name, (baseNameCounts.get(name) ?? 0) + 1);
+    }
+    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
+                ? withoutExtension(script.relativePath)
+                : baseName;
+        targets[name] = createTarget(definition, projectRoot, script);
+    }
+    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);
+    return {
+        command: definition.command(quoteShellArg(node_path_1.posix.relative(targetCwd, path)), shebang, watch === true),
+        options: { ...options, cwd: targetCwd },
+        cache: false,
+        ...(watch === true && { continuous: true }),
+        metadata: {
+            technologies: [definition.technology],
+            description: description ?? `Runs ${relativePath}`,
+            ...metadata,
+        },
+        ...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%`.
+ */
+function quoteShellArg(arg) {
+    if (/^[\w@%+=:,./-]+$/.test(arg)) {
+        return arg;
+    }
+    return '"' + arg.replace(/(["\\$`])/g, '\\$1') + '"';
+}
+function withoutExtension(path) {
+    return path.slice(0, path.length - (0, node_path_1.extname)(path).length);
+}

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

@@ -0,0 +1,6 @@
+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

@@ -0,0 +1,52 @@
+"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;
+}

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

@@ -0,0 +1,9 @@
+export interface NodeScriptsPluginOptions {
+    /**
+     * `dependsOn` for `bin` targets whose file is build output (not a tracked
+     * workspace file). Defaults to `["build"]`.
+     */
+    binDependsOn?: string[];
+}
+export declare const createNodes: import("@nx/devkit").CreateNodes<NodeScriptsPluginOptions>;
+export declare const createNodesV2: import("@nx/devkit").CreateNodes<NodeScriptsPluginOptions>;

package/dist/src/plugins/scripts/node-plugin.js

@@ -0,0 +1,52 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNodesV2 = exports.createNodes = void 0;
+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 create_script_nodes_1 = require("./create-script-nodes");
+exports.createNodes = (0, create_script_nodes_1.createScriptNodes)({
+    cacheName: 'js-node-scripts',
+    technology: 'node',
+    claims: (shebang) => shebang.interpreter === 'node',
+    command: (file, shebang, watch) => ['node', ...(watch ? ['--watch'] : []), ...shebang.args, file].join(' '),
+    extraTargets: createBinTargets,
+});
+exports.createNodesV2 = exports.createNodes;
+async function createBinTargets(projectRoot, workspaceRoot, options) {
+    const packageJsonPath = (0, node_path_1.join)(workspaceRoot, projectRoot, 'package.json');
+    if (!(0, node_fs_1.existsSync)(packageJsonPath)) {
+        return {};
+    }
+    const bins = readBinEntries((0, devkit_1.readJsonFile)(packageJsonPath));
+    if (!bins.length) {
+        return {};
+    }
+    const binFiles = bins.map(([, path]) => node_path_1.posix.join(projectRoot, node_path_1.posix.normalize(path)));
+    const tracked = new Set(await (0, internal_1.globWithWorkspaceContext)(workspaceRoot, binFiles));
+    const targets = {};
+    bins.forEach(([name, path], i) => {
+        const target = {
+            command: `node ${(0, create_script_nodes_1.quoteShellArg)(node_path_1.posix.normalize(path))}`,
+            options: { cwd: projectRoot },
+            cache: false,
+            metadata: {
+                technologies: ['node'],
+                description: `Runs the ${name} bin`,
+            },
+        };
+        if (!tracked.has(binFiles[i])) {
+            target.dependsOn = options?.binDependsOn ?? ['build'];
+        }
+        targets[name] = target;
+    });
+    return targets;
+}
+function readBinEntries(packageJson) {
+    const { name, bin } = packageJson;
+    if (typeof bin === 'string') {
+        return name ? [[name.replace(/^@[^/]+\//, ''), bin]] : [];
+    }
+    return Object.entries(bin ?? {}).filter((entry) => typeof entry[1] === 'string');
+}

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

@@ -0,0 +1,14 @@
+export interface Shebang {
+    /** Program that runs the file, e.g. `node` or `tsx`. */
+    interpreter: string;
+    /** 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;
+/**
+ * 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`.
+ */
+export declare function parseShebang(line: string): Shebang | null;
+export declare function stripBom(text: string): string;

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

@@ -0,0 +1,50 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.readShebangLine = readShebangLine;
+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) {
+    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);
+    }
+    finally {
+        (0, node_fs_1.closeSync)(fd);
+    }
+    const 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();
+}
+/**
+ * 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`.
+ */
+function parseShebang(line) {
+    let tokens = line.split(/\s+/).filter(Boolean);
+    if (tokens.length && (0, node_path_1.basename)(tokens[0]) === 'env') {
+        tokens = tokens.slice(1);
+        if (tokens[0] === '-S') {
+            tokens = tokens.slice(1);
+        }
+    }
+    if (tokens.length && PACKAGE_RUNNERS.has((0, node_path_1.basename)(tokens[0]))) {
+        tokens = tokens.slice(1);
+    }
+    if (!tokens.length) {
+        return null;
+    }
+    return { interpreter: (0, node_path_1.basename)(tokens[0]), args: tokens.slice(1) };
+}
+function stripBom(text) {
+    return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}

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

@@ -0,0 +1,2 @@
+export declare const createNodes: import("@nx/devkit").CreateNodes<Record<string, never>>;
+export declare const createNodesV2: import("@nx/devkit").CreateNodes<Record<string, never>>;

package/dist/src/plugins/scripts/tsx-plugin.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNodesV2 = exports.createNodes = void 0;
+const create_script_nodes_1 = require("./create-script-nodes");
+exports.createNodes = (0, create_script_nodes_1.createScriptNodes)({
+    cacheName: 'js-tsx-scripts',
+    technology: 'tsx',
+    claims: (shebang) => shebang.interpreter === 'tsx',
+    command: (file, shebang, watch) => ['tsx', ...(watch ? ['watch'] : []), ...shebang.args, file].join(' '),
+});
+exports.createNodesV2 = exports.createNodes;

package/dist/tsx.d.ts

@@ -0,0 +1 @@
+export { createNodes, createNodesV2 } from './src/plugins/scripts/tsx-plugin';

package/dist/tsx.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNodesV2 = exports.createNodes = void 0;
+var tsx_plugin_1 = require("./src/plugins/scripts/tsx-plugin");
+Object.defineProperty(exports, "createNodes", { enumerable: true, get: function () { return tsx_plugin_1.createNodes; } });
+Object.defineProperty(exports, "createNodesV2", { enumerable: true, get: function () { return tsx_plugin_1.createNodesV2; } });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nx/js",
-  "version": "24.0.0-beta.1",
+  "version": "24.0.0-beta.2",
   "private": false,
   "type": "commonjs",
   "files": [
@@ -39,6 +39,12 @@
       "typescript": [
         "dist/typescript.d.ts"
       ],
+      "node": [
+        "dist/node.d.ts"
+      ],
+      "tsx": [
+        "dist/tsx.d.ts"
+      ],
       "plugins/jest/local-registry": [
         "dist/plugins/jest/local-registry.d.ts"
       ],
@@ -96,6 +102,16 @@
       "types": "./dist/typescript.d.ts",
       "default": "./dist/typescript.js"
     },
+    "./node": {
+      "@nx/nx-source": "./node.ts",
+      "types": "./dist/node.d.ts",
+      "default": "./dist/node.js"
+    },
+    "./tsx": {
+      "@nx/nx-source": "./tsx.ts",
+      "types": "./dist/tsx.d.ts",
+      "default": "./dist/tsx.js"
+    },
     "./plugins/jest/local-registry": {
       "@nx/nx-source": "./plugins/jest/local-registry.ts",
       "types": "./dist/plugins/jest/local-registry.d.ts",
@@ -138,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.1",
-    "@nx/workspace": "24.0.0-beta.1",
+    "@nx/devkit": "24.0.0-beta.2",
+    "@nx/workspace": "24.0.0-beta.2",
     "@zkochan/js-yaml": "0.0.7",
     "babel-plugin-const-enum": "^1.0.1",
     "babel-plugin-macros": "^3.1.0",
@@ -159,14 +175,14 @@
     "tslib": "^2.3.0"
   },
   "devDependencies": {
-    "@nx/esbuild": "24.0.0-beta.1",
-    "@nx/eslint": "24.0.0-beta.1",
-    "@nx/jest": "24.0.0-beta.1",
-    "@nx/oxlint": "24.0.0-beta.1",
-    "@nx/rollup": "24.0.0-beta.1",
-    "@nx/vite": "24.0.0-beta.1",
-    "@nx/vitest": "24.0.0-beta.1",
-    "nx": "24.0.0-beta.1"
+    "@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"
   },
   "peerDependencies": {
     "@swc/cli": ">=0.6.0 <0.9.0",