feat: add support for parser/stringifier

Author: skovy

package.json

@@ -45,13 +45,14 @@
     "@types/glob": "^7.2.0",
     "@types/node": "^17.0.13",
     "dripip": "^0.10.0",
+    "execa": "^5.1.1",
     "husky": "^7.0.4",
+    "postcss-scss": "^4.0.3",
     "rimraf": "^3.0.2",
     "tsdx": "^0.14.1",
     "tslib": "^2.3.1",
     "tsup": "^5.11.11",
-    "typescript": "^4.5.5",
-    "execa": "^5.1.1"
+    "typescript": "^4.5.5"
   },
   "dependencies": {
     "bundle-require": "^3.0.2",

recipes/rename-scss-variable/input/a.scss

@@ -0,0 +1,20 @@
+@mixin reset-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.a {
+  // Inline comment
+  color: green;
+  margin: 20px;
+
+  &.b {
+    border: 1px solid orange;
+    color: $old-color-var;
+  }
+}
+
+ul {
+  @include horizontal-list;
+}

recipes/rename-scss-variable/input/nested/b.scss

@@ -0,0 +1,3 @@
+.class {
+  background: $old-color-var;
+}

recipes/rename-scss-variable/output/a.scss

@@ -0,0 +1,20 @@
+@mixin reset-list {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+.a {
+  // Inline comment
+  color: green;
+  margin: 20px;
+
+  &.b {
+    border: 1px solid orange;
+    color: $new-color-var;
+  }
+}
+
+ul {
+  @include horizontal-list;
+}

recipes/rename-scss-variable/output/nested/b.scss

@@ -0,0 +1,3 @@
+.class {
+  background: $new-color-var;
+}

recipes/rename-scss-variable/transform.ts

@@ -0,0 +1,16 @@
+import { Transform } from '../../src';
+import { parse, stringify } from 'postcss-scss';
+
+export const transform: Transform = (fileInfo, api) => {
+  const root = api.parse(fileInfo.source);
+
+  root.walk(node => {
+    if (node.type === 'decl' && node.value === '$old-color-var') {
+      node.value = '$new-color-var';
+    }
+  });
+
+  return root.toString(stringify);
+};
+
+export const parser = parse;

src/api.ts

@@ -1,14 +1,49 @@
-import postcss, { Root } from 'postcss';
-
+import postcss, { Root, Parser } from 'postcss';
 export interface TransformAPI {
   /**
    * Parse a raw CSS string into an abstract syntax tree and return a PostCSS `Root` node.
    */
   parse(source: string): Root;
 }
 
-const parse: TransformAPI['parse'] = source => {
-  return postcss.parse(source);
+const createAPIParse = ({
+  parser,
+}: {
+  parser?: Parser;
+}): TransformAPI['parse'] => {
+  const parse: TransformAPI['parse'] = source => {
+    const result = postcss().process(source, {
+      // Silence a warning about sourcemaps. Not relevant to this use case.
+      from: undefined,
+      parser,
+    });
+
+    // Explicitly destructure root, which lazy evaluates and populates an error
+    // if one occurs. The error field can then be checked.
+    const { root } = result;
+
+    // Re-surface an PostCSS parsing errors.
+    // https://github.com/postcss/postcss/issues/1708
+    if ((result as any).error) {
+      throw (result as any).error;
+    }
+
+    if (root?.type === 'root') {
+      return root;
+    } else {
+      throw new Error(`Unexpected root node: ${root}`);
+    }
+  };
+
+  return parse;
 };
 
-export const api: TransformAPI = { parse };
+export const createAPI = ({
+  parser,
+}: { parser?: Parser } = {}): TransformAPI => {
+  const api: TransformAPI = {
+    parse: createAPIParse({ parser }),
+  };
+
+  return api;
+};

src/perform.ts

@@ -1,4 +1,4 @@
-import { api } from './api';
+import { createAPI } from './api';
 import { getAllFilesToTransform, getFileInfo, writeFile } from './files';
 import { loadTransform } from './transform';
 
@@ -18,8 +18,9 @@ interface ProcessTransformOptions {
  * Perform a transformation across a set of files.
  */
 export const perform = async (options: ProcessTransformOptions) => {
-  const transform = await loadTransform(options.transform);
+  const { transform, parser } = await loadTransform(options.transform);
   const files = getAllFilesToTransform(options.files);
+  const api = createAPI({ parser });
 
   files.map(file => {
     const fileInfo = getFileInfo(file);
@@ -33,7 +34,7 @@ export const perform = async (options: ProcessTransformOptions) => {
     } catch (err) {
       if (err instanceof Error) {
         console.error(
-          `The following error occurred transforming "${file}":\n  ${err.message}`
+          `The following error occurred transforming "${file}":\n  ${err.message}${err.stack}`
         );
       } else {
         console.error(

src/transform.ts

@@ -1,4 +1,5 @@
 import { bundleRequire } from 'bundle-require';
+import { Parser } from 'postcss';
 import { TransformAPI } from './api';
 import { TransformFileInfo } from './files';
 
@@ -34,14 +35,22 @@ export const validateTransform = (transform: unknown): Transform => {
   }
 };
 
+interface LoadTransformResult {
+  transform: Transform;
+  parser?: Parser;
+}
+
 /**
  * Load and validate the transform file given the filepath.
  */
-export const loadTransform = async (filepath: string): Promise<Transform> => {
+export const loadTransform = async (
+  filepath: string
+): Promise<LoadTransformResult> => {
   try {
     const { mod } = await bundleRequire({ filepath });
     const transform = validateTransform(mod.transform || mod.default);
-    return transform;
+    const parser = mod.parser;
+    return { transform, parser };
   } catch (err) {
     console.error(
       `An error occurred loading the transform file. Verify "${filepath}" exists.`

test/api.test.ts

@@ -1,7 +1,9 @@
 import { Declaration, Rule } from 'postcss';
-import { api } from '../src/api';
+import { createAPI } from '../src/api';
 
 describe('api', () => {
+  const api = createAPI();
+
   describe('#parse', () => {
     it('should return the root node of an abstract syntax tree', () => {
       const root = api.parse(`.class { color: orange; }`);