Add support for @debug rules

Author: nex3

pkg/sass-parser/README.md

@@ -246,3 +246,14 @@ const sassParser = require('sass-parser');
 const root = new sassParser.Root();
 root.append('content: "hello, world!"');
 ```
+
+### Known Incompatibilities
+
+There are a few cases where an operation that's valid in PostCSS won't work with
+`sass-parser`:
+
+* Trying to convert a Sass-specific at-rule like `@if` or `@mixin` into a
+  different at-rule by changing its name is not supported.
+
+* Trying to add child nodes to a Sass statement that doesn't support children
+  like `@use` or `@error` is not supported.

pkg/sass-parser/lib/index.ts

@@ -33,6 +33,11 @@ export {
   InterpolationRaws,
   NewNodeForInterpolation,
 } from './src/interpolation';
+export {
+  DebugRule,
+  DebugRuleProps,
+  DebugRuleRaws,
+} from './src/statement/debug-rule';
 export {
   GenericAtRule,
   GenericAtRuleProps,

pkg/sass-parser/lib/src/sass-internal.ts

@@ -76,6 +76,10 @@ declare namespace SassInternal {
     readonly value?: Interpolation;
   }
 
+  class DebugRule extends Statement {
+    readonly expression: Expression;
+  }
+
   class Stylesheet extends ParentStatement<Statement[]> {}
 
   class StyleRule extends ParentStatement<Statement[]> {
@@ -113,6 +117,7 @@ export type ParentStatement<T extends Statement[] | null> =
   SassInternal.ParentStatement<T>;
 export type AtRootRule = SassInternal.AtRootRule;
 export type AtRule = SassInternal.AtRule;
+export type DebugRule = SassInternal.DebugRule;
 export type Stylesheet = SassInternal.Stylesheet;
 export type StyleRule = SassInternal.StyleRule;
 export type Interpolation = SassInternal.Interpolation;
@@ -123,6 +128,7 @@ export type StringExpression = SassInternal.StringExpression;
 export interface StatementVisitorObject<T> {
   visitAtRootRule(node: AtRootRule): T;
   visitAtRule(node: AtRule): T;
+  visitDebugRule(node: DebugRule): T;
   visitStyleRule(node: StyleRule): T;
 }
 

pkg/sass-parser/lib/src/statement/__snapshots__/debug-rule.test.ts.snap

@@ -0,0 +1,20 @@
+// Jest Snapshot v1, https://goo.gl/fbAQLP
+
+exports[`a @debug rule toJSON 1`] = `
+{
+  "debugExpression": <foo>,
+  "inputs": [
+    {
+      "css": "@debug foo",
+      "hasBOM": false,
+      "id": "<input css _____>",
+    },
+  ],
+  "name": "debug",
+  "params": "foo",
+  "raws": {},
+  "sassType": "debug-rule",
+  "source": <1:1-1:11 in 0>,
+  "type": "atrule",
+}
+`;

pkg/sass-parser/lib/src/statement/at-rule-internal.d.ts

@@ -15,8 +15,6 @@ import {AtRule, ChildNode, Comment, Declaration, NewNode} from '.';
  * @hidden
  */
 export class _AtRule<Props> extends postcss.AtRule {
-  declare nodes: ChildNode[];
-
   // Override the PostCSS container types to constrain them to Sass types only.
   // Unfortunately, there's no way to abstract this out, because anything
   // mixin-like returns an intersection type which doesn't actually override

pkg/sass-parser/lib/src/statement/debug-rule.test.ts

@@ -0,0 +1,205 @@
+// Copyright 2024 Google Inc. Use of this source code is governed by an
+// MIT-style license that can be found in the LICENSE file or at
+// https://opensource.org/licenses/MIT.
+
+import {DebugRule, StringExpression, sass, scss} from '../..';
+import * as utils from '../../../test/utils';
+
+describe('a @debug rule', () => {
+  let node: DebugRule;
+  function describeNode(description: string, create: () => DebugRule): void {
+    describe(description, () => {
+      beforeEach(() => void (node = create()));
+
+      it('has a name', () => expect(node.name.toString()).toBe('debug'));
+
+      it('has an expression', () =>
+        expect(node).toHaveStringExpression('debugExpression', 'foo'));
+
+      it('has matching params', () => expect(node.params).toBe('foo'));
+
+      it('has undefined nodes', () => expect(node.nodes).toBeUndefined());
+    });
+  }
+
+  describeNode(
+    'parsed as SCSS',
+    () => scss.parse('@debug foo').nodes[0] as DebugRule
+  );
+
+  describeNode(
+    'parsed as Sass',
+    () => sass.parse('@debug foo').nodes[0] as DebugRule
+  );
+
+  describeNode(
+    'constructed manually',
+    () =>
+      new DebugRule({
+        debugExpression: {text: 'foo'},
+      })
+  );
+
+  describeNode('constructed from ChildProps', () =>
+    utils.fromChildProps({
+      debugExpression: {text: 'foo'},
+    })
+  );
+
+  it('throws an error when assigned a new name', () =>
+    expect(
+      () =>
+        (new DebugRule({
+          debugExpression: {text: 'foo'},
+        }).name = 'bar')
+    ).toThrow());
+
+  describe('assigned a new expression', () => {
+    beforeEach(() => {
+      node = scss.parse('@debug foo').nodes[0] as DebugRule;
+    });
+
+    it('sets an empty string expression as undefined params', () => {
+      node.params = undefined;
+      expect(node.params).toBe('');
+      expect(node).toHaveStringExpression('debugExpression', '');
+    });
+
+    it('sets an empty string expression as empty string params', () => {
+      node.params = '';
+      expect(node.params).toBe('');
+      expect(node).toHaveStringExpression('debugExpression', '');
+    });
+
+    it("removes the old expression's parent", () => {
+      const oldExpression = node.debugExpression;
+      node.debugExpression = {text: 'bar'};
+      expect(oldExpression.parent).toBeUndefined();
+    });
+
+    it("assigns the new expression's parent", () => {
+      const expression = new StringExpression({text: 'bar'});
+      node.debugExpression = expression;
+      expect(expression.parent).toBe(node);
+    });
+
+    it('assigns the expression explicitly', () => {
+      const expression = new StringExpression({text: 'bar'});
+      node.debugExpression = expression;
+      expect(node.debugExpression).toBe(expression);
+    });
+
+    it('assigns the expression as ExpressionProps', () => {
+      node.debugExpression = {text: 'bar'};
+      expect(node).toHaveStringExpression('debugExpression', 'bar');
+    });
+
+    it('assigns the expression as params', () => {
+      node.params = 'bar';
+      expect(node).toHaveStringExpression('debugExpression', 'bar');
+    });
+  });
+
+  describe('stringifies', () => {
+    describe('to SCSS', () => {
+      it('with default raws', () =>
+        expect(
+          new DebugRule({
+            debugExpression: {text: 'foo'},
+          }).toString()
+        ).toBe('@debug foo;'));
+
+      it('with afterName', () =>
+        expect(
+          new DebugRule({
+            debugExpression: {text: 'foo'},
+            raws: {afterName: '/**/'},
+          }).toString()
+        ).toBe('@debug/**/foo;'));
+
+      it('with between', () =>
+        expect(
+          new DebugRule({
+            debugExpression: {text: 'foo'},
+            raws: {between: '/**/'},
+          }).toString()
+        ).toBe('@debug foo/**/;'));
+    });
+  });
+
+  describe('clone', () => {
+    let original: DebugRule;
+    beforeEach(() => {
+      original = scss.parse('@debug foo').nodes[0] as DebugRule;
+      // TODO: remove this once raws are properly parsed
+      original.raws.between = '  ';
+    });
+
+    describe('with no overrides', () => {
+      let clone: DebugRule;
+      beforeEach(() => void (clone = original.clone()));
+
+      describe('has the same properties:', () => {
+        it('params', () => expect(clone.params).toBe('foo'));
+
+        it('debugExpression', () =>
+          expect(clone).toHaveStringExpression('debugExpression', 'foo'));
+
+        it('raws', () => expect(clone.raws).toEqual({between: '  '}));
+
+        it('source', () => expect(clone.source).toBe(original.source));
+      });
+
+      describe('creates a new', () => {
+        it('self', () => expect(clone).not.toBe(original));
+
+        for (const attr of ['debugExpression', 'raws'] as const) {
+          it(attr, () => expect(clone[attr]).not.toBe(original[attr]));
+        }
+      });
+    });
+
+    describe('overrides', () => {
+      describe('raws', () => {
+        it('defined', () =>
+          expect(original.clone({raws: {afterName: '  '}}).raws).toEqual({
+            afterName: '  ',
+          }));
+
+        it('undefined', () =>
+          expect(original.clone({raws: undefined}).raws).toEqual({
+            between: '  ',
+          }));
+      });
+
+      describe('debugExpression', () => {
+        describe('defined', () => {
+          let clone: DebugRule;
+          beforeEach(() => {
+            clone = original.clone({debugExpression: {text: 'bar'}});
+          });
+
+          it('changes params', () => expect(clone.params).toBe('bar'));
+
+          it('changes debugExpression', () =>
+            expect(clone).toHaveStringExpression('debugExpression', 'bar'));
+        });
+
+        describe('undefined', () => {
+          let clone: DebugRule;
+          beforeEach(() => {
+            clone = original.clone({debugExpression: undefined});
+          });
+
+          it('preserves params', () => expect(clone.params).toBe('foo'));
+
+          it('preserves debugExpression', () =>
+            expect(clone).toHaveStringExpression('debugExpression', 'foo'));
+        });
+      });
+    });
+  });
+
+  it('toJSON', () =>
+    expect(scss.parse('@debug foo').nodes[0]).toMatchSnapshot());
+});