eslint-plugin-test-governance 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -6,6 +6,57 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-08
+
+This release changes how the plugin is configured, ahead of 1.0.
+[Upgrading to 0.5](https://github.com/Huldoser/eslint-plugin-test-governance/blob/main/docs/upgrading.md#upgrading-to-05)
+shows what to change, with a before and after for each one.
+
+### Changed
+
+- **Breaking:** `configure()` needs a `framework`, as in
+  `configure({ framework: 'playwright', ticket: { preset: 'jira' } })`, and so does
+  `settings['test-governance']` in a config you build yourself. Before, a config without one checked
+  files as Playwright tests. Now `configure()` fails when the config file loads, and hand-written
+  settings fail on the first lint, with a message that names the three frameworks. To share options
+  between frameworks, pass the same options to a `configure()` for each one.
+- **Breaking:** `reportDynamicTitles` is renamed to `reportUnreadableTags`, because it also reports
+  tags and details objects imported from another module, not only titles. It works the same way, and
+  a config that still uses the old name fails with a message that names the new one.
+- Vitest's `skipIf(true)` and `runIf(false)` always skip, so they need a ticket, like `{ skip: true }`
+  and Playwright's `test.skip(true)`. `skipIf(false)` and `runIf(true)` never skip, so a `// SKIP:`
+  marker above one is reported as left over. Any other condition is still a conditional skip. Before,
+  a literal condition was treated like any other.
+
+### Removed
+
+- **Breaking:** `configs.recommended` is gone. It checked every file as Playwright tests, so pick the
+  config for your framework instead: `configs.playwright`, `configs.jest` or `configs.vitest`. For
+  Playwright, replace `configs.recommended` with `configs.playwright`, and
+  `extends: ['test-governance/recommended']` with `extends: ['test-governance/playwright']`. The
+  rules and their severities are the same. A config that still reads `configs.recommended` fails when
+  it loads, with a message that points to the upgrade guide, rather than spreading nothing and turning
+  the rules off.
+
+### Fixed
+
+- Tags kept in a `const` or an enum in the same file count, as in `{ tag: TAGS.NEW }` after
+  `const TAGS = { NEW: '@new' } as const`, with spreads, `as const` and `satisfies`, and so do titles
+  and details objects kept in a constant. Before, a test tagged this way needed no ticket, and a
+  correct `// NEW:` marker above it was reported as left over.
+- Tags and details imported from another module can't be read, so a marker for a tag state above such
+  a test is no longer reported as left over, and neither is a Vitest state marker such as `// SKIP:`
+  above a test whose options object is imported. With `reportUnreadableTags: true`, the unreadable
+  tags are reported, like titles that aren't static text.
+- Vitest tag names, which are written without the `@` (`{ tags: ['flaky'] }`), match the states:
+  `'new'` is `@new`, and a custom state with `when: '@flaky'` matches `'flaky'`. Before, they never
+  matched. `no-conflicting-states` shows and fixes them without the `@`.
+- `context.skip()` in Vitest's `beforeEach`, global or imported, needs a ticket, like the one in
+  `test.beforeEach`. Before, it wasn't checked.
+- A marker in the wrong case with a ticket, such as `// skip: TRADE-1`, is reported by
+  `no-orphaned-marker` once the test is no longer skipped, and by `marker-matches-state` above a test in
+  another state. Before, it was only reported while the test was still in that state.
+
 ## [0.4.0] - 2026-10-08
 
 ### Added
@@ -194,7 +245,8 @@ First release.
 - Support for ESLint 9 and 10 flat config, JavaScript and TypeScript test files, `.extend()`
   fixtures, describe blocks, runtime skips and tags in titles or the `tag` option.
 
-[Unreleased]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.5.0...HEAD
+[0.5.0]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.4.0...v0.5.0
 [0.4.0]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.3.1...v0.4.0
 [0.3.1]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.3.0...v0.3.1
 [0.3.0]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.2.1...v0.3.0

package/README.md

@@ -7,6 +7,8 @@
 ESLint rules that keep a Playwright, Jest or Vitest suite honest. Every skipped, fixme, todo, `@new`
 or `@unstable` test must point at the ticket that tracks it:
 
+<!-- example: valid -->
+
 ```ts
 // SKIP: TRADE-123
 test.skip('rejects a margin order above the buying power', async ({ page }) => {
@@ -18,7 +20,8 @@ Without the comment, `test-governance/require-ticket` fails the lint. When the t
 skip removed, `no-orphaned-marker` flags the leftover comment. The markers are plain
 comments, so `grep -rn "SKIP:" tests/` lists every disabled test and its ticket.
 
-> **Status:** early release (0.x). Options may still change before 1.0.
+> **Status:** early release (0.x). Options may still change before 1.0. Coming from 0.4?
+> [Upgrading to 0.5](docs/upgrading.md#upgrading-to-05) shows what to change.
 
 ## Install
 
@@ -31,6 +34,9 @@ Requires ESLint 9 or 10 with flat config, and Node.js 22.12 or later. For TypeSc
 
 ## Usage
 
+Pick the config for the framework your tests use, `configs.playwright`, `configs.jest` or
+`configs.vitest`, and point it at those test files with `files`:
+
 ```js
 // eslint.config.js
 import tsParser from '@typescript-eslint/parser';
@@ -40,11 +46,16 @@ export default [
   { files: ['**/*.ts'], languageOptions: { parser: tsParser } },
   {
     files: ['tests/**/*.{js,ts}'],
-    ...testGovernance.configs.recommended,
+    ...testGovernance.configs.playwright,
   },
 ];
 ```
 
+There is no default config. Each framework declares, skips and tags tests its own way, so the rules
+need to know which one a file uses. In a Jest or Vitest config, `test`, `it` and `describe` belong to
+that framework, whether they are globals or imported from `@jest/globals` or `vitest`, the way the
+Jest and Vitest ESLint plugins are set up.
+
 With ESLint's `defineConfig()` (ESLint 9.22 or later), put the config in `extends`:
 
 ```js
@@ -57,25 +68,26 @@ export default defineConfig([
   { files: ['**/*.ts'], languageOptions: { parser: tsParser } },
   {
     files: ['tests/**/*.{js,ts}'],
-    extends: [testGovernance.configs.recommended],
+    extends: [testGovernance.configs.playwright],
   },
 ]);
 ```
 
 Any flat config file works. The package is ESM, and `require('eslint-plugin-test-governance')` in an
 `eslint.config.cjs` returns the plugin itself. Inside `defineConfig()`, once the plugin is registered
-under `plugins`, the string form `extends: ['test-governance/recommended']` works too. ESLint loads
+under `plugins`, the string form `extends: ['test-governance/playwright']` works too. ESLint loads
 an `eslint.config.ts` through [`jiti`](https://github.com/unjs/jiti), so install it as a dev
 dependency too.
 
-To change the defaults, use `configure()`. It returns the same recommended config with your options
-stored in `settings['test-governance']`, which all the rules read:
+To change the defaults, use `configure()`. It takes the framework and your options, and returns that
+framework's config with the options stored in `settings['test-governance']`, which all the rules read:
 
 ```js
 export default [
   {
     files: ['tests/**/*.{js,ts}'],
     ...testGovernance.configure({
+      framework: 'playwright',
       // Only accept Jira keys from these projects (or Jira URLs).
       ticket: { preset: 'jira', projects: ['TRADE', 'RISK'] },
       // Turn on the @new and @unstable states.
@@ -98,40 +110,40 @@ eslint-plugin-test-governance: invalid options:
   - ticket.preset must be one of "any", "jira", "github", … (got "jria")
 ```
 
-### Jest and Vitest
+### Frameworks
 
-`recommended` is for Playwright. For Jest and Vitest, use `configs.jest` or `configs.vitest` and
-point it at those test files with `files`, the way the Jest and Vitest ESLint plugins are set up.
-In those files, `test`, `it` and `describe` belong to that framework, whether they are globals or
-imported from `@jest/globals` or `vitest`. Each framework config sets only the framework, so the
-options of an earlier `configure()` still apply to its files:
+A project with tests in more than one framework gives each framework its own config, pointed at its
+files. To share options between them, pass the same options to each `configure()`:
 
 ```js
+const options = { ticket: { preset: 'jira', projects: ['TRADE'] } };
+
 export default [
-  {
-    files: ['e2e/**/*.spec.ts', 'src/**/*.test.ts'],
-    ...testGovernance.configure({ ticket: { preset: 'jira', projects: ['TRADE'] } }),
-  },
-  // Unit tests run on Vitest; the e2e specs stay on Playwright.
-  { files: ['src/**/*.test.ts'], ...testGovernance.configs.vitest },
+  // The e2e specs run on Playwright, the unit tests on Vitest.
+  { files: ['e2e/**/*.spec.ts'], ...testGovernance.configure({ framework: 'playwright', ...options }) },
+  { files: ['src/**/*.test.ts'], ...testGovernance.configure({ framework: 'vitest', ...options }) },
 ];
 ```
 
-`configure({ framework: 'jest', ... })` gives the Jest config with options in one call, and
-`configs.playwright` is the Playwright config with its framework set, for a file list that needs it.
-All four configs turn on the same rules. What puts a test in a state in each framework:
+`configs.playwright`, `configs.jest` and `configs.vitest` set only the framework, so one listed after a
+`configure()` for the same files keeps that config's options and changes only the framework. All three
+turn on the same rules. What puts a test in a state in each framework:
 
-| State (marker)                         | Playwright                                                                                                          | Jest                                                                 | Vitest                                                                                                          |
-| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------- |
-| `skip` (`// SKIP:`)                    | `test.skip(...)`, `test.describe.skip`, `test.skip()` in a body, `testInfo.skip()`, `test.step.skip`, `step.skip()` | `test.skip`, `it.skip`, `describe.skip`, `xit`, `xtest`, `xdescribe` | `test.skip`, `it.skip`, `describe.skip`, `suite.skip`, `{ skip: true }`, `context.skip()` or `skip()` in a body |
-| `todo` (`// TODO:`)                    |                                                                                                                     | `test.todo`, `it.todo`                                               | `test.todo`, `describe.todo`, `{ todo: true }`                                                                  |
-| `fixme` (`// FIXME:`)                  | `test.fixme(...)`, `test.describe.fixme`, `testInfo.fixme()`                                                        |                                                                      |                                                                                                                 |
-| `fail` (`// FAIL:`), off by default    | `test.fail(...)`, `testInfo.fail()`                                                                                 | `test.failing`                                                       | `test.fails`, `{ fails: true }`                                                                                 |
-| `slow` (`// SLOW:`), off by default    | `test.slow()`, `testInfo.slow()`                                                                                    |                                                                      |                                                                                                                 |
-| conditional skip, no ticket by default | `test.skip(condition)`, `if (...) test.skip()`                                                                      |                                                                      | `skipIf(...)`, `runIf(...)`, `{ skip: condition }`, `context.skip(condition)`, `if (...) context.skip()`        |
-| tags such as `@new` (`// NEW:`)        | the title, `{ tag }`                                                                                                | the title                                                            | the title, `{ tags }`                                                                                           |
+| State (marker)                         | Playwright                                                                                                          | Jest                                                                 | Vitest                                                                                                                                                             |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `skip` (`// SKIP:`)                    | `test.skip(...)`, `test.describe.skip`, `test.skip()` in a body, `testInfo.skip()`, `test.step.skip`, `step.skip()` | `test.skip`, `it.skip`, `describe.skip`, `xit`, `xtest`, `xdescribe` | `test.skip`, `it.skip`, `describe.skip`, `suite.skip`, `skipIf(true)`, `runIf(false)`, `{ skip: true }`, `context.skip()` or `skip()` in a body or in `beforeEach` |
+| `todo` (`// TODO:`)                    |                                                                                                                     | `test.todo`, `it.todo`                                               | `test.todo`, `describe.todo`, `{ todo: true }`                                                                                                                     |
+| `fixme` (`// FIXME:`)                  | `test.fixme(...)`, `test.describe.fixme`, `testInfo.fixme()`                                                        |                                                                      |                                                                                                                                                                    |
+| `fail` (`// FAIL:`), off by default    | `test.fail(...)`, `testInfo.fail()`                                                                                 | `test.failing`                                                       | `test.fails`, `{ fails: true }`                                                                                                                                    |
+| `slow` (`// SLOW:`), off by default    | `test.slow()`, `testInfo.slow()`                                                                                    |                                                                      |                                                                                                                                                                    |
+| conditional skip, no ticket by default | `test.skip(condition)`, `if (...) test.skip()`                                                                      |                                                                      | `skipIf(condition)`, `runIf(condition)`, `{ skip: condition }`, `context.skip(condition)`, `if (...) context.skip()`                                               |
+| tags such as `@new` (`// NEW:`)        | the title, `{ tag }`                                                                                                | the title                                                            | the title, `{ tags }`, where `'new'` and `'@new'` both mean `@new`                                                                                                 |
 
 Table-driven tests count too: `test.skip.each(table)(...)`, `describe.skip.each` and Vitest's `.for`.
+A literal condition decides on its own: `skipIf(true)` and `runIf(false)` always skip, and `skipIf(false)`,
+`runIf(true)` and `{ skip: false }` never do.
+Vitest writes tag names without the `@`, as in `{ tags: ['flaky'] }`, so a name in `tags` counts as the
+tag with an `@` in front: `'flaky'` is `@flaky`, and a custom state with `when: '@flaky'` matches it.
 
 ## Rules
 
@@ -139,27 +151,29 @@ Table-driven tests count too: `test.skip.each(table)(...)`, `describe.skip.each`
 
 💼 [Configurations](https://github.com/Huldoser/eslint-plugin-test-governance#usage) enabled in.\
 ⚠️ [Configurations](https://github.com/Huldoser/eslint-plugin-test-governance#usage) set to warn in.\
-✅ Set in the `recommended` [configuration](https://github.com/Huldoser/eslint-plugin-test-governance#usage).\
+🃏 Set in the `jest` [configuration](https://github.com/Huldoser/eslint-plugin-test-governance#usage).\
+🎭 Set in the `playwright` [configuration](https://github.com/Huldoser/eslint-plugin-test-governance#usage).\
+⚡ Set in the `vitest` [configuration](https://github.com/Huldoser/eslint-plugin-test-governance#usage).\
 🔧 Automatically fixable by the [`--fix` CLI option](https://eslint.org/docs/user-guide/command-line-interface#--fix).\
 💡 Manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).
 
-| Name                                                                   | Description                                                                       | 💼  | ⚠️  | 🔧  | 💡  |
-| :--------------------------------------------------------------------- | :-------------------------------------------------------------------------------- | :-- | :-- | :-- | :-- |
-| [marker-matches-state](docs/rules/marker-matches-state.md)             | Require the marker keyword to match the test's state                              | ✅  |     |     | 💡  |
-| [no-conflicting-states](docs/rules/no-conflicting-states.md)           | Disallow state tags that contradict each other, differ in case or look like typos |     | ✅  | 🔧  |     |
-| [no-orphaned-marker](docs/rules/no-orphaned-marker.md)                 | Disallow marker comments that no longer match a test state                        | ✅  |     |     | 💡  |
-| [require-ticket](docs/rules/require-ticket.md)                         | Require a ticket marker comment above skipped, fixme and tagged tests             | ✅  |     |     | 💡  |
-| [require-ticket-in-comments](docs/rules/require-ticket-in-comments.md) | Require FIXME and TODO comments in test files to start with a ticket              | ✅  |     |     | 💡  |
+| Name                                                                   | Description                                                                       | 💼       | ⚠️       | 🔧  | 💡  |
+| :--------------------------------------------------------------------- | :-------------------------------------------------------------------------------- | :------- | :------- | :-- | :-- |
+| [marker-matches-state](docs/rules/marker-matches-state.md)             | Require the marker keyword to match the test's state                              | 🃏 🎭 ⚡ |          |     | 💡  |
+| [no-conflicting-states](docs/rules/no-conflicting-states.md)           | Disallow state tags that contradict each other, differ in case or look like typos |          | 🃏 🎭 ⚡ | 🔧  |     |
+| [no-orphaned-marker](docs/rules/no-orphaned-marker.md)                 | Disallow marker comments that no longer match a test state                        | 🃏 🎭 ⚡ |          |     | 💡  |
+| [require-ticket](docs/rules/require-ticket.md)                         | Require a ticket marker comment above skipped, fixme and tagged tests             | 🃏 🎭 ⚡ |          |     | 💡  |
+| [require-ticket-in-comments](docs/rules/require-ticket-in-comments.md) | Require FIXME and TODO comments in test files to start with a ticket              | 🃏 🎭 ⚡ |          |     | 💡  |
 
 <!-- end auto-generated rules list -->
 
 ## Defaults
 
-The defaults follow how most teams already work, so `recommended` is useful with no options.
+The defaults follow how most teams already work, so each framework config is useful with no options.
 
 | Setting                                                                                                   | Default                                                                      | Why                                                                                                                      |
 | --------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| States that need a ticket                                                                                 | `skip`, `fixme`; in Jest and Vitest `skip`, `todo`                           | Every team skips tests. Chromium, GitLab and Slack all require a bug link on disabled tests.                             |
+| States that need a ticket                                                                                 | `skip`, `fixme`; in Jest and Vitest `skip`, `todo`                           | Every team skips tests. Chromium DevTools, GitLab and Slack all require a bug link on disabled tests.                    |
 | `@new`, `@unstable`                                                                                       | off; `lifecycleTags: true` turns both on                                     | A promotion workflow is not universal. Teams that call it `@flaky` or `@quarantine` use `customStates`.                  |
 | Conditional skips (`test.skip(browserName === 'webkit', ...)`, `if (...) test.skip()`, a skip in `catch`) | no ticket needed                                                             | These are usually permanent platform limits, not bugs. `requireTicketForConditional: true` changes this.                 |
 | `test.fail`, `test.slow`, Jest's `test.failing`, Vitest's `test.fails`                                    | off                                                                          | They don't remove coverage. Turn them on with `states: { fail: true, slow: true }`.                                      |
@@ -175,12 +189,13 @@ The defaults follow how most teams already work, so `recommended` is useful with
 ## Options
 
 All options go in `configure({...})`, or in `settings['test-governance']` if you build the config
-yourself. The rules have no options of their own: they all read these shared settings, so they
-always agree on ticket formats, states and markers. To turn a rule off, set it to `'off'` as usual.
+yourself. `framework` is required, and every other option has a default. The rules have no options
+of their own: they all read these shared settings, so they always agree on ticket formats, states
+and markers. To turn a rule off, set it to `'off'` as usual.
 
 | Option                        | Type                                                     | Default                           | Description                                                                                                                                                                                                                                                                                                                                                                                   |
 | ----------------------------- | -------------------------------------------------------- | --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `framework`                   | `'playwright' \| 'jest' \| 'vitest'`                     | `'playwright'`                    | The test framework of the files the config applies to. `configs.jest` and `configs.vitest` set it. See [Jest and Vitest](#jest-and-vitest).                                                                                                                                                                                                                                                   |
+| `framework`                   | `'playwright' \| 'jest' \| 'vitest'`                     | required                          | The test framework of the files the config applies to. `configs.playwright`, `configs.jest` and `configs.vitest` set it, and `configure()` needs it. See [Frameworks](#frameworks).                                                                                                                                                                                                           |
 | `ticket`                      | `TicketSpec \| TicketSpec[]`                             | `{ preset: 'any' }`               | Accepted ticket formats. An array accepts a ticket that matches any entry. See [Ticket presets](#ticket-presets).                                                                                                                                                                                                                                                                             |
 | `placeholders`                | `string[]`                                               | see above                         | Tickets rejected as placeholders. `*` matches any characters. Case-insensitive; a leading `#` is ignored. Your list replaces the default one, so repeat the defaults you want to keep. Tickets numbered 0 are always rejected.                                                                                                                                                                |
 | `lifecycleTags`               | `boolean`                                                | `false`                           | Turns on the `new` (`@new`) and `unstable` (`@unstable`) states.                                                                                                                                                                                                                                                                                                                              |
@@ -191,7 +206,7 @@ always agree on ticket formats, states and markers. To turn a rule off, set it t
 | `allowNotes`                  | `boolean`                                                | `false`                           | Allow free text after the tickets, e.g. `// SKIP: TRADE-123 flaky on CI`. Applies to markers and to `FIXME` / `TODO` comments.                                                                                                                                                                                                                                                                |
 | `comments`                    | `false \| { keywords?: string[] }`                       | `{ keywords: ['FIXME', 'TODO'] }` | Comment keywords that must start with a ticket anywhere in a test file, e.g. `// TODO: TRADE-123`. Your keywords replace the default ones. `false` allows free-form comments.                                                                                                                                                                                                                 |
 | `testFunctions`               | `string[]`                                               | `['test']`                        | Names treated as the framework's `test`. Jest and Vitest default to `['test', 'it']`. Your list replaces the default one, so include those names if you still need them. See below.                                                                                                                                                                                                           |
-| `reportDynamicTitles`         | `boolean`                                                | `false`                           | When a tag state is on, report titles that aren't static text, since their tags can't be read.                                                                                                                                                                                                                                                                                                |
+| `reportUnreadableTags`        | `boolean`                                                | `false`                           | When a tag state is on, report titles that aren't static text, and tags or details that can't be read in the file, such as ones imported from another module, since their tags can't be checked.                                                                                                                                                                                              |
 
 ### Ticket presets
 
@@ -216,6 +231,7 @@ reports in GitHub:
 
 ```js
 testGovernance.configure({
+  framework: 'playwright',
   ticket: { preset: 'jira', projects: ['TRADE'] },
   lifecycleTags: true,
   states: { unstable: { ticket: { preset: 'github' } } },
@@ -254,7 +270,7 @@ variable declared inside a function that happens to be called `test`.
 
 ### Syntax the rules understand
 
-The [Jest and Vitest](#jest-and-vitest) table lists what each framework's tests can do. In Playwright:
+The [Frameworks](#frameworks) table lists what each framework's tests can do. In Playwright:
 
 - `test.skip('title', fn)`, `test.fixme(...)`, `test.fail(...)`, with or without a details object,
   and with a body defined elsewhere, as in `test.skip('places a limit order', placeLimitOrder)`.
@@ -267,12 +283,13 @@ The [Jest and Vitest](#jest-and-vitest) table lists what each framework's tests
   receives. Only the step is skipped, so a marker above the step or above a skipped test around it
   covers it.
 - Tags in titles (string or template literal) and in `{ tag: '@new' }` / `{ tag: [...] }`, inherited
-  from enclosing describes.
+  from enclosing describes. Tags, titles and details can also come from a `const` or an enum declared
+  in the same file, as in `{ tag: TAGS.NEW }` after `const TAGS = { NEW: '@new' } as const`, including
+  arrays and spreads of them.
 
-Not covered in this version: tests generated in loops with dynamic titles (see
-`reportDynamicTitles`), fixtures imported from other modules under a name not in `testFunctions`,
-Playwright annotations as markers, Vitest's `context.skip()` in a global `beforeEach` (the one on
-`test.beforeEach` is covered), and other runners such as Mocha, Bun and `node:test`.
+Not covered in this version: tests generated in loops with dynamic titles, and tags or details imported
+from other modules (see `reportUnreadableTags`), fixtures imported from other modules under a name not in
+`testFunctions`, Playwright annotations as markers, and other runners such as Mocha, Bun and `node:test`.
 
 ## TypeScript
 
@@ -287,6 +304,7 @@ import tsParser from '@typescript-eslint/parser';
 import testGovernance, { type GovernanceOptions } from 'eslint-plugin-test-governance';
 
 const options: GovernanceOptions = {
+  framework: 'playwright',
   lifecycleTags: true,
   ticket: { preset: 'jira', projects: ['TRADE'] },
 };

package/dist/index.d.ts

@@ -13,10 +13,10 @@ export interface FlatConfig {
     settings?: Record<string, unknown>;
 }
 /**
- * `recommended` is the Playwright config. `playwright`, `jest` and `vitest` turn on the same rules
- * for that framework; point each one at its test files with `files`.
+ * One config per framework. `playwright`, `jest` and `vitest` turn on the same rules for that framework's
+ * tests; point each one at its test files with `files`.
  */
-export type ConfigName = 'recommended' | FrameworkName;
+export type ConfigName = FrameworkName;
 export interface TestGovernancePlugin extends ESLint.Plugin {
     meta: {
         name: string;
@@ -25,14 +25,13 @@ export interface TestGovernancePlugin extends ESLint.Plugin {
     };
     rules: Record<RuleName, Rule.RuleModule>;
     configs: Record<ConfigName, FlatConfig>;
-    configure(options?: GovernanceOptions): FlatConfig;
+    configure(options: GovernanceOptions): FlatConfig;
 }
 declare const plugin: TestGovernancePlugin;
 /**
- * Returns the recommended config with shared options in `settings['test-governance']`,
- * so all rules read the same ticket formats and states. With `framework`, it is that
- * framework's config.
+ * Returns the config of `options.framework` with shared options in `settings['test-governance']`,
+ * so all rules read the same ticket formats and states.
  */
-export declare function configure(options?: GovernanceOptions): FlatConfig;
-export declare const configs: Record<ConfigName, FlatConfig>;
+export declare function configure(options: GovernanceOptions): FlatConfig;
+export declare const configs: Record<"playwright" | "jest" | "vitest", FlatConfig>;
 export default plugin;

package/dist/index.js

@@ -5,6 +5,7 @@ import noOrphanedMarker from "./rules/no-orphaned-marker.js";
 import requireTicketInComments from "./rules/require-ticket-in-comments.js";
 import requireTicket from "./rules/require-ticket.js";
 import { FRAMEWORK_NAMES } from "./utils/constants.js";
+import { ConfigError } from "./utils/errors.js";
 import { compileOptions, SETTINGS_KEY } from "./utils/options.js";
 const PLUGIN_NAME = 'test-governance';
 // Read at load time so the reported version always matches the published package.
@@ -18,7 +19,8 @@ const ruleModules = {
 };
 // Public types come from `eslint` itself, so users don't need typescript-eslint installed.
 export const rules = ruleModules;
-const recommendedRules = Object.fromEntries(Object.keys(ruleModules).map((name) => [
+// Every framework config turns on all the rules, at the severity in each rule's `meta.docs.recommended`.
+const configRules = Object.fromEntries(Object.keys(ruleModules).map((name) => [
     `${PLUGIN_NAME}/${name}`,
     ruleModules[name].meta.docs.recommended,
 ]));
@@ -29,34 +31,36 @@ const plugin = {
     configure,
 };
 /**
- * Returns the recommended config with shared options in `settings['test-governance']`,
- * so all rules read the same ticket formats and states. With `framework`, it is that
- * framework's config.
+ * Returns the config of `options.framework` with shared options in `settings['test-governance']`,
+ * so all rules read the same ticket formats and states.
  */
-export function configure(options = {}) {
+export function configure(options) {
     compileOptions(options); // fail on a bad config at load time, not on the first lint
     return {
-        name: `${PLUGIN_NAME}/${options.framework ?? 'recommended'}`,
+        name: `${PLUGIN_NAME}/${options.framework}`,
         plugins: { [PLUGIN_NAME]: plugin },
-        rules: { ...recommendedRules },
+        rules: { ...configRules },
         settings: { [SETTINGS_KEY]: options },
     };
 }
-plugin.configs.recommended = {
-    name: `${PLUGIN_NAME}/recommended`,
-    plugins: { [PLUGIN_NAME]: plugin },
-    rules: { ...recommendedRules },
-};
 // Each sets its framework, so it wins over a `configure()` that applies to all files when listed after it.
 for (const framework of FRAMEWORK_NAMES) {
     plugin.configs[framework] = configure({ framework });
 }
+// `configs.recommended` was removed in 0.5.0. Reading it throws, so `...configs.recommended` fails with this
+// message instead of spreading nothing and turning the rules off without a word. It isn't enumerable, so
+// tools that list the configs don't see it.
+Object.defineProperty(plugin.configs, 'recommended', {
+    get() {
+        throw new ConfigError('configs.recommended was removed in 0.5.0. Use the config for your framework: configs.playwright, configs.jest or configs.vitest. See https://github.com/Huldoser/eslint-plugin-test-governance/blob/main/docs/upgrading.md');
+    },
+});
 export const configs = plugin.configs;
 export default plugin;
 /**
  * Makes `require('eslint-plugin-test-governance')` return the plugin itself rather than the module
  * namespace. With the namespace, a CommonJS config that registers the plugin next to
- * `configs.recommended` fails with "Cannot redefine plugin".
+ * `configs.playwright` fails with "Cannot redefine plugin".
  *
  * @internal Left out of the type declarations: TypeScript before 5.6 can't parse a string export
  * name, so it would reject the whole file.

package/dist/rules/no-conflicting-states.js

@@ -51,6 +51,8 @@ export default createRule({
         }
         function checkSpelling(occurrence) {
             const { tag, range } = occurrence;
+            // A Vitest tag name is written without its `@`, so show it, and fix it, the same way.
+            const written = (name) => (occurrence.plain ? name.slice(1) : name);
             if (tagStates.some((s) => s.tag === tag))
                 return;
             const lower = tag.toLowerCase();
@@ -59,8 +61,8 @@ export default createRule({
                 context.report({
                     node: occurrence.node,
                     messageId: 'tagCase',
-                    data: { found: tag, expected: sameLetters.tag },
-                    fix: range && ((fixer) => fixer.replaceTextRange(range, sameLetters.tag)),
+                    data: { found: written(tag), expected: written(sameLetters.tag) },
+                    fix: range && ((fixer) => fixer.replaceTextRange(range, written(sameLetters.tag))),
                 });
                 return;
             }
@@ -72,7 +74,11 @@ export default createRule({
                     editDistance(lower, expected) <= typoThreshold(expected.length - 1));
             });
             if (near) {
-                context.report({ node: occurrence.node, messageId: 'tagTypo', data: { found: tag, expected: near.tag } });
+                context.report({
+                    node: occurrence.node,
+                    messageId: 'tagTypo',
+                    data: { found: written(tag), expected: written(near.tag) },
+                });
             }
         }
     },

package/dist/rules/no-orphaned-marker.js

@@ -37,7 +37,7 @@ export default createRule({
             for (const marker of strayMarkers(subject, options)) {
                 // TODO is the everyday work-comment keyword, so `// TODO: TRADE-12` above a test that isn't a todo
                 // is a tracked note about it far more often than a todo test's forgotten marker.
-                if (marker.state.name === 'todo' && options.workCommentKeywords.has(marker.keyword))
+                if (marker.state.name === 'todo' && options.workCommentKeywords.has(marker.keyword.toUpperCase()))
                     continue;
                 markers.push({ marker, messageId: 'orphaned', subject: name });
             }

package/dist/rules/require-ticket.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("../utils/create-rule.ts").Rule<"missingTicket" | "invalidTicket" | "placeholderTicket" | "extraText" | "removeExtraText" | "missingMarker" | "markerCase" | "dynamicTitle">;
+declare const _default: import("../utils/create-rule.ts").Rule<"missingTicket" | "invalidTicket" | "placeholderTicket" | "extraText" | "removeExtraText" | "missingMarker" | "markerCase" | "dynamicTitle" | "dynamicTags">;
 export default _default;

package/dist/rules/require-ticket.js

@@ -19,6 +19,7 @@ export default createRule({
             extraText: 'Only ticket IDs are allowed after `{{marker}}:`, separated by commas. Put details in the ticket instead of `{{text}}`.',
             removeExtraText: 'Remove `{{text}}`.',
             dynamicTitle: "This title isn't static text, so its tags can't be checked. Use a string or template literal.",
+            dynamicTags: "These tags can't be read in this file, so they can't be checked. Use strings, or constants declared in this file.",
         },
     },
     create(context, analysis, options) {
@@ -27,8 +28,11 @@ export default createRule({
         const reported = new Set();
         const reportOnce = (key) => !reported.has(key) && Boolean(reported.add(key));
         for (const subject of analysis.subjects) {
-            if (subject.dynamicTitle && options.reportDynamicTitles && hasTagStates) {
-                context.report({ node: subject.node.arguments[0], messageId: 'dynamicTitle' });
+            if (options.reportUnreadableTags && hasTagStates) {
+                if (subject.dynamicTitle)
+                    context.report({ node: subject.node.arguments[0], messageId: 'dynamicTitle' });
+                for (const node of subject.unreadTags)
+                    context.report({ node, messageId: 'dynamicTags' });
             }
             for (const { state, required } of subject.states) {
                 if (!required)

package/dist/utils/analyze.d.ts

@@ -30,12 +30,15 @@ export type StateMarker = Marker & {
 export declare function isStateMarker(marker: Marker): marker is StateMarker;
 export interface TagOccurrence {
     tag: string;
-    node: TSESTree.Literal | TSESTree.TemplateLiteral;
+    /** Where to report the tag: the text it is written in, or the name it comes from, as `Tags.NEW`. */
+    node: Node;
     /**
-     * Where the tag is written in the source. Unset when an escape such as `\u002D` comes before the
-     * tag or inside it, since the source then no longer lines up with the title.
+     * Where the tag is written in the source. Unset when it comes from a constant, or when an escape such
+     * as `\u002D` comes before the tag or inside it, since the source then no longer lines up with the title.
      */
     range?: TSESTree.Range;
+    /** Set for a Vitest tag name such as `'flaky'` in `tags`, which is written without its `@`. */
+    plain?: true;
 }
 interface StateSource {
     state: StateDef;
@@ -58,6 +61,13 @@ export interface Subject {
     tags: TagOccurrence[];
     /** Tags this node inherits from enclosing describes. */
     inheritedTags: Set<string>;
+    /** Tag values, or a whole details object, on this node that can't be read, as `{ tag: TAGS.NEW }` with `TAGS` imported. */
+    unreadTags: Node[];
+    /**
+     * States this node may be in without the code showing it: tag states when tags can't be read, and
+     * Vitest's option states when its options object can't. Includes those of enclosing describes.
+     */
+    unknownStates: Set<string>;
     /** True when this node is skipped or fixme'd by any means, whether or not those states are on. */
     skipped: boolean;
     ownSkip: boolean;
@@ -108,7 +118,11 @@ export declare function missingStates(subject: Subject): StateDef[];
  * after it.
  */
 export declare function isProse(marker: Marker): boolean;
-/** Markers in the subject's own block for states that don't apply to it, leaving out work comments. */
+/**
+ * Markers in the subject's own block for states that don't apply to it, leaving out work comments and
+ * states its code may hide, such as a tag from a constant imported from another file. A marker in the
+ * wrong case, as `// skip: TRADE-1`, counts when it starts with a valid ticket.
+ */
 export declare function strayMarkers(subject: Subject, options: ResolvedOptions): StateMarker[];
 /**
  * Where to report a problem with a test or describe: from the callee to the end of the title