SWC low level visitors

[jerrykingxyz]

Summary

Explain how swc transform the source js and explain low-level visitors which in used
NOTE: This page is written base on swc v1.3.1

Glossary

visitor

visitor is the minimal unit to access and change ast, usually it is a struct which impl Fold, FoldMut, Visit or VisitMut

pass

pass is a special visitor, it can ensure sub visitor run in order.

Guide-level explanation

Flow diagram

Swc have three function to transform js - process_js, process_js_file, process_js_with_custom_pass.
Bacause of the process_js and process_js_file are just wrappers forprocess_js_with_custom_pass, we just need to see how process_js_with_custom_pass works.

There are four main function calls in process_js_with_custom_pass:

• read_config
  Scan .swcrc file form every parent dir of current work file, and return the nearest config.

• config.build_as_input
  Transform input config and generate pass.

• run config.pass + custom_after_pass
  Run all of pass to transform ast

• print
  Transform ast to string

Visitors (Execute order sort)

• resolver
  Firstly all scopes (fn, block) has it's own SyntaxContext.
  Resolver visits all identifiers in module, and look for binding identifies in the scope. Those identifiers now have the SyntaxContext of scope (fn, block). While doing so, resolver tries to resolve normal identifiers (no hygiene info) as a reference to identifier of scope. If the resolver find suitable variable, the identifier reference will have same context as the variable.

let a = 1;
{
    let a = 2;
    use(a);
}
use(a)
// resolver does
// 1. Define `a` with top level context.
// 2. Found a block, so visit block with a new syntax context.
// 3. Defined `a` with syntax context of the block statement.
// 5. Found usage of `a`, and determines that it's reference to `a` in the block. So the reference to `a` will have same syntax context as `a` in the block.
// 6. Found usage of `a` (last line), and determines that it's a reference to top-level `a`, and change syntax context of `a` on last line to top-level syntax context.

• swc_ecma_lints::rules::all
  Some rule to check ast. can add (feature = "non_critical_lints") to enable more rules.

vec![
  const_assign::const_assign(),
  duplicate_bindings::duplicate_bindings(),
  duplicate_exports::duplicate_exports(),
  no_dupe_args::no_dupe_args(),
]

• decorators (condition: syntax.decorators())
  Transform js decorator

@test
class A {}

class A {
  @test
  aa() {}
}

• import_assertions (condition: jsc.experimental.keep_import_assertions)
  Transform import assertions

import json from "./foo.json" assert { type: "json" };
import("foo.json", { assert: { type: "json" } });

• typescript::strip_with_jsx (condition: syntax.typescript())
  Transform typescript to javascript. If you are using jsx, you should use this before jsx pass

• plugins (condition: feature = "plugin" or feature = "plugin-bytecheck")
  Cache and run experimental.plugins

• custom_before_pass
  Run custom_before_pass input by process_js_with_custom_pass

• react::react (condition: syntax.jsx())
  Transform jsx to js.

• const_modules (condition: jsc.transform.const_modules)
  Transform const modules

// config
{
  "jsc": {
    "transform": {
      "constModules": {
        "globals": {
          "@ember/env-flags": {
            "DEBUG": "true"
          },
          "@ember/features": {
            "FEATURE_A": "false",
            "FEATURE_B": "true"
          }
        }
      }
    }
  }
}
// source 
import { DEBUG } from "@ember/env-flags";
import { FEATURE_A, FEATURE_B } from "@ember/features";

console.log(DEBUG, FEATURE_A, FEATURE_B);

// output
console.log(true, false, true);

• optimization (condition: jsc.transform.optimizer.globals)
  Set variables to inline.

// config
{
  "jsc": {
    "transform": {
      "optimizer": {
        "globals": {
          "vars": {
            "__DEBUG__": "true"
          }
        }
      }
    }
  }
}

// source
console.log(__DEBUG__)
// output
console.log(true)

• export_default_from (condition: syntax.export_default_from())
  Allow to export default, more info see @babel/plugin-proposal-export-default-from

export v from "mod";

• simplifier (condition: jsc.transform.optimizer.simplify)
  Performs simplify-expr, inlining, remove-dead-branch and dce until nothing changes.

// config
{
  "jsc": {
    "transform": {
      "optimizer": {
        // default is true
        "simplify": true
      }
    }
  }
}

// source
console.log([1, 2, 3, 4].length)
if ([1, 2, 3, 4].length > 2) {
  console.log("true")
} else {
  console.log("false")
}
// output
console.log(4)
console.log("true")

• json_parse (condition: jsc.transform.optimizer.jsonify)
  Transform json to optimize performance of literals

// config
{
  "jsc": {
    "transform": {
      "optimizer": {
        "jsonify": {
          "minCost": 0
        }
      }
    }
  }
}

// source
console.log({ a: 1 })
// output
console.log(JSON.parse('{"a":1}'))

• paren_remover
  Remove useless paren

// source
const a = 123;
console.log(a + (123 * a));
// output
const a = 123;
console.log(a + 123 * a);

• private_in_object (condition: syntax.private_in_object())
  Make private field in class checkable, more info see babel-plugin-proposal-private-property-in-object

// source
class Foo {
  #bar = "bar";

  test(obj) {
    return #bar in obj;
  }
}
console.log(new Foo().test({a: 1}))

// output
var _tmp, _brand_check_bar = new WeakSet();
class Foo {
    #bar = (_tmp = "bar", _brand_check_bar.add(this), _tmp);
    test(obj) {
        return _brand_check_bar.has(obj);
    }
}
console.log(new Foo().test({a:1}));

• compat_pass
  Transform source code to compat es version, if env exists use swc_ecma_preset_env::preset_env, else will transform to jsc.target esversion

// config
{
  "env": {
    "targets": {
      "chrome": "60"
    },
    "mode": "usage",
  }
}

// source
console.log('abcdabcd'.replaceAll('a', 'b'))

// output
import "core-js/modules/es.string.replace.js";
import "core-js/modules/es.regexp.exec.js";
console.log('abcdabcd'.replaceAll('a', 'b'));

• modules::import_analysis::import_analyzer (condition: module.type is commonjs, amd, umd)
  Analysis source code import, and mark some helper enabled

• compat::reserved_words::reserved_words
  Transform keyword variables to _keyword, more info see babel-plugin-transform-reserved-words

// source
var abstract = 1;
var x = abstract + 1;
// output
var _abstract = 1;
var x = _abstract + 1;

• helper::inject_helpers
  Inject enabled helpers to source code

// source
class A {}

console.log(new A())

// output
// module
import _classCallCheck from "@swc/helpers/src/_classCallCheck.mjs";
var A = function A() {
    "use strict";
    _classCallCheck(this, A);
};
console.log(new A());

// script
function _classCallCheck(instance, Constructor) {
    if (!(instance instanceof Constructor)) {
        throw new TypeError("Cannot call a class as a function");
    }
}
var A = function A() {
    "use strict";
    _classCallCheck(this, A);
};
console.log(new A());

• ModuleConfig::build
  Transform esm to CommonJS or UMD/AMD

• MinifierPass
  Minify js code

• hygiene_with_config
  The pass actually modifies the identifiers in the way that different identifier (with respect to span hygiene) becomes different identifier. (e.g. a1 for a#6, a2 for a#23)

• fixer
  Fixes ast nodes before printing so semantics are preserved

• jest::jest (condition: jsc.transform.hidden.jest)
  Some transform for jest, hidden options only use for other swc lib

• dropped_comments_preserver (condition: jsc.preserve_all_comments)
  Keep all comments be preserved during compilation

Conclusion

1. we can use low-level visitor to replace process_js_with_custom_pass and remove some useless visitor to make the transition process clearer and more controllable
2. we can use different visitor in parse & generate process to make the compilation more reasonable
   generate visitors:ModuleConfig::build to the end