@jesscss/plugin-less-compat 2.0.0-alpha.1 → 2.0.0-alpha.11

package/README.md

@@ -1,139 +1,74 @@
 # @jesscss/plugin-less-compat
 
-Less.js compatibility layer for Jess. This plugin enables Less.js plugins and visitors to work seamlessly with Jess-compiled stylesheets by providing bidirectional transformation between Jess AST nodes and Less.js AST nodes.
+**A Less compatibility bridge for Jess.**
 
-## ⚠️ Experimental Status
+[Jess](https://github.com/jesscss/jess) accepts typed AST-v2 `Fn` values here
+and provides the shared Jess-owned bridge for Less-style plugin function
+registration and Less-shaped function values.
 
-**This package is experimental and largely LLM-generated.** It was created to explore compatibility between Jess and Less.js plugins, but:
+The public compiler does **not** support Less 4 visitors, post-processors, file
+manager plugins, or a full Less tree AST adapter.
 
-- **No long-term maintenance commitment**: This package is unlikely to be actively maintained in the future
-- **Use at your own risk**: While it may work for some use cases, it has not been thoroughly tested across all Less.js plugins
-- **Breaking changes likely**: The API and implementation may change or be removed without notice
-- **Not production-ready**: This is an experimental exploration, not a production-grade compatibility layer
+## How it works
 
-If you need Less.js plugin compatibility, consider:
-- Using Less.js directly for projects that require extensive Less.js plugin support
-- Contributing improvements if you find this package useful
-- Creating your own compatibility layer tailored to your specific needs
+- **Native functions only** — pass `Fn` values from `@jesscss/core/value`; their
+  bodies receive typed values and `FnCtx` capabilities.
+- **Less plugin function bridge** — pass Less-style plugins with
+  `install(less, manager, functions)` through `plugins`. The bridge supplies a
+  Less-shaped `functions.functionRegistry` and the supported `less.tree`
+  constructor facades, then lazily adapts function arguments and return values at
+  the Jess boundary.
 
-## Features
+For example, migrate a Less `functionRegistry.add('increment', fn)` contribution
+to a typed function and register it through `functions`:
 
-- 🔄 **Bidirectional Transformation**: Convert between Jess and Less AST nodes
-- 🎯 **Lazy Conversion**: Proxy-based lazy conversion for optimal performance
-- 🔌 **Plugin Compatibility**: Use existing Less.js plugins with Jess
-- 🧩 **Visitor Support**: Run Less.js visitors on Jess AST trees
-- 📦 **Type Safe**: Full TypeScript support
+```ts
+import { Compiler } from 'jess';
+import { defineFunction, makeDimension } from '@jesscss/core/value';
+import lessCompatPlugin from '@jesscss/plugin-less-compat';
 
-## Installation
-
-```bash
-pnpm add @jesscss/plugin-less-compat
-```
-
-## Usage
-
-### Basic Usage with Less Plugins
-
-```typescript
-import { Compiler } from '@jesscss/jess';
-import lessPlugin from '@jesscss/plugin-less';
-import { lessCompatPlugin } from '@jesscss/plugin-less-compat';
-import autoprefix from 'less-plugin-autoprefix';
+const increment = defineFunction('increment', {
+  params: [{ kinds: ['Dimension'] }] as const,
+  body: value => makeDimension(value.number + 1, value.unit)
+});
 
 const compiler = new Compiler({
-  plugins: [
-    lessPlugin(),
-    lessCompatPlugin({
-      visitors: [autoprefix]
-    })
-  ]
+  compile: { plugins: [lessCompatPlugin({ functions: [increment] })] }
 });
-
-const result = await compiler.compile('styles.less');
-```
-
-### Advanced: Direct Transformation
-
-```typescript
-import { toLessTree, fromLessTree } from '@jesscss/plugin-less-compat/transform';
-import customLessVisitor from './custom-visitor';
-
-const jessTree = parseJess(source);
-const lessTree = toLessTree(jessTree);
-
-// Apply custom Less visitor
-lessTree.accept(customLessVisitor);
-
-// Convert back to Jess
-const modifiedJessTree = fromLessTree(lessTree);
 ```
 
-### Using with Multiple Less Plugins
+For legacy Less function plugins:
 
-```typescript
-import { lessCompatPlugin } from '@jesscss/plugin-less-compat';
-import autoprefix from 'less-plugin-autoprefix';
-import cleanCSS from 'less-plugin-clean-css';
+```ts
+const legacyPlugin = {
+  install(less, _manager, functions) {
+    functions.add('increment', value =>
+      new less.tree.Dimension(value.value + 1, value.unit)
+    );
+  }
+};
 
 const compiler = new Compiler({
-  plugins: [
-    lessPlugin(),
-    lessCompatPlugin({
-      visitors: [
-        autoprefix,
-        cleanCSS
-      ]
-    })
-  ]
+  compile: { plugins: [lessCompatPlugin({ plugins: [legacyPlugin] })] }
 });
 ```
 
-## Supported Less Plugins
-
-This package has been tested with:
-
-- ✅ `less-plugin-autoprefix` - Automatic vendor prefixing
-- ✅ `less-plugin-clean-css` - CSS minification
-- ✅ `less-plugin-dls` - Design Language System support
-
-Other Less.js plugins should work, but may require additional testing.
-
-## API
-
-### `lessCompatPlugin(options?)`
-
-Creates a Jess plugin that enables Less.js compatibility.
-
-**Options:**
-- `visitors?: LessVisitor[]` - Array of Less.js visitors to apply
-- `cache?: boolean` - Enable conversion caching (default: `true`)
-
-### `toLessTree(jessRules: Rules)`
-
-Converts a Jess `Rules` tree to a Less.js-compatible tree.
-
-### `fromLessTree(lessTree: LessNode)`
-
-Converts a Less.js tree back to a Jess `Rules` tree.
-
-### `toLessNode(jessNode: Node, options?)`
-
-Converts a single Jess node to a Less.js-compatible node.
-
-### `fromLessNode(lessNode: LessNode, options?)`
-
-Converts a single Less.js node back to a Jess node.
-
-## Implementation Status
-
-This package is currently in **alpha**.
-
-Developer notes and historical analyses live in [DESIGN.md](./DESIGN.md) and `_archive/`.
+Less-shaped values are boundary values only. Jess owns their conversion back
+into typed AST-v2 values.
 
-## Contributing
+## Status
 
-Contributions welcome! Please see the main Jess repository for contribution guidelines.
+**Alpha / experimental.** The supported public routes are native function
+contribution and Less plugin function bridging. If you need Less visitors,
+post-processors, file managers, or broad Less tree AST mutation support today,
+use Less.js directly.
 
-## License
+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. Current
+design notes live in [DESIGN.md](./DESIGN.md).
 
-MIT
+- 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

@@ -0,0 +1,342 @@
+Object.defineProperties(exports, {
+	__esModule: { value: true },
+	[Symbol.toStringTag]: { value: "Module" }
+});
+let _jesscss_core = require("@jesscss/core");
+let _jesscss_core_value = require("@jesscss/core/value");
+//#region src/less-api-bridge.ts
+const isThenable = (value) => value !== null && typeof value === "object" && "then" in value && typeof value.then === "function";
+function isLoadedPluginModule(value) {
+	if (typeof value !== "object" || value === null) return false;
+	if (!("functions" in value) || value.functions === void 0) return true;
+	return typeof value.functions === "object" && value.functions !== null && Object.values(value.functions).every((fn) => typeof fn === "function");
+}
+const nativeNil = () => {
+	const nil = {
+		type: "Nil",
+		value: "",
+		eval: () => nil
+	};
+	return nil;
+};
+var LessDimension = class {
+	type = "Dimension";
+	constructor(value, unit = "") {
+		this.value = value;
+		this.unit = unit;
+	}
+	valueOf() {
+		return this.value;
+	}
+};
+var LessQuoted = class {
+	type = "Quoted";
+	constructor(quote, value, escaped = false) {
+		this.quote = quote;
+		this.value = value;
+		this.escaped = escaped;
+	}
+	valueOf() {
+		return this.value;
+	}
+};
+var LessColor = class {
+	type = "Color";
+	value;
+	constructor(rgb, alpha = 1) {
+		this.rgb = rgb;
+		this.alpha = alpha;
+		this.value = typeof rgb === "string" ? rgb.startsWith("#") ? rgb : `#${rgb}` : `rgb(${rgb.join(", ")})`;
+	}
+	valueOf() {
+		return this.value;
+	}
+};
+var LessAnonymous = class {
+	type = "Anonymous";
+	value;
+	constructor(value) {
+		this.value = String(value);
+	}
+	valueOf() {
+		return this.value;
+	}
+};
+var LazyExpression = class {
+	type = "Expression";
+	#value;
+	constructor(source) {
+		this.source = source;
+	}
+	get value() {
+		return this.#value ??= this.source.map(toNativeLessValue);
+	}
+	valueOf() {
+		return (0, _jesscss_core_value.emitValue)(this.source);
+	}
+};
+var LazyValueList = class {
+	type = "Value";
+	#value;
+	constructor(source) {
+		this.source = source;
+	}
+	get value() {
+		return this.#value ??= this.source.value.map(toNativeLessValue);
+	}
+	get separator() {
+		return this.source.sep;
+	}
+	valueOf() {
+		return this.source.bytes;
+	}
+};
+var LazyDetachedDeclaration = class {
+	type = "Declaration";
+	#value;
+	#hasValue = false;
+	constructor(name, source) {
+		this.name = name;
+		this.source = source;
+	}
+	get value() {
+		if (!this.#hasValue) {
+			this.#value = toNativeLessValue(this.source);
+			this.#hasValue = true;
+		}
+		return this.#value;
+	}
+	eval() {
+		return this;
+	}
+};
+var LazyDetachedRuleset = class {
+	type = "Mixin";
+	name = nativeNil();
+	args = nativeNil();
+	#rules;
+	constructor(source) {
+		this.source = source;
+	}
+	get ruleset() {
+		return { rules: this.rules };
+	}
+	get rules() {
+		return this.#rules ??= this.source.rules.map((rule) => new LazyDetachedDeclaration(rule.name, rule.value));
+	}
+	eval() {
+		return this;
+	}
+};
+function isRawSequence(value) {
+	return Array.isArray(value);
+}
+function isPluginDetached(value) {
+	return !isRawSequence(value) && value.type === "DetachedRuleset";
+}
+function toNativeLessValue(value) {
+	if (isRawSequence(value)) return new LazyExpression(value);
+	if (isPluginDetached(value)) return new LazyDetachedRuleset(value);
+	switch (value.type) {
+		case "Dimension": return new LessDimension(value.number, value.unit);
+		case "Quoted": return new LessQuoted(value.quote, value.value, value.escaped);
+		case "Color": return {
+			type: "Color",
+			rgb: value.rgb,
+			alpha: value.alpha,
+			valueOf: () => value.bytes
+		};
+		case "List": return value.sep === "," || value.sep === "/" ? new LazyValueList(value) : new LessAnonymous(value.bytes);
+		default: return new LessAnonymous(value.bytes);
+	}
+}
+function isNativeValue(value) {
+	return value !== null && typeof value === "object" && "bytes" in value && typeof value.bytes === "string";
+}
+function fromNativeLessValue(value) {
+	if (isNativeValue(value)) return value;
+	if (typeof value === "number") return (0, _jesscss_core_value.makeDimension)(value);
+	if (typeof value === "string") return (0, _jesscss_core_value.sniffLiteral)(value);
+	if (value && typeof value === "object") {
+		const candidate = value;
+		if ((candidate.type === "Dimension" || candidate.type === "Num") && typeof candidate.value === "number") return (0, _jesscss_core_value.makeDimension)(candidate.value, typeof candidate.unit === "string" ? candidate.unit : "");
+		if (candidate.type === "Quoted" && typeof candidate.value === "string") return (0, _jesscss_core_value.makeQuoted)(candidate.value, candidate.quote === "'" ? "'" : "\"", candidate.escaped === true);
+		if (candidate.type === "Color") {
+			if (Array.isArray(candidate.rgb)) {
+				const [r = 0, g = 0, b = 0] = candidate.rgb.map(Number);
+				const alpha = typeof candidate.alpha === "number" ? candidate.alpha : 1;
+				return (0, _jesscss_core_value.makeColorRgb)([
+					r,
+					g,
+					b
+				], alpha, _jesscss_core_value.HEX);
+			}
+			if (typeof candidate.rgb === "string") return (0, _jesscss_core_value.sniffLiteral)(candidate.rgb.startsWith("#") ? candidate.rgb : `#${candidate.rgb}`);
+		}
+		if (candidate.type === "Expression" && Array.isArray(candidate.value)) return candidate.value.map(fromNativeLessValue);
+		if (candidate.type === "Value" && Array.isArray(candidate.value)) {
+			const separator = candidate.separator === "/" ? "/" : ",";
+			return (0, _jesscss_core_value.makeList)(candidate.value.map((item) => fromNativeLessValue(item)), separator);
+		}
+		if (typeof candidate.value === "string") return (0, _jesscss_core_value.sniffLiteral)(candidate.value);
+		if (typeof candidate.valueOf === "function") return (0, _jesscss_core_value.sniffLiteral)(String(candidate.valueOf()));
+	}
+	return (0, _jesscss_core_value.makeKeyword)(value == null ? "" : String(value));
+}
+var LessApiBridge = class {
+	less;
+	registry;
+	globalFns;
+	#fns = [];
+	#nativeFns = /* @__PURE__ */ new WeakMap();
+	#contextualFns = /* @__PURE__ */ new WeakMap();
+	#registered = /* @__PURE__ */ new Map();
+	constructor(plugins = []) {
+		this.registry = {
+			add: (name, fn) => {
+				this.addFunction(name, fn);
+			},
+			addMultiple: (functions) => {
+				for (const [name, fn] of Object.entries(functions)) this.registry.add(name, fn);
+			},
+			get: (name) => this.#registered.get(name.toLowerCase())
+		};
+		this.less = {
+			functions: { functionRegistry: this.registry },
+			tree: {
+				Dimension: LessDimension,
+				Quoted: LessQuoted,
+				Color: LessColor,
+				Anonymous: LessAnonymous
+			}
+		};
+		for (const plugin of plugins) plugin.install?.(this.less, void 0, this.registry);
+		this.globalFns = this.#fns;
+	}
+	addFunction(name, fn) {
+		const lowerName = name.toLowerCase();
+		this.#registered.set(lowerName, fn);
+		const adapted = (0, _jesscss_core_value.defineFunction)(lowerName, {
+			variadic: true,
+			params: [],
+			body: (value) => this.invokeNativeFunction(fn, (0, _jesscss_core_value.groupItems)(value))
+		});
+		this.#nativeFns.set(adapted, fn);
+		this.#fns.push(adapted);
+		return adapted;
+	}
+	addContextualFunction(name, fn) {
+		const adapted = (0, _jesscss_core_value.defineFunction)(name.toLowerCase(), {
+			variadic: true,
+			params: [],
+			body: () => {
+				throw new Error(`Less @plugin function "${name}" needs live plugin invocation capabilities; it cannot run through plain function dispatch.`);
+			}
+		});
+		this.#contextualFns.set(adapted, fn);
+		this.#fns.push(adapted);
+		return adapted;
+	}
+	invokeNativeFunction(fn, args) {
+		const result = fn(...args.map(toNativeLessValue));
+		return isThenable(result) ? Promise.resolve(result).then(fromNativeLessValue) : fromNativeLessValue(result);
+	}
+	invokeContextualFunction(fn, args, ctx) {
+		const result = fn(args.map(toNativeLessValue), {
+			lookupVariable: (name) => {
+				const hit = ctx.lookupVariable(name);
+				return hit === null ? null : {
+					value: toNativeLessValue(hit.value),
+					important: hit.important
+				};
+			},
+			callFunction: (name, callArgs) => {
+				const answer = ctx.callFunction(name, callArgs.map(fromNativeLessValue));
+				return answer === void 0 ? void 0 : toNativeLessValue(answer);
+			},
+			currentFileInfo: ctx.currentFileInfo,
+			log: (record) => ctx.log(record),
+			markImportant: () => ctx.markImportant()
+		});
+		return isThenable(result) ? Promise.resolve(result).then(fromNativeLessValue) : fromNativeLessValue(result);
+	}
+	invokeRawFunction(fn, args, ctx) {
+		const contextual = this.#contextualFns.get(fn);
+		if (contextual) return this.invokeContextualFunction(contextual, args, ctx);
+		const native = this.#nativeFns.get(fn);
+		return native ? this.invokeNativeFunction(native, args) : void 0;
+	}
+	createPluginHost(optionsOrLoader) {
+		const loadPluginModule = typeof optionsOrLoader === "function" ? optionsOrLoader : optionsOrLoader?.loadPluginModule;
+		const host = {
+			...this.globalFns.length === 0 ? {} : { globalFns: this.globalFns },
+			invokeRawFunction: (fn, args, ctx) => this.invokeRawFunction(fn, args, ctx)
+		};
+		if (loadPluginModule) host.loadPlugin = (request) => {
+			const loaded = loadPluginModule(request);
+			const addLoaded = (module) => {
+				const functions = isLoadedPluginModule(module) ? module.functions : void 0;
+				if (!functions) return [];
+				return Object.entries(functions).map(([name, fn]) => this.addContextualFunction(name, fn));
+			};
+			return isThenable(loaded) ? Promise.resolve(loaded).then(addLoaded) : addLoaded(loaded);
+		};
+		return host;
+	}
+};
+//#endregion
+//#region src/plugin.ts
+/**
+* Transitional package boundary for applications that previously installed the
+* Less compatibility plugin. It contributes only native AST-v2 `Fn` values.
+*
+* Less 4 visitor hooks, `functionRegistry` callbacks, and `@plugin` script
+* execution were legacy tree-runtime APIs. They are intentionally unsupported
+* on the public AST-v2 compiler route: preserving them would require a second
+* evaluator and Node-to-Less/ Less-to-Node conversion bridge.
+*/
+var LessCompatPlugin = class extends _jesscss_core.AbstractPlugin {
+	name = "less-compat";
+	bridges = /* @__PURE__ */ new WeakMap();
+	constructor(opts = {}) {
+		super();
+		this.opts = opts;
+	}
+	setContext(context) {
+		let bridge = this.bridges.get(context);
+		if (!bridge) {
+			bridge = new LessApiBridge(this.opts.plugins ?? []);
+			this.bridges.set(context, bridge);
+		}
+		const bridgeHost = bridge.createPluginHost(({ specifier, options }) => context.getPluginModule(specifier, options));
+		const functions = this.opts.functions;
+		const host = context.pluginHost;
+		const globalFns = [
+			...host?.globalFns ?? [],
+			...bridgeHost.globalFns ?? [],
+			...functions ?? []
+		];
+		context.pluginHost = {
+			...host,
+			...globalFns.length === 0 ? {} : { globalFns },
+			loadPlugin: bridgeHost.loadPlugin || host?.loadPlugin ? (request) => {
+				const baseLoaded = host?.loadPlugin?.(request);
+				const bridgeLoaded = bridgeHost.loadPlugin?.(request);
+				const merge = (baseFns, bridgeFns) => [...baseFns ?? [], ...bridgeFns ?? []];
+				const baseThenable = baseLoaded && typeof baseLoaded === "object" && "then" in baseLoaded;
+				const bridgeThenable = bridgeLoaded && typeof bridgeLoaded === "object" && "then" in bridgeLoaded;
+				if (baseThenable || bridgeThenable) return Promise.all([baseLoaded ?? [], bridgeLoaded ?? []]).then(([baseFns, bridgeFns]) => merge(baseFns, bridgeFns));
+				return merge(baseLoaded, bridgeLoaded);
+			} : void 0,
+			invokeRawFunction: (fn, args, ctx) => bridgeHost.invokeRawFunction?.(fn, args, ctx) ?? host?.invokeRawFunction?.(fn, args, ctx)
+		};
+	}
+};
+const lessCompatPlugin = (opts) => new LessCompatPlugin(opts);
+//#endregion
+exports.LessApiBridge = LessApiBridge;
+exports.LessCompatPlugin = LessCompatPlugin;
+exports.default = lessCompatPlugin;
+exports.fromNativeLessValue = fromNativeLessValue;
+exports.lessCompatPlugin = lessCompatPlugin;
+exports.toNativeLessValue = toNativeLessValue;

package/lib/index.d.ts

@@ -5,5 +5,5 @@
  * Enables Less.js plugins and visitors to work with Jess AST.
  */
 export { LessCompatPlugin, default as lessCompatPlugin, type LessCompatPluginOptions } from './plugin.js';
-export * from './transform/index.js';
-export { isLessPlugin, isJessPlugin, filterPlugins } from './plugin-utils.js';
+export { LessApiBridge, fromNativeLessValue, toNativeLessValue, type ContextualPluginFunction, type NativeLessApi, type NativeLessFunction, type NativeLessFunctionRegistry, type NativeLessPlugin } from './less-api-bridge.js';
+export { default } from './plugin.js';