diff --git a/README.md b/README.md index a62ffd2983..362ca95a07 100644 --- a/README.md +++ b/README.md @@ -206,7 +206,7 @@ or ### Replacing `template-lint-disable` comments -Inline disable directives need to be rewritten to ESLint's syntax, prefixed with `ember/template-`. For now, only two scopes are supported: the next line, or the rest of the file. For example, replace: +Inline disable directives need to be rewritten to ESLint's syntax, prefixed with `ember/template-`. ESLint's own scopes are the next line and the rest of the file, but an `eslint-disable` / `eslint-enable` pair delimits an arbitrary region, so every template-lint scope has an exact equivalent. For example, replace: ```hbs {{!template-lint-disable no-invalid-role}} @@ -218,7 +218,15 @@ with: {{!eslint-disable-next-line ember/template-no-invalid-role}} ``` -The [`template-no-template-lint-directives`](docs/rules/template-no-template-lint-directives.md) rule (enabled by the `template-lint-migration` config) does this rewrite for you: run `eslint --fix` once and it converts every `template-lint-disable` / `template-lint-enable` comment in your templates. +or, to cover a region rather than one line, bracket it: + +```hbs +{{!eslint-disable ember/template-no-invalid-role}} +
+{{!eslint-enable ember/template-no-invalid-role}} +``` + +The [`template-no-template-lint-directives`](docs/rules/template-no-template-lint-directives.md) rule (enabled by the `template-lint-migration` config) does this rewrite for you: run `eslint --fix` once and it converts every `template-lint-disable` / `template-lint-enable` comment in your templates, including the element-scoped and `-tree` forms, preserving each directive's original scope. To disable a rule for an entire `.gjs`/`.gts` file, use a regular ESLint file-level directive in the JS region — it applies to the `` contents as well: diff --git a/docs/rules/template-no-template-lint-directives.md b/docs/rules/template-no-template-lint-directives.md index 13caf9737d..0edba74561 100644 --- a/docs/rules/template-no-template-lint-directives.md +++ b/docs/rules/template-no-template-lint-directives.md @@ -15,9 +15,30 @@ The fixer: - replaces `template-lint-disable` / `template-lint-enable` with `eslint-disable` / `eslint-enable`; - prefixes each rule name with `ember/template-` (the namespace the rules are published under in this plugin); - joins multiple rule names with `,` (ESLint's directive syntax) instead of whitespace (template-lint's syntax); -- when the directive appears inside an element's opening tag (between attributes), lifts it to its own line just before the element. ESLint scopes line-based directives from the line they appear on, and the violation typically lives on the element's start line, so leaving the directive inside the attribute list would put it after the violation it's meant to cover. +- converts an element-scoped directive into an `eslint-disable` / `eslint-enable` pair bracketing that element (see below). -The `-tree` suffix on a directive (e.g. `template-lint-disable-tree`) does **not** match this rule. ESLint has no equivalent of template-lint's subtree-scoped directives, so they need manual handling rather than a mechanical conversion. +### Preserving scope + +`template-lint-disable` means different things depending on where it sits, and a +conversion that ignores that either hides violations or floods a migration with +noise. ESLint has no element scope, but an `eslint-disable` / `eslint-enable` +pair delimits an arbitrary region, which reproduces every template-lint scope +exactly: + +| `template-lint-disable` placement | scope | conversion | +| ---------------------------------- | ----------------------------------------------- | ----------------------------------------------------------------------- | +| standing alone | comment → end of template | `eslint-disable` (rest of file) | +| paired with `template-lint-enable` | between the two | `eslint-disable` … `eslint-enable` | +| inside an element's opening tag | that element's opening tag, not its descendants | `eslint-disable` before the element, `eslint-enable` as its first child | +| with the `-tree` suffix | that element and its descendants | `eslint-disable` before the element, `eslint-enable` after it | + +The closing comment is inserted without a surrounding newline. `{{! }}` comments +compile away and leave no trace in the DOM, but a newline would add a whitespace +text node, which can change inline layout. + +To suppress a rule across a whole file, use a file-level ESLint directive — in +`.gjs`/`.gts` a `/* eslint-disable ember/template-… */` in the JS region also +covers the `` contents. ## Examples @@ -38,7 +59,15 @@ Examples of **incorrect** code for this rule: class='example' {{! template-lint-disable no-invalid-interactive }} {{on 'click' this.click}} -> +>hi +``` + +```hbs +