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

package/lib/grammar-helpers.d.ts

@@ -0,0 +1,208 @@
+/**
+ * Jess grammar reducer helpers, hoisted out of `jess-parser/src/grammar.ts`.
+ *
+ * These are the module-private helpers the Jess grammar's `node(...)`/`leaf(...)`
+ * 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 `compose([cssBaseRules, rules(jessDelta)])`
+ * 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. A relative same-package import is sufficient (proven by B0-less):
+ * parseman carries same-package relative-import provenance, not only
+ * workspace-package imports.
+ *
+ * This is a pure code motion (B0-jess): every body is byte-identical to its
+ * former in-grammar definition and the helpers keep calling each other exactly
+ * as before. No reducer logic, recognition const, or rule structure changed.
+ *
+ * Cross-dialect dedup (promoting the helpers that turn out byte-identical to the
+ * css/scss/less helpers into the shared `@jesscss/core/ast` module) is
+ * deliberately DEFERRED to a separate pass, guarded by the open-recursion rule:
+ * a helper is only shareable when its whole transitive helper-closure is
+ * identical too.
+ */
+import type { FieldCapture, FieldMap } from 'parseman';
+import type { Token, AnonymousMixin, Apply, AtRuleBlock, AtRuleStatement, Combinator as AstCombinator, Declaration, CollectionEntry, ExtendInstruction, For, ForBinding, If, IfBranch, InterpPart, Interpolation, Keyword, MixinCall, MixinDefinition, UnknownAtRuleBlock, Param, Quoted, PseudoSelector, Reference, SelectorBranch, SelectorTerm, Ruleset, SelectorList, SimpleSelector, SimpleToken, Sequence, Statement, StyleImport, Url, ValueNode, ValueSlot, VariableDeclaration, Lookup, GuardNode, While } from '@jesscss/core/ast';
+type ExpressionFact = {
+    readonly value: ValueNode;
+    readonly src: string;
+};
+type JessOperatorFact = {
+    readonly value: string;
+    readonly src: string;
+};
+type JessReferenceTail = {
+    readonly step: Reference['steps'][number];
+    readonly src: string;
+};
+type JessComplexTail = {
+    readonly combinator: ' ' | '>' | '+' | '~' | '||';
+    readonly term: SelectorTerm;
+};
+type JessSelectorSegment = {
+    combinator?: AstCombinator;
+    term: SelectorTerm;
+};
+type JessQueryFeatureName = {
+    readonly property: Keyword;
+};
+type JessAtRuleHeader = {
+    readonly name: string;
+    readonly prelude: ValueNode | null;
+};
+type JessMixinCallArgument = MixinCall['args'][number];
+declare function requireToken(value: unknown): Token;
+declare function requireFields(fields: FieldMap | undefined, name: string): readonly FieldCapture[];
+declare function jessCombinator(value: Token): JessComplexTail['combinator'];
+declare function jessRelativeCombinator(child: unknown): '>' | '+' | '~';
+declare function jessBranchSegments(branch: SelectorBranch): [JessSelectorSegment, ...JessSelectorSegment[]];
+declare function isExpressionFact(value: unknown): value is ExpressionFact;
+declare function isJessAtRuleHeader(value: unknown): value is JessAtRuleHeader;
+declare function requireJessAtRuleHeader(value: unknown): JessAtRuleHeader;
+declare function isAtRuleNameToken(value: unknown): value is Token;
+declare function isSelectorTerm(value: unknown): value is SelectorTerm;
+declare function isSimpleSelector(value: unknown): value is SimpleSelector;
+declare function isJessSelectorBranch(value: unknown): value is SelectorBranch;
+declare function isJessSelectorList(value: unknown): value is SelectorList;
+declare function isJessReferenceTail(value: unknown): value is JessReferenceTail;
+declare function isPseudoSelector(value: unknown): value is PseudoSelector;
+declare function isSimpleToken(value: unknown): value is SimpleToken;
+declare const selectorTermFromTokens: (tokens: readonly SimpleToken[]) => SelectorTerm;
+declare function requireSelectorList(value: unknown): SelectorList;
+declare function requireJessReferenceTail(value: unknown): JessReferenceTail;
+declare function requireString(value: unknown): string;
+declare function requireInterpolation(value: unknown): Interpolation;
+declare function requireKeyword(value: unknown): Keyword;
+declare function staticSelectorText(selector: SelectorList): string;
+declare const JESS_STRUCTURED_PSEUDOS: Set<string>;
+declare function isExtendInstruction(value: unknown): value is ExtendInstruction;
+declare function isParam(value: unknown): value is Param;
+declare function isParamList(value: unknown): value is Param[];
+declare function isMixinCallArray(value: unknown): value is MixinCall[];
+declare function isExtendInstructionArray(value: unknown): value is ExtendInstruction[];
+declare function isValueNode(value: unknown): value is ValueNode;
+declare function isValueNodeArray(value: unknown): value is ValueNode[];
+declare function isValueSlotArray(value: ValueSlot): value is readonly ValueSlot[];
+declare function jessValueSlot(value: ValueSlot): ValueSlot;
+declare function isSequence(value: ValueSlot): value is Sequence;
+declare function isJessValueSlotValue(value: unknown): value is ValueSlot;
+declare function requireValueSlot(value: unknown): ValueSlot;
+declare function isJessMixinCallArgument(value: unknown): value is JessMixinCallArgument;
+declare function requireValueNode(value: unknown): ValueNode;
+declare function isGuardNode(value: unknown): value is GuardNode;
+declare function requireGuardNode(value: unknown): GuardNode;
+declare function isJessInterpolation(value: unknown): value is Interpolation;
+declare function isInterpolationLiteral(part: InterpPart): part is {
+    readonly lit: string;
+};
+declare function appendInterpolationLiteral(parts: Interpolation['parts'], text: string): void;
+declare function templateInterpolationFromChildren(children: readonly unknown[]): Interpolation;
+/**
+ * Flatten the grammar-owned parts of a custom-property value. Custom-property
+ * values are never evaluated, so every byte outside a typed `$[…]` segment
+ * stays literal `<declaration-value>` text and the reduction only joins grammar
+ * children — it never rescans source. Nested balanced groups arrive as nested
+ * arrays from the paren/square/curly productions.
+ */
+declare function appendCustomValueParts(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. */
+declare function customValueFromChildren(children: readonly unknown[]): ValueNode;
+declare function requireExpressionFact(value: unknown): ExpressionFact;
+declare function requireJessOperatorFact(value: unknown): JessOperatorFact;
+declare function foldExpression(children: readonly unknown[]): ExpressionFact;
+/**
+ * A {@link Lookup} name is `string | ValueNode` now that `@@indirect` is spelled
+ * as a node-valued name; a literal name is its own spelling, a node-valued one
+ * defers to the expression printer.
+ */
+declare function lookupNameSource(name: string | ValueNode): string;
+declare function expressionSource(value: ValueNode): string;
+/**
+ * Fold one logical rung left-associatively (§4.5.5). The result is an
+ * `Operation` carrying the word itself as its operator — the node that means
+ * "return one of these operands, short-circuiting" — so the transpiled `.jess`
+ * still reads `$a or $default` rather than a rewritten `$if` that duplicates
+ * the operand and no direct author would write.
+ */
+declare function foldLogicalExpression(kind: 'and' | 'or', children: readonly unknown[]): ExpressionFact;
+declare function referenceBaseSource(value: ValueNode): string;
+/** A member step is a `LookupStep` whose name is a literal — the old `DotLookup`. */
+declare function isMemberStep(step: JessReferenceTail['step'] | undefined): boolean;
+declare function declarationMemberReferenceFromVariableBase(base: Lookup, tails: readonly JessReferenceTail[]): Reference | null;
+declare function interpolationFromChildren(children: readonly unknown[], span?: {
+    readonly start: number;
+    readonly end: number;
+}): Interpolation;
+/**
+ * Reduce a `${…}` interpolation. BARE-vs-BRACKETED selects the namespace:
+ *
+ * - `${foo}`      → the VARIABLE `$foo`
+ * - `${[foo]}`    → a LOOKUP, i.e. the PROPERTY `foo` declared in scope
+ * - `${["a b"]}`  → the same lookup; the quotes are only escaping, because
+ *                   `a b` is not a valid identifier. `[foo]` and `["foo"]` are
+ *                   the same plain-string key (ledger P14), so quoting never
+ *                   carries meaning here.
+ * - `${[$k]}`     → a lookup whose key is computed from `$k`.
+ */
+declare function dollarBraceInterpolation(children: readonly unknown[], span?: {
+    readonly start: number;
+    readonly end: number;
+}): Interpolation;
+declare function referenceArgSource(value: JessMixinCallArgument['value']): string;
+declare function tokenSource(children: readonly unknown[]): string;
+declare function sourceFromState(state: unknown): string | undefined;
+declare function interpolationValue(child: unknown): Interpolation;
+declare function quotedInterpolationFromChildren(children: readonly unknown[]): Quoted | Interpolation;
+declare function escapedInterpolationFromChildren(children: readonly unknown[]): Interpolation;
+declare function quotedExpressionFact(children: readonly unknown[]): ExpressionFact;
+declare function reduceColonFeature(children: readonly unknown[], lostMessage: string): ValueNode;
+declare function jessFunctionOpenName(child: unknown): string;
+declare function requireStatements(children: readonly unknown[]): Statement[];
+declare function collectBlockStatements(children: readonly unknown[], open: number): Statement[];
+declare function collectBodyStatements(children: readonly unknown[], open: number): Statement[];
+declare function requireStatementList(value: unknown): Statement[];
+declare function isIfBranch(value: unknown): value is IfBranch;
+declare function requireIfBranch(value: unknown): IfBranch;
+declare function requireIfBranchArray(value: unknown): IfBranch[];
+declare function requireIfBranchTuple(value: IfBranch[]): [IfBranch, ...IfBranch[]];
+declare function requireForBinding(value: unknown): ForBinding;
+declare function isAtRuleBlock(value: unknown): value is AtRuleBlock;
+declare function isAtRuleStatement(value: unknown): value is AtRuleStatement;
+declare function isUnknownAtRuleBlock(value: unknown): value is UnknownAtRuleBlock;
+declare function isStyleImport(value: unknown): value is StyleImport;
+declare function isApply(value: unknown): value is Apply;
+declare function isReferenceCall(value: unknown): value is Reference;
+declare function isQuoted(value: unknown): value is Quoted;
+declare function isUrl(value: unknown): value is Url;
+declare function urlFromChildren(children: readonly unknown[]): Url;
+declare function requireLiteralQuoted(value: unknown): Quoted;
+declare function isJessDeclaration(value: unknown): value is Declaration;
+declare function isCollectionEntry(value: unknown): value is CollectionEntry;
+declare function isRuleset(value: unknown): value is Ruleset;
+declare function isMixinDefinition(value: unknown): value is MixinDefinition;
+declare function isMixinCall(value: unknown): value is MixinCall;
+declare function isFor(value: unknown): value is For;
+declare function isIf(value: unknown): value is If;
+declare function isWhile(value: unknown): value is While;
+declare function requireExactToken(value: unknown, expected: string): void;
+declare function isVarDeclaration(value: unknown): value is VariableDeclaration;
+declare function reduceGuardTruth(children: readonly unknown[]): GuardNode;
+declare function reduceIfCompare(children: readonly unknown[]): GuardNode;
+declare function reduceGuardCompare(children: readonly unknown[]): GuardNode;
+declare function reduceGuardAnd(children: readonly unknown[]): GuardNode;
+declare function reduceGuardOr(children: readonly unknown[]): GuardNode;
+declare function reduceVarDeclaration(children: readonly unknown[]): VariableDeclaration;
+declare function reduceLambda(children: readonly unknown[]): AnonymousMixin;
+declare function reduceCompound(children: readonly unknown[]): SelectorTerm;
+declare function reduceSelectorTail(children: readonly unknown[]): SelectorBranch;
+declare function reduceSelectorList(children: readonly unknown[]): SelectorList;
+declare function isCalcOperator(text: string): boolean;
+declare function dollarValueFromChildren(children: readonly unknown[]): ValueNode;
+declare function foldCalcOperation(children: readonly unknown[]): ValueNode;
+export { requireToken, requireFields, jessCombinator, jessRelativeCombinator, jessBranchSegments, isExpressionFact, isJessAtRuleHeader, requireJessAtRuleHeader, isAtRuleNameToken, isSelectorTerm, isSimpleSelector, isJessSelectorBranch, isJessSelectorList, isJessReferenceTail, isPseudoSelector, isSimpleToken, selectorTermFromTokens, requireSelectorList, requireJessReferenceTail, requireString, requireInterpolation, requireKeyword, staticSelectorText, JESS_STRUCTURED_PSEUDOS, isExtendInstruction, isParam, isParamList, isMixinCallArray, isExtendInstructionArray, isValueNode, isValueNodeArray, isValueSlotArray, jessValueSlot, isSequence, isJessValueSlotValue, requireValueSlot, isJessMixinCallArgument, requireValueNode, isGuardNode, requireGuardNode, isJessInterpolation, isInterpolationLiteral, appendInterpolationLiteral, templateInterpolationFromChildren, appendCustomValueParts, customValueFromChildren, requireExpressionFact, requireJessOperatorFact, foldExpression, lookupNameSource, expressionSource, foldLogicalExpression, referenceBaseSource, isMemberStep, declarationMemberReferenceFromVariableBase, interpolationFromChildren, dollarBraceInterpolation, referenceArgSource, tokenSource, sourceFromState, interpolationValue, quotedInterpolationFromChildren, escapedInterpolationFromChildren, quotedExpressionFact, reduceColonFeature, jessFunctionOpenName, requireStatements, collectBlockStatements, collectBodyStatements, requireStatementList, isIfBranch, requireIfBranch, requireIfBranchArray, requireIfBranchTuple, requireForBinding, isAtRuleBlock, isAtRuleStatement, isUnknownAtRuleBlock, isStyleImport, isApply, isReferenceCall, isQuoted, isUrl, urlFromChildren, requireLiteralQuoted, isJessDeclaration, isCollectionEntry, isRuleset, isMixinDefinition, isMixinCall, isFor, isIf, isWhile, requireExactToken, isVarDeclaration, reduceGuardTruth, reduceIfCompare, reduceGuardCompare, reduceGuardAnd, reduceGuardOr, reduceVarDeclaration, reduceLambda, reduceCompound, reduceSelectorTail, reduceSelectorList, isCalcOperator, dollarValueFromChildren, foldCalcOperation };
+export type { ExpressionFact, JessOperatorFact, JessReferenceTail, JessComplexTail, JessSelectorSegment, JessQueryFeatureName, JessAtRuleHeader, JessMixinCallArgument };

package/lib/grammar.d.ts

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

package/package.json

@@ -3,9 +3,9 @@
   "publishConfig": {
     "access": "public"
   },
-  "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"
   },
   "description": "Jess parser with direct canonical AST parsing and an explicit language-service CST entry",
   "main": "lib/index.cjs",
@@ -65,11 +65,11 @@
   "license": "MIT",
   "dependencies": {
     "color-name": "~2.0.0",
-    "@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": {
@@ -78,9 +78,9 @@
   },
   "devDependencies": {
     "@types/color-name": "^1.1.1",
-    "parseman": "^0.50.1",
-    "@jesscss/parser-shared": "2.0.0-alpha.12",
-    "@jesscss/core": "2.0.0-alpha.12"
+    "parseman": "^0.50.5",
+    "@jesscss/core": "2.0.0-alpha.13",
+    "@jesscss/parser-shared": "2.0.0-alpha.13"
   },
   "type": "module",
   "module": "lib/index.js",