less 4.9.1 → 5.0.0-alpha.10

package/lib/options.js

@@ -0,0 +1,227 @@
+/**
+ * Options mapping between Less render options and Jess compiler config.
+ * @module less/lib/options
+ */
+
+import lessPlugin from '@jesscss/plugin-less';
+import { lessCompatPlugin } from '@jesscss/plugin-less-compat';
+import { logger } from './logger.js';
+
+const unsupportedAlphaOptions = new Map([
+  ['globalVars', 'global variable injection is not supported'],
+  ['modifyVars', 'modify-var injection is not supported'],
+  ['javascriptEnabled', 'JavaScript evaluation is not supported'],
+]);
+
+function validateAlphaOptions(options) {
+  for (const [name, reason] of unsupportedAlphaOptions) {
+    // 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}`);
+    }
+  }
+}
+
+/**
+ * @param {any} value
+ * @param {WeakSet<object>} [seen]
+ * @returns {string}
+ */
+function stableStringify(value, seen = new WeakSet()) {
+  if (value == null || typeof value !== 'object') {
+    if (typeof value === 'function') {
+      return JSON.stringify(`[function ${value.name || 'anonymous'}]`);
+    }
+    return JSON.stringify(value);
+  }
+  if (seen.has(value)) {
+    return '"[Circular]"';
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    return `[${value.map((item) => stableStringify(item, seen)).join(',')}]`;
+  }
+  if (value.name && typeof value.name === 'string' && ('install' in value || 'parser' in value || 'opts' in value)) {
+    return stableStringify({
+      plugin: value.name,
+      opts: value.opts || {},
+    }, seen);
+  }
+  const entries = Object.keys(value)
+    .sort()
+    .map((key) => `${JSON.stringify(key)}:${stableStringify(value[key], seen)}`);
+  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
+ * @returns {{ configOptions: object, filePath?: string }}
+ */
+export function createLessOptions(options) {
+  const opts = options || {};
+  validateAlphaOptions(opts);
+  const filePath = opts.filename || undefined;
+  const lessPlugins = Array.isArray(opts.plugins) ? opts.plugins : [];
+  const skipLessCompat =
+    opts.__jessSkipLessCompatWhenPluginFree === true && lessPlugins.length === 0;
+
+  const math = /** @type {number|string|undefined} */ (opts.math);
+  const mathMode =
+    math === 0 || math === 'always' ? 'always' :
+    math === 2 || math === 'parens' || math === 'strict' ? 'parens' :
+    'parens-division';
+
+  // `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(lessPluginOptions)];
+  if (!skipLessCompat) {
+    plugins.push(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,
+    },
+    output,
+    language: {},
+  };
+
+  return { configOptions, filePath };
+}
+
+/**
+ * Stable compiler cache key for a Jess compiler configured from Less options.
+ * @param {object} configOptions Jess compiler config
+ * @returns {string}
+ */
+export function getCompilerCacheKey(configOptions) {
+  return stableStringify(configOptions);
+}
+
+/**
+ * Map Jess render result to Less-style result.
+ * @param {import('./options.js').JessRenderResult} result Jess compiler result
+ * @param {import('./options.js').LessRenderOptions} [options] Original Less options
+ * @returns {import('./options.js').LessRenderResult}
+ */
+export function mapRenderResult(result, options) {
+  const opts = options || {};
+  /** @type {import('./options.js').LessRenderResult} */
+  const out = {
+    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;
+  }
+
+  // Structured Jess warnings (e.g. selector/parentless-ampersand). Exposed so
+  // callers and tests can assert them, mirroring how errors surface.
+  if (result.warnings && Array.isArray(result.warnings)) {
+    out.warnings = result.warnings;
+  }
+
+  return out;
+}
+
+export default { createLessOptions, getCompilerCacheKey, mapRenderResult };

package/lib/types.js

@@ -0,0 +1,20 @@
+/**
+ * JSDoc type definitions for Less.js v5 (Jess wrapper).
+ * @module less/lib/types
+ */
+
+/**
+ * @typedef {import('./options.js').LessRenderResult} LessRenderResult
+ */
+
+/**
+ * @typedef {Object} LessStatic
+ * @property {number[]} version Less-compatible version tuple
+ * @property {function(string, import('./options.js').LessRenderOptions?, function?): Promise<LessRenderResult>} render Render Less to CSS
+ * @property {function(string, import('./options.js').LessRenderOptions?): Promise<LessRenderResult>} renderFile Render Less file to CSS
+ * @property {import('./logger.js').default} logger Logger instance
+ * @property {import('./lessc-helper.js').default} lesscHelper CLI helper
+ * @property {object} Compiler Jess Compiler class
+ */
+
+export {};

package/lib/version.js

@@ -0,0 +1,19 @@
+/**
+ * Version info for Less.js v5 (Jess wrapper).
+ * @module less/lib/version
+ */
+
+import { createRequire } from 'module';
+import parseNodeVersion from 'parse-node-version';
+
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+const semver = pkg.version || '5.0.0-alpha.0';
+const parsed = parseNodeVersion(`v${semver}`);
+
+export const version = {
+  semver,
+  array: [parsed.major, parsed.minor, parsed.patch],
+};
+
+export default version;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "less",
-	"version": "4.9.1",
+	"version": "5.0.0-alpha.10",
 	"description": "Leaner CSS",
 	"homepage": "http://lesscss.org",
 	"author": {
@@ -15,7 +15,7 @@
 	},
 	"repository": {
 		"type": "git",
-		"url": "https://github.com/less/less.js.git"
+		"url": "git+https://github.com/less/less.js.git"
 	},
 	"master": {
 		"url": "https://github.com/less/less.js/blob/master/",
@@ -24,21 +24,17 @@
 	"license": "Apache-2.0",
 	"type": "module",
 	"bin": {
-		"lessc": "./bin/lessc"
+		"lessc": "bin/lessc"
 	},
 	"main": "./dist/less-node.cjs",
 	"exports": {
 		".": {
-			"browser": "./dist/less.cjs",
-			"import": "./lib/less-node/index.js",
+			"import": "./lib/index.js",
 			"require": "./dist/less-node.cjs",
-			"default": "./lib/less-node/index.js"
+			"default": "./lib/index.js"
 		},
 		"./lib/*": "./lib/*",
-		"./dist/less-node.cjs": "./dist/less-node.cjs",
-		"./dist/less.cjs": "./dist/less.cjs",
-		"./dist/less.js": "./dist/less.js",
-		"./dist/less.min.js": "./dist/less.min.js"
+		"./dist/less-node.cjs": "./dist/less-node.cjs"
 	},
 	"directories": {
 		"test": "./test"
@@ -49,32 +45,29 @@
 		"!lib/**/*.map",
 		"dist",
 		"index.cjs",
-		"README.md"
+		"README.md",
+		"V5-STATUS.md"
 	],
-	"browser": "./dist/less.js",
 	"engines": {
-		"node": ">=18"
+		"node": "^20.19.0 || >=22.12.0"
 	},
 	"scripts": {
-		"quicktest": "grunt quicktest",
-		"test": "grunt test",
-		"test:node": "grunt test:node",
-		"test:coverage": "c8 -r lcov -r json-summary -r text-summary -r html --include=\"lib/**/*.js\" --include=\"bin/**/*.js\" --exclude=\"dist/**\" --exclude=\"**/*.test.js\" --exclude=\"**/*.spec.js\" --exclude=\"test/**\" --exclude=\"tmp/**\" --exclude=\"**/abstract-file-manager.js\" --exclude=\"**/abstract-plugin-loader.js\" grunt shell:test && node scripts/coverage-report.js && node scripts/coverage-lines.js",
-		"grunt": "grunt",
+		"quicktest": "npm run test:legacy-node",
+		"test:alpha": "npm run typecheck && npm run build && npm run test:lessc && node test/jess-alpha-fast-path.mjs && node test/alpha-support.mjs && node test/alpha-sourcemaps.mjs && node test/alpha-fixtures.mjs",
+		"test:lessc": "node test/lessc-alpha.mjs",
+		"test": "npm run test:alpha",
+		"test:module": "node test/test-es6.js && node test/test-cjs.cjs",
+		"test:legacy-node": "node test/index.js",
+		"test:node": "npm run test:module",
+		"test:coverage": "c8 -r lcov -r json-summary -r text-summary -r html --include=\"lib/**/*.js\" --include=\"bin/**/*.js\" --exclude=\"dist/**\" --exclude=\"**/*.test.js\" --exclude=\"**/*.spec.js\" --exclude=\"test/**\" --exclude=\"tmp/**\" --exclude=\"**/abstract-file-manager.js\" --exclude=\"**/abstract-plugin-loader.js\" npm run test:legacy-node && node scripts/coverage-report.js && node scripts/coverage-lines.js",
 		"lint": "eslint '**/*.{ts,js}'",
 		"lint:fix": "eslint '**/*.{ts,js}' --fix",
 		"typecheck": "tsc --noEmit",
 		"build": "node build/rollup.js --dist",
-		"prepublishOnly": "npm run typecheck && grunt dist && grunt test:node"
-	},
-	"optionalDependencies": {
-		"errno": "^0.1.1",
-		"graceful-fs": "^4.1.2",
-		"probe-image-size": "^7.2.3",
-		"make-dir": "^5.1.0",
-		"mime": "^1.4.1",
-		"needle": "^3.1.0",
-		"source-map": "~0.6.0"
+		"build:browser": "node build/browser-dev.mjs --minify",
+		"benchmark": "node benchmark/benchmark-runner.cjs",
+		"benchmark:all": "node benchmark/run-and-compare.mjs",
+		"prepublishOnly": "npm run typecheck && npm run build && npm run build:browser && npm run test:lessc"
 	},
 	"devDependencies": {
 		"@less/test-data": "workspace:*",
@@ -92,21 +85,13 @@
 		"chalk": "^4.1.2",
 		"cosmiconfig": "~9.0.0",
 		"cross-env": "^7.0.3",
+		"esbuild": "^0.25.0",
 		"eslint": "^7.29.0",
 		"fs-extra": "^8.1.0",
-		"git-rev": "^0.2.1",
 		"glob": "~11.0.3",
 		"globby": "^10.0.1",
-		"grunt": "^1.5.0",
-		"grunt-cli": "^1.3.2",
-		"grunt-contrib-clean": "^1.0.0",
-		"grunt-contrib-connect": "^1.0.2",
-		"grunt-eslint": "^23.0.0",
-		"grunt-saucelabs": "^9.0.1",
-		"grunt-shell": "^1.3.0",
 		"html-template-tag": "^3.2.0",
 		"jest-diff": "~30.1.2",
-		"jit-grunt": "^0.10.0",
 		"less-plugin-autoprefix": "^1.5.1",
 		"less-plugin-clean-css": "^1.6.0",
 		"minimist": "^1.2.0",
@@ -114,15 +99,14 @@
 		"mocha-teamcity-reporter": "^3.0.0",
 		"npm-run-all": "^4.1.5",
 		"performance-now": "^0.2.0",
-		"phin": "^2.2.3",
 		"playwright": "1.50.1",
 		"promise": "^7.1.1",
 		"read-glob": "^3.0.0",
 		"resolve": "^1.17.0",
 		"rollup": "^2.52.2",
 		"rollup-plugin-terser": "^5.1.1",
+		"semver": "^6.3.0",
 		"shx": "^0.3.2",
-		"time-grunt": "^1.3.0",
 		"typescript": "^5.7.0",
 		"uikit": "2.27.4",
 		"url": "^0.11.4",
@@ -158,8 +142,20 @@
 	"rawcurrent": "https://raw.github.com/less/less.js/v",
 	"sourcearchive": "https://github.com/less/less.js/archive/v",
 	"dependencies": {
-		"copy-anything": "^3.0.5",
+		"@jesscss/compiler": "2.0.0-alpha.23",
+		"@jesscss/core": "2.0.0-alpha.23",
+		"@jesscss/plugin-less": "2.0.0-alpha.23",
+		"@jesscss/plugin-less-compat": "2.0.0-alpha.23",
+		"@jesscss/plugin-node-modules": "2.0.0-alpha.23",
 		"parse-node-version": "^1.0.1"
 	},
+	"peerDependencies": {
+		"@jesscss/plugin-js": "2.0.0-alpha.23"
+	},
+	"peerDependenciesMeta": {
+		"@jesscss/plugin-js": {
+			"optional": true
+		}
+	},
 	"gitHead": "1df9072ee9ebdadc791bf35dfb1dbc3ef9f1948f"
 }