Development Guide

July 9, 2026 · View on GitHub

Developer guide for the @vscode-adblock-syntax/syntaxes package: the TextMate grammar source for adblock filter syntax, its compiler, and its tokenization tests.

This is part of a monorepo. For environment setup and repo-wide commands, start with the root DEVELOPMENT.md. For code guidelines and architecture, see AGENTS.md.

Table of Contents

Overview

This package owns the syntax-highlighting grammar. The grammar is authored in YAML (adblock.yaml-tmlanguage) and compiled to a TextMate PList (out/adblock.plist) that the root extension contributes to VSCode (and that GitHub Linguist uses). It also provides a tokenization test harness that loads the real grammar with vscode-textmate + vscode-oniguruma and asserts token scopes for sample rules. All dependencies are build/test-only.

Prerequisites

Node.js v22, pnpm v10, Git. See the root Prerequisites. Run pnpm install once from the repository root.

Getting Started

Build the grammar so the compiled out/adblock.plist exists (the tokenization tests load it):

pnpm --filter @vscode-adblock-syntax/syntaxes build

To preview highlighting visually, open the test/static folder in the Extension Development Host (F5 from the repo root).

Development Workflow

Run these from this directory, or from the repo root with the --filter @vscode-adblock-syntax/syntaxes flag.

Build

pnpm --filter @vscode-adblock-syntax/syntaxes build           # tsx scripts/build.ts (YAML -> PList)
pnpm --filter @vscode-adblock-syntax/syntaxes build -- --watch # incremental rebuilds

The prebuild script clears out/ first. Never hand-edit the generated PList — edit the YAML source and rebuild.

Test

pnpm --filter @vscode-adblock-syntax/syntaxes test    # Vitest tokenization tests

Tokenization tests live in test/adblock/, grouped by rule category (comments, cosmetic, network). They tokenize sample rules with the real grammar and assert scopes via the custom expect-tokenization matcher in test/setup/custom-matchers. Build the grammar before running tests.

Lint

pnpm --filter @vscode-adblock-syntax/syntaxes lint        # ESLint + markdownlint
pnpm --filter @vscode-adblock-syntax/syntaxes lint:code   # ESLint (add -- --fix)
pnpm --filter @vscode-adblock-syntax/syntaxes lint:md     # markdownlint

Type check

pnpm --filter @vscode-adblock-syntax/syntaxes exec tsc --noEmit

Common Tasks

Updating the grammar

  1. Edit the grammar in adblock.yaml-tmlanguage.
  2. Add or modify example rules under test/static/rules (link related GitHub issues in the rule files).
  3. Rebuild the grammar, then add or update tokenization tests under test/adblock/ and run the test command above.
  4. Open the test/static folder in the Extension Development Host to verify highlighting visually.

You can also experiment with the grammar on the online TextMate test page.

The grammar's scope name (text.adblock), output path (syntaxes/out/adblock.plist), and embedded-language mapping are wired up in the root package.json contributes.grammars. Update that manifest if scope names or output paths change.

Troubleshooting

  • Tests fail to load the grammar: run the build first; tests load the compiled out/adblock.plist.
  • Build fails with a YAML error: the build validates the source and reports a located error (e.g. file:line:col); fix the YAML at that position.
  • Highlighting looks wrong in the host: rebuild the grammar and reload the Extension Development Host window.

Additional Resources