AGLint

<!-- markdownlint-disable -->

 

<p align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="https://cdn.adguard.com/website/github.com/AGLint/aglint_logo_darkmode.svg"> <img alt="AGLint" src="https://cdn.adguard.com/website/github.com/AGLint/aglint_logo_lightmode.svg" width="350px"> </picture> </p> <h3 align="center">Universal adblock filter list linter.</h3> <p align="center"> Supported syntaxes: </p> <p align="center"> <a href="https://adguard.com"><img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px"> AdGuard</a> | <a href="https://github.com/gorhill/uBlock"><img src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg" width="14px"> uBlock Origin</a> | <a href="https://getadblock.com"><img src="https://cdn.adguard.com/website/github.com/AGLint/ab_logo.svg" width="14px"> AdBlock</a> | <a href="https://adblockplus.org"><img src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg" width="14px"> Adblock Plus</a> </p> <p align="center"> <a href="https://www.npmjs.com/package/@adguard/aglint"><img src="https://img.shields.io/npm/v/@adguard/aglint" alt="NPM version" /></a> <a href="https://www.npmjs.com/package/@adguard/aglint"><img src="https://img.shields.io/npm/dm/@adguard/aglint" alt="NPM Downloads" /></a> <a href="https://github.com/AdguardTeam/AGLint/blob/master/LICENSE"><img src="https://img.shields.io/npm/l/@adguard/aglint" alt="License" /></a> </p> <!-- markdownlint-restore -->

Table of Contents:

• Introduction
• Features
• Getting started
  • Prerequisites
  • Installation & Usage
  • Integrate AGLint into your project
• VSCode extension
• Special comments (inline configuration)
  • Ignore adblock rules
    • Ignore single adblock rule
    • Ignore multiple adblock rules
    • Disable some linter rules
    • Change linter rules configuration
• Ignoring files or folders
  • Default ignores
• Configuration
  • Create a configuration file
  • Configuration file name and format
  • Configuration file structure
  • Configuration presets
  • Default configuration file
  • Configuration cascading and hierarchy
    • Why the root option is important
• Linter rules <!-- TODO: maybe should be sorted alphabetically ? -->
  • if-closed
  • single-selector
  • duplicated-modifiers
  • unknown-preprocessor-directives
  • duplicated-hint-platforms
  • duplicated-hints
  • unknown-hints-and-platforms
  • invalid-domain-list
  • invalid-modifiers
  • inconsistent-hint-platforms
  • no-short-rules
  • no-excluded-rules
  • no-invalid-css-syntax
  • no-invalid-css-declaration
• Compatibility
• Use programmatically
• Development & Contribution
• Ideas & Questions
• License
• References

Introduction

AGLint is a universal adblock filter list linter. It supports all popular syntaxes currently in use:

<!--markdownlint-disable MD013-->

• <img src="https://cdn.adguard.com/website/github.com/AGLint/adg_logo.svg" width="14px" alt="AdGuard"> [AdGuard][adg-url]
• <img src="https://cdn.adguard.com/website/github.com/AGLint/ubo_logo.svg" width="14px" alt="uBlock Origin"> [uBlock Origin][ubo-url]
• <img src="https://cdn.adguard.com/website/github.com/AGLint/abp_logo.svg" width="14px" alt="Adblock Plus"> [Adblock Plus][abp-url]
• <img src="https://cdn.adguard.com/website/github.com/AGLint/ab_logo.svg" width="14px" alt="AdBlock"> [AdBlock][ab-url]

<!--markdownlint-enable MD013-->

AGLint can be used as a command-line tool or as a TS/JS library in the Node.js or browser environment.

Our goal is to provide a tool that can be used by everyone who is interested in adblock filters. We want to make it easy to create and maintain filter lists.

Generally the philosophy of AGLint are inspired by [ESLint][eslint]. If you are familiar with ESLint, you will find it easy to use AGLint as well.

Features

• :earth_americas: Universal: supports all syntaxes currently in use: AdGuard, uBlock Origin and AdBlock / Adblock Plus.
• :zap: Fast: made with performance in mind.
• :thumbsup: Easy to use: it can be used as a CLI tool or programmatically.
• :art: Customizable: you can customize the default configuration by creating a file named .aglintrc in the root of your repo.
• :gear: Extensible: you can add your own rules to the linter.
• :globe_with_meridians: Cross-platform: it works on Windows, Linux and macOS.
• :globe_with_meridians: Open-source: the source code is available here on GitHub.
• :free: Free: it is free to use and free to modify.
• :rocket: Latest technologies: it is written in TypeScript and can be used in Node.js and browsers as well.

Getting started

Mainly AGLint is a CLI tool, but it can also be used programmatically. Here is a very short instruction on how to use it as a CLI tool with the default configuration.

Prerequisites

Ensure that Node.js is installed on your computer. Optionally, you can also install pnpm or Yarn for package management.

Installation & Usage

1. Install AGLint to your project:
   • NPM: npm install -D @adguard/aglint
   • PNPM: pnpm install -D @adguard/aglint
   • Yarn: yarn add -D @adguard/aglint
2. Initialize the configuration file for AGLint:
   • NPM: npx aglint init
   • PNPM: pnpm aglint init
   • Yarn: yarn aglint init
3. Run AGLint:
   • NPM: npx aglint
   • PNPM: pnpm aglint
   • Yarn: yarn aglint

That's all! :hugs: The linter will check all filter lists in your project and print the results to the console.

[!NOTE] You can also install AGLint globally, so you can use it without npx or pnpm, but we recommend to install it locally to your project.

[!NOTE] If you want to lint just some specific files, you can pass them as arguments: aglint path/to/file.txt path/to/another/file.txt

[!NOTE] To see all available options, run aglint --help.

To customize the default configuration, see Configuration for more info. If you want to use AGLint programmatically, see Use programmatically.

Integrate AGLint into your project

If you would like to integrate AGLint into your project / filter list, please read our detailed [Integration guide][integration-guide] for more info.

VSCode extension

We have created a VSCode extension that fully covers adblock filter list syntax. It is available [here][vscode-extension].

This extension enables syntax highlighting, and it's compatible with AGLint. Typically, it means that this extension will detect all syntax errors and show them in the editor, and on top of that, it will also show some warnings and hints, because it also runs AGLint under the hood.

GitHub Linguist [also uses][linguist-pr] this extension to highlight adblock filter lists.

We strongly recommend using this extension if you are working with adblock filter lists.

Special comments (inline configuration)

You may not want to lint some adblock rules, so you can add special inline comments to disable linting for a single adblock rule or for the rest of the file. To do that, you need to add special comments to your adblock filter list, which can be used to change the linter's behavior. Generally these "control comments" begins with the ! aglint prefix.

In the following sections you can find more info about these comments.

Ignore adblock rules

Ignore single adblock rule

You can completely disable linting for an adblock rule by adding ! aglint-disable-next-line comment before the adblock rule. For example, example.com##.ad will be ignored in the following case:

! aglint-disable-next-line
example.com##.ad
example.net##.ad

This lets you disable linting for a single adblock rule, but it doesn't disable linting for the rest of the file. If you want to disable linting for the rest of the file, you can add ! aglint-disable comment before the first adblock rule or add the file path to the ignore list (.aglintignore file). See Ignoring files or folders for more info.

Ignore multiple adblock rules

If you want to ignore multiple adblock rules, you can add ! aglint-disable comment before the first adblock rule and ! aglint-enable comment after the last adblock rule. For example, example.com##.ad and example.net##.ad will be ignored in the following case:

! aglint-disable
example.com##.ad
example.net##.ad
! aglint-enable
example.org##.ad

Disable some linter rules

In some cases, you may want to disable some linter rules for a s