new-eslint-rule
Scaffold a new lint rule in `@grafana/eslint-plugin-design` — generates the rule implementation skeleton, RuleTester test file, per-rule markdown doc, and wires the rule into the plugin's barrel and `configs.recommended`. Use when adding a new deterministic check derived from `@grafana/design-catalog` (migration recipe, STYLING.md anti-pattern, USAGE.md anti-pattern). Does not write the visitor logic itself — that's authored by hand against the actual AST shape the rule needs to inspect.
- License 许可
- Apache-2.0
- 所属仓库
- torkelo/scenes2
- 最近更新
- 2026-11-14
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- new-eslint-rule
- metadata
- { "source": ".hatch/_skills/new-eslint-rule/SKILL.md", "generated": "hatch@v1.2.0" }
- description
- Scaffold a new lint rule in `@grafana/eslint-plugin-design` — generates the rule implementation skeleton, RuleTester test file, per-rule markdown doc, and wires the rule into the plugin's barrel and `configs.recommended`. Use when adding a new deterministic check derived from `@grafana/design-catalog` (migration recipe, STYLING.md anti-pattern, USAGE.md anti-pattern). Does not write the visitor logic itself — that's authored by hand against the actual AST shape the rule needs to inspect.
- allowed-tools
- Read, Write, Edit, Glob, Grep, Bash
- argument-hint
- <rule-slug>
03 SKILL.md 正文
Scaffold a new lint rule
Create a new rule $ARGUMENTS[0] in @grafana/eslint-plugin-design. The slug is the rule's canonical name — kebab-case, no @grafana/design/ prefix. Examples that match the existing convention: no-bare-grafana-data-import, prefer-usage-md-cross-link, no-deprecated-icon-shim-import.
Before starting
Read these reference files to ensure the new rule matches current convention:
packages/eslint-plugin-design/src/index.ts— plugin barrel; you'll add the new rule here.packages/eslint-plugin-design/src/utils/ast-helpers.ts—createRulehelper, shared AST predicates (isStyleFile,isInsideIife,getImportSourceForJsxName,getFilename).packages/eslint-plugin-design/src/utils/catalog-loaders.ts— lazy-loaders for catalog data from@grafana/design-catalog. If the rule needs a list of canonical components, valid token names, or recipe slugs, source them from here rather than hard-coding.- An existing rule whose shape is close to the one you're building. List
packages/eslint-plugin-design/src/rules/— if a rule of the same AST category already exists, read it + its matching test + doc alongside so the new files match the convention. If no same-shape rule exists yet, use the shape guide below.
Shape guide:
| Category | AST entry point | Key utilities | Typical fix |
|---|---|---|---|
| Import-shape rules | ImportDeclaration / ImportSpecifier |
Track import bindings in a Set<string>; visit Identifier references later |
Rewrite or remove import specifiers |
| JSX-shape rules | JSXElement / JSXAttribute |
getImportSourceForJsxName(context, name) from ../utils/ast-helpers.js to gate on the source module |
Rewrite JSX attributes or children |
| Style-file gating rules | any node, gated on filename | isStyleFile(getFilename(context)) from ../utils/ast-helpers.js; isInsideIife(node) for cssVariables IIFEs |
Often advisory (no auto-fix) |
| Call-expression rules | CallExpression |
Gate on callee.name resolving to an import binding; inspect arguments |
Rewrite or remove arguments |
| Selector-key rules in object expressions | ObjectExpression / Property |
Match the key of each Property against a selector pattern (Emotion css({}) rule tree) |
Advisory; rule-shape changes are bespoke |
Step 1 — Gather rule metadata
If the user hasn't already described the rule, ask:
-
What does the rule catch? One sentence on the anti-pattern. This becomes the rule's
meta.docs.description. -
Severity in
recommended—errororwarn. Errors block CI by convention; warnings surface as advisory annotations. Lean towarderrorfor unambiguous anti-patterns sourced from a migration recipe; lean towardwarnfor "should consider" guidance. -
Auto-fix? —
none,partial(fix some violations, leave call sites), orfull(every violation auto-fixable). Drives the rule'smeta.fixablefield and the doc's auto-fix section. -
AST entry point(s) — which TSESTree node types the visitor inspects (
ImportDeclaration,JSXElement,CallExpression,Literal,ObjectExpression, etc.). Drives the create function's return shape. -
Catalog source — which
@grafana/design-catalogentry motivates this rule. Usually one of:- A migration-recipe slug (e.g.
usestyles2-to-getdesigntokens). - A
STYLING.mdsection heading. - A component USAGE.md anti-pattern.
- A
CLAUDE.mdparagraph.
The doc links back to this source so consumers can chase the rationale.
- A migration-recipe slug (e.g.
Derive the camelCase rule name from the slug — no-bare-grafana-data-import → noBareGrafanaDataImport. This is the exported binding from the rule file and the import name in the barrel.
Step 2 — Generate the three rule files
All paths under packages/eslint-plugin-design/. Use Write for new files.
src/rules/$ARGUMENTS[0].ts
Skeleton — fill in the description, messageIds, and create body once the rule's logic is clear.
/**
* <One-paragraph rationale. Reference the catalogue source.>
*/
import type { TSESTree } from '@typescript-eslint/utils';
import { createRule } from '../utils/ast-helpers.js';
type MessageIds = '<messageId1>' /* | '<messageId2>' */;
export const <camelCaseRuleName> = createRule<[], MessageIds>({
name: '<rule-slug>',
meta: {
type: 'problem', // or 'suggestion'
docs: {
description: '<one-sentence description matching the user's brief>',
},
// fixable: 'code', // uncomment if the rule provides any auto-fix
schema: [],
messages: {
'<messageId1>': '<violation message — explain remediation>',
},
},
defaultOptions: [],
create(context) {
return {
// <AST entry point>(node: TSESTree.<NodeType>) {
// if (/* violation condition */) {
// context.report({ node, messageId: '<messageId1>' });
// }
// },
};
},
});
Notes:
type: 'problem'for unambiguous violations (e.g.errorseverity);type: 'suggestion'for advisory rules (e.g.warnseverity). Drives ESLint's reported metadata.- Multiple
messageIds if the rule reports distinct violations (e.g. an import-level violation and a call-site violation). Convention: one messageId per logical reason the rule fires. - If the rule uses shared helpers, import them from
../utils/ast-helpers.js(note the.jsextension — required for ESM imports). - If the rule needs catalog data, import from
../utils/catalog-loaders.js.
tests/rules/$ARGUMENTS[0].test.ts
import { <camelCaseRuleName> } from '../../src/rules/$ARGUMENTS[0].js';
import { ruleTester } from '../rule-tester.js';
ruleTester.run('$ARGUMENTS[0]', <camelCaseRuleName>, {
valid: [
// At least three real fixtures that should NOT trigger.
// Include one obvious case (correct code) and at least one
// false-positive guard (code that superficially looks like a
// violation but isn't — wrong import source, wrong file name,
// wrong AST shape).
],
invalid: [
// At least three fixtures that SHOULD trigger.
// Each must exercise a distinct messageId or auto-fix path.
// Shape:
// {
// code: '<source>',
// output: '<source after --fix, or null if no fix>',
// errors: [{ messageId: '<messageId1>' }],
// },
],
});
Convention: every messageId declared in the rule's meta is exercised by at least one fixture in invalid. Every auto-fix path has its output verified.
docs/rules/$ARGUMENTS[0].md
# `$ARGUMENTS[0]`
> **Severity in `recommended`:** <error | warn>
> **Auto-fix:** <none | partial | full> — <one-line description of what's auto-fixed>
## Summary
<One-sentence restatement of the rule for skim-readers.>
## Motivation
<One or two paragraphs explaining the anti-pattern and why the canonical
form is preferred. Link to the catalogue source at the end.>
Sourced from the [`<recipe-slug>`](../../../design-catalog/src/resources/migration-recipes.json) migration recipe.
## Incorrect
\`\`\`ts
// minimal violating snippet
\`\`\`
## Correct
\`\`\`ts
// canonical replacement
\`\`\`
## Auto-fix
<Describe what the auto-fix does and what it leaves manual. If the rule
has no auto-fix, replace this section with "Not auto-fixable. <one-line
reason>".>
## Options
<List `meta.schema` options if any. Otherwise: "None.">
## References
- [`migration-recipes.json` — `<recipe-slug>`](../../../design-catalog/src/resources/migration-recipes.json)
- [Doc URL](https://github.com/grafana/design/blob/main/packages/eslint-plugin-design/docs/rules/$ARGUMENTS[0].md)
Replace the catalog-source reference (recipe slug, STYLING.md section, etc.) with whatever the rule is actually motivated by.
Step 3 — Wire the rule into the plugin barrel
Edit packages/eslint-plugin-design/src/index.ts:
-
Add the import in the import block, keeping alphabetical order:
import { <camelCaseRuleName> } from './rules/$ARGUMENTS[0].js'; -
Add the rule to the
rulesobject, keyed by its slug, keeping alphabetical order:'$ARGUMENTS[0]': <camelCaseRuleName>, -
Add the rule to
configs.recommended.rulesat the chosen severity, keeping alphabetical order:'@grafana/design/$ARGUMENTS[0]': '<error | warn>',
The barrel is already type-checked, so a missed entry surfaces at build time.
Step 4 — Validate
Run from the repo root:
pnpm install # only if dependencies changed
pnpm --filter=@grafana/eslint-plugin-design typecheck
pnpm --filter=@grafana/eslint-plugin-design lint
pnpm --filter=@grafana/eslint-plugin-design build
pnpm --filter=@grafana/eslint-plugin-design test
pnpm prettier --write packages/eslint-plugin-design/src/rules/$ARGUMENTS[0].ts packages/eslint-plugin-design/tests/rules/$ARGUMENTS[0].test.ts packages/eslint-plugin-design/docs/rules/$ARGUMENTS[0].md
The rule's RuleTester suite will fail until you write real fixtures — that's expected at this stage. Use the test runner's failure output as the prompt to flesh out the test cases.
Step 5 — Hand off
The scaffolding is done; the user (or the same session, with the rule's contract now clear) writes:
- The visitor body inside
create(context). - The auto-fix closure if
fixable: 'code'. - The real
valid/invalidfixtures in the test file. - The prose paragraphs (motivation, incorrect/correct examples, references) in the doc.
When the rule is functionally complete, the conventional commit on this branch is:
feat(eslint-plugin-design): add $ARGUMENTS[0] rule
The scaffolded src/index.ts edit is part of the same commit so the plugin barrel and the new rule land together.
Rules of the road
- Slug is the contract. The file name, the export name (camelCased), the
meta.name, the messageId namespace, the doc URL — all derive from the slug. Pick it once at the start; don't rename mid-flow. - Imports use
.jsextensions. This package is ESM; the build emits.jsfiles and TypeScript needs the explicit extension on intra-package imports. - Anti-pattern source first. A rule without a catalog / docs source to point at is a rule reviewers will push back on. If the user can't name the source, that's a signal to either write the source first or reconsider the rule.
- Don't write the visitor logic for the user. Scaffolding gives a working skeleton; the visitor needs the rule author's judgment about AST shapes, false-positive guards, and remediation strategy. Stop after the wire-up step.
errorvswarnaligns with severity, not opinion-strength. Errors fail CI, warnings annotate. The choice is mostly about whether a violation is unambiguously wrong (error) or might be intentional in some cases (warn).
04 同仓库更多 Skills
validate-plugin
validate a Grafana plugin using the official Grafana plugin validator
build-plugin
build a Grafana plugin using the standard build process (frontend and backend if applicable)
validate-plugin
暂无简介
build-plugin
暂无简介
stop-slop
Remove AI writing patterns from prose. Use when drafting, editing, or reviewing text to eliminate predictable AI tells.
snag-fixer
Lightweight agent for quick fixes, tweaks, and small improvements. Optimized for single-task focused work without bloating context. Used by snag workflow for sequential fix processing.