CONTRIBUTING.md

Contributing

Contributions are welcome to the Go compiler!

Setup

Go

Go 1.20+ is needed to work with this repo. On Macs, installing via Homebrew is recommended: brew install go. For Windows & Linux, you can follow Go’s installation guide if you don’t have your own preferred method of package installation.

If you use VS Code as your primary editor, installing the Go extension is highly recommended.

Node

You will also need Node.js installed, as well as PNPM 8.x (npm i -g pnpm). More often than not, you won’t need to touch JS in this repo, but in case you do, be sure to run pnpm install first.

Code Structure

A simple explanation of the compiler process is:

1. Tokenizes (internal/token.go)
2. Scans (internal/js_scanner.go)
3. Prints (internal/printer/print-to-js.go)

Tokenizing takes the raw .astro text and turns it into simple tokens such as FrontmatterStart, FrontmatterEnd, TagStart, TagEnd, etc.

Scanning does a basic scanning of the JS to pull out imports after the tokenizer has made it clear where JS begins and ends.

Printing takes all the output up till now and generates (prints) valid TypeScript that can be executed within Node.

When adding a new feature or debugging an issue, start at the tokenizer, then move onto the scanner, and finally end at the printer. By starting at the lowest level of complexity (tokenizer), it will be easier to reason about.

Tests

It's important to run the test from the root of the project. Doing so, go will load all the necessary global information needed to run the tests.

Run all tests

go test -v ./internal/...

Run a specific test suite

go test -v ./internal/printer

Run a specific test case

Many of our test cases are designed like this:

func TestPrintToJSON(t *testing.T) {
  tests := []jsonTestcase{
  	{
  	  name:   "basic",
  	  source: `<h1>Hello world!</h1>`,
  	  want:   []ASTNode{{Type: "element", Name: "h1", Children: []ASTNode{{Type: "text", Value: "Hello world!"}}}},
  	},
    {
  	  name:   "Comment preserves whitespace",
  	  source: `<!-- hello -->`,
  	  want:   []ASTNode{{Type: "comment", Value: " hello "}},
  	}
  }
}

In this particular instance, the test case is name of the function, a slash /, followed by the name field. If the test case has spaces, you can use them.

go test -v ./internal/... -run TestPrintToJSON/basic
go test -v ./internal/... -run TestPrintToJSON/Comment preserves whitespace

Snapshot testing

We use go-snaps for snapshot testing. Visit their repository for more details on how to use it

Update snapshots

Some of our tests use snapshot tests. If some of you changes are expected to update some snapshot tests, you can use the environment variable UPDATE_SNAPS to do so:

UPDATE_SNAPS=true go test -v ./internal/...

Instead, if there are some obsolete snapshots, you can UPDATE_SNAPS=clean:

UPDATE_SNAPS=clean go test -v ./internal/...

Adding new test cases

The printer tests emit only snapshots. Go to printer_test.go and add a new test case:

{
	name: "New name for this test"
	code: "<div></div>"
}

Then run the below command, and a new snapshot named new_name_for_this_test.snap should appear in the snapshot folder.

go test -v ./internal/printer/printer_test.go

Other tests, like tokenizer and scanner be found in internal/token_test.go, internal/js_scanner_test.go and respectively.

Those tests don't emit any snapshot, and you'll have to add a want field:

{
	name: "New name for this test"
	code: "<div></div>",
	want: want{
		code: "<div></div>"
	}
}