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

package/README.md

@@ -1,11 +1,29 @@
 # @jesscss/less-parser
 
-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`.
-
-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.
+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
 
@@ -13,7 +31,20 @@ Two ways to use it:
 npm install @jesscss/less-parser
 ```
 
-`@jesscss/core` is an **optional** peer dependency — needed only for the core-coupled `.` entry, not for `./cst` or `./grammar`.
+`@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)
 
@@ -43,8 +74,7 @@ Pass a different `startRule` (any capitalized grammar rule, e.g. `'SelectorList'
 | `@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. |
+| `@jesscss/less-parser` (`.`) | `parse` | Parse Less directly to canonical AST v2 `Stylesheet`. It does not load the CST grammar. |
 
 ## Default CST shape
 
@@ -131,34 +161,6 @@ type BuildHost = (
 
 ## 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
-
-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];`?
+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/ast/grammar.d.ts

@@ -0,0 +1,2 @@
+export declare const lessAstGrammar: Record<string, import("parseman").FusedRule>;
+//# sourceMappingURL=grammar.d.ts.map

package/lib/ast/grammar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grammar.d.ts","sourceRoot":"","sources":["../../src/ast/grammar.ts"],"names":[],"mappings":"AA49CA,eAAO,MAAM,cAAc,8CAuhGvB,CAAC"}