@adonisjs/eslint-ast-grep

Run ast-grep YAML rules through ESLint.

Write lint rules as ast-grep YAML, test them with the ast-grep CLI, and enforce them from ESLint alongside your other rules. Matching runs on @ast-grep/napi inside the ESLint process, so editors, --cache, severity overrides, and disable comments all work as usual.

Installation

npm i -D @adonisjs/eslint-ast-grep

Usage

// eslint.config.js
import { configApp } from '@adonisjs/eslint-config'
import { astGrep } from '@adonisjs/eslint-ast-grep'

export default configApp(...astGrep(['./rules', '@adonisjs/core/rules']))

astGrep accepts one source or an array. A source is either:

• a local file or directory, starting with ./, ../, or /, resolved from the current working directory
• a path inside an installed package, such as @scope/pkg/rules, found by walking node_modules from the current working directory. The package does not need to export the directory.

Directories are searched recursively for .yml and .yaml files, and a file may hold several YAML documents. Duplicate rule ids are an error.

Options:

astGrep('./rules', {
  root: import.meta.dirname, // where sources resolve from, defaults to process.cwd()
  namespace: 'ast-grep', // rule id prefix, "ast-grep/<id>" by default
})

How YAML fields map to ESLint

The whole YAML document is handed to ast-grep as the matcher, so rule, constraints, utils, and transform behave exactly as documented by ast-grep.

| YAML field | ESLint behaviour | | ------------------ | ----------------------------------------------------------------------------------------- | | id | Creates the rule ast-grep/<id>. | | language | Selects the grammar. NAPI bundles JavaScript, TypeScript, and TSX. | | files, ignores | Scope the rule with ESLint glob semantics. Without files, the rule runs on JS/TS files. | | severity | error → error; hint, info, warning → warning; off → off. Defaults to hint. | | message | Interpolates $VAR, $$VAR, and $$$VAR captures and transforms. Defaults to the id. | | note | Appended to the message as a second sentence. | | url | Sets the rule's documentation URL. | | fix | Unsupported. Loading fails with an error naming the rule. |

ESLint owns file discovery, so only files ESLint already lints are checked. labels, metadata, and anything from sgconfig.yml such as global utils are ignored.

Testing rules

Use the ast-grep CLI. Rules tested with ast-grep test run unchanged under ESLint.