@jesscss/scss-parser 2.0.0-alpha.7

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2018 Matthew Dean
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,132 @@
+# @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.
+
+## Install
+
+```sh
+npm install @jesscss/scss-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 { parseScssCst } from '@jesscss/scss-parser/cst'
+
+const result = parseScssCst('$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
+parseScssCst(input: string, startRule = 'Stylesheet', options?: { collapse?: boolean }): ScssCstParseResult
+```
+
+Pass a different `startRule` (any capitalized grammar rule) to parse a fragment.
+
+## Public API
+
+| Entry | Export | Purpose |
+| --- | --- | --- |
+| `@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. |
+
+## 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 and 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": "node", "type": "InterpolatedSelector", "grammarType": "InterpolatedSelector",
+          "children": [ { "_tag": "leaf", "value": "." }, { "_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 SCSS-specific nodes: `$c: …` becomes a `VarDeclaration`, `$c` in value position becomes a `Reference`, selectors parse through `InterpolatedSelector` (so `#{…}` interpolation is captured in place), and the color keyword `red` parses as `NamedColor`.
+
+Pass `{ collapse: true }` to unwrap single-child wrapper types (`Reference`, `NamedColor`, `InterpolatedSelector`) into their child.
+
+## 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 { scssGrammar } from '@jesscss/scss-parser/grammar'
+
+const myHost = (type, children, fields, span) => ({ type, span, children: children.filter(Boolean) })
+
+const result = run(scssGrammar.Stylesheet, '$c: red; .foo { color: $c; }', {
+  build: myHost,
+  trivia: scssGrammar.rw
+})
+
+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
+```
+
+`parseScssCst(...)` 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). 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.

package/lib/builders.d.ts

@@ -0,0 +1,154 @@
+/**
+ * ScssGrammar — Parséman-based SCSS parser, extending LessGrammar.
+ *
+ * Adds SCSS-specific grammar on top of Less (which in turn extends CSS):
+ *   - Variable declarations: $var: value [!default|!global];  →  VarDeclaration
+ *   - Variable references:   $var                             →  Reference
+ *   - Line comments:         // ...  (added to rw trivia)
+ *
+ * Inherits from LessGrammar:
+ *   - Nested rulesets, & ampersand, relative selectors
+ *   - anyDeclaration entry point
+ *   - atRuleBody, declarationList, Stylesheet overrides
+ *   - Less merge operators on Declaration (harmless for SCSS)
+ *
+ * Chevrotain note: in the Chevrotain architecture, ScssRecursiveParser
+ * extends CssRecursiveParser independently of LessRecursiveParser.
+ * Here we take the Parséman inheritance chain
+ * CssParser → LessGrammar → ScssGrammar to maximise code reuse.
+ */
+import type { FieldMap, Span } from 'parseman';
+import type { CSTLeaf, CSTError } from 'parseman';
+import { LessGrammar } from '@jesscss/less-parser/jess';
+import { type Node, type LocationInfo, type TreeContext, Rules, Quoted } from '@jesscss/core';
+type JessNode = Node<any, any>;
+type Child = JessNode | CSTLeaf | CSTError;
+export declare class ScssGrammar extends LessGrammar {
+    rw: import("parseman").Combinator<string>;
+    protected _trivia: import("parseman").Combinator<string>;
+    protected _parseContext?: TreeContext;
+    setContext(context?: TreeContext): void;
+    scssVar: import("parseman").Combinator<string>;
+    VarDeclaration: (g: any) => import("parseman").Combinator<[unknown, string, unknown, string | null, string | null]>;
+    Reference: (g: any) => any;
+    protected buildNode(type: string, span: Span, children: ReadonlyArray<JessNode | CSTLeaf | CSTError>, _state: unknown, _rawChildren: ReadonlyArray<{
+        _tag: string;
+    }>, fields?: FieldMap, triviaLog?: readonly number[]): JessNode;
+    private _buildScssVarDeclaration;
+    /**
+     * `ns.$member: value [!default|!global];` — a namespaced variable ASSIGNMENT.
+     * Built as a `VarDeclaration` whose name carries the namespace (`ns.member`);
+     * `!default` → conditional-assign, `!global` → `setDefined`. Mirrors the
+     * member-read shape (`Reference{ target, key }`) on the write side while
+     * staying within the `string | Interpolated` declaration-name contract.
+     */
+    private _buildScssNsVarDeclaration;
+    private _buildScssReference;
+    /**
+     * `left [op right]` → Condition, or a bare operand when there is no operator.
+     * `!=` desugars to `=` + negate (matches the Chevrotain scssComparison).
+     */
+    private _buildScssComparison;
+    /**
+     * Every condition term is wrapped in a Paren, matching the Chevrotain
+     * `scssConditionInParens` production (both the `( … )` group and the bare
+     * comparison / value branch wrap their result in a single Paren).
+     */
+    private _buildScssCondInParens;
+    /** Optional leading `not` negates the term. */
+    private _buildScssCondTerm;
+    /** Fold a left-associative `and` / `or` chain of terms into Conditions. */
+    private _buildScssCondJoin;
+    /** A `{ … }` control-block body → Rules. */
+    private _buildScssRules;
+    /**
+     * `@if cond { … } (@else if cond { … })* (@else { … })?` → nested `If` chain.
+     * Children arrive as alternating condition / Rules nodes, with an optional
+     * trailing bare Rules (the final `@else`). Fold from the last branch inward.
+     */
+    private _buildScssIf;
+    /** A `$name` loop-binding with no value (`paramVar` — prints as `$name`). */
+    private _scssParamVar;
+    /**
+     * `@each $a[, $b …] in <expr> { … }` → `For` with a node iterable.
+     * Normalizes to Jess `$for ($a of …)` / `$for ([$a, $b] of …)`.
+     */
+    private _buildScssEach;
+    /**
+     * `@for $i from <start> (to|through) <end> { … }` → `For` with a range iterable.
+     * `through` is inclusive end; `to` is exclusive (`includeEnd: false`).
+     */
+    private _buildScssFor;
+    /** `@while <cond> { … }` → `While`. */
+    private _buildScssWhile;
+    /** Build a module-qualified or plain mixin `Reference`. */
+    private _buildScssMixinName;
+    /** `$x: val` keyword arg, `val...` spread, or plain value. */
+    private _buildScssCallArg;
+    private _buildScssCallArgsInner;
+    /** Mixin param: `...$rest`, `$rest...`, `$a: default`, or bare `$a`. */
+    private _buildScssMixinParam;
+    private _buildScssMixinParams;
+    /** `@mixin name($params) { … }` → `Mixin` (inner vars default to private). */
+    private _buildScssMixin;
+    /** `using ($c, $n)` param list for `@include … using (…)`. */
+    private _buildScssIncludeUsing;
+    /**
+     * `@include name(args) [using (…)] [ { … } ];` → `Call(Reference(type=mixin))`.
+     * An optional content block becomes an anonymous visible `Mixin` on the call.
+     */
+    private _buildScssInclude;
+    /** `@content[(args)];` → `Call(Reference('content', type=mixin))`. */
+    private _buildScssContent;
+    /** `@function name($params) { … }` → `Func` with `returnName: 'result'`. */
+    private _buildScssFunction;
+    /** `@return <value>;` → `$result: <value>;` */
+    private _buildScssReturn;
+    private _buildScssInterpBare;
+    /** `foo-#{$bar}` name segments → Interpolated(role=name) or plain Any. */
+    private _buildScssInterpolatedName;
+    private _buildScssInterpValue;
+    private _buildScssInterpolatedSelector;
+    private _scssInterpDeclName;
+    private _buildScssDeclaration;
+    private _buildScssCustomDeclaration;
+    protected _buildQuoted(children: ReadonlyArray<Child>, loc: LocationInfo): Node<any, any> | Quoted;
+    /** `("k": v, …)` pair inside a map literal. */
+    private _buildScssMapPair;
+    private _buildScssMapLiteral;
+    /** `ns.$var`, `ns.fn(…)`, `ns.\#foo(…)`, or a plain ident. */
+    private _buildScssIdentValue;
+    protected _buildStylesheet(children: ReadonlyArray<Child>, loc: LocationInfo): Rules<never, import("@jesscss/core").RulesOptions & Record<string, any> & {
+        semi?: boolean;
+    }>;
+    private _flattenScssImportLists;
+    private _buildScssNestedProps;
+    private _buildScssDiagnostic;
+    private _buildScssAtRootFilter;
+    private _buildScssAtRootSelector;
+    private _buildScssAtRootPlain;
+    private _buildScssWithConfigEntry;
+    private _buildScssWithConfig;
+    private _buildScssUseAs;
+    private _buildScssUse;
+    private _buildScssForward;
+    private _buildScssPlaceholderSelector;
+    private _buildScssPermissiveAtRule;
+    private _buildScssLayerBlock;
+    protected _buildQueryAtRuleBlock(children: ReadonlyArray<Child>, loc: LocationInfo): JessNode;
+    protected _buildScssParen(rawChildren: ReadonlyArray<{
+        _tag: string;
+    }>, loc: LocationInfo): JessNode;
+    private _buildScssExtendTarget;
+    private _scssExtendTargetFrom;
+    private _buildScssExtend;
+    private _buildScssImportItem;
+    private _buildScssImportAtRule;
+    protected _buildCall(rawChildren: ReadonlyArray<{
+        _tag: string;
+    }>, loc: LocationInfo): JessNode;
+    protected _buildSquareParen(rawChildren: ReadonlyArray<{
+        _tag: string;
+    }>, loc: LocationInfo): JessNode;
+}
+export {};

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 parseScssCst(input, startRule = "Stylesheet", options) {
+	return (0, _jesscss_css_parser_cst.parseCst)(require_grammar.scssGrammar, input, startRule, options);
+}
+/** Incremental (`.edit()`-able) SCSS document — see `parseDocCst`. */
+function parseScssDoc(input, startRule = "Stylesheet") {
+	return (0, _jesscss_css_parser_cst.parseDocCst)(require_grammar.scssGrammar, input, startRule);
+}
+//#endregion
+exports.parseScssCst = parseScssCst;
+exports.parseScssDoc = parseScssDoc;

package/lib/cst.d.ts

@@ -0,0 +1,5 @@
+import { type CssCstNode, type CssCstParseOptions, type CssCstParseResult, type ParseDoc } from '@jesscss/css-parser/cst';
+export declare function parseScssCst(input: string, startRule?: string, options?: CssCstParseOptions): CssCstParseResult;
+/** Incremental (`.edit()`-able) SCSS document — see `parseDocCst`. */
+export declare function parseScssDoc(input: string, startRule?: string): ParseDoc<CssCstNode>;
+export type { CssCstChild as ScssCstChild, CssCstError as ScssCstError, CssCstLeaf as ScssCstLeaf, CssCstNode as ScssCstNode, CssCstParseOptions as ScssCstParseOptions, CssCstParseResult as ScssCstParseResult, CssCstType as ScssCstType } from '@jesscss/css-parser/cst';

package/lib/cst.js

@@ -0,0 +1,12 @@
+import { scssGrammar } from "./grammar.js";
+import { parseCst, parseDocCst } from "@jesscss/css-parser/cst";
+//#region src/cst.ts
+function parseScssCst(input, startRule = "Stylesheet", options) {
+	return parseCst(scssGrammar, input, startRule, options);
+}
+/** Incremental (`.edit()`-able) SCSS document — see `parseDocCst`. */
+function parseScssDoc(input, startRule = "Stylesheet") {
+	return parseDocCst(scssGrammar, input, startRule);
+}
+//#endregion
+export { parseScssCst, parseScssDoc };