Course overview

Introduction

Understand the basics of an AST and how it relates to real-world code

What is an Abstract Syntax Tree? Visualizing Code Like a Compiler

Looking at an example code snippet and how it relates to the resulting AST

How to View Abstract Syntax Tree Code With AST Explorer

An overview of the tooling available in the web frontend (JavaScript) ecosystem that rely on ASTs

The Best JavaScript AST Tools - ESLint, Babel, Terser, and More

A quick overview of the basic environment setup used throughout this course

Environment setup

Understanding Abstract Syntax Trees (AST)

Exploring tools to convert (or parse) JavaScript into a real AST

How to Generate a JavaScript AST With Babel Plugins

Programmatically traverse an AST and visit arbitrary nodes

Traversing an AST With Babel Traverse

Add Type Safety and Prevent Runtime Errors With AST

Working with Abstract Syntax Trees

A practical example of needing to perform a code audit (static analysis) to understand the current state of a codebase

Practical code audits

Create a custom script to audit a codebase

How to Audit Your Code With AST Programming

Introduce a shared Button component to replace all existing button elements

How to Add a Component and Update an AST

A rough formula to determine when to use AST-based tooling

When to Use Abstract Syntax Tree Tooling to Refactor at Scale

Code Audits

Transforming code in place by mutating an AST

How to Mutate an AST and Automatically Replace Code Components

Using jscodeshift to make the same code transformations with less boilerplate

How to Create Codemods Using jscodeshift

Create tests for jscodeshift transforms for a faster feedback loop

How to Unit Test jscodeshift Transforms With ts-jest

Codemods

Implement a linting rule to prevent the code we just transformed from being reintroduced in the future

How to Ensure Codebase is Up to Date With Linting Rules

Use ESLint to create the same linting rule for the code with less boilerplate

How to Use ESLint to Create AST Rules With Babel Traverse

Testing custom ESLint linting rules to verify they work as expected

How to Test Custom ESLint Linting Rules With AST

Linting

In this course, we'll start with the fundamentals of abstract syntax trees (ASTs) and learn the basic mental models. This general AST knowledge can be translated to almost any tool that works with ASTs.

## Why this course?

Understanding and using ASTs unlocks the ability to make sweeping changes in a safe and reliable way in any size codebase.

## Course topics

Throughout this course, we'll have converted source code into ASTs, traversed, mutated, and generated ASTs. With these concepts we'll then explore several practical applications including things like code audits (static analysis), code transformations (codemods), and linting.

### Module 1

We'll learn the fundamentals of abstract syntax trees. 

- What is an AST?
- How to explore an AST
- Examples of JavaScript tools that work with ASTs

### Module 2

We'll learn how to work with ASTs.

- How to turn code into an AST
- How to programmatically navigate any AST 
- How to leverage TypeScript to prevent runtime errors

### Module 3

We'll learn how to statically analyze, or "audit" code to understand the state of the codebase using abstract syntax trees.

- An introduction to an example codebase and refactor
- Understanding the state of the current codebase
- When to use an AST-based tool versus doing something manually

### Module 4

We'll learn how to transform, or "codemod" code from one state to another using abstract syntax trees.

- How to make changes to an AST
- How to change ASTs with [jscodeshift](https://github.com/facebook/jscodeshift)
- How to test a code transform

### Module 5

We'll learn how to write rules, or "lint" code using abstract syntax trees.

- How to create rules for code
- How to create custom rules with [ESLint](https://eslint.org)
- How to test a rule

In this course, you'll learn the fundamentals of abstract syntax trees, what they are, how they work, and dive into several practical use cases of abstract syntax trees to maintain a JavaScript codebase.

Practical Abstract Syntax Trees

JavaScript tools that work with abstract syntax trees

How to parse, traverse, and generate abstract syntax trees

Practical skill set for maintaining large JavaScript codebases

 components. To get to this point, we first performed an audit of the codebase to understand how 

 elements were being used today. Then, we created a 

 component that was capable of handling all those use cases. Finally, we performed a codemod to transform all of the 

This completes the original refactor described in Module 3. However, an actual codebase will continue to evolve and have further changes made. How do we ensure the codebase 

A common approach for this is to create a 

 for that codebase that enforces this. Any time a change is made, the codebase can be checked against that rule. If there are any violations, the change can be blocked.

For example, in a git workflow, a change is made in a branch off the main branch. Before that branch can be merged, this rule (in addition to other things like tests) need to pass. This way, the main branch should never violate this rule.

This concept of applying rules to code is commonly referred to as 

Let's start by creating a new linter directory and adding the necessary dependencies.

# Create a new directory for the linter script
mkdir linter

# Change into the new linter directory
cd linter

# Initialize a new package.json file
npm init -y

# Add the necessary dependencies
npm i @babel/parser @babel/traverse @babel/code-frame glob ts-node typescript
npm i -D @types/babel__traverse @types/babel__code-frame @types/glob

 file with much of the same initial setup as the previous custom audit script.

import { parse } from "@babel/parser";
import traverse from "@babel/traverse";
import * as fs from "fs";
import * as glob from "glob";

const files = glob.sync("../flash-cards/src/components/**/*.js");

files.forEach((file) => {
  const contents = fs.readFileSync(file).toString();

  const ast = parse(contents, {
    sourceType: "module",
    plugins: ["jsx"],
  });

  traverse(ast, {
    JSXOpeningElement({ node }) {
      if (node.name.type === "JSXIdentifier" && node.name.name === "button") {
        // Find the JSXAttribute (prop) with a name of
        // `className` where it's value is a space separated
        // string of class names where one of the class
        // names is `button`.
        const hasButtonClassName = node.attributes.find((attribute) => {
          return (
            attribute.type === "JSXAttribute" &&
            attribute.name.type === "JSXIdentifier" &&
            attribute.name.name === "className" &&
            attribute.value.type === "StringLiteral" &&
            attribute.value.value.split(" ").includes("button")
          );
        });

        // Ignore any button elements that don't also have 
        // the button class name
        if (!hasButtonClassName) return;

        // TODO: lint...
      }
    },
  });
});

Since all the nodes that matched these criteria were transformed in the previous module, no nodes will match these criteria in the codebase.

To test this, a new violation can intentionally be added to verify it works as expected. Update the 

 component in the Flash codebase (or any other component) with the following snippet anywhere in the component.

    <button className="button">
      Hello World!
    </button>

Now there is a violation, the linting rule can be updated to log the file and line that violates this rule, to make it easy to find and fix. Each node contains a 

 property that is an object with information about the starting and ending lines and the column numbers.

// Example value of the `loc` property on a node:
{
  "start": { "line": 23, "column": 4 },
  "end": { "line": 23, "column": 31 }
}

 for this module. It will otherwise hide all of the 

This location information can be appended to the filename to make it easier to jump directly to the position in the code that the violation occurs.

    JSXOpeningElement({ node }) {
      if (node.name.type === "JSXIdentifier" && node.name.name === "button") {
        const hasButtonClassName = node.attributes.find((attribute) => {
          return (
            attribute.type === "JSXAttribute" &&
            attribute.name.type === "JSXIdentifier" &&
            attribute.name.name === "className" &&
            attribute.value.type === "StringLiteral" &&
            attribute.value.value.split(" ").includes("button")
          );
        });

        if (!hasButtonClassName) return;

        // At this point, it means a violation (eg: 
        // `<button className="button" />`) was found. 
        // Print the error, the current file, and 
        // concatenate the line and column of the 
        // violation position in the original source 
        // code. This makes it easy to copy and paste 
        // into an editor like VSCode and it'll open the
        // file with the cursor at that position.
        const { start } = node.loc;
        console.error(
          `${path.resolve(file)}:${start.line}:${start.column + 1}`
        );
        console.error(
          `  Found "button" element that should be "Button" component.`
        );
      }
    },

Now, let's run the script with the known violation.

---
title: How to Ensure Codebase is Up to Date With Linting Rules
description: Implement a linting rule to prevent the code we just transformed from being reintroduced in the future
privateVideoUrl: "https://fullstack.wistia.com/medias/ev3e1mm4g4"
code: https://gitlab.com/fullstackio/books/newline-course-apps/spencer-miskoviak-practical-abstract-syntax-trees-app/-/tree/main/code/module_06/lesson_06.01/App?ref_type=heads
---

# Creating rules for code

The Flash codebase now uses `Button` components. To get to this point, we first performed an audit of the codebase to understand how `button` elements were being used today. Then, we created a `Button` component that was capable of handling all those use cases. Finally, we performed a codemod to transform all of the `button` elements to the `Button` component.

This completes the original refactor described in Module 3. However, an actual codebase will continue to evolve and have further changes made. How do we ensure the codebase _stays_ up-to-date using the `Button` component where appropriate?

A common approach for this is to create a **rule** for that codebase that enforces this. Any time a change is made, the codebase can be checked against that rule. If there are any violations, the change can be blocked.

For example, in a git workflow, a change is made in a branch off the main branch. Before that branch can be merged, this rule (in addition to other things like tests) need to pass. This way, the main branch should never violate this rule.

This concept of applying rules to code is commonly referred to as **linting**.

## Creating a rule

Let's start by creating a new linter directory and adding the necessary dependencies.

```bash
# Create a new directory for the linter script
mkdir linter

# Change into the new linter directory
cd linter

# Initialize a new package.json file
npm init -y

# Add the necessary dependencies
npm i @babel/parser @babel/traverse @babel/code-frame glob ts-node typescript
npm i -D @types/babel__traverse @types/babel__code-frame @types/glob
```

Then, create a new `rule-00.ts` file with much of the same initial setup as the previous custom audit script.

```typescript { actualFilename=./protected/linter/rule-00.ts endChar=1281 endLine=42 startChar=0 startLine=1 statedFilename=rule-00.ts url=https&#x3A;//gitlab.com/fullstackio/books/practical-ast-and-codemods/module_06/lesson_06.01/protected/linter/rule-00.ts }
import { parse } from "@babel/parser";
import traverse from "@babel/traverse";
import * as fs from "fs";
import * as glob from "glob";

const files = glob.sync("../flash-cards/src/components/**/*.js");

files.forEach((file) => {
  const contents = fs.readFileSync(file).toString();

  const ast = parse(contents, {
    sourceType: "module",
    plugins: ["jsx"],
  });

  traverse(ast, {
    JSXOpeningElement({ node }) {
      if (node.name.type === "JSXIdentifier" && node.name.name === "button") {
        // Find the JSXAttribute (prop) with a name of
        // `className` where it's value is a space separated
        // string of class names where one of the class
        // names is `button`.
        const hasButtonClassName = node.attributes.find((attribute) => {
          return (
            attribute.type === "JSXAttribute" &&
            attribute.name.type === "JSXIdentifier" &&
            attribute.name.name === "className" &&
            attribute.value.type === "StringLiteral" &&
            attribute.value.value.split(" ").includes("button")
          );
        });

        // Ignore any button elements that don't also have 
        // the button class name
        if (!hasButtonClassName) return;

        // TODO: lint...
      }
    },
  });
});
```

Since all the nodes that matched these criteria were transformed in the previous module, no nodes will match these criteria in the codebase.

To test this, a new violation can intentionally be added to verify it works as expected. Update the `LandingPage` component in the Flash codebase (or any other component) with the following snippet anywhere in the component.

```javascript { actualFilename=./protected/flash-cards/src/components/LandingPage/LandingPage.js endLine=25 startLine=23 statedFilename=src/components/LandingPage/LandingPage.js url=https&#x3A;//gitlab.com/fullstackio/books/practical-ast-and-codemods/module_06/lesson_06.01/protected/flash-cards/src/components/LandingPage/LandingPage.js#L23 }
    <button className="button">
      Hello World!
    </button>
```

Now there is a violation, the linting rule can be updated to log the file and line that violates this rule, to make it easy to find and fix. Each node contains a `loc` property that is an object with information about the starting and ending lines and the column numbers.

```json
// Example value of the `loc` property on a node:
{
  "start": { "line": 23, "column": 4 },
  "end": { "line": 23, "column": 31 }
}
```

:::note

When using AST Explorer, make sure **Hide location data** is **disabled** for this module. It will otherwise hide all of the `loc` properties from the tree view.

:::

This location information can be appended to the filename to make it easier to jump directly to the position in the code that the violation occurs.

```typescript { actualFilename=./protected/linter/rule-01.ts endChar=1651 endLine=48 startChar=418 startLine=18 statedFilename=rule-01.ts url=https&#x3A;//gitlab.com/fullstackio/books/practical-ast-and-codemods/module_06/lesson_06.01/protected/linter/rule-01.ts#L18 }
    JSXOpeningElement({ node }) {
      if (node.name.type === "JSXIdentifier" && node.name.name === "button") {
        const hasButtonClassName = node.attributes.find((attribute) => {
          return (
            attribute.type === "JSXAttribute" &&
            attribute.name.type === "JSXIdentifier" &&
            attribute.name.name === "className" &&
            attribute.value.type === "StringLiteral" &&
            attribute.value.value.split(" ").includes("button")
          );
        });

        if (!hasButtonClassName) return;

        // At this point, it means a violation (eg: 
        // `<button className="button" />`) was found. 
        // Print the error, the current file, and 
        // concatenate the line and column of the 
        // violation position in the original source 
        // code. This makes it easy to copy and paste 
        // into an editor like VSCode and it'll open the
        // file with the cursor at that position.
        const { start } = node.loc;
        console.error(
          `${path.resolve(file)}:${start.line}:${start.column + 1}`
        );
        console.error(
          `  Found "button" element that should be "Button" component.`
        );
      }
    },
```

Spencer Miskoviak

The flash codebase now uses button components.

To get to this point, we first performed an audit of the codebase to understand

Then we created a button component that was capable of handling all of those

Finally, we performed a code mod to transform all of the button elements to the

This completes the original refactor described in Module 3.

However, an actual codebase will continue to evolve and have further changes

How do we ensure the codebase remains up to date using the button component

A common approach for this is to create a rule for that codebase that enforces

Any time a change is made, the codebase can be checked against that rule.

If there are any violations, the change can be blocked.

For example, in a git workflow, a change is made in a branch off the main

Before that branch can be merged back into the main branch, this rule, in

This way, the main branch should never violate this rule.

This concept of applying rules to code is commonly referred to as linting.

We can get started by creating another new directory called linter.

And again, initialize a new package.json file.

Finally, we can install the same dependencies as the original audit script

And we can also install the type packages for these.

We can start by copying all of the contents from the previous audit script.

Again, we can remove all of the logging and tracking of the props and values.

Since all the nodes that match these criteria were transformed in the previous

nodes will match these criteria in the codebase.

To test this, let's intentionally add a new violation.

Update the landing page component in the flash codebase, or any one of the

with the following button snippet anywhere in the component.

Now that we know there is a violation, the linting rule can be updated to log

in line that violates this rule, to make it easy to find and fix.

Let's put the snippet of code into AST Explorer to see what kind of location

First, make sure the "high-location data" option is disabled.

Each node contains a location property that is an object with information about

and ending lines and the column numbers for this given node's code.

With this in mind, this location information can be appended to the file name

easier to jump directly to the position in the code that the violation occurs.

Let's get the current JSX opening element starting position.

Then, let's print the full file path using node's path helper.

We can see here that we're getting a type error.

That start does not exist on type of null.

For the purpose of this script, we're not expecting the location property to be

so we can add an exclamation point to assert that it's not null.

Finally, let's print a helpful message describing why this error is occurring.

Now, let's switch back to the terminal and run this new linter rule.

We can see that it prints the full error message here.

Additionally, it provides the full file path and starting position of the line

of where this violation occurred in the source code.

This script provides the basics for a linting rule.

However, copying and pasting the file path to see the code that is violating

It would be nice to include the snippet of code that is causing the violation

Fortunately, there's another Babel package that works great for this, Babel

This package allows printing a piece of code with an inline message or code

It was already installed earlier, so let's update the script to use this

We can start by importing the codeframe columns function from Babel codeframe.

Then we can use this function below to print the code that violates this rule.

Then the location of the exact code that is relevant.

We already have the contents defined above, but we don't have the location or

For the location, we can use the existing location data from the node.

However, the columns are off by one, so we'll need to add one to each of those

First, we want to enable syntax highlighting by setting the highlight code

Second, we can move our error message to be inline.

Running the script will now highlight the same violation, but this time, the