@jesscss/scss-parser 2.0.0-alpha.12 → 2.0.0-alpha.13

package/lib/grammar-helpers.d.ts

@@ -0,0 +1,234 @@
+/**
+ * SCSS grammar reducer helpers, hoisted out of `scss-parser/src/grammar.ts`.
+ *
+ * These are the module-private helpers the SCSS grammar's `node(...)` reducers
+ * call. They lived inside `grammar.ts` as free module scope, which is fine for a
+ * standalone `composeLeaf(...)` grammar but not for a COMPOSABLE delta: the
+ * parseman compose analyzer can only carry a reducer across a package boundary
+ * when every name the reducer reads has import provenance. A free module-private
+ * helper has none, so composing `[cssBaseRules, rules(scssDelta)]` refused them.
+ * Hoisting them into this importable module gives each one a resolvable import,
+ * and the analyzer re-emits those imports into the composing module.
+ *
+ * This is a pure code motion (B0-scss): every body is byte-identical to its
+ * former in-grammar definition and the helpers keep calling each other exactly
+ * as before. These are SCSS's OWN helpers — promoting the ones that turn out
+ * byte-identical to the css/less/jess helpers into the shared
+ * `@jesscss/core/ast` module is a separate, deferred dedup pass (guarded by the
+ * open-recursion rule: a helper is only shareable when its whole transitive
+ * helper-closure is identical too).
+ */
+import type { AnonymousMixin, AtRuleBlock, AtRuleStatement, CallArg, Collection, CollectionEntry, Color, Comment, CompoundSelector, Declaration, Dimension, ExtendInstruction, For, ForBinding, FunctionCall, GuardNode, If, IfValue, Interpolation, Keyword, Lookup, MixinCall, MixinDefinition, UnknownAtRuleBlock, Param, Quoted, Reference, Ruleset, SelectorBranch, SelectorList, SelectorTerm, SimpleSelector, SimpleToken, Statement, StyleImport, Token, Url, ValueNode, ValueSlot, VariableDeclaration, While } from '@jesscss/core/ast';
+export type ScssValuePair = {
+    readonly separator: string;
+    readonly value: ValueSlot;
+};
+export type ScssValueTail = {
+    readonly kind: 'space' | 'slash';
+    readonly value: ValueNode;
+    readonly separator: string;
+};
+/** One authored call argument. The AST's own {@link CallArg}, not a local
+ *  look-alike: a `$name:` argument is the SAME node whether the callee is a
+ *  mixin (`@include m($x: 1)`) or a function (`color.adjust($c, $lightness: -10%)`),
+ *  and every one is built by `callArg` so the array stays monomorphic. */
+export type ScssCallArg = CallArg<ValueSlot>;
+/** An argument-list separator carrying the argument it precedes. */
+export type ScssArgumentPair = {
+    readonly separator: string;
+    readonly value: ScssCallArg;
+};
+export type ScssSegmentCombinator = ' ' | '>' | '+' | '~' | '|' | '||';
+export declare const scriptModuleExtensions: readonly [".js", ".mjs", ".cjs", ".ts", ".mts", ".cts", ".json"];
+export declare function isScriptModulePath(path: string): boolean;
+export declare function requireToken(value: unknown): Token;
+export declare function scssSourceText(value: unknown): string;
+/** Map query/media-prelude children to value nodes, coercing bare keyword tokens
+ *  (`and`/`or`/media types) to `Keyword`s while passing structured values through. */
+export declare function keywordizeValues(children: readonly unknown[]): ValueNode[];
+/** Concatenate the authored spelling of every child. The canonical opaque
+ *  representation for attribute selectors and non-structured pseudo arguments. */
+export declare function joinSourceText(children: readonly unknown[]): string;
+/** Concatenate every child token value into one opaque static-prelude token. */
+export declare function joinTokenValue(children: readonly unknown[]): Token;
+/** Shared reducer for a static `"…"` / `'…'` quoted value: the opening quote is
+ * `children[0]`, the raw body is `children[1]`, and both the source spelling and
+ * decoded body are preserved verbatim (never interpolation). */
+export declare function staticQuoted(children: readonly unknown[]): Quoted;
+export declare function isQuoted(value: unknown): value is Quoted;
+export declare function isUrl(value: unknown): value is Url;
+export declare function isSimpleSelector(value: unknown): value is SimpleSelector;
+export declare function isCompoundSelector(value: unknown): value is CompoundSelector;
+export declare function isSelectorTerm(value: unknown): value is SelectorTerm;
+export declare function isScssSelectorBranch(value: unknown): value is SelectorBranch;
+export declare function isScssSelectorList(value: unknown): value is SelectorList;
+export declare function requireSelectorList(value: unknown): SelectorList;
+export declare const scssSelectorTermFromTokens: (tokens: readonly SimpleToken[]) => SelectorTerm;
+export declare function isScssSimpleToken(value: unknown): value is SimpleToken;
+export declare function scssCombinatorText(value: unknown): ' ' | '>' | '+' | '~' | '||';
+export declare function scssRelativeCombinator(value: unknown): '>' | '+' | '~';
+export declare function scssBranchSegments(branch: SelectorBranch): [{
+    combinator?: ScssSegmentCombinator;
+    term: SelectorTerm;
+}, ...Array<{
+    combinator?: ScssSegmentCombinator;
+    term: SelectorTerm;
+}>];
+export declare function isScssImportTarget(value: unknown): value is Quoted | Url | Interpolation;
+export declare function isParam(value: unknown): value is Param;
+export declare function isParamArray(value: unknown): value is Param[];
+export declare function isAnonymousMixin(value: unknown): value is AnonymousMixin;
+export declare function requireForBinding(value: unknown): ForBinding;
+export declare function requireString(value: unknown): string;
+export declare function isVarRef(value: unknown): value is Lookup;
+export declare function isColor(value: unknown): value is Color;
+export declare function isDimension(value: unknown): value is Dimension;
+export declare function isFunctionCall(value: unknown): value is FunctionCall;
+export declare function isScssInterpolation(value: unknown): value is Interpolation;
+export declare function requireInterpolation(value: unknown): Interpolation;
+export declare function appendLiteral(parts: Interpolation['parts'], text: string): void;
+/** Flatten a grammar-owned raw template without ever reparsing its bytes. */
+export declare function interpolationFromTemplateChildren(children: readonly unknown[]): Interpolation;
+/**
+ * Turn the grammar-owned parts of a custom-property value into one canonical
+ * value. Custom-property values are not evaluated: everything outside a typed
+ * `#{…}` stays literal `<declaration-value>` text, so the reduction only joins
+ * grammar children — it never rescans source. Nested balanced groups arrive as
+ * nested arrays from the paren/square/curly productions.
+ */
+export declare function customValueFromParts(children: readonly unknown[], parts: Interpolation['parts'], seen: {
+    interpolated: boolean;
+}): void;
+/** Reduce a whole custom-property value to `Interpolation` (when it carries a
+ * `#{…}`) or to verbatim `Any` text. */
+export declare function customValue(children: readonly unknown[]): ValueNode;
+export declare function isArithmeticOperator(text: string): boolean;
+/** Fold a grammar-produced left-associative operator chain. Precedence belongs
+ * to the caller's product/sum production, never to a source-text recovery.
+ *
+ * Operands and operator characters arrive in authored order with the operators'
+ * padding interleaved. The pads are their own terms, so an operator no longer
+ * sits a constant distance from its operand and the fold reads the shape rather
+ * than a fixed stride — and a pad can hold a comment whose own `/` and `*` would
+ * defeat any attempt to recover the operator from the padded text. */
+export declare function scssFoldOperation(children: readonly unknown[]): ValueNode;
+export declare function isScssValue(value: unknown): value is ValueNode;
+export declare function scssValueSlot(value: ValueNode): ValueSlot;
+export declare function isSequence(value: ValueSlot): value is Extract<ValueNode, {
+    type: 'Sequence';
+}>;
+export declare function isScssValueSlotValue(value: unknown): value is ValueSlot;
+export declare function requireValueSlot(value: unknown): ValueSlot;
+export declare function isScssDeclaration(value: unknown): value is Declaration;
+export declare function isCollection(value: unknown): value is Collection;
+export declare function isCollectionEntry(value: unknown): value is CollectionEntry;
+export declare function isRuleset(value: unknown): value is Ruleset;
+export declare function isMixinDefinition(value: unknown): value is MixinDefinition;
+export declare function isMixinCall(value: unknown): value is MixinCall;
+export declare function isFor(value: unknown): value is For;
+export declare function isIf(value: unknown): value is If;
+export declare function isWhile(value: unknown): value is While;
+export declare function isAtRuleBlock(value: unknown): value is AtRuleBlock;
+export declare function isAtRuleStatement(value: unknown): value is AtRuleStatement;
+export declare function isComment(value: unknown): value is Comment;
+export declare function isStyleImport(value: unknown): value is StyleImport;
+export declare function isExtendInstruction(value: unknown): value is ExtendInstruction;
+export declare function requireValue(value: unknown): ValueNode;
+export declare function requireKeyword(value: unknown): Keyword;
+/** The best-effort authored spelling of a value node for a Reference `raw`. */
+export declare function referenceKeyRaw(node: ValueNode): string;
+/** The `.jess` spelling of one `@content(…)` argument, used to build the lowered
+ *  `$content(…)` Reference `raw`. Same read as {@link referenceKeyRaw}, plus the
+ *  `$name:` prefix a named argument carries. */
+export declare function contentArgRaw(arg: ScssCallArg): string;
+/** `map.get` is the `sass:map` module spelling of the global `map-get`. Both are
+ *  the same function, so both lower to the same accessor read — a grammar that
+ *  accepted only one spelling into the accessor form would emit two different
+ *  trees for one semantics. */
+export declare const MAP_GET_SPELLINGS: Set<string>;
+/** The comparison spellings a call argument may carry (§4.5.2). Named here so
+ * the operator token is found by WHAT IT IS rather than by a child index the
+ * optional trivia arms would shift. */
+export declare const COMPARISON_OPERATORS: Set<string>;
+/** Lower `map-get($m, k)` to the shared `$[…]` accessor read `$m[k]`: a Reference
+ *  whose single LookupStep carries the key. A `$var` key selects the
+ *  variable-namespace lookup; every other key is a value-equality member lookup
+ *  (map keys compare by value, never by position, so `index` is never used). */
+export declare function lowerMapGet(base: ValueNode, key: ValueNode): Reference;
+/**
+ * Lower Sass `if(<cond>, a, b)` to the value-position `$if` (§4.5.3b).
+ *
+ * It wears call parentheses but it is SYNTAX, not a function (§4.5.3a) — it is
+ * branch-lazy and its first argument is a condition, neither of which a
+ * `sassFns` entry could express. Lowering it here, in the grammar that knows the
+ * dialect, is what lets ONE evaluator answer `if(0, T, F)` with `T` for `.scss`
+ * and `F` for `.less`: {@link scssTruth} fixes Sass+'s rule (§4.4.6 — falsy iff
+ * `false`, `null`, `""` or `()`) at parse time, Less's grammar fixes its own,
+ * and core never learns which dialect a guard came from.
+ *
+ * Anything but the three-argument form is left an ordinary call — plain CSS
+ * `if()` is not this construct.
+ */
+export declare function lowerSassIf(args: readonly ScssCallArg[]): IfValue | undefined;
+export declare function reduceScssCall(name: string, children: readonly unknown[], minArgumentIndex: number): FunctionCall | Reference | IfValue;
+/** A Sass map key stays an authored value node; equality belongs to value-domain
+ * map comparison, not to declaration-name stringification. */
+export declare function mapKeyValue(node: ValueNode): ValueSlot;
+/**
+ * The SCSS condition lowering (§4.4.2, as revised by §4.4.6): `@if $x` means
+ * `$if($x)` — the SAME truth node `.jess` uses.
+ *
+ * **Sass+ takes §4.4's emptiness rule** (owner, 2026-08-07): falsy iff `false`,
+ * `null`, `""` or `()`. It previously spelled Sass's own rule out —
+ * `not(($x == false) or ($x == null))` — to keep `""` and `()` truthy. What
+ * forced the change was INTERNAL CONTRADICTION, not reference parity: `or`/`and`
+ * lower to jess's native operators (§4.5.5), so `.scss "" or 2` already answered
+ * `2` under jess truthiness while `@if ""` took the true branch under Sass's.
+ * One dialect, one value, two answers, decided by which construct you wrote.
+ *
+ * This is why `.scss` must mint the value-domain `Null` (§4.3): with
+ * `keyword('null')` in the value lane, `$if($x)` would silently take the TRUE
+ * branch for `null`.
+ *
+ * `.less` is unaffected — `when (@x)` still lowers to `$if($x == true)`.
+ */
+export declare function scssTruth(value: ValueSlot): GuardNode;
+/**
+ * Sass's `not <value>` — the NEGATION of {@link scssTruth}, i.e. "is `$x`
+ * falsy". Under §4.4.6 that is exactly jess's `not($x)`, so it is the truth node
+ * under a `not` wrapper and cannot drift from the positive form.
+ */
+export declare function scssNegation(value: ValueSlot): GuardNode;
+/**
+ * The authored spelling of a `not` operand, kept so the {@link Condition} it
+ * lowers to can replay verbatim when no evaluator is injected. Same job — and
+ * the same explicit type list — as the Less grammar's condition source: a shape
+ * with no known spelling is a recognition defect, not something to guess at.
+ */
+export declare function scssConditionSource(value: ValueSlot): string;
+/**
+ * Fold one logical rung left-associatively onto `Operation` nodes carrying the
+ * word itself as the operator. The operator token is kept out of the fold by
+ * shape (only values participate), so the rung reduces the same way whether it
+ * spelled `and` or `or`.
+ */
+export declare function foldLogicalOperation(children: readonly unknown[]): ValueNode;
+export declare function isGuardNode(value: unknown): value is GuardNode;
+export declare function requireGuardNode(value: unknown): GuardNode;
+export declare function scssOptionalValue(value: unknown): ValueNode | null;
+/** A reduced {@link ScssCallArg} — the payload every argument production yields. */
+export declare function isScssCallArg(value: unknown): value is ScssCallArg;
+export declare function requireScssCallArg(value: unknown): ScssCallArg;
+/** An {@link ScssArgumentPair} — a separator plus the argument it precedes. */
+export declare function isScssArgumentPair(value: unknown): value is ScssArgumentPair;
+export declare function isScssValuePair(value: unknown): value is ScssValuePair;
+export declare function isScssValueTail(value: unknown): value is ScssValueTail;
+export declare function isVarDeclaration(value: unknown): value is VariableDeclaration;
+export declare function isStatementChild(child: unknown, allowDeclarations: boolean): child is Statement;
+export declare function isReferenceStatement(value: unknown): value is Reference;
+export declare function isUnknownAtRuleBlock(value: unknown): value is UnknownAtRuleBlock;
+export declare function statements(children: readonly unknown[], allowDeclarations?: boolean): Statement[];
+export declare function statementChildren(children: readonly unknown[], allowDeclarations?: boolean): Statement[];
+export declare function requireStatementList(value: unknown): Statement[];
+export declare function keyframeSelectorListFromChildren(children: readonly unknown[]): SelectorList;
+export declare function scssPseudoName(opener: string): string;

package/lib/grammar.d.ts

@@ -1,6 +1,6 @@
-export declare const scssGrammar: Record<string, import("parseman").Runnable>;
+export declare const scssGrammar: Record<string, import("parseman").FusedRule>;
 /** AST artifact with Parseman line/column tracking enabled. */
-export declare const scssPositionsGrammar: Record<string, import("parseman").Runnable>;
-export declare const scssCstGrammar: Record<string, import("parseman").Runnable>;
+export declare const scssPositionsGrammar: Record<string, import("parseman").FusedRule>;
+export declare const scssCstGrammar: Record<string, import("parseman").FusedRule>;
 /** CST artifact with Parseman line/column tracking enabled. */
-export declare const scssCstPositionsGrammar: Record<string, import("parseman").Runnable>;
+export declare const scssCstPositionsGrammar: Record<string, import("parseman").FusedRule>;

package/package.json

@@ -4,9 +4,9 @@
     "access": "public"
   },
   "description": "",
-  "version": "2.0.0-alpha.12",
+  "version": "2.0.0-alpha.13",
   "engines": {
-    "node": "^20.19.0 || >=22.18.0"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "main": "lib/index.cjs",
   "types": "lib/index.d.ts",
@@ -62,11 +62,11 @@
     "lib"
   ],
   "dependencies": {
-    "@jesscss/css-parser": "2.0.0-alpha.12"
+    "@jesscss/css-parser": "2.0.0-alpha.13"
   },
   "peerDependencies": {
-    "parseman": "^0.50.1",
-    "@jesscss/core": "2.0.0-alpha.12"
+    "parseman": "^0.50.5",
+    "@jesscss/core": "2.0.0-alpha.13"
   },
   "peerDependenciesMeta": {
     "@jesscss/core": {
@@ -74,10 +74,10 @@
     }
   },
   "devDependencies": {
-    "parseman": "^0.50.1",
+    "parseman": "^0.50.5",
     "sass-spec": "github:sass/sass-spec",
-    "@jesscss/parser-shared": "2.0.0-alpha.12",
-    "@jesscss/core": "2.0.0-alpha.12"
+    "@jesscss/core": "2.0.0-alpha.13",
+    "@jesscss/parser-shared": "2.0.0-alpha.13"
   },
   "author": "Matthew Dean <matthew-dean@users.noreply.github.com>",
   "license": "MIT",