@jesscss/plugin-node-modules 2.0.0-alpha.7 → 2.0.0-alpha.9

package/README.md

@@ -1,74 +1,35 @@
 # @jesscss/plugin-node-modules
 
-Jess plugin for resolving and loading npm packages from `node_modules`.
-
-## Overview
-
-This plugin provides npm/node_modules resolution and loading capabilities for all Jess language plugins. It uses Node's module resolution algorithm (`require.resolve`) to find and load npm packages.
-
-## Usage
-
-```typescript
-import { Compiler } from '@jesscss/jess';
-import nodeModulesPlugin from '@jesscss/plugin-node-modules';
-
-const compiler = new Compiler({
-  compile: {
-    plugins: [
-      nodeModulesPlugin(),
-      // ... other plugins
-    ]
-  }
-});
-```
-
-## API
-
-### `resolvePackage(packageName: string): string | null`
-
-Resolve an npm package name to its absolute path.
-
-```typescript
-const plugin = new NodeModulesPlugin();
-const path = plugin.resolvePackage('less-plugin-clean-css');
-// Returns: '/path/to/node_modules/less-plugin-clean-css/index.js' or null
-```
-
-### `loadPackage(packageName: string): Promise<Record<string, any> | null>`
-
-Load an npm package module.
-
-```typescript
-const plugin = new NodeModulesPlugin();
-const module = await plugin.loadPackage('less-plugin-clean-css');
-// Returns: the module exports, or null if not found
-```
-
-### `tryResolvePackages(packageNames: string[]): Promise<{ name: string; module: Record<string, any> } | null>`
-
-Try to resolve a package name with multiple possible names. Returns the first successfully resolved package.
-
-```typescript
-const plugin = new NodeModulesPlugin();
-const result = await plugin.tryResolvePackages([
-  'clean-css',
-  'less-plugin-clean-css'
-]);
-// Returns: { name: 'less-plugin-clean-css', module: {...} } or null
-```
-
-## Integration with Other Plugins
-
-Other plugins (like `@jesscss/plugin-less-compat`) can use this plugin to resolve npm packages:
-
-```typescript
-// In jess-plugin-less-compat
-const nodeModulesPlugin = plugins.find(p => p.name === 'node-modules');
-if (nodeModulesPlugin instanceof NodeModulesPlugin) {
-  const module = await nodeModulesPlugin.loadPackage('less-plugin-clean-css');
-}
-```
-
-## Options
-
-- `enabled` (boolean, default: `true`): Whether to enable auto-resolution of npm packages.
+**Import resolver that loads npm packages from `node_modules` — a seed of the
+JavaScript-execution / CSS-in-JS story.**
+
+This plugin gives Jess's language plugins a way to resolve and load npm packages
+by name, using Node's module resolution (`require.resolve` /
+`createRequire`). Other plugins use it to pull in packages referenced from a
+stylesheet — for example [`@jesscss/plugin-less-compat`](../jess-plugin-less-compat)
+resolving a Less `@plugin "package-name"` off `node_modules`.
+
+## Why it exists — the convergence angle
+
+One of the four tools [Jess](https://github.com/jesscss/jess) aims to converge is
+**CSS-in-JS**: running real JavaScript inside your stylesheets (`@use` /
+`@plugin`) so styles can be dynamic without leaving CSS files. Reaching npm
+packages is a building block of that story. Paired with
+[`@jesscss/plugin-js`](../jess-plugin-js) (which executes the modules), it lets a
+stylesheet pull logic and data from the JS ecosystem.
+
+That convergence is **roadmap — being proven through the alpha, not claimed as
+done.** What ships here today is just the resolver seam; don't read it as a
+finished CSS-in-JS system.
+
+## Status
+
+**Alpha.** Part of Jess. The programmatic plugin/compiler API is **not yet
+stabilized** — the `jess` CLI is the documented public surface for the alpha.
+Watch the
+[docs site](https://jesscss.github.io/) for the API once it settles.
+
+- Project overview & positioning: <https://github.com/jesscss/jess#readme>
+- Docs: <https://jesscss.github.io/> (currently pre-alpha content)
+- Issues: <https://github.com/jesscss/jess/issues>
+- License: MIT

package/lib/index.cjs

@@ -47,7 +47,8 @@ var NodeModulesPlugin = class extends _jesscss_core.AbstractPlugin {
 		this.opts = opts;
 		try {
 			let currentDir;
-			if (typeof __filename !== "undefined") currentDir = node_path.dirname(__filename);
+			if (opts.basePath !== void 0) currentDir = opts.basePath;
+			else if (typeof __filename !== "undefined") currentDir = node_path.dirname(__filename);
 			else try {
 				const url = require("url").pathToFileURL(__filename).href;
 				currentDir = node_path.dirname((0, node_url.fileURLToPath)(url));
@@ -64,18 +65,45 @@ var NodeModulesPlugin = class extends _jesscss_core.AbstractPlugin {
 	* Uses Node's module resolution algorithm (same as require.resolve).
 	*
 	* @param packageName - The npm package name (e.g., "less-plugin-clean-css")
+	* @param fromDir - Optional directory to start `node_modules` resolution from
+	*   (walked up per Node's algorithm). When given it takes precedence over the
+	*   plugin's `basePath`; used to resolve a package relative to the importing
+	*   file (e.g. an `@import "pkg/x"` resolving against the importer's directory).
 	* @returns The absolute path to the package, or null if not found
 	*/
-	resolvePackage(packageName) {
+	resolvePackage(packageName, fromDir) {
 		if (this.opts.enabled === false) return null;
 		try {
-			return this._require.resolve(packageName);
+			return fromDir !== void 0 ? this._require.resolve(packageName, { paths: [fromDir] }) : this._require.resolve(packageName);
 		} catch (e) {
-			if (e.code === "MODULE_NOT_FOUND") return null;
+			if (e instanceof Error && e.code === "MODULE_NOT_FOUND") return null;
 			throw e;
 		}
 	}
 	/**
+	* Context resolution hook for bare package specifiers. Core owns only the
+	* resolver-plugin pipeline; this plugin owns Node's module-resolution policy.
+	*/
+	resolve(filePath, currentDir, searchPaths) {
+		const paths = Array.isArray(filePath) ? filePath : [filePath];
+		const bases = [currentDir, ...searchPaths];
+		const resolved = [];
+		for (const candidate of paths) {
+			if (!isBareModuleSpecifier(candidate)) {
+				resolved.push(candidate);
+				continue;
+			}
+			let modulePath = null;
+			for (const base of bases) {
+				modulePath = this.resolvePackage(candidate, base) ?? this.resolvePackage(`${candidate}.less`, base);
+				if (modulePath) break;
+			}
+			modulePath ??= this.resolvePackage(candidate) ?? this.resolvePackage(`${candidate}.less`);
+			resolved.push(modulePath ?? candidate);
+		}
+		return resolved;
+	}
+	/**
 	* Load an npm package module.
 	*
 	* @param packageName - The npm package name (e.g., "less-plugin-clean-css")
@@ -85,7 +113,8 @@ var NodeModulesPlugin = class extends _jesscss_core.AbstractPlugin {
 		const resolvedPath = this.resolvePackage(packageName);
 		if (!resolvedPath) return null;
 		try {
-			return this._require(resolvedPath) || null;
+			const module = this._require(resolvedPath);
+			return isRecord(module) ? module : null;
 		} catch {
 			return null;
 		}
@@ -118,7 +147,9 @@ var NodeModulesPlugin = class extends _jesscss_core.AbstractPlugin {
 	async import(absoluteFilePath) {
 		if (this.opts.enabled === false) throw new Error(`Plugin "${this.name}" cannot import "${absoluteFilePath}" (disabled)`);
 		if (absoluteFilePath.includes("node_modules")) try {
-			return this._require(absoluteFilePath);
+			const module = this._require(absoluteFilePath);
+			if (!isRecord(module)) throw new TypeError(`Module "${absoluteFilePath}" did not export an object.`);
+			return module;
 		} catch (e) {
 			const message = e instanceof Error ? e.message : String(e);
 			throw new Error(`Failed to import "${absoluteFilePath}": ${message}`);
@@ -126,6 +157,12 @@ var NodeModulesPlugin = class extends _jesscss_core.AbstractPlugin {
 		throw new Error(`Plugin "${this.name}" cannot import "${absoluteFilePath}" (not a node_modules path)`);
 	}
 };
+function isBareModuleSpecifier(candidate) {
+	return !node_path.isAbsolute(candidate) && !candidate.startsWith("./") && !candidate.startsWith("../") && !candidate.startsWith("/") && !/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(candidate);
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object";
+}
 const nodeModulesPlugin = ((opts) => {
 	return new NodeModulesPlugin(opts);
 });

package/lib/index.d.ts

@@ -5,6 +5,14 @@ interface NodeModulesPluginOptions {
      * Default: true
      */
     enabled?: boolean;
+    /**
+     * Directory to anchor Node's module resolution at. When set, `require.resolve`
+     * walks `node_modules` starting from this directory (instead of the plugin's own
+     * location). Used to resolve packages relative to a consuming project or a
+     * fixture tree rather than where the plugin is installed.
+     * Default: the plugin file's directory (falling back to `process.cwd()`).
+     */
+    basePath?: string;
 }
 export type { NodeModulesPluginOptions };
 /**
@@ -26,9 +34,18 @@ export declare class NodeModulesPlugin extends AbstractPlugin {
      * Uses Node's module resolution algorithm (same as require.resolve).
      *
      * @param packageName - The npm package name (e.g., "less-plugin-clean-css")
+     * @param fromDir - Optional directory to start `node_modules` resolution from
+     *   (walked up per Node's algorithm). When given it takes precedence over the
+     *   plugin's `basePath`; used to resolve a package relative to the importing
+     *   file (e.g. an `@import "pkg/x"` resolving against the importer's directory).
      * @returns The absolute path to the package, or null if not found
      */
-    resolvePackage(packageName: string): string | null;
+    resolvePackage(packageName: string, fromDir?: string): string | null;
+    /**
+     * Context resolution hook for bare package specifiers. Core owns only the
+     * resolver-plugin pipeline; this plugin owns Node's module-resolution policy.
+     */
+    resolve(filePath: string | string[], currentDir: string, searchPaths: string[]): string[];
     /**
      * Load an npm package module.
      *

package/lib/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAGL,cAAc,EACf,MAAM,eAAe,CAAC;AAKvB,UAAU,wBAAwB;IAChC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;CACnB;AAED,YAAY,EAAE,wBAAwB,EAAE,CAAC;AAEzC;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,SAAQ,cAAc;IAKhC,IAAI,EAAE,wBAAwB;IAJjD,IAAI,SAAkB;IAEtB,OAAO,CAAC,QAAQ,CAAc;gBAEX,IAAI,GAAE,wBAA6B;IA8BtD;;;;;;OAMG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAoBlD;;;;;OAKG;IACG,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAiB3E;;;;;;;OAOG;IACG,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IAU/G;;;;;;OAMG;IACG,MAAM,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAoBrE;AAED,QAAA,MAAM,iBAAiB,UAAY,wBAAwB,sBAExC,CAAC;AAEpB,eAAe,iBAAiB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,cAAc,EACf,MAAM,eAAe,CAAC;AAKvB,UAAU,wBAAwB;IAChC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;;OAMG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,YAAY,EAAE,wBAAwB,EAAE,CAAC;AAEzC;;;;;;;;GAQG;AACH,qBAAa,iBAAkB,SAAQ,cAAc;IAKhC,IAAI,EAAE,wBAAwB;IAJjD,IAAI,SAAkB;IAEtB,OAAO,CAAC,QAAQ,CAAc;gBAEX,IAAI,GAAE,wBAA6B;IAkCtD;;;;;;;;;;OAUG;IACH,cAAc,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAsBpE;;;OAGG;IACM,OAAO,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,EAAE,EAAE,UAAU,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,GAAG,MAAM,EAAE;IAyBlG;;;;;OAKG;IACG,WAAW,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,GAAG,IAAI,CAAC;IAiB3E;;;;;;;OAOG;IACG,kBAAkB,CAAC,YAAY,EAAE,MAAM,EAAE,GAAG,OAAO,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAA;KAAE,GAAG,IAAI,CAAC;IAU/G;;;;;;OAMG;IACG,MAAM,CAAC,gBAAgB,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC;CAuBrE;AAcD,QAAA,MAAM,iBAAiB,UAAY,wBAAwB,sBAExC,CAAC;AAEpB,eAAe,iBAAiB,CAAC"}

package/lib/index.js

@@ -23,7 +23,8 @@ var NodeModulesPlugin = class extends AbstractPlugin {
 		this.opts = opts;
 		try {
 			let currentDir;
-			if (typeof __filename !== "undefined") currentDir = path.dirname(__filename);
+			if (opts.basePath !== void 0) currentDir = opts.basePath;
+			else if (typeof __filename !== "undefined") currentDir = path.dirname(__filename);
 			else try {
 				const url = import.meta.url;
 				currentDir = path.dirname(fileURLToPath(url));
@@ -40,18 +41,45 @@ var NodeModulesPlugin = class extends AbstractPlugin {
 	* Uses Node's module resolution algorithm (same as require.resolve).
 	*
 	* @param packageName - The npm package name (e.g., "less-plugin-clean-css")
+	* @param fromDir - Optional directory to start `node_modules` resolution from
+	*   (walked up per Node's algorithm). When given it takes precedence over the
+	*   plugin's `basePath`; used to resolve a package relative to the importing
+	*   file (e.g. an `@import "pkg/x"` resolving against the importer's directory).
 	* @returns The absolute path to the package, or null if not found
 	*/
-	resolvePackage(packageName) {
+	resolvePackage(packageName, fromDir) {
 		if (this.opts.enabled === false) return null;
 		try {
-			return this._require.resolve(packageName);
+			return fromDir !== void 0 ? this._require.resolve(packageName, { paths: [fromDir] }) : this._require.resolve(packageName);
 		} catch (e) {
-			if (e.code === "MODULE_NOT_FOUND") return null;
+			if (e instanceof Error && e.code === "MODULE_NOT_FOUND") return null;
 			throw e;
 		}
 	}
 	/**
+	* Context resolution hook for bare package specifiers. Core owns only the
+	* resolver-plugin pipeline; this plugin owns Node's module-resolution policy.
+	*/
+	resolve(filePath, currentDir, searchPaths) {
+		const paths = Array.isArray(filePath) ? filePath : [filePath];
+		const bases = [currentDir, ...searchPaths];
+		const resolved = [];
+		for (const candidate of paths) {
+			if (!isBareModuleSpecifier(candidate)) {
+				resolved.push(candidate);
+				continue;
+			}
+			let modulePath = null;
+			for (const base of bases) {
+				modulePath = this.resolvePackage(candidate, base) ?? this.resolvePackage(`${candidate}.less`, base);
+				if (modulePath) break;
+			}
+			modulePath ??= this.resolvePackage(candidate) ?? this.resolvePackage(`${candidate}.less`);
+			resolved.push(modulePath ?? candidate);
+		}
+		return resolved;
+	}
+	/**
 	* Load an npm package module.
 	*
 	* @param packageName - The npm package name (e.g., "less-plugin-clean-css")
@@ -61,7 +89,8 @@ var NodeModulesPlugin = class extends AbstractPlugin {
 		const resolvedPath = this.resolvePackage(packageName);
 		if (!resolvedPath) return null;
 		try {
-			return this._require(resolvedPath) || null;
+			const module = this._require(resolvedPath);
+			return isRecord(module) ? module : null;
 		} catch {
 			return null;
 		}
@@ -94,7 +123,9 @@ var NodeModulesPlugin = class extends AbstractPlugin {
 	async import(absoluteFilePath) {
 		if (this.opts.enabled === false) throw new Error(`Plugin "${this.name}" cannot import "${absoluteFilePath}" (disabled)`);
 		if (absoluteFilePath.includes("node_modules")) try {
-			return this._require(absoluteFilePath);
+			const module = this._require(absoluteFilePath);
+			if (!isRecord(module)) throw new TypeError(`Module "${absoluteFilePath}" did not export an object.`);
+			return module;
 		} catch (e) {
 			const message = e instanceof Error ? e.message : String(e);
 			throw new Error(`Failed to import "${absoluteFilePath}": ${message}`);
@@ -102,6 +133,12 @@ var NodeModulesPlugin = class extends AbstractPlugin {
 		throw new Error(`Plugin "${this.name}" cannot import "${absoluteFilePath}" (not a node_modules path)`);
 	}
 };
+function isBareModuleSpecifier(candidate) {
+	return !path.isAbsolute(candidate) && !candidate.startsWith("./") && !candidate.startsWith("../") && !candidate.startsWith("/") && !/^[a-zA-Z][a-zA-Z0-9+.-]*:/.test(candidate);
+}
+function isRecord(value) {
+	return value !== null && typeof value === "object";
+}
 const nodeModulesPlugin = ((opts) => {
 	return new NodeModulesPlugin(opts);
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jesscss/plugin-node-modules",
-  "version": "2.0.0-alpha.7",
+  "version": "2.0.0-alpha.9",
   "description": "Jess plugin for resolving and loading npm packages from node_modules",
   "main": "lib/index.cjs",
   "types": "lib/index.d.ts",
@@ -16,7 +16,7 @@
     "lib"
   ],
   "dependencies": {
-    "@jesscss/core": "2.0.0-alpha.7"
+    "@jesscss/core": "2.0.0-alpha.9"
   },
   "devDependencies": {
     "@types/node": "^20.0.0",