@jesscss/scss-parser 2.0.0-alpha.10

package/lib/index.cjs

@@ -0,0 +1,111 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_grammar = require("./grammar.cjs");
+let parseman = require("parseman");
+let _jesscss_core_ast = require("@jesscss/core/ast");
+//#region src/ast/lower-user-function-calls.ts
+/**
+* SCSS call-site lowering: a user `@function f(...)` was lowered (in the grammar)
+* to a `$var`-bound value lambda (`AnonymousMixin` with `params`). A CALL to that
+* function — `f(2)` — parses as an ordinary `FunctionCall`, indistinguishable at
+* the leaf from a builtin Sass call (`darken(...)`). This post-parse pass rewrites
+* every `FunctionCall` whose name is a USER-defined `@function` into the shared
+* `$f(args)` invoke form (a `Reference` with a `Call` step on the bound variable),
+* so it reaches the general "call a value-lambda" evaluator path. Builtin Sass
+* functions are left as `FunctionCall`s and continue to route to `fns`.
+*
+* User-function names are collected from the WHOLE document first (Sass hoists and
+* effectively globalises function definitions), so a call may precede its `@function`.
+* The only SCSS construct that binds an `AnonymousMixin` to a `$var` is `@function`,
+* so "a VariableDeclaration whose value is an AnonymousMixin" is an exact marker.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isFunctionCall(value) {
+	return isRecord(value) && value.type === "FunctionCall" && typeof value.name === "string" && Array.isArray(value.args);
+}
+/** A non-array value slot is a single value node. */
+function isValueNode(slot) {
+	return !Array.isArray(slot);
+}
+function isStylesheet$1(value) {
+	return isRecord(value) && value.type === "Stylesheet" && Array.isArray(value.children);
+}
+/** Collect every user `@function` name: a VariableDeclaration bound to an
+*  AnonymousMixin (the only SCSS shape that produces one). */
+function collectUserFunctionNames(node, into) {
+	if (Array.isArray(node)) {
+		for (const child of node) collectUserFunctionNames(child, into);
+		return;
+	}
+	if (!isRecord(node)) return;
+	if (node.type === "VariableDeclaration" && typeof node.name === "string" && isRecord(node.value) && node.value.type === "AnonymousMixin") into.add(node.name);
+	for (const key of Object.keys(node)) collectUserFunctionNames(node[key], into);
+}
+/** Best-effort authored spelling of a call argument, for a Reference `raw`
+*  fallback (only ever emitted if the invoke fails to resolve). */
+function argRaw(slot) {
+	if (!isValueNode(slot)) return slot.map(argRaw).join(" ");
+	if (slot.type === "VariableReference") return `$${slot.name}`;
+	if ("src" in slot && typeof slot.src === "string") return slot.src;
+	return "";
+}
+/** Deep-transform the tree, rewriting user-function `FunctionCall`s (post-order,
+*  so nested user calls inside the args lower first). Non-AST scalars pass through. */
+function rewrite(node, userFns) {
+	if (Array.isArray(node)) return node.map((child) => rewrite(child, userFns));
+	if (!isRecord(node)) return node;
+	const out = {};
+	for (const key of Object.keys(node)) out[key] = rewrite(node[key], userFns);
+	if (isFunctionCall(out) && userFns.has(out.name)) {
+		const args = out.args.map((value) => ({ value }));
+		const raw = `${out.name}(${out.args.map(argRaw).join(", ")})`;
+		return (0, _jesscss_core_ast.reference)((0, _jesscss_core_ast.variableReference)(out.name, "live"), [{
+			type: "Call",
+			args
+		}], raw);
+	}
+	return out;
+}
+/**
+* Rewrite user-`@function` call sites in a parsed SCSS document to `$f(args)`
+* lambda invokes. Returns the document unchanged when it defines no user function.
+*/
+function lowerUserFunctionCalls(sheet) {
+	const userFns = /* @__PURE__ */ new Set();
+	collectUserFunctionNames(sheet.children, userFns);
+	if (userFns.size === 0) return sheet;
+	const lowered = rewrite(sheet, userFns);
+	if (!isStylesheet$1(lowered)) throw new TypeError("SCSS user-function lowering did not preserve the Stylesheet root.");
+	return lowered;
+}
+//#endregion
+//#region src/index.ts
+/** Structured failure from the public direct SCSS parser. */
+var ScssParseError = class extends SyntaxError {
+	code = "parse/syntax-error";
+	offset;
+	expected;
+	constructor(offset, expected) {
+		const detail = expected.length > 0 ? ` Expected: ${expected.join(", ")}.` : "";
+		super(`SCSS parser error.${detail}`);
+		this.name = "ScssParseError";
+		this.offset = offset;
+		this.expected = expected;
+	}
+};
+function isStylesheet(value) {
+	return typeof value === "object" && value !== null && "type" in value && value.type === "Stylesheet" && "children" in value && Array.isArray(value.children);
+}
+/** Parse SCSS directly into the canonical AST v2 document. */
+function parse(input) {
+	const entry = require_grammar.scssAstGrammar.Stylesheet;
+	const trivia = require_grammar.scssAstGrammar.whitespace;
+	if (entry === void 0 || trivia === void 0) throw new TypeError("SCSS AST grammar is missing its public document entry.");
+	const result = (0, parseman.run)(entry, input, { trivia });
+	if (!result.ok || result.unconsumedFrom !== null || !isStylesheet(result.value)) throw new ScssParseError(result.ok ? result.unconsumedFrom ?? result.span.end : result.span.start, result.expected);
+	return (0, _jesscss_core_ast.withTriviaMap)((0, _jesscss_core_ast.withSourceSpan)(lowerUserFunctionCalls(result.value), result.span), (0, _jesscss_core_ast.createTriviaMapFromParseman)(input, result.triviaMap));
+}
+//#endregion
+exports.ScssParseError = ScssParseError;
+exports.parse = parse;

package/lib/index.d.ts

@@ -0,0 +1,10 @@
+import { type Stylesheet } from '@jesscss/core/ast';
+/** Structured failure from the public direct SCSS parser. */
+export declare class ScssParseError extends SyntaxError {
+    readonly code: 'parse/syntax-error';
+    readonly offset: number;
+    readonly expected: readonly string[];
+    constructor(offset: number, expected: readonly string[]);
+}
+/** Parse SCSS directly into the canonical AST v2 document. */
+export declare function parse(input: string): Stylesheet;

package/lib/index.js

@@ -0,0 +1,109 @@
+import { scssAstGrammar } from "./grammar.js";
+import { run } from "parseman";
+import { createTriviaMapFromParseman, reference, variableReference, withSourceSpan, withTriviaMap } from "@jesscss/core/ast";
+//#region src/ast/lower-user-function-calls.ts
+/**
+* SCSS call-site lowering: a user `@function f(...)` was lowered (in the grammar)
+* to a `$var`-bound value lambda (`AnonymousMixin` with `params`). A CALL to that
+* function — `f(2)` — parses as an ordinary `FunctionCall`, indistinguishable at
+* the leaf from a builtin Sass call (`darken(...)`). This post-parse pass rewrites
+* every `FunctionCall` whose name is a USER-defined `@function` into the shared
+* `$f(args)` invoke form (a `Reference` with a `Call` step on the bound variable),
+* so it reaches the general "call a value-lambda" evaluator path. Builtin Sass
+* functions are left as `FunctionCall`s and continue to route to `fns`.
+*
+* User-function names are collected from the WHOLE document first (Sass hoists and
+* effectively globalises function definitions), so a call may precede its `@function`.
+* The only SCSS construct that binds an `AnonymousMixin` to a `$var` is `@function`,
+* so "a VariableDeclaration whose value is an AnonymousMixin" is an exact marker.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+function isFunctionCall(value) {
+	return isRecord(value) && value.type === "FunctionCall" && typeof value.name === "string" && Array.isArray(value.args);
+}
+/** A non-array value slot is a single value node. */
+function isValueNode(slot) {
+	return !Array.isArray(slot);
+}
+function isStylesheet$1(value) {
+	return isRecord(value) && value.type === "Stylesheet" && Array.isArray(value.children);
+}
+/** Collect every user `@function` name: a VariableDeclaration bound to an
+*  AnonymousMixin (the only SCSS shape that produces one). */
+function collectUserFunctionNames(node, into) {
+	if (Array.isArray(node)) {
+		for (const child of node) collectUserFunctionNames(child, into);
+		return;
+	}
+	if (!isRecord(node)) return;
+	if (node.type === "VariableDeclaration" && typeof node.name === "string" && isRecord(node.value) && node.value.type === "AnonymousMixin") into.add(node.name);
+	for (const key of Object.keys(node)) collectUserFunctionNames(node[key], into);
+}
+/** Best-effort authored spelling of a call argument, for a Reference `raw`
+*  fallback (only ever emitted if the invoke fails to resolve). */
+function argRaw(slot) {
+	if (!isValueNode(slot)) return slot.map(argRaw).join(" ");
+	if (slot.type === "VariableReference") return `$${slot.name}`;
+	if ("src" in slot && typeof slot.src === "string") return slot.src;
+	return "";
+}
+/** Deep-transform the tree, rewriting user-function `FunctionCall`s (post-order,
+*  so nested user calls inside the args lower first). Non-AST scalars pass through. */
+function rewrite(node, userFns) {
+	if (Array.isArray(node)) return node.map((child) => rewrite(child, userFns));
+	if (!isRecord(node)) return node;
+	const out = {};
+	for (const key of Object.keys(node)) out[key] = rewrite(node[key], userFns);
+	if (isFunctionCall(out) && userFns.has(out.name)) {
+		const args = out.args.map((value) => ({ value }));
+		const raw = `${out.name}(${out.args.map(argRaw).join(", ")})`;
+		return reference(variableReference(out.name, "live"), [{
+			type: "Call",
+			args
+		}], raw);
+	}
+	return out;
+}
+/**
+* Rewrite user-`@function` call sites in a parsed SCSS document to `$f(args)`
+* lambda invokes. Returns the document unchanged when it defines no user function.
+*/
+function lowerUserFunctionCalls(sheet) {
+	const userFns = /* @__PURE__ */ new Set();
+	collectUserFunctionNames(sheet.children, userFns);
+	if (userFns.size === 0) return sheet;
+	const lowered = rewrite(sheet, userFns);
+	if (!isStylesheet$1(lowered)) throw new TypeError("SCSS user-function lowering did not preserve the Stylesheet root.");
+	return lowered;
+}
+//#endregion
+//#region src/index.ts
+/** Structured failure from the public direct SCSS parser. */
+var ScssParseError = class extends SyntaxError {
+	code = "parse/syntax-error";
+	offset;
+	expected;
+	constructor(offset, expected) {
+		const detail = expected.length > 0 ? ` Expected: ${expected.join(", ")}.` : "";
+		super(`SCSS parser error.${detail}`);
+		this.name = "ScssParseError";
+		this.offset = offset;
+		this.expected = expected;
+	}
+};
+function isStylesheet(value) {
+	return typeof value === "object" && value !== null && "type" in value && value.type === "Stylesheet" && "children" in value && Array.isArray(value.children);
+}
+/** Parse SCSS directly into the canonical AST v2 document. */
+function parse(input) {
+	const entry = scssAstGrammar.Stylesheet;
+	const trivia = scssAstGrammar.whitespace;
+	if (entry === void 0 || trivia === void 0) throw new TypeError("SCSS AST grammar is missing its public document entry.");
+	const result = run(entry, input, { trivia });
+	if (!result.ok || result.unconsumedFrom !== null || !isStylesheet(result.value)) throw new ScssParseError(result.ok ? result.unconsumedFrom ?? result.span.end : result.span.start, result.expected);
+	return withTriviaMap(withSourceSpan(lowerUserFunctionCalls(result.value), result.span), createTriviaMapFromParseman(input, result.triviaMap));
+}
+//#endregion
+export { ScssParseError, parse };

package/package.json

@@ -0,0 +1,71 @@
+{
+  "name": "@jesscss/scss-parser",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "",
+  "version": "2.0.0-alpha.10",
+  "engines": {
+    "node": "^20.19.0 || >=22.12.0"
+  },
+  "main": "lib/index.cjs",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "import": "./lib/index.js",
+      "require": "./lib/index.cjs"
+    },
+    "./cst": {
+      "types": "./lib/cst.d.ts",
+      "import": "./lib/cst.js",
+      "require": "./lib/cst.cjs"
+    },
+    "./grammar": {
+      "types": "./lib/grammar.d.ts",
+      "import": "./lib/grammar.js",
+      "require": "./lib/grammar.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "dependencies": {
+    "@jesscss/css-parser": "2.0.0-alpha.10"
+  },
+  "peerDependencies": {
+    "parseman": "^0.41.0",
+    "@jesscss/core": "2.0.0-alpha.10"
+  },
+  "peerDependenciesMeta": {
+    "@jesscss/core": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "parseman": "^0.41.0",
+    "sass-spec": "github:sass/sass-spec",
+    "@jesscss/parser-shared": "0.0.0",
+    "@jesscss/core": "2.0.0-alpha.10"
+  },
+  "author": "Matthew Dean <matthew-dean@users.noreply.github.com>",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/jesscss/jess/issues"
+  },
+  "homepage": "https://github.com/jesscss/jess#readme",
+  "type": "module",
+  "module": "lib/index.js",
+  "scripts": {
+    "postinstall": "node ./scripts/materialize-sass-spec-cache.cjs",
+    "ci": "pnpm build && pnpm test",
+    "build": "pnpm --filter @jesscss/parser-shared build && pnpm compile",
+    "compile": "tsdown --tsconfig tsconfig.build.json --no-dts && tsc -p tsconfig.build.json --emitDeclarationOnly --noCheck",
+    "dev": "tsdown --tsconfig tsconfig.build.json --no-dts --watch",
+    "sass-spec:cache": "node ./scripts/materialize-sass-spec-cache.cjs",
+    "test": "vitest --run --passWithNoTests",
+    "lint:fix": "eslint --fix '**/*.{js,ts}'",
+    "lint": "eslint '**/*.{js,ts}'"
+  }
+}