@jesscss/less-parser 2.0.0-alpha.5 → 2.0.0-alpha.7

package/README.md

@@ -1,8 +1,137 @@
-# Jess - Less parser
+# @jesscss/less-parser
 
-Translates a Less string to a Jess AST.
+A [Less](https://lesscss.org/) parser built on [parseman](https://www.npmjs.com/package/parseman). The grammar is the 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 shared CSS base in `@jesscss/css-parser`.
 
-## Ideas
+Two ways to use it:
+
+- **As part of Jess** — the default `.` entry is wired into `@jesscss/core` and produces the core AST the Jess compiler evaluates (this is what runs when Jess compiles Less). This is the internal, core-coupled path.
+- **As a standalone CST parser** — the `./cst` entry has **no dependency on `@jesscss/core`**. Install just this package and parse Less source text into a concrete syntax tree (CST). You can also plug your own builders onto the grammar to produce your own AST instead of the default CST.
+
+## Install
+
+```sh
+npm install @jesscss/less-parser
+```
+
+`@jesscss/core` is an **optional** peer dependency — needed only for the core-coupled `.` entry, not for `./cst` or `./grammar`.
+
+## 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` (`.`) | `LessParser` (also `Parser`), `parseLessFn`, `lessGrammar`, tokens, … | The Jess-internal barrel. **Core-coupled** (the functional parser builds the core AST). Prefer `./cst` if you don't need `@jesscss/core`. |
+| `@jesscss/less-parser/jess` | `LessParser`, `LessGrammar`, `parseLessFn`, … | Internal Jess-facing surface. |
+
+## 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 a Jess AST; the sections below track the migration rules that entails.
 
 ### Converting Less 1.x-5.x to Less 6
 
@@ -19,7 +148,6 @@ Translates a Less string to a Jess AST.
 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 `$()`
@@ -33,4 +161,4 @@ Translates a Less string to a Jess AST.
 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];`?
+11. Convert `@foo: extract(@bar, 1)` to `@let foo: $bar[0];`?

package/lib/builders.d.ts

@@ -0,0 +1,381 @@
+/**
+ * LessGrammar — builder methods for the Less grammar.
+ *
+ * Builder-only class: no grammar rules, no Parséman Parser base.
+ * Grammar rules live in grammar-fn.ts (macro-compiled functional grammar),
+ * which uses LessGrammar via a thin BuilderHost subclass.
+ * Extends CssParser to inherit the shared CSS builder methods.
+ */
+import type { FieldMap, Span } from 'parseman';
+import type { CSTLeaf, CSTError } from 'parseman';
+import { CssParser, type Spanned, type Component } from '@jesscss/css-parser/jess';
+import { type Node, type LocationInfo, Ruleset, type MathMode, Quoted } from '@jesscss/core';
+type JessNode = Node<any, any>;
+type Child = JessNode | CSTLeaf | CSTError;
+export declare class LessGrammar extends CssParser {
+    /** Math mode governing when arithmetic operates / when `/` divides. Less default. */
+    mathMode: MathMode;
+    /** Bare ident/keyword token in value or guard position. */
+    private _lessKeyword;
+    private _isKeywordLike;
+    private _isEmptyKeywordLike;
+    protected buildNode(type: string, span: Span, children: ReadonlyArray<JessNode | CSTLeaf | CSTError>, _state: unknown, _rawChildren: ReadonlyArray<{
+        _tag: string;
+    }>, fields?: FieldMap, triviaLog?: readonly number[]): JessNode;
+    /**
+     * The operand of a `Negative` (`-value`). The grammar emits the leading `-`
+     * as a leaf followed by the operand, which may itself be a node or a bare
+     * string terminal (e.g. `-@color` → `var(--color)`'s inner `-color-accent`).
+     * Prefer a node child; otherwise take the operand leaf's text so `Negative`
+     * coerces it to the canonical node form rather than receiving `undefined`.
+     */
+    private _negativeOperand;
+    private _buildVarDeclaration;
+    /**
+     * Build a Less variable reference and its accessor/call chain. Faithful 1:1
+     * port of the Chevrotain `varReference` + `lookupOrCall` productions
+     * (productions/values.ts, productions/guards.ts): a `@var` base glued to a
+     * left-folded chain of `[index]` accessors and `(call)`s. The grammar's
+     * noTrivia() guarantees the chain is adjacent (no whitespace between segments).
+     */
+    private _buildReference;
+    /**
+     * Build a namespace INDEXED-accessor value: a `.`/`#` selector-path head glued to
+     * a `[accessor]` (and any further `[accessor]`/`(call)` chain), e.g.
+     * `#ns.options[val1]`. The grammar (NsAccessor) captures this as ONE value operand
+     * so it survives arithmetic folding; here we reassemble it into the mixin-ruleset
+     * name Reference + accessor chain — the SAME shape the declaration-value
+     * _assembleSegment path produces for a lone `#ns.options[val1]`. Call-headed forms
+     * (`.mixin()`, `.mixin()[k]`) do NOT reach here (they keep the GluedParen path).
+     * Leaves: [ headText, '[', key?, ']', '(', content?, ')' … ].
+     */
+    private _buildNsAccessor;
+    /**
+     * Apply one `[key]` accessor to `base`, reproducing lookupOrCall's key logic:
+     * type is `variable` when the key token starts with `@`, else `index`; the key
+     * text runs through getInterpolatedOrString (handling `$@x`/`@{x}` interpolation),
+     * and index keys are wrapped in a Quoted.
+     */
+    private _applyReferenceAccessor;
+    /**
+     * Build mixin-call args for a `(…)` segment in a reference chain from the raw
+     * captured content. Comma-separated values become a List; an empty segment
+     * yields null (no args). Sub-structure here is intentionally shallow — the
+     * accessor-chain call form is rare and no consumer inspects nested arg shape.
+     */
+    private _buildRefCallArgs;
+    private _buildNamedColor;
+    private _normalizeCompareOp;
+    /** A guard comparison operator leaf (`=`, `<`, `>=`, `=<`, `=~`, …). */
+    private _isCompareOpLeaf;
+    /**
+     * Split a guard term's ordered components into `left [op right]`. A bare-keyword
+     * operand (`foo`, `true`) is a leaf string — not a node — so `nodeChildren`
+     * alone drops it; walk the ordered stream so string operands become real
+     * keyword nodes (their guard truthiness is decided at eval by `Condition`).
+     */
+    private _guardComparison;
+    private _buildComparison;
+    /**
+     * Coerce a `_assembleValue` result — a single Component or a raw space-group
+     * array — into ONE Node, so it can be a Condition operand. A single string
+     * becomes a keyword; a space-group array becomes a `Sequence` (the same coercion
+     * the List serializer applies to a raw group).
+     */
+    private _condOperandNode;
+    /**
+     * `CondArgTerm` — a name-independent condition-argument term: optional leading
+     * `not`, a bounded value operand, and an optional `<op> right` comparison. Builds
+     * a `Condition` (comparison → `[left, op, right]`; bare `not` → `{negate:true}`)
+     * or, when neither a `not` nor a `compareOp` is present, the plain operand value
+     * (byte-identical to an ordinary value arg). Multi-token operands (`1px solid`)
+     * survive as a `Sequence`, unlike the single-operand guard path.
+     */
+    private _buildCondArgTerm;
+    /**
+     * Fold a left-associative `and`/`or` chain of condition-arg terms into Conditions.
+     *
+     * Less accepts a bare `and`/`or` join in value-position condition args (`if(@a > 5
+     * and @b < 2, …)`) — verified against less@4.6.7 (`if`/`boolean` route their arg
+     * through `condition()` with no `needsParens`, so bare comparisons split on `and`/
+     * `or`). We keep accepting the bare form for Less parity, but NORMALIZE the AST so
+     * each join operand is `Paren`-wrapped: `@a > 5 and @b < 2` builds the SAME tree as
+     * the explicitly-parenthesised `(@a > 5) and (@b < 2)`. This is a structural
+     * normalisation only — `Paren(Condition)` evaluates to the same boolean as the bare
+     * `Condition`, so rendered CSS is byte-identical. A single unjoined operand (one
+     * node) is untouched (no synthetic Paren).
+     */
+    private _buildCondArgJoin;
+    /** Coerce a default() call/reference into a DefaultGuard, mirroring isDefaultGuardCall. */
+    private _maybeDefaultGuard;
+    /** guardInParens: `(` guardOr `)` → Paren, or a bare default() → Paren(DefaultGuard). */
+    private _buildGuardInParens;
+    /** A single guard term: optional `not`, then a paren-guard or a comparison/value. */
+    private _buildGuardTerm;
+    /** Fold a left-associative chain of terms joined by `and` / `or`. */
+    private _buildGuardJoin;
+    /** guard: `when` guardOr — returns the single guardOr child. */
+    private _buildGuard;
+    /**
+     * Deprecated Less `%(format, args…)` string formatting, LOWERED at build time.
+     *
+     * Jess already has full string interpolation, so `%()` is redundant Less-4 legacy —
+     * we emit a `percent-format` deprecation warning and, when the format is a string
+     * literal, splice its `%[sda]` directives into the canonical `Interpolated` node
+     * (the same one `@{var}` string interpolation builds), wrapped in a `Quoted` that
+     * preserves the literal's quote char / escaped flag:
+     *   - `%s`  → bare interpolation slot (a Quoted arg inserts with its quotes stripped);
+     *   - `%d`/`%a` → identical bare slot (d/a are the same in Less);
+     *   - `%S`/`%D`/`%A` → the arg WRAPPED in `escape(…)` (URL-encode);
+     *   - `%%` → a literal `%`.
+     * A dynamic (non-literal) format (`%(hello)`, `%(e("…"), …)`) can't be lowered at
+     * parse time, so it falls back to a best-effort runtime `%` Call with the same warning.
+     */
+    private _buildFormatCall;
+    /**
+     * Turn a printf-style format string into an `Interpolated` source + replacements.
+     * `%[sda]` → one `INTERPOLATION_PLACEHOLDER` slot consuming the next positional arg
+     * (uppercase → wrapped in `escape(…)` to URL-encode); `%%` → a literal `%`.
+     */
+    private _lowerFormatString;
+    private _buildInterpolatedSelector;
+    private _buildLessPseudo;
+    private _buildLessDeclaration;
+    /**
+     * Port of `processLegacyMSFilterToken` (lessRecursiveParser.ts): a `progid:…`
+     * filter value string → Interpolated(role=any) with `@var` runs templated out,
+     * or a plain Keyword when the run has no variables.
+     */
+    private _buildLegacyMSFilter;
+    private _buildAmpersand;
+    /** The append value of a `&`-led ampersand token: the suffix after `&` (`&-bar` →
+     * `-bar`, `&1` → `1`), or undefined for a bare `&`. */
+    private _ampersandTemplateValue;
+    /**
+     * A single extend target inside `extend( … )`: a complex selector plus its
+     * optional `all` / `!all` flag (selectors.ts `complexSelector`'s OPTION2 flag).
+     * Produced as an `Extend` carrier the surrounding pseudo/statement groups.
+     */
+    private _buildExtendTarget;
+    /**
+     * `:extend( … )` pseudo form (selectors.ts `extend`): groups its ExtendTarget
+     * children. Targets sharing one flag collapse to a single Extend whose target is
+     * a SelectorList (or the lone selector); mixed flags stay as one Extend each,
+     * returned in a List. Mirrors mergeExtends' target-and-flag grouping.
+     */
+    private _buildExtendPseudo;
+    /**
+     * `&:extend( … );` (or bare `:extend( … );`) statement form (selectors.ts
+     * `ampersandExtend`). The ExtendPseudo child already carries the grouped
+     * Extend(s); the leading `&` is just the statement marker.
+     */
+    private _buildExtendStatement;
+    /**
+     * Decode a single `[key]` accessor into its Less lookup-key AST — the ONE shared
+     * decoder for every accessor-chain builder path (var-decl value, declaration value,
+     * at-rule prelude, namespace ref). Accepts either a raw authored key STRING (the
+     * text inside the brackets, e.g. `@@foo`, `$@x`, `bar`, ``), or a SquareParen `Paren`
+     * node whose inner content the grammar already parsed (a raw string or a `@var`
+     * Reference). Returns the key exactly as the reference lookupOrCall production would:
+     *
+     *   `[]`        → -1        (index, empty)
+     *   `[@@name]`  → Reference{type:variable,key:name}   (dynamic variable lookup)
+     *   `[$@name]` / `[@$name]` → Quoted(Interpolated(@name))  (dynamic property lookup)
+     *   `[@name]`   → 'name'    (static variable lookup; bare string key)
+     *   `[$name]`   → Quoted('name')   (property lookup; `$` marker dropped)
+     *   `[name]`    → Quoted('name')   (index)
+     *
+     * Exactly one `@`/`$` marker is the lookup marker and is never kept.
+     */
+    private _decodeAccessorKey;
+    protected _assembleSegment(seg: Spanned[], loc: LocationInfo): Component;
+    private _buildEscapedValue;
+    private _buildInterpValue;
+    /**
+     * A quoted string value. Unlike plain CSS, Less interpolates `@{var}` / `${prop}`
+     * inside quoted (and escaped `~"…"`) strings and inside `@import` paths. When the
+     * raw content holds an interpolation, split it into an `Interpolated` value the same
+     * way the reference parser's `processStringInterpolation` does (source with
+     * INTERPOLATION_PLACEHOLDER, `@var`/`$prop` references in `replacements`); otherwise
+     * fall through to the plain CSS builder (bare-string value).
+     */
+    /**
+     * The Less `Url` grammar tokenizes the inner string as bare leaves (no child
+     * node), so the css base builder wraps a quoted url body in a raw-string
+     * `Quoted` — which never interpolates `@{var}`/`${prop}`. Less 4.x DOES resolve
+     * interpolation inside a QUOTED url body (`url("@{base}/@{i}.svg")`), the same as
+     * any other quoted string, so route the quoted inner through the same
+     * interpolation-aware construction `_buildQuoted` uses. Unquoted url bodies stay
+     * verbatim (Less 4.x leaves `url(@{x})` literal), as does a quoted body with no
+     * interpolation.
+     */
+    protected _buildUrl(children: ReadonlyArray<Child>, loc: LocationInfo): JessNode;
+    protected _buildQuoted(children: ReadonlyArray<Child>, loc: LocationInfo): JessNode | Quoted;
+    /**
+     * Build an escaped `~'…'` Quoted (at-rule prelude position), interpolating any
+     * `@{var}` / `${prop}` in its body the same way `_buildQuoted` does — so
+     * `~'@{a} / @{b}'` renders its substituted values instead of literal text.
+     */
+    private _buildEscapedQuoted;
+    /**
+     * Split a quoted-string body on `@{…}` / `${…}` interpolations into an
+     * `Interpolated` (source + reference replacements). Port of the reference parser's
+     * `processStringInterpolation`/`findInterpolations` (productions/values.ts): brace
+     * matching is nesting-aware, and a nested-interpolated name resolves through a
+     * variable Reference wrapped in an Expression.
+     */
+    private _buildStringInterpolation;
+    /**
+     * Locate `@{…}` / `${…}` interpolation runs in a string, counting nested braces so
+     * `@{@{x}}` and `@{fn(a, b)}` are matched whole. Returns start/end/prefix/content.
+     */
+    private _findInterpolations;
+    protected _buildCall(rawChildren: ReadonlyArray<{
+        _tag: string;
+    }>, loc: LocationInfo): JessNode;
+    private _buildLessCustomDecl;
+    /**
+     * `--foo: { color: @a; }` — a curly-brace custom-property value whose body
+     * opportunistically structured as a declaration list (customCurlyBlock in the
+     * grammar), so nested `@var`/calls evaluate normally instead of staying opaque
+     * text. Wrapped in a Block(type: 'curly') so `{`/`}` re-render around it.
+     */
+    private _buildLessCustomBlock;
+    private _warnDeprecatedValue;
+    private _warnCustomPropVars;
+    private _warnAtRulePreludeVars;
+    /**
+     * The first bare `@ident` reference in an at-rule prelude that is deprecated
+     * under Less 4.x PR #4462 (`variable-in-at-rule-prelude`), or null when there
+     * is none. A bare `@var` in a *structural* (top-level) prelude position still
+     * resolves but is deprecated in favour of `@{var}` interpolation; the scan
+     * therefore ignores, mirroring `hasTopLevelBareVariable` / `warnBareAtRuleVariable`:
+     *   - the leading at-rule name itself (`@media`, `@-moz-document`, …);
+     *   - `@{ident}` interpolation — the supported migration target;
+     *   - a `@var` inside `(...)` — a declaration/feature value (e.g. the `@size`
+     *     in `@media (min-width: @size)`), which stays valid;
+     *   - `@`/`(` characters inside string literals, which are not structural.
+     */
+    private _firstTopLevelBareAtVar;
+    private _buildMixinCall;
+    /**
+     * `@name(...)` (no `:`) → a detached-ruleset variable CALL. Faithful port of
+     * `varDeclarationOrCall`'s LParen branch (selectors.ts): build a `Reference`
+     * over the var name (`type: 'variable', role: 'name'`), wrap in a `Call` with
+     * the (optional) args, and wrap THAT in an `Expression` (a top-level variable
+     * call is an expression, not a parenthesized one). `!important` sets
+     * `markImportant` on the Call, mirroring the production.
+     */
+    private _buildVarCall;
+    /** `...` or `@name...` variadic arg → `Rest`. Definition-shape (string name); a
+     * CALL turns it into `Rest(Reference)` via `_convertArgsForCall`. */
+    private _buildRest;
+    /** `@name: value` named arg/param → `VarDeclaration`. The value is assembled by the
+     * shared value builder (`_assembleValue`) — the same machinery as a declaration
+     * value, so trivia and Keyword-ification are handled and no manual trimming is
+     * needed. Named args flow through function calls too; the runtime decides whether
+     * the target accepts them. */
+    private _buildNamedArg;
+    /** Mixin-call args are assembled by the SAME builder as function-call args
+     * (`_assembleArgs` via `_betweenParens`) — identical comma/semicolon and value
+     * handling. Named args are `VarDeclaration`s and variadic args `Rest`, which pass
+     * through as single components. A bare `@name` is a `Reference` (the call shape);
+     * the mixin-DEFINITION builder reinterprets a lone `@name` as a param. */
+    private _buildMixinArgs;
+    /** Less forbids mixing the COMMA and SEMICOLON argument separators: once a
+     * semicolon separates args, a comma is a value-list separator, so a semicolon-group
+     * may not hold 2+ named params (`@a: 1, @b: 2`). `_assembleArgs` renders such a group
+     * as a List of ≥2 VarDeclarations. (This is purely about the `,` vs `;` argument
+     * separators — a `/` inside a value is unrelated and never checked.) Applies to BOTH
+     * mixin and function calls (args are unified). */
+    private _checkMixedArgDelimiters;
+    /**
+     * Lower Less `;`-separated call args to the unified Jess representation: the outer
+     * args `List{ sep: ';' }` becomes comma-separated, and each element that is itself
+     * a comma-`List` (a `;`-group that held a comma-list) is wrapped in an escaped
+     * `Paren` — the same shape Jess authors write as `~(1, 2)`. So
+     * `.mixin(1, 2; 3, 4)` and Jess `mixin(~(1, 2), ~(3, 4))` converge on one AST.
+     *
+     * The escaped `Paren` evaluates to its inner value STRIPPED (paren.ts §escaped),
+     * so `~(1, 2)` binds/renders identically to the bare list `1, 2` — representation
+     * only, semantics unchanged. Scalar (non-List) elements pass through untouched.
+     *
+     * MUST run AFTER `_checkMixedArgDelimiters` (which inspects the `;`-List).
+     */
+    private _lowerSemiArgs;
+    /**
+     * Mixin-DEFINITION param conversion. With combinator-composed args a bare `@name`
+     * value parses as a `Reference{variable}` (the CALL shape); in a DEFINITION it is a
+     * param, so convert it to `VarDeclaration(name, Nil)`. Named params (`@a: 1`),
+     * variadic (`Rest`) and pattern-match values stay as-is. Returns a NEW List (the
+     * def/call split must not mutate a shared node).
+     */
+    private _convertArgsForDefinition;
+    /**
+     * Mixin-CALL argument conversion (reference `convertArgsForCall`, root.ts).
+     * `_buildMixinArgs` builds bare `@name` args as definition-style VarDeclarations
+     * (Nil value) — correct for a DEFINITION param, but in a CALL a bare `@name` is a
+     * variable being PASSED, i.e. a `Reference{type:variable}`. Named args (`@a: 1`)
+     * and value args stay as-is; a `Rest('name')` becomes `Rest(Reference{variable})`.
+     * Returns a NEW List (the def/call split must not mutate a shared node).
+     */
+    private _convertArgsForCall;
+    private _buildAnonMixin;
+    /**
+     * `each(<iterable>, { … })` → a `For` control node (the $for shape), not a Call.
+     * The value(s) before the comma are the iterable; the callback block's body becomes
+     * the loop rules. A literal block callback carries no captured params here, so the
+     * pattern defaults to the Less `[value, key, index]` triple.
+     */
+    /** A bare detached ruleset `{ … }` in value / argument position → a Mixin holding
+     * its rules (same shape `@var: { … }` produces in `_buildVarDeclaration`). */
+    private _buildDetachedRuleset;
+    private _buildEachFor;
+    private _eachPattern;
+    private _buildMixinOrQualified;
+    private _extractExtendsFromSelectorText;
+    private _selectorHasNestedExtend;
+    private _treeHasExtend;
+    /**
+     * A guarded ruleset (`sel when …`) is parsed by the shared CSS builder, which
+     * has no `when` concept, so the Guard CST child folds into the body as the
+     * first rule — always a Paren/Condition/DefaultGuard. Lift it into the
+     * ruleset's `guard` field (rebuilt through the canonical Ruleset ctor so the
+     * guard is adopted) so it gates output instead of rendering as a `{ true }`
+     * body. Non-guarded rulesets never begin their body with one of these node
+     * types, so the leading-node check is unambiguous.
+     */
+    private _liftRulesetGuard;
+    protected _buildRuleset(children: ReadonlyArray<Child>, rawChildren: ReadonlyArray<{
+        _tag: string;
+    }>, loc: LocationInfo): Ruleset;
+    private _extractExtendsFromSelector;
+    private static _isCssUrl;
+    private _buildImportAtRuleFromPrelude;
+    protected _buildAtRuleBlock(children: ReadonlyArray<Child>, loc: LocationInfo): JessNode;
+    /**
+     * Shared AtRule assembly used by both the flat `AtRuleBlock` builder and the
+     * structured, committed `QueryAtRuleBlock` builder. `preludeText` is the raw
+     * prelude source (already `{`/`}` stripped); routing it through
+     * `_buildAtRulePrelude` keeps the emitted AST identical regardless of which
+     * grammar rule matched.
+     */
+    private _buildAtRuleFromParts;
+    /**
+     * Builder for the structured, committed `@media`/`@container`/`@supports`
+     * query block. The grammar rule parses the prelude with real query structure
+     * (so a stray/unbalanced bracket is rejected instead of swallowed) and commits
+     * on `expect('{')`, but the AST is reconstructed from the prelude source text
+     * via the shared `_buildAtRuleFromParts` path — so well-formed queries emit the
+     * exact same AtRule the flat `AtRuleBlock` builder would.
+     */
+    private _buildLessQueryAtRuleBlock;
+    private _buildAtRulePrelude;
+    protected _buildAtRuleStatement(children: ReadonlyArray<Child>, loc: LocationInfo): JessNode;
+    private _buildUseAtRuleFromPrelude;
+    private _parenToArgs;
+    private _tryParseNamespaceRef;
+    private _assembleLessValue;
+}
+export {};
+//# sourceMappingURL=builders.d.ts.map

package/lib/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../src/builders.ts"],"names":[],"mappings":"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"}

package/lib/cst.cjs

@@ -0,0 +1,14 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_grammar = require("./grammar.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.lessGrammar, input, startRule, options);
+}
+/** Incremental (`.edit()`-able) Less document — see `parseDocCst`. */
+function parseLessDoc(input, startRule = "Stylesheet") {
+	return (0, _jesscss_css_parser_cst.parseDocCst)(require_grammar.lessGrammar, 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 { lessGrammar } from "./grammar.js";
+import { parseCst, parseDocCst } from "@jesscss/css-parser/cst";
+//#region src/cst.ts
+function parseLessCst(input, startRule = "Stylesheet", options) {
+	return parseCst(lessGrammar, input, startRule, options);
+}
+/** Incremental (`.edit()`-able) Less document — see `parseDocCst`. */
+function parseLessDoc(input, startRule = "Stylesheet") {
+	return parseDocCst(lessGrammar, input, startRule);
+}
+//#endregion
+export { parseLessCst, parseLessDoc };