less 5.0.0-alpha.1 → 5.0.0-alpha.11

package/dist/less-node.cjs

@@ -1,5 +1,5 @@
 /**
- * Less - Leaner CSS v5.0.0-alpha.1
+ * Less - Leaner CSS v5.0.0-alpha.11
  * http://lesscss.org
  *
  * Copyright (c) 2009-2026, Alexis Sellier <self@cloudhead.net>
@@ -18,8 +18,8 @@ var compiler = require('@jesscss/compiler');
 var nodeModulesPlugin = require('@jesscss/plugin-node-modules');
 var lessPlugin = require('@jesscss/plugin-less');
 var pluginLessCompat = require('@jesscss/plugin-less-compat');
-var parseNodeVersion = require('parse-node-version');
 var core = require('@jesscss/core');
+var parseNodeVersion = require('parse-node-version');
 
 function _interopDefaultLegacy (e) { return e && typeof e === 'object' && 'default' in e ? e : { 'default': e }; }
 
@@ -27,31 +27,94 @@ var nodeModulesPlugin__default = /*#__PURE__*/_interopDefaultLegacy(nodeModulesP
 var lessPlugin__default = /*#__PURE__*/_interopDefaultLegacy(lessPlugin);
 var parseNodeVersion__default = /*#__PURE__*/_interopDefaultLegacy(parseNodeVersion);
 
+/**
+ * Less logger wired to Jess's logger singleton.
+ * Forwards to Jess and maintains Less-style addListener/removeListener for compatibility.
+ * @module less/lib/logger
+ */
+
+/** @typedef {{ error?: (msg: string) => void, warn?: (msg: string) => void, info?: (msg: string) => void, debug?: (msg: string) => void }} LogListener */
+
+/** @type {LogListener[]} */
+const _listeners = [];
+
+/** @param {'error'|'warn'|'info'|'debug'} type @param {string} msg */
+function _fireEvent(type, msg) {
+  for (const listener of _listeners) {
+    const fn = listener[type];
+    if (fn) fn(msg);
+  }
+}
+
+// Wrap Jess's logger so Less listeners receive Jess's log output without
+// writing directly to stderr/stdout. Library consumers should be able to catch
+// `less.render()` rejections without surprise terminal output; the CLI owns
+// deciding whether/how to print diagnostics.
+core.logger.configure?.({
+  log(...args) {
+    _fireEvent('debug', args.map(String).join(' '));
+  },
+  info(...args) {
+    _fireEvent('info', args.map(String).join(' '));
+  },
+  warn(...args) {
+    _fireEvent('warn', args.map(String).join(' '));
+  },
+  error(...args) {
+    _fireEvent('error', args.map(String).join(' '));
+  },
+});
+
+/** Less-compatible logger backed by Jess's singleton */
+const logger = {
+  /** @param {string} msg */
+  error(msg) {
+    _fireEvent('error', msg);
+  },
+
+  /** @param {string} msg */
+  warn(msg) {
+    _fireEvent('warn', msg);
+  },
+
+  /** @param {string} msg */
+  info(msg) {
+    _fireEvent('info', msg);
+  },
+
+  /** @param {string} msg */
+  debug(msg) {
+    _fireEvent('debug', msg);
+  },
+
+  /** @param {LogListener} listener */
+  addListener(listener) {
+    _listeners.push(listener);
+  },
+
+  /** @param {LogListener} listener */
+  removeListener(listener) {
+    const i = _listeners.indexOf(listener);
+    if (i >= 0) _listeners.splice(i, 1);
+  },
+};
+
 /**
  * Options mapping between Less render options and Jess compiler config.
  * @module less/lib/options
  */
 
 const unsupportedAlphaOptions = new Map([
-  ['sourceMap', 'source maps are not supported'],
-  ['sourceMapFilename', 'source maps are not supported'],
-  ['sourceMapRootpath', 'source maps are not supported'],
-  ['sourceMapBasepath', 'source maps are not supported'],
-  ['sourceMapURL', 'source maps are not supported'],
-  ['sourceMapFileInline', 'source maps are not supported'],
   ['globalVars', 'global variable injection is not supported'],
   ['modifyVars', 'modify-var injection is not supported'],
-  ['strictUnits', 'strict unit mode is not supported'],
-  ['rootpath', 'URL rootpath rewriting is not supported'],
-  ['rewriteUrls', 'URL rewriting is not supported'],
-  ['urlArgs', 'URL argument rewriting is not supported'],
   ['javascriptEnabled', 'JavaScript evaluation is not supported'],
-  ['compress', 'compressed output is not supported'],
 ]);
 
 function validateAlphaOptions(options) {
   for (const [name, reason] of unsupportedAlphaOptions) {
-    if (Object.prototype.hasOwnProperty.call(options, name)) {
+    // A falsy value is the 4.x default ("off") and requests nothing, so it is
+    // a no-op here; only an actual request for the feature is unsupported.
+    if (options[name]) {
       throw new Error(`${name} is not supported: ${reason}`);
     }
   }
@@ -88,6 +151,55 @@ function stableStringify(value, seen = new WeakSet()) {
   return `{${entries.join(',')}}`;
 }
 
+/**
+ * `collapseNesting` accepts `false` (keep authored nesting — the v5 default),
+ * `'native'` (CSS Nesting desugaring: parent wrapped in `:is()`, child selector
+ * lists distributed, specificity-faithful), `'compact'` (like `'native'` but
+ * also folds same-combinator descendant runs into one `:is()`), or the
+ * deprecated boolean `true` (alias for `'native'`). Anything else is rejected.
+ * @param {unknown} value
+ * @returns {boolean|'native'|'compact'}
+ */
+function resolveCollapseNesting(value) {
+  if (value === false || value === true || value === 'native' || value === 'compact') {
+    return value;
+  }
+  throw new Error(
+    `collapseNesting must be false, 'native', 'compact', or true `
+    + `(deprecated alias for 'native'); got ${JSON.stringify(value)}`
+  );
+}
+
+/**
+ * Build the compiler's `output.sourceMap` value from Less options. Source maps
+ * are enabled when `sourceMap` is truthy; the object form (or the flat legacy
+ * `sourceMap*` options) configures the details. Returns `undefined` when no
+ * source map is requested.
+ * @param {import('./options.js').LessRenderOptions} opts
+ * @returns {undefined | true | Record<string, unknown>}
+ */
+function resolveSourceMap(opts) {
+  if (!opts.sourceMap) {
+    return undefined;
+  }
+  const config = (typeof opts.sourceMap === 'object' && opts.sourceMap !== null)
+    ? { ...opts.sourceMap }
+    : {};
+  // Fold the flat legacy `sourceMap*` options into the object form the compiler
+  // reads; an explicit object sub-option wins over its flat alias.
+  const flat = [
+    'sourceMapURL', 'sourceMapFilename', 'sourceMapFullFilename',
+    'sourceMapRootpath', 'sourceMapBasepath', 'sourceMapFileInline',
+    'sourceMapOutputFilename', 'outputSourceFiles', 'disableSourcemapAnnotation'
+  ];
+  for (const key of flat) {
+    if (opts[key] !== undefined && config[key] === undefined) {
+      config[key] = opts[key];
+    }
+  }
+  return Object.keys(config).length > 0 ? config : true;
+}
+
 /**
  * Map Less render options to Jess compiler config.
  * @param {import('./options.js').LessRenderOptions} [options] Less-style options
@@ -107,26 +219,60 @@ function createLessOptions(options) {
     math === 2 || math === 'parens' || math === 'strict' ? 'parens' :
     'parens-division';
 
-  const plugins = [lessPlugin__default["default"]()];
+  // `unitMode` is the option ('loose' | 'preserve' | 'strict'); `strictUnits`
+  // is its deprecated boolean alias: true → 'strict'; false means "not strict",
+  // i.e. the default ('preserve') — never the Less 4.x 'loose' fold, which only
+  // an explicit `unitMode: 'loose'` selects. Any use warns so the mapping is
+  // never discovered by staring at output. Left unset so the compiler default applies.
+  const unitMode = opts.unitMode !== undefined ? opts.unitMode
+    : opts.strictUnits === true ? 'strict'
+    : undefined;
+  if (opts.strictUnits !== undefined && opts.unitMode === undefined) {
+    logger.warn(
+      `strictUnits is deprecated; use unitMode. strictUnits: ${String(opts.strictUnits)} now means `
+      + `unitMode: '${unitMode ?? 'preserve'}'${opts.strictUnits ? '' : " (Less 4.x unit folding is unitMode: 'loose')"}`
+    );
+  }
+
+  // URL rewriting lives on the Less plugin (it rewrites `url(...)` during
+  // serialization), not in `output`. Only forward keys the caller set so the
+  // plugin's own v5 defaults apply otherwise.
+  const lessPluginOptions = {};
+  if (opts.rootpath !== undefined) lessPluginOptions.rootpath = opts.rootpath;
+  if (opts.rewriteUrls !== undefined) lessPluginOptions.rewriteUrls = opts.rewriteUrls;
+  if (opts.urlArgs !== undefined) lessPluginOptions.urlArgs = opts.urlArgs;
+
+  const plugins = [lessPlugin__default["default"](lessPluginOptions)];
   if (!skipLessCompat) {
     plugins.push(pluginLessCompat.lessCompatPlugin({ plugins: lessPlugins }));
   }
 
+  // The projection/serialization options the compiler reads off `output`:
+  // `collapseNesting` (nesting flatten mode), `compress` (minified output), and
+  // `sourceMap`. Emitted as a single file-less array entry so an explicit render
+  // option overrides a file-local styles.config for every key (the config merge
+  // appends it as the override default); left `{}` when the caller set none.
+  const outputEntry = {};
+  if (opts.collapseNesting !== undefined) {
+    outputEntry.collapseNesting = resolveCollapseNesting(opts.collapseNesting);
+  }
+  if (opts.compress !== undefined) {
+    outputEntry.compress = opts.compress;
+  }
+  const sourceMap = resolveSourceMap(opts);
+  if (sourceMap !== undefined) {
+    outputEntry.sourceMap = sourceMap;
+  }
+  const output = Object.keys(outputEntry).length > 0 ? [outputEntry] : {};
+
   const configOptions = {
     compile: {
       searchPaths: opts.paths || [],
       mathMode,
+      ...(unitMode !== undefined && { unitMode }),
       plugins,
     },
-    // Less v5 preserves authored nesting unless its explicit compatibility
-    // switch requests flattened CSS. Keep that public Less option at the
-    // wrapper boundary; Jess owns the one renderer and its output mode.
-    // A file's styles.config may use an output array. A file-less output entry
-    // is the compiler's documented per-render override for that shape, so an
-    // explicit public Less option remains authoritative over fixture config.
-    output: Object.prototype.hasOwnProperty.call(opts, 'collapseNesting')
-      ? [{ collapseNesting: opts.collapseNesting === true }]
-      : {},
+    output,
     language: {},
   };
 
@@ -154,6 +300,13 @@ function mapRenderResult(result, options) {
     css: result.css ?? '',
   };
 
+  // Less 4.x returns the source map as `result.map` (a JSON string) when one was
+  // requested; forward it so `less.render(src, { sourceMap: true })` behaves the
+  // same. The compiler writes the `sourceMappingURL` annotation into `css` itself.
+  if (result.map !== undefined) {
+    out.map = result.map;
+  }
+
   if (result.imports && Array.isArray(result.imports)) {
     out.imports = result.imports;
   }
@@ -172,7 +325,7 @@ function mapRenderResult(result, options) {
  * @module less/lib/version
  */
 
-const semver = "5.0.0-alpha.1";
+const semver = "5.0.0-alpha.11";
 const parsed = parseNodeVersion__default["default"](`v${semver}`);
 
 const version = {
@@ -180,78 +333,6 @@ const version = {
   array: [parsed.major, parsed.minor, parsed.patch],
 };
 
-/**
- * Less logger wired to Jess's logger singleton.
- * Forwards to Jess and maintains Less-style addListener/removeListener for compatibility.
- * @module less/lib/logger
- */
-
-/** @typedef {{ error?: (msg: string) => void, warn?: (msg: string) => void, info?: (msg: string) => void, debug?: (msg: string) => void }} LogListener */
-
-/** @type {LogListener[]} */
-const _listeners = [];
-
-/** @param {'error'|'warn'|'info'|'debug'} type @param {string} msg */
-function _fireEvent(type, msg) {
-  for (const listener of _listeners) {
-    const fn = listener[type];
-    if (fn) fn(msg);
-  }
-}
-
-// Wrap Jess's logger so Less listeners receive Jess's log output without
-// writing directly to stderr/stdout. Library consumers should be able to catch
-// `less.render()` rejections without surprise terminal output; the CLI owns
-// deciding whether/how to print diagnostics.
-core.logger.configure?.({
-  log(...args) {
-    _fireEvent('debug', args.map(String).join(' '));
-  },
-  info(...args) {
-    _fireEvent('info', args.map(String).join(' '));
-  },
-  warn(...args) {
-    _fireEvent('warn', args.map(String).join(' '));
-  },
-  error(...args) {
-    _fireEvent('error', args.map(String).join(' '));
-  },
-});
-
-/** Less-compatible logger backed by Jess's singleton */
-const logger = {
-  /** @param {string} msg */
-  error(msg) {
-    _fireEvent('error', msg);
-  },
-
-  /** @param {string} msg */
-  warn(msg) {
-    _fireEvent('warn', msg);
-  },
-
-  /** @param {string} msg */
-  info(msg) {
-    _fireEvent('info', msg);
-  },
-
-  /** @param {string} msg */
-  debug(msg) {
-    _fireEvent('debug', msg);
-  },
-
-  /** @param {LogListener} listener */
-  addListener(listener) {
-    _listeners.push(listener);
-  },
-
-  /** @param {LogListener} listener */
-  removeListener(listener) {
-    const i = _listeners.indexOf(listener);
-    if (i >= 0) _listeners.splice(i, 1);
-  },
-};
-
 /**
  * Helper functions for lessc CLI.
  * Adapted from lib.bak/less-node/lessc-helper.js.
@@ -291,11 +372,23 @@ const lesscHelper = {
     console.log('  --quiet                      Suppresses output of warnings.');
     console.log('  -v, --version                Prints version number and exit.');
     console.log('  --verbose                    Be verbose.');
-    console.log('  --collapse-nesting           Flatten nested rules after preserving source-order cascade.');
+    console.log('  --collapse-nesting[=MODE]    Flatten nested rules: native (default), or compact.');
+    console.log('  -x, --compress               Compress output by removing whitespace.');
+    console.log('  --math=MODE                  Math mode: parens-division (default), always, or parens.');
+    console.log('  --unit-mode=MODE             Unit handling in math: preserve (default), strict, or loose (Less 4.x guessing).');
+    console.log('  --strict-units[=on|off]      Deprecated: on is --unit-mode=strict, off is the default (preserve).');
+    console.log('  --source-map[=FILE]          Emit a source map (FILE, or <destination>.map by default).');
+    console.log('  --source-map-inline          Embed the source map as a data URI instead of a file.');
+    console.log('  --source-map-include-source  Embed the source files in the map (sourcesContent).');
+    console.log('  --source-map-rootpath=PATH   Prepend PATH to every source in the map.');
+    console.log('  --source-map-basepath=PATH   Strip PATH from the front of every source in the map.');
+    console.log('  --source-map-url=URL         Override the sourceMappingURL annotation.');
+    console.log('  --rewrite-urls[=all|local|off]  Rewrite url(...) references in imported files.');
+    console.log('  --rootpath=PATH              Prepend PATH to url(...) and import references.');
+    console.log('  --url-args=ARGS             Append ARGS (e.g. cache-buster) to every url(...).');
     console.log('');
     console.log('This release intentionally supports a smaller CLI surface.');
-    console.log('Source maps, browser compilation, legacy plugin flags, lint-only mode, and');
-    console.log('URL rewrite flags will be revisited in later alphas.');
+    console.log('Browser compilation, legacy plugin flags, and lint-only mode are not supported.');
     console.log('');
     console.log('Report bugs to: http://github.com/less/less.js/issues');
     console.log('Home page: <http://lesscss.org/>');

package/lib/browser-dev.js

@@ -0,0 +1,86 @@
+/**
+ * Less.js v5 — browser build (powered by Jess).
+ *
+ * A single-file, in-browser Less→CSS compiler. It drives `@jesscss/compiler`'s
+ * `renderToResult` with an inline `source` and NO `filePath`, so the Node-only
+ * config-discovery layer (cosmiconfig/env-paths/fs) is never reached. `@import`
+ * / file access is unsupported here (see build/browser-stubs/fs.js).
+ *
+ * Bundled to an IIFE that defines `window.less` with the same public shape as
+ * the Less 4.x browser build: `less.render(input, options?, callback?)` returns
+ * a Promise and also invokes the err-first callback when one is given.
+ *
+ * @module less/browser-dev
+ */
+
+import { Compiler } from '@jesscss/compiler';
+import { createLessOptions, mapRenderResult } from './options.js';
+
+/* Injected at build time from packages/less/package.json. */
+/* global __LESS_VERSION__ */
+const semver = typeof __LESS_VERSION__ === 'string' ? __LESS_VERSION__ : '5.0.0-alpha.0';
+const versionArray = semver.split('.').map((n) => parseInt(n, 10) || 0).slice(0, 3);
+
+/**
+ * Build a Less-4.x-shaped error from the first Jess diagnostic. No fs fallback:
+ * in the browser there is no file to re-read for the source extract.
+ * @param {import('./options.js').JessRenderResult} result
+ */
+function createRenderError(result) {
+  const diagnostic = (result?.errors || [])[0];
+  const error = new Error(diagnostic?.message || 'Less render failed');
+  error.type = diagnostic?.phase || 'Syntax';
+  error.filename = diagnostic?.filePath || 'input';
+  error.line = diagnostic?.line || 1;
+  error.column = diagnostic?.column || 1;
+  const lines = diagnostic?.lines;
+  error.extract = Array.isArray(lines) ? lines.map(String) : undefined;
+  error.jessErrors = result?.errors || [];
+  error.jessWarnings = result?.warnings || [];
+  return error;
+}
+
+/**
+ * Render Less source to CSS. Mirrors the Less 4.x API: `options` and `callback`
+ * are both optional, `callback` may be passed as the second argument, and the
+ * returned Promise resolves to a `{ css, warnings }` result. When a callback is
+ * given it is invoked err-first and the Promise is still returned.
+ * @param {string} input Less source
+ * @param {object|Function} [options] Less-style options (math, collapseNesting, plugins) — or the callback
+ * @param {Function} [callback] err-first `(error, result)` callback
+ * @returns {Promise<{ css: string, warnings?: unknown[] }>}
+ */
+function render(input, options, callback) {
+  if (typeof options === 'function') {
+    callback = options;
+    options = {};
+  }
+  options = options || {};
+  const promise = (async () => {
+    const { configOptions } = createLessOptions(options);
+    // ponytail: fresh Compiler per call — no defaultPlugins hook, so no
+    // node-modules import plugin and no @jesscss/plugin-js. Single-file preview
+    // rarely re-renders in a hot loop; a cache map is not worth the surface.
+    const compiler = new Compiler(configOptions);
+    const result = await compiler.renderToResult(
+      { source: input, language: 'less', extension: '.less' },
+      { ...configOptions, suppressWarnings: true }
+    );
+    if (result.errors?.length) {
+      throw createRenderError(result);
+    }
+    return mapRenderResult(result, options);
+  })();
+  if (typeof callback === 'function') {
+    promise.then((result) => callback(null, result), (error) => callback(error));
+  }
+  return promise;
+}
+
+const less = {
+  version: versionArray,
+  render,
+};
+
+export default less;
+export { render, versionArray as version };

package/lib/lessc-helper.js

@@ -37,11 +37,23 @@ const lesscHelper = {
     console.log('  --quiet                      Suppresses output of warnings.');
     console.log('  -v, --version                Prints version number and exit.');
     console.log('  --verbose                    Be verbose.');
-    console.log('  --collapse-nesting           Flatten nested rules after preserving source-order cascade.');
+    console.log('  --collapse-nesting[=MODE]    Flatten nested rules: native (default), or compact.');
+    console.log('  -x, --compress               Compress output by removing whitespace.');
+    console.log('  --math=MODE                  Math mode: parens-division (default), always, or parens.');
+    console.log('  --unit-mode=MODE             Unit handling in math: preserve (default), strict, or loose (Less 4.x guessing).');
+    console.log('  --strict-units[=on|off]      Deprecated: on is --unit-mode=strict, off is the default (preserve).');
+    console.log('  --source-map[=FILE]          Emit a source map (FILE, or <destination>.map by default).');
+    console.log('  --source-map-inline          Embed the source map as a data URI instead of a file.');
+    console.log('  --source-map-include-source  Embed the source files in the map (sourcesContent).');
+    console.log('  --source-map-rootpath=PATH   Prepend PATH to every source in the map.');
+    console.log('  --source-map-basepath=PATH   Strip PATH from the front of every source in the map.');
+    console.log('  --source-map-url=URL         Override the sourceMappingURL annotation.');
+    console.log('  --rewrite-urls[=all|local|off]  Rewrite url(...) references in imported files.');
+    console.log('  --rootpath=PATH              Prepend PATH to url(...) and import references.');
+    console.log('  --url-args=ARGS             Append ARGS (e.g. cache-buster) to every url(...).');
     console.log('');
     console.log('This release intentionally supports a smaller CLI surface.');
-    console.log('Source maps, browser compilation, legacy plugin flags, lint-only mode, and');
-    console.log('URL rewrite flags will be revisited in later alphas.');
+    console.log('Browser compilation, legacy plugin flags, and lint-only mode are not supported.');
     console.log('');
     console.log('Report bugs to: http://github.com/less/less.js/issues');
     console.log('Home page: <http://lesscss.org/>');

package/lib/options.d.ts

@@ -13,10 +13,46 @@ export interface LessRenderOptions {
   plugins?: unknown[];
   math?: number | 'always' | 'parens-division' | 'parens' | 'strict';
   /**
-   * Opt into Less 4-style flattened output. Less v5 preserves authored nesting
-   * by default.
+   * How to flatten authored nesting. Less v5 preserves authored nesting by
+   * default (`false`). `'native'` applies the CSS Nesting desugaring (parent
+   * wrapped in `:is()`, child selector lists distributed — specificity-faithful,
+   * matching the browser and Less 4.x); `'compact'` additionally folds
+   * same-combinator descendant runs into a single `:is()`. `true` is a
+   * deprecated alias for `'native'`.
    */
-  collapseNesting?: boolean;
+  collapseNesting?: boolean | 'native' | 'compact';
+  /** Minified output. */
+  compress?: boolean;
+  /** Prepend a path to every rewritten `url(...)` and imported reference. */
+  rootpath?: string;
+  /** Rewrite relative `url(...)` against the importing file: `'all'` | `'local'` | `'off'` (or boolean). */
+  rewriteUrls?: boolean | 'all' | 'local' | 'off';
+  /** Append a query string to every non-data `url(...)`. */
+  urlArgs?: string;
+  /**
+   * Emit a source map. `true` turns it on with defaults; the object form (or the
+   * flat legacy `sourceMap*` options) configures it. Returned as `result.map`.
+   */
+  sourceMap?: boolean | {
+    sourceMapURL?: string;
+    sourceMapFilename?: string;
+    sourceMapFullFilename?: string;
+    sourceMapRootpath?: string;
+    sourceMapBasepath?: string;
+    sourceMapFileInline?: boolean;
+    sourceMapOutputFilename?: string;
+    outputSourceFiles?: boolean;
+    disableSourcemapAnnotation?: boolean;
+  };
+  sourceMapURL?: string;
+  sourceMapFilename?: string;
+  sourceMapFullFilename?: string;
+  sourceMapRootpath?: string;
+  sourceMapBasepath?: string;
+  sourceMapFileInline?: boolean;
+  sourceMapOutputFilename?: string;
+  outputSourceFiles?: boolean;
+  disableSourcemapAnnotation?: boolean;
   /** @internal Jess alpha benchmark-only flag for source graphs already proven @plugin-free. */
   __jessSkipLessCompatWhenPluginFree?: boolean;
 }