@jesscss/less-parser 2.0.0-alpha.1 → 2.0.0-alpha.11

package/README.md

@@ -1,36 +1,166 @@
-# Jess - Less parser
-
-Translates a Less string to a Jess AST.
-
-## Ideas
-
-### Converting Less 1.x-5.x to Less 6
-
-1. Auto-wrap parens around division to dis-ambiguate.
-2. Convert `@import` to `@use` and `@include` syntax.
-3. Throw errors on `@plugin` and ask to refactor with `@from`
-4. Convert function references to `@from '#less' ([func])`
-5. Add parentheses after mixin calls e.g. `.ns > .mixin;` to `.ns.mixin();`
-6. Convert local imports from `@import 'local'` to `@include './local.less'`
-7. Convert `@import (less) './file.css';` to `@include './file.css' as less;`
-8. Convert `@import (inline) './file.css';` to `@include './file.css' as text;`
-9. Convert `@import (reference) './file.less';` to `@use './file.less';`
-10. Files that consume variables, mixins, or rules (like with extend) should have a `@use` added.
-11. Don't allow `.class` as a value in a declaration. Convert to `\.class` e.g. `@foo: .class` should be converted to `@foo: \.class` (or `selector(.class)`?).
-12. In a custom property value, convert `@variable` to `@{variable}`.
-
-
-### Converting Less 1.x-4.x to Jess
-
-1. Auto-wrap expressions (like math) with `$()`
-2. Convert mixin definitions `.my-mixin()` to `@mixin my-mixin()`
-3. Convert mixin calls to function calls: `#ns > .mixin()` to `$ns.mixin()`
-4. Throw errors on mixed case mixins: `.my-mixin()` and `.myMixin()`
-5. Throw errors on mixed hash and class mixins: `#my-mixin()` and `.my-mixin()`
-5. Convert variable declarations `@my-var` with `$my-var`
-6. Convert interpolated vars `@{my-var}` to `$(my-var)`
-7. Convert property references `$prop` to `$[prop]`
-8. Convert color names in expressions to hex values (or wrapped in `color()`?) (because Jess doesn't support color keywords in expressions). Alternatively, should Jess allow `keyword` to denote keywords?
-9. Convert `@rest...` to `...rest`
-10. Convert `.rules()` to `@include .rules()` if `.rules` is a selector. What if it's a selector and mixin? Maybe something like `@include .rules, $rules();`? This might change the execution order from Less though.
-11. Convert `@foo: extract(@bar, 1)` to `@let foo: $bar[0];`?
+# @jesscss/less-parser
+
+The Less grammar, layered on the CSS base parser, with core-free CST entry points.
+
+> **Status: alpha.** Part of [Jess](https://github.com/jesscss/jess). The broader
+> language/tooling picture is still early. Expect gaps and
+> [report bugs](https://github.com/jesscss/jess/issues). Docs live at
+> [jesscss.github.io](https://jesscss.github.io/).
+
+## What it is
+
+The Less grammar is the shared CSS grammar plus a Less delta:
+`lessGrammar = compose([cssGrammar, <Less delta>])`. It adds `@variable` /
+`@{interpolation}`, mixins, and the rest of Less on top of the spec-aligned CSS
+base in [`@jesscss/css-parser`](https://www.npmjs.com/package/@jesscss/css-parser),
+built on [parseman](https://www.npmjs.com/package/parseman) — **the fastest
+general-purpose JavaScript parser** in its
+[published benchmarks](https://matthew-dean.github.io/parseman/guide/benchmarks)
+(see `@jesscss/css-parser` for figures and engineering details). It is the parser
+Jess uses when it compiles `.less` — the "Now" tier of the language roadmap, and
+the one dialect shipping in the alpha.
+
+The default `parse()` operation constructs canonical AST v2 `Stylesheet` directly
+through parser-local Parseman reductions. Use the explicit `./cst` entry when a
+language-service or document consumer needs a CST. The package has no
+core-owned parser driver or AST construction host.
+
+## Install
+
+```sh
+npm install @jesscss/less-parser
+```
+
+`@jesscss/core` is an optional peer for consumers using the default AST v2
+`parse()` result. The explicit CST and grammar subpaths remain core-free.
+Those explicit entries expose Parseman types and grammar values, so consumers
+of them must also provide the package's `parseman` peer.
+
+## Canonical AST parsing
+
+```js
+import { parse } from '@jesscss/less-parser'
+
+const stylesheet = parse('@c: red;\n.foo { color: @c; }')
+
+stylesheet.type // 'Stylesheet'
+```
+
+## Standalone usage (core-free)
+
+```js
+import { parseLessCst } from '@jesscss/less-parser/cst'
+
+const result = parseLessCst('@c: red;\n.foo { color: @c; }')
+
+result.ok               // true
+result.errors           // ParseError[] (empty when ok)
+result.unconsumedFrom   // index of first unparsed char, or null
+result.tree             // the CST root (a StyleSheet node)
+```
+
+Signature:
+
+```ts
+parseLessCst(input: string, startRule = 'Stylesheet', options?: { collapse?: boolean }): LessCstParseResult
+```
+
+Pass a different `startRule` (any capitalized grammar rule, e.g. `'SelectorList'`, `'Declaration'`) to parse a fragment.
+
+## Public API
+
+| Entry | Export | Purpose |
+| --- | --- | --- |
+| `@jesscss/less-parser/cst` | `parseLessCst` | Core-free parse of a Less string to a CST. |
+| `@jesscss/less-parser/cst` | `LessCstNode`, `LessCstLeaf`, `LessCstError`, `LessCstChild`, `LessCstParseResult`, `LessCstType` (types) | CST type definitions (aliases of the shared `@jesscss/css-parser/cst` types). |
+| `@jesscss/less-parser/grammar` | `lessGrammar` | The compiled Less grammar (a rule map). Extend it with `compose()` or drive it directly with parseman's `run`. |
+| `@jesscss/less-parser` (`.`) | `parse` | Parse Less directly to canonical AST v2 `Stylesheet`. It does not load the CST grammar. |
+
+## Default CST shape
+
+The CST is parseman's, produced by the shared `cssCstBuildHost`. Three kinds of node:
+
+- **node** — `{ _tag: 'node', type, grammarType, span: { start, end }, state, children }` (`grammarType` = raw rule name; `type` = friendly public name).
+- **leaf** — `{ _tag: 'leaf', value, span }` for terminals.
+- **error** — `{ _tag: 'error', type, span, expected, children, state }` where recovery happened.
+
+Spans are `[start, end)` offsets; whitespace, block comments, **and Less line comments (`//`)** are trivia and do not appear as children.
+
+Parsing `@c: red;\n.foo { color: @c; }` yields (abridged):
+
+```jsonc
+{
+  "_tag": "node", "type": "StyleSheet", "grammarType": "Stylesheet",
+  "children": [
+    { "_tag": "node", "type": "VarDeclaration", "grammarType": "VarDeclaration", "span": { "start": 0, "end": 8 },
+      "children": [
+        { "_tag": "leaf", "value": "@c" }, { "_tag": "leaf", "value": ":" },
+        { "_tag": "node", "type": "NamedColor", "grammarType": "NamedColor",
+          "children": [ { "_tag": "leaf", "value": "red" } ] },
+        { "_tag": "leaf", "value": ";" }
+      ] },
+    { "_tag": "node", "type": "QualifiedRule", "grammarType": "Ruleset", "span": { "start": 9, "end": 28 },
+      "children": [
+        { "_tag": "leaf", "value": ".foo" }, { "_tag": "leaf", "value": "{" },
+        { "_tag": "node", "type": "Declaration", "grammarType": "Declaration",
+          "children": [
+            { "_tag": "leaf", "value": "color" }, { "_tag": "leaf", "value": ":" },
+            { "_tag": "node", "type": "Reference", "grammarType": "Reference",
+              "children": [ { "_tag": "leaf", "value": "@c" } ] },
+            { "_tag": "leaf", "value": ";" }
+          ] },
+        { "_tag": "leaf", "value": "}" }
+      ] }
+  ]
+}
+```
+
+Note the Less-specific nodes: a top-level `@c: …` becomes a `VarDeclaration`, a `@c` value becomes a `Reference`, and the color keyword `red` parses as `NamedColor` (the CSS-only grammar has no such rule — see `@jesscss/css-parser`).
+
+Pass `{ collapse: true }` to unwrap single-child wrapper types (`Reference`, `NamedColor`, `InterpolatedSelector`) into their child.
+
+### Name-independent condition arguments
+
+A top-level condition operator (`> < >= <= = and or not`) inside **any** call's argument parses as a `Condition` node — there is **no** parse-time name-dispatch on `if`/`boolean`. `if(@a > 5, 1, 2)`, `boolean(not(2 < 1))`, `#ns.if(@a > 5)`, and `foo(@a > 5 and @b < 2)` all route through the ordinary function/mixin `Call` production; the shared call-arg rule (`ArgCondition` → `CondArgOr`/`CondArgAnd`/`CondArgTerm`) layers the condition-operator precedence chain on top of the normal value production. The layer is structurally gated: it only matches when a real operator is present, so a plain value / space-list argument (and mixin-definition params) fall through to the unchanged `valueSequence` byte-identically. Eval treats `if`/`boolean` as ordinary registered functions that consume the parsed `Condition`, so this is a parse-only unification (a deliberate v5 loosening vs Less 4.x, which name-dispatched and errored on the namespaced/generic forms).
+
+One known gap: a namespace/accessor call in **value** position (`b: #ns.if(@a > 5)`, `b: .if(@a > 5)`) is reassembled from a raw permissive-paren capture (`_buildRefCallArgs`), a separate shallow path that does not run the condition layer — its args stay a value list. Statement-position (`#ns.if(@a > 5) { }` / bare `#ns.if(@a > 5)`) and all function-call forms are covered.
+
+## Extending with your own builders
+
+The grammar is decoupled from the tree it builds. Every capitalized rule is a parseman `node()`; when you drive a grammar with a `build` host, each `node()` calls your host instead of constructing the default CST. Use parseman's `run` with your own host and the grammar's trivia rule:
+
+```js
+import { run } from 'parseman'
+import { lessGrammar } from '@jesscss/less-parser/grammar'
+
+const myHost = (type, children, fields, span) => ({ type, span, children: children.filter(Boolean) })
+
+const result = run(lessGrammar.Stylesheet, '@c: red; .foo { color: @c; }', {
+  build: myHost,
+  trivia: lessGrammar.rw   // Less trivia = whitespace + block + line comments
+})
+
+result.value   // the root node your host returned
+```
+
+The `BuildHost` signature (from parseman):
+
+```ts
+type BuildHost = (
+  type: string,
+  children: readonly unknown[],
+  fields: FieldMap | undefined,
+  span: { start: number; end: number },
+  rawChildren: readonly unknown[],
+  triviaLog: readonly number[],
+  state: unknown
+) => unknown
+```
+
+`parseLessCst(...)` is this pattern with the shared `cssCstBuildHost` (see `@jesscss/css-parser`, `src/cst.ts`) as a reference host.
+
+## Part of Jess
+
+This package is developed as part of [Jess](https://github.com/jesscss/jess).
+Jess translates a Less string into the core Jess AST, which the compiler then
+evaluates and renders to CSS. Licensed MIT.

package/lib/cst.cjs

@@ -0,0 +1,14 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_grammar = require("./grammar2.cjs");
+let _jesscss_css_parser_cst = require("@jesscss/css-parser/cst");
+//#region src/cst.ts
+function parseLessCst(input, startRule = "Stylesheet", options) {
+	return (0, _jesscss_css_parser_cst.parseCst)(require_grammar.lessCstGrammar, input, startRule, options);
+}
+/** Incremental (`.edit()`-able) Less document — see `parseDocCst`. */
+function parseLessDoc(input, startRule = "Stylesheet") {
+	return (0, _jesscss_css_parser_cst.parseDocCst)(require_grammar.lessCstGrammar, input, startRule);
+}
+//#endregion
+exports.parseLessCst = parseLessCst;
+exports.parseLessDoc = parseLessDoc;

package/lib/cst.d.ts

@@ -0,0 +1,6 @@
+import { type CssCstNode, type CssCstParseOptions, type CssCstParseResult, type ParseDoc } from '@jesscss/css-parser/cst';
+export declare function parseLessCst(input: string, startRule?: string, options?: CssCstParseOptions): CssCstParseResult;
+/** Incremental (`.edit()`-able) Less document — see `parseDocCst`. */
+export declare function parseLessDoc(input: string, startRule?: string): ParseDoc<CssCstNode>;
+export type { CssCstChild as LessCstChild, CssCstError as LessCstError, CssCstLeaf as LessCstLeaf, CssCstNode as LessCstNode, CssCstParseOptions as LessCstParseOptions, CssCstParseResult as LessCstParseResult, CssCstType as LessCstType } from '@jesscss/css-parser/cst';
+//# sourceMappingURL=cst.d.ts.map

package/lib/cst.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cst.d.ts","sourceRoot":"","sources":["../src/cst.ts"],"names":[],"mappings":"AAAA,OAAO,EAAyB,KAAK,UAAU,EAAE,KAAK,kBAAkB,EAAE,KAAK,iBAAiB,EAAE,KAAK,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGjJ,wBAAgB,YAAY,CAC1B,KAAK,EAAE,MAAM,EACb,SAAS,SAAe,EACxB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,iBAAiB,CAEnB;AAED,sEAAsE;AACtE,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,SAAe,GAAG,QAAQ,CAAC,UAAU,CAAC,CAE1F;AAED,YAAY,EACV,WAAW,IAAI,YAAY,EAC3B,WAAW,IAAI,YAAY,EAC3B,UAAU,IAAI,WAAW,EACzB,UAAU,IAAI,WAAW,EACzB,kBAAkB,IAAI,mBAAmB,EACzC,iBAAiB,IAAI,kBAAkB,EACvC,UAAU,IAAI,WAAW,EAC1B,MAAM,yBAAyB,CAAC"}

package/lib/cst.js

@@ -0,0 +1,12 @@
+import { n as lessCstGrammar } from "./grammar2.js";
+import { parseCst, parseDocCst } from "@jesscss/css-parser/cst";
+//#region src/cst.ts
+function parseLessCst(input, startRule = "Stylesheet", options) {
+	return parseCst(lessCstGrammar, input, startRule, options);
+}
+/** Incremental (`.edit()`-able) Less document — see `parseDocCst`. */
+function parseLessDoc(input, startRule = "Stylesheet") {
+	return parseDocCst(lessCstGrammar, input, startRule);
+}
+//#endregion
+export { parseLessCst, parseLessDoc };

package/lib/grammar.cjs

@@ -0,0 +1,5 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_grammar = require("./grammar2.cjs");
+exports.lessAstGrammar = require_grammar.lessAstGrammar;
+exports.lessCstGrammar = require_grammar.lessCstGrammar;
+exports.lessGrammar = require_grammar.lessGrammar;

package/lib/grammar.d.ts

@@ -0,0 +1,5 @@
+export declare const lessGrammar: Record<string, import("parseman").FusedRule>;
+export declare const lessAstGrammar: Record<string, import("parseman").FusedRule>;
+/** Public Less CST artifact: the same grammar factory compiled in CST mode. */
+export declare const lessCstGrammar: Record<string, import("parseman").FusedRule>;
+//# sourceMappingURL=grammar.d.ts.map

package/lib/grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../src/grammar.ts"],"names":[],"mappings":"AAuvLA,eAAO,MAAM,WAAW,8CAAwL,CAAC;AACjN,eAAO,MAAM,cAAc,8CAAc,CAAC;AAE1C,+EAA+E;AAC/E,eAAO,MAAM,cAAc,8CAAyM,CAAC"}

package/lib/grammar.js

@@ -0,0 +1,2 @@
+import { n as lessCstGrammar, r as lessGrammar, t as lessAstGrammar } from "./grammar2.js";
+export { lessAstGrammar, lessCstGrammar, lessGrammar };