less 5.0.0-alpha.1 → 5.0.0-alpha.10

package/README.md

@@ -13,10 +13,12 @@
 > [!IMPORTANT]
 > This package README is for Less 5 alpha.1. Less 5 is a Jess-powered compiler
 > preview for early testing and is not yet a drop-in replacement for Less 4.x.
-> Alpha.1 focuses on Node.js `less.render()`, `less.renderFile()`, `lessc`,
-> variables, arithmetic, mixins, sibling file imports, and nested-rule output.
-> Source maps, browser compilation, legacy plugin host APIs, URL rewriting, and
-> compressed-output parity are still work in progress.
+> It covers Node.js `less.render()`, `less.renderFile()`, and `lessc`, plus
+> variables, arithmetic, mixins, imports, and nested-rule output. Source maps,
+> URL rewriting, and `compress` now work through the `less.render()` API; the
+> legacy `@plugin` hook ABI is intentionally not carried over (function plugins
+> are supported). See the **[Less 5 feature status](V5-STATUS.md)** for the full
+> list of what is implemented, in progress, and intentionally not.
 
 Less extends CSS with variables, mixins, functions, nesting, and more — then compiles to standard CSS. Write cleaner stylesheets with less code.
 
@@ -64,8 +66,10 @@ npx lessc styles.less styles.css
 
 ### Browser
 
-Less 5 alpha.1 does not include browser compilation support. A new browser
-build mechanism will be introduced in a future alpha.
+A browser build ships in the package (`dist/less-browser-dev.js`) and defines
+`window.less` with the same render API; it powers the online playground. Full
+browser-API parity with Less 4 is still being validated — see the
+[feature status](V5-STATUS.md).
 
 ## Why Less?
 

package/V5-STATUS.md

@@ -0,0 +1,71 @@
+# Less 5 (alpha) — feature status
+
+Less 5 is a from-scratch compiler (the [Jess](https://github.com/jesscss/jess)
+engine) behind the same `less.render(input, options)` / `lessc` interface Less 4
+users know. The tables below compare Less 4 with the current Less 5 alpha —
+what's implemented, what's still in progress, and what will **intentionally
+not** be carried over (with the reason).
+
+> **Status:** alpha, published under the npm `alpha` dist-tag
+> (`npm install less@alpha`). APIs and output may still change. This page is kept
+> honest by the `packages/less` alpha test suite — if a row here drifts from
+> actual behavior, the suite fails.
+
+The headline change: **Less 5 preserves your authored nesting by default** (it
+emits nested CSS) instead of always flattening. Opt into flattened output with
+`collapseNesting`.
+
+**Legend:** ✅ supported · ⏳ in progress · ❌ not supported (by design) · ➖ not applicable
+
+## Language & output
+
+| Feature | Less 4 | Less 5 | Notes |
+| --- | :---: | :---: | --- |
+| Variables, mixins (guards, named args), operations, functions | ✅ | ✅ | The Less builtin function library is ported. |
+| `:extend` | ✅ | ✅ | |
+| Nested-rule output | ➖ | ✅ | Less 4 always flattened; Less 5 **preserves** authored nesting by default. |
+| `collapseNesting` (flatten instead) | ➖ | ✅ | `false` (default) / `'native'` (specificity-faithful) / `'compact'`. |
+| `@media` query merging | ✅ | ❌ | Less 5 emits nested `@media` instead of rewriting to `@media (a) and (b)`. Browsers have nested `@media` far longer than native *selector* nesting, so nested output is safe — and merging can blow up combinatorially (each nested query multiplies out). |
+| Inline JavaScript (backticks) | ✅ | ❌ | Removed. Script modules are the planned replacement for computed values; they are tracked separately from stylesheet composition below. |
+| IE `progid:` / `filter` hacks | ✅ | ❌ | Removed. |
+
+## Options (`less.render` API)
+
+| Feature | Less 4 | Less 5 | Notes |
+| --- | :---: | :---: | --- |
+| `math` modes | ✅ | ✅ | `always` / `parens-division` (default) / `parens`. |
+| `unitMode` (formerly `strictUnits`) | ✅ | ✅ | `loose` / `preserve` (default) / `strict`. |
+| `compress` | ✅ | ✅ | Minified, but not byte-identical to Less 4 `-x` (nesting preserved by default). |
+| Source maps (`sourceMap`) | ✅ | ✅ | Returns `result.map`; annotation, inline data URI, `outputSourceFiles`, and the `rootpath`/`basepath`/`url` path variants all supported. |
+| URL rewriting (`rewriteUrls` / `rootpath` / `urlArgs`) | ✅ | ✅ | Rewrites `url(...)` references. |
+| `globalVars` / `modifyVars` injection | ✅ | ❌ | Not supported — these throw rather than silently no-op. |
+| `javascriptEnabled` | ✅ | ❌ | JavaScript evaluation is not supported. |
+
+## Plugins (`@plugin`)
+
+| Feature | Less 4 | Less 5 | Notes |
+| --- | :---: | :---: | --- |
+| Function plugins (`functions.add`) | ✅ | ✅ | Via the opt-in `@jesscss/plugin-less-compat` layer — the common `@plugin` shape. |
+| npm-package imports | ✅ | ✅ | Native via `@jesscss/plugin-node-modules` (the `less-plugin-npm-import` case). |
+| Visitor / tree-visitor ABI, full `less.tree` | ✅ | ❌ | Intentional — the Less 4 tree is not the Less 5 AST; a translation layer isn't worth it. |
+| Pre-/post-processor hooks | ✅ | ❌ | Run PostCSS after Less; minification is native via `compress`. |
+| File-manager hooks | ✅ | ❌ | The common case (npm import) is covered natively. |
+| `@plugin (options)` + `registerPlugin` lifecycle | ✅ | ❌ | Deprecated Less 4 lifecycle; not built. |
+
+## Imports, CLI & tooling
+
+| Feature | Less 4 | Less 5 | Notes |
+| --- | :---: | :---: | --- |
+| Sibling / relative `@import` | ✅ | ✅ | |
+| Remote (`http(s)`) imports | ✅ | ⏳ | Gated behind an explicit network policy; not on by default. |
+| `@compose` stylesheet modules | ➖ | ✅ | Isolated, non-transitive modules with inferred or explicit namespaces, `as *`, and per-edge `with` or shared `set` configuration. See the [canonical Modules and Imports source](https://github.com/jesscss/jess/blob/dev/packages/docs/docs-content/docs/shared/02-Language/14-modules-and-imports.mdx). |
+| `@use` / `@from` script and data modules | ➖ | ⏳ | Reserved for JavaScript, TypeScript, JSON, and built-in modules; Less 5 does not recognize or execute them as modules yet. See the [canonical Modules and Imports source](https://github.com/jesscss/jess/blob/dev/packages/docs/docs-content/docs/shared/02-Language/14-modules-and-imports.mdx). |
+| Browser build (`window.less`) | ✅ | ✅ | `dist/less-browser-dev.js` ships and powers the playground; full 4.x browser-API parity is ⏳. |
+| `lessc` CLI (compile) | ✅ | ✅ | Compiles files. |
+| `lessc` CLI **flags** for the newer options | ✅ | ✅ | `--compress`/`-x`, `--source-map[=file]` (+ `--source-map-inline` / `-include-source` / `-rootpath` / `-basepath` / `-url`), `--rewrite-urls` / `--rootpath` / `--url-args`, `--math` are all wired. |
+| Diagnostics (`file:line:column` + excerpt) | ➖ | ✅ | Precise diagnostics, not raw parser offsets. |
+
+---
+
+*Found a row that contradicts actual behavior? Please open an issue — a drift
+between this page and the compiler is a bug.*

package/bin/lessc

@@ -17,28 +17,19 @@ let output = null;
 let silent = false;
 let quiet = false;
 let verbose = false;
+let sourceMapEnabled = false;
+let sourceMapExplicitFile = null;
+const sourceMapOptions = {};
 
 const unsupportedOptions = new Map([
-  ['--source-map', 'source maps are not supported'],
-  ['--source-map-map-inline', 'source maps are not supported'],
-  ['--source-map-include-source', 'source maps are not supported'],
-  ['--source-map-rootpath', 'source maps are not supported'],
-  ['--source-map-basepath', 'source maps are not supported'],
-  ['--source-map-url', 'source maps are not supported'],
   ['--plugin', 'legacy lessc plugin flags are not supported'],
   ['--depends', 'dependency-only output is not supported'],
   ['--lint', 'lint-only mode is not supported'],
-  ['--compress', 'compressed output is not supported'],
-  ['-x', 'compressed output is not supported'],
   ['--clean-css', 'clean-css compression is not supported'],
-  ['--rewrite-urls', 'URL rewriting is not supported'],
-  ['--rootpath', 'URL rootpath rewriting is not supported'],
-  ['--url-args', 'URL argument rewriting is not supported'],
   ['--global-var', 'global variable injection is not supported'],
   ['--modify-var', 'modify-var injection is not supported'],
   ['--js', 'JavaScript evaluation is not supported'],
   ['--no-js', 'JavaScript evaluation flags are not supported'],
-  ['--strict-units', 'strict unit mode is not supported'],
 ]);
 
 function stripTerminalFormatting(value) {
@@ -137,8 +128,87 @@ function parseArgs() {
       verbose = true;
       continue;
     }
-    if (arg === '--collapse-nesting') {
-      options.collapseNesting = true;
+    const collapseNestingMatch = arg.match(/^--collapse-nesting(?:=(.+))?$/);
+    if (collapseNestingMatch) {
+      options.collapseNesting = collapseNestingMatch[1] ?? true;
+      continue;
+    }
+    if (arg === '--compress' || arg === '-x') {
+      options.compress = true;
+      continue;
+    }
+    const mathMatch = arg.match(/^--math=(.+)$/);
+    if (mathMatch) {
+      options.math = mathMatch[1];
+      continue;
+    }
+    // URL rewriting (forwarded to the Less plugin). `--rewrite-urls` with no
+    // value is Less 4.x's `all`.
+    const rewriteUrlsMatch = arg.match(/^--rewrite-urls(?:=(.+))?$/);
+    if (rewriteUrlsMatch) {
+      options.rewriteUrls = rewriteUrlsMatch[1] ?? 'all';
+      continue;
+    }
+    const rootpathMatch = arg.match(/^--rootpath=(.+)$/);
+    if (rootpathMatch) {
+      options.rootpath = rootpathMatch[1];
+      continue;
+    }
+    const urlArgsMatch = arg.match(/^--url-args=(.+)$/);
+    if (urlArgsMatch) {
+      options.urlArgs = urlArgsMatch[1];
+      continue;
+    }
+    // Source maps. The `--source-map-*` sub-flags are matched before the bare
+    // `--source-map[=file]` (their `$`-anchored patterns don't overlap, but the
+    // ordering documents intent). Each sub-flag also enables source maps.
+    if (arg === '--source-map-inline' || arg === '--source-map-map-inline') {
+      sourceMapEnabled = true;
+      sourceMapOptions.sourceMapFileInline = true;
+      continue;
+    }
+    if (arg === '--source-map-include-source') {
+      sourceMapEnabled = true;
+      sourceMapOptions.outputSourceFiles = true;
+      continue;
+    }
+    const smRootpathMatch = arg.match(/^--source-map-rootpath=(.+)$/);
+    if (smRootpathMatch) {
+      sourceMapEnabled = true;
+      sourceMapOptions.sourceMapRootpath = smRootpathMatch[1];
+      continue;
+    }
+    const smBasepathMatch = arg.match(/^--source-map-basepath=(.+)$/);
+    if (smBasepathMatch) {
+      sourceMapEnabled = true;
+      sourceMapOptions.sourceMapBasepath = smBasepathMatch[1];
+      continue;
+    }
+    const smUrlMatch = arg.match(/^--source-map-url=(.+)$/);
+    if (smUrlMatch) {
+      sourceMapEnabled = true;
+      sourceMapOptions.sourceMapURL = smUrlMatch[1];
+      continue;
+    }
+    const sourceMapMatch = arg.match(/^--source-map(?:=(.+))?$/);
+    if (sourceMapMatch) {
+      sourceMapEnabled = true;
+      if (sourceMapMatch[1]) {
+        sourceMapExplicitFile = sourceMapMatch[1];
+      }
+      continue;
+    }
+    // Deprecated 4.x spellings (--strict-units, --strict-units=on|off, -su=on|off)
+    // set the deprecated `strictUnits` boolean; `createLessOptions` maps it to
+    // `unitMode` and warns during compile, after the logger listener is attached.
+    const strictUnitsMatch = arg.match(/^(?:--strict-units|-su)(?:=(on|off))?$/);
+    if (strictUnitsMatch) {
+      options.strictUnits = strictUnitsMatch[1] !== 'off';
+      continue;
+    }
+    const unitModeMatch = arg.match(/^--unit-mode=(.+)$/);
+    if (unitModeMatch) {
+      options.unitMode = unitModeMatch[1];
       continue;
     }
     const optionName = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
@@ -178,6 +248,44 @@ function parseArgs() {
   }
 }
 
+// Assemble the `sourceMap` render option from the CLI source-map flags and
+// return the sidecar `.map` path to write (null when inlined or unset). The
+// engine writes the `sourceMappingURL` annotation into the CSS and returns
+// `result.map`; the CLI owns writing that map to disk, mirroring Less 4.x lessc.
+function resolveSourceMap() {
+  if (!sourceMapEnabled) {
+    return null;
+  }
+  let mapFilePath = null;
+  if (sourceMapOptions.sourceMapFileInline !== true) {
+    if (sourceMapExplicitFile) {
+      mapFilePath = path.resolve(process.cwd(), sourceMapExplicitFile);
+    } else if (output) {
+      mapFilePath = `${output}.map`;
+    } else {
+      // Writing CSS to stdout leaves nowhere for a sidecar; inline the map.
+      sourceMapOptions.sourceMapFileInline = true;
+    }
+  }
+  if (mapFilePath) {
+    // Annotation URL (unless --source-map-url set it) points at the map relative
+    // to the CSS output directory — so a map written to another directory still
+    // resolves (dist/app.css -> ../maps/app.map), and the same-dir common case
+    // stays a bare basename. With no output file (stdout) there is no directory
+    // to resolve against, so fall back to the basename.
+    if (sourceMapOptions.sourceMapURL === undefined) {
+      sourceMapOptions.sourceMapFilename = output
+        ? path.relative(path.dirname(output), mapFilePath).split(path.sep).join('/')
+        : path.basename(mapFilePath);
+    }
+    if (output) {
+      sourceMapOptions.sourceMapOutputFilename = path.basename(output);
+    }
+  }
+  options.sourceMap = sourceMapOptions;
+  return mapFilePath;
+}
+
 async function run() {
   parseArgs();
 
@@ -187,6 +295,8 @@ async function run() {
     printUsage();
   }
 
+  const mapFilePath = resolveSourceMap();
+
   less.logger.addListener({
     info(msg) {
       if (verbose) console.log(msg);
@@ -225,6 +335,12 @@ async function run() {
       if (!silent) outputJessDiagnostics([], result.warnings || []);
       process.stdout.write(result.css);
     }
+
+    if (mapFilePath && result.map) {
+      fs.mkdirSync(path.dirname(mapFilePath), { recursive: true });
+      fs.writeFileSync(mapFilePath, result.map, 'utf8');
+      if (!silent) console.log(`lessc: wrote ${mapFilePath}`);
+    }
   } catch (err) {
     if (!silent) {
       if (!outputJessError(err)) {