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

package/README.md

@@ -2,7 +2,14 @@
 
 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), which *is* Less.js v5. Only `.less` rendering ships today. SCSS is **not a goal of this phase** — this parser is early and exists to seed the future **"Sass+"** dialect (roadmap milestone #2, after Less.js). 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/).
+> **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
 
@@ -21,10 +28,13 @@ 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 ways to use it:
+Two parser representations are available:
 
-- **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.
+- **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
 
@@ -32,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)
 
@@ -62,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
 
@@ -146,4 +168,7 @@ type BuildHost = (
 
 ## Part of Jess
 
-This package is developed as part of [Jess](https://github.com/jesscss/jess), the Less.js v5 rewrite. SCSS is the least-mature Jess dialect and is not the focus of the Less alpha — it seeds the roadmap "Sass+" dialect. For production use, prefer `@jesscss/css-parser` / `@jesscss/less-parser`. Licensed MIT.
+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.