Authoring custom patterns

We recommend authoring Grit patterns in .md files, as this format allows you to combine documentation, GritQL, and source code examples in a single file.

VS Code

We recommend installing the Grit extension to get syntax highlighting and authoring assistance for Grit patterns.

You can watch this video to see the extension in action.

Authoring Walkthrough

Tips

  • Use the grit patterns test command to test all defined patterns in your repo.
  • As you are iterating on a pattern, you can use --watch to automatically re-run tests when you save a file.
  • You can use --filter to run a subset of patterns: this speeds up the test cycle when you are working on a specific pattern.

Markdown Format

Patterns can be stored in *.md files within a .grit/patterns folder at the root of your repo.

  • The name of the file is used as the name of the pattern (without the .md extension).
  • The title of the pattern is retrieved from the first heading in the file. This can be overridden by adding a title field in the front matter.
  • The description of the pattern is retrieved from the first non-heading paragraph in the file.
  • The GritQL body is retrieved from the first fenced code block in the file.
  • Additional pattern metadata can be configured as YAML in the frontmatter of the markdown file, delineated between --- lines at the start of the document.
    • level: (Optional, one of none, info, warn, error) The enforcement level of the pattern for running diagnostics via grit check. Defaults to info.
    • tags: (Optional, string[]) A list of tags which can be used to filter patterns.
  • Subheadings are used for each test case, following these conventions:
    • If a subheading has a single code block, it represents a test case that should be matched by the pattern. You don't need to provide a transformed example.
    • If a subheading has two code blocks, the first represents the input and the second represents the expected output.
    • A negative test case should have two identical code blocks.
    • Within the sample patterns, you can use // @filename: example.js to represent multiple input/output files that should be tested as a group - like this example.

Example

Here is an example of a markdown pattern file:

MARKDOWN .grit/patterns/remove_console_log.md
---
tags: [optional, tags, here]
---
# Remove console.log

Remove console.log in production code.

```grit
`console.log($_)` => .
```

## Test case one

This is the first test case. You can include an explanation of the case here.

```typescript
console.error("keep this");
console.log('remove this!');
```

It is fine to include additional descriptive text around the test cases.
This is often used to explain the context of the test case, or to explain a convention.

```typescript
console.error("keep this");

```

You can find many more examples in the Grit standard library.