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

package/README.md

@@ -1,13 +1,40 @@
 # @jesscss/scss-parser
 
-A [SCSS/Sass](https://sass-lang.com/) parser built on [parseman](https://www.npmjs.com/package/parseman). The grammar is the CSS grammar plus an SCSS delta: `scssGrammar = compose([cssGrammar, <SCSS delta>])`, layered on the shared CSS base in `@jesscss/css-parser`.
-
-The goal is **parse coverage**: not every Sass/SCSS feature is necessarily *evaluated*, but the surface syntax should parse. This is the earliest-stage of the four Jess parsers (`2.0.0-alpha.1`).
-
-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 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 SCSS 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.
+An SCSS grammar for Jess, layered on the CSS base parser — **experimental, and not the focus of the Less alpha.**
+
+> **Status: experimental / roadmap.** Part of
+> [Jess](https://github.com/jesscss/jess). The current alpha ships through
+> `.less`; SCSS is **not a goal of this phase**. This parser is early and exists
+> to seed the future **"Sass+"** dialect. Don't rely on it for production;
+> prefer [`@jesscss/css-parser`](https://www.npmjs.com/package/@jesscss/css-parser)
+> / [`@jesscss/less-parser`](https://www.npmjs.com/package/@jesscss/less-parser).
+> [Report bugs](https://github.com/jesscss/jess/issues); docs live at
+> [jesscss.github.io](https://jesscss.github.io/).
+
+## What it is
+
+The SCSS grammar is the shared CSS grammar plus an SCSS delta:
+`scssGrammar = compose([cssGrammar, <SCSS delta>])`, layered on the spec-aligned
+CSS base in `@jesscss/css-parser` and 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).
+
+The current goal is **parse coverage**: the surface `$`-variable / SCSS syntax
+should parse into a tree, but not every Sass/SCSS feature is necessarily
+*evaluated*. This is the least-mature of the Jess parsers (the `.jess` parser
+trails it), and the seed for the roadmap "Sass+" dialect rather than a shipped
+Sass replacement. The language roadmap is ordered: **Now Less.js → Next Sass+ →
+Final `.jess`.**
+
+Two parser representations are available:
+
+- **Canonical AST v2** — the default `parse()` entry constructs a `Stylesheet`
+  directly through parser-local Parseman reductions.
+- **Explicit CST** — the `./cst` entry has **no dependency on
+  `@jesscss/core`** and parses SCSS source text into a concrete syntax tree for
+  language-service/document consumers.
 
 ## Install
 
@@ -15,7 +42,20 @@ Two ways to use it:
 npm install @jesscss/scss-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 dependency — needed for the default
+AST v2 `parse()` entry, not for `./cst` or `./grammar`.
+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/scss-parser'
+
+const stylesheet = parse('$c: red;\n.foo { color: $c; }')
+
+stylesheet.type // 'Stylesheet'
+```
 
 ## Standalone usage (core-free)
 
@@ -45,8 +85,7 @@ Pass a different `startRule` (any capitalized grammar rule) to parse a fragment.
 | `@jesscss/scss-parser/cst` | `parseScssCst` | Core-free parse of an SCSS string to a CST. |
 | `@jesscss/scss-parser/cst` | `ScssCstNode`, `ScssCstLeaf`, `ScssCstError`, `ScssCstChild`, `ScssCstParseResult`, `ScssCstType` (types) | CST type definitions (aliases of the shared `@jesscss/css-parser/cst` types). |
 | `@jesscss/scss-parser/grammar` | `scssGrammar` | The compiled SCSS grammar (a rule map). Extend it with `compose()` or drive it directly with parseman's `run`. |
-| `@jesscss/scss-parser` (`.`) | `ScssParser` (also `Parser`), `parseScssFn`, `scssGrammar`, tokens, … | The Jess-internal barrel. **Core-coupled** (the functional parser builds the core AST). Prefer `./cst` if you don't need `@jesscss/core`. |
-| `@jesscss/scss-parser/jess` | `ScssParser`, `ScssGrammar`, `parseScssFn`, … | Internal Jess-facing surface. |
+| `@jesscss/scss-parser` (`.`) | `parse` | Parse SCSS directly to canonical AST v2 `Stylesheet`. It does not load the CST grammar. |
 
 ## Default CST shape
 
@@ -129,4 +168,7 @@ type BuildHost = (
 
 ## Part of Jess
 
-This package is developed as part of [Jess](https://github.com/jesscss/jess). The core-coupled `.` entry integrates with `@jesscss/core`; the `./cst` and `./grammar` entries are usable on their own. SCSS is the least-mature of the Jess dialects — prefer `@jesscss/css-parser` / `@jesscss/less-parser` for production use.
+This package is developed as part of [Jess](https://github.com/jesscss/jess).
+SCSS is the least-mature Jess dialect and is not the focus of the current
+alpha; it seeds the roadmap "Sass+" dialect. For production use, prefer
+`@jesscss/css-parser` / `@jesscss/less-parser`. Licensed MIT.