eslint-plugin-test-governance 0.13.0 → 0.13.2

package/CHANGELOG.md

@@ -6,6 +6,97 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.13.2] - 2026-11-08
+
+### Fixed
+
+- Local aliases such as `const check = it; check.skip(...)`, and aliases of conditional test functions,
+  are checked like the functions they keep.
+- A helper's parameter or block variable named like a test context no longer makes its `skip()` or
+  `test()` calls count as runtime skips or subtests.
+- Runtime calls with a literal `false` condition, such as Playwright's `test.skip(false)`, need neither
+  a ticket nor a reason.
+- Details, options and annotations use the last value of a property, including values from object
+  spreads. An unread spread or computed key no longer leaves an earlier value treated as certain.
+- A tag read beyond an array's bounds no longer crashes linting. An index after a spread, or a string
+  such as `'01'` that isn't an array index, is left unread instead of using the wrong tag.
+- Circular object spreads no longer overflow the stack during analysis.
+- Playwright annotation arrays read tickets from spreads of arrays declared in the same file, and
+  report unread spreads with `reportUnreadableTags`.
+- A ticket marker in a block comment no longer hides unrelated `TODO` or `FIXME` work comments on
+  other lines of that block.
+- The `pattern` preset matches the whole ticket even with the multiline flag, and no longer accepts
+  trailing line breaks outside the pattern.
+- Moving a ticket into an annotation preserves comments inside an empty details object.
+- node:test's `todo` state no longer makes `no-conflicting-states` call a new test skipped: Node still
+  runs its body.
+
+## [0.13.1] - 2026-11-06
+
+### Fixed
+
+- The `rally` preset no longer takes a prefix with no number, such as `US` or `TC`, as a ticket, so
+  `// SKIP: TC` and, with `allowNotes`, a note that starts with "US" or "DE" need a real ticket.
+- A second `configure()` for some of the same files, such as `{ preset: 'github' }` for a legacy folder after
+  `{ preset: 'jira', projects: ['TRADE'] }` for all files, replaces the earlier ticket format. ESLint merged the
+  two key by key, so linting failed with "ticket.projects is not an option of the github preset".
+- The `github` preset reads Gitea's, Forgejo's and Codeberg's pull request links, `/<owner>/<repo>/pulls/12`.
+- A `pattern` with an unmatched `)`, such as `TRADE-\d+)|(.*`, is a configuration error. It used to close the
+  group that anchors the pattern, so every ticket passed.
+- `plane` checks its `projects` as `jira` does: a key must start with a letter and have two or more characters,
+  since no other key can match.
+- An option named like a built-in object member, such as `customStates: { constructor: ... }`, is checked like
+  any other.
+- A marker in an `eslint-disable` comment, as in `/* eslint-disable jest/no-disabled-tests -- SKIP: TRADE-1 */`,
+  covers every test up to the `eslint-enable`, also when the comment sits directly above a describe or a test that
+  isn't skipped. `no-orphaned-marker` called it left over there, and its suggestion removed the marker the
+  skipped tests below relied on. Such a marker is now reported only when none of the tests it covers is in its
+  state, and `require-ticket-in-comments` no longer reports its note a second time.
+- `require-ticket-for-commented-out-tests` counts only a call that declares a test, describe or step. Everyday
+  lines such as `// test.slow();`, `// test.use({ ... })` and `// test.describe.configure({ ... })` were reported,
+  and in a comment block above a skipped test they took that test's marker, so `require-ticket` reported it too,
+  even with the commented-out rule off.
+- A test function kept in a constant is read when a condition picks it, as
+  `const itUnlessWindows = isWindows ? it.skip : it`, when a call builds it, as `describe.runIf(hasDocker)`,
+  `it.skipIf(true)` or `it.skip.each(table)`, and when the constant is declared inside a describe. A marker above
+  such a test was reported as not directly above a test.
+- With `requireReasonForConditional`, the description of an `eslint-disable` comment that covers a stretch of the
+  file no longer counts as the reason for every conditional skip in it. A reason written as a template literal
+  counts in Vitest's `context.skip(...)` and in node:test's `skip` option, and so does a comment at the end of a
+  one-line `test.skipIf(isMobile)(...)` or after an `if`'s opening line, as `if (isMobile) { // why`.
+- Suggestions edit only the marker's own line: removing a leftover marker from a block comment that says more,
+  such as a doc comment, another marker or an ESLint directive's description, keeps the rest of the comment, and
+  renaming a marker no longer renames the same word in prose above it.
+- With `annotations: { only: true }`, there is no suggestion to move a ticket into the details when it would break
+  the call: a Vitest test with a timeout or options after its function, or details with a computed key such as
+  `['annotation']`.
+- The suggestion to add a marker uses the file's own line breaks, so it no longer leaves a bare line feed in a
+  file with CRLF line endings.
+- Playwright's `test.describe.configure({ retries })` is read, with `states: { retry: true }`, when the options
+  sit in a constant or a spread, and when `describe` comes from `const { describe } = test`.
+- A marker above `test.describe('orders', () => test.skip(...))`, whose arrow body is the test, belongs to the test
+  as well, so `no-orphaned-marker` no longer calls it left over on the describe.
+- node:test's `t.skip(message)` and `t.todo(message)` and Jasmine's `pending(message)` take no condition, so they
+  need a ticket whatever the message is, also one held in a name or built in a template. A message in a name was
+  read as a condition.
+- A tag constant used in several titles, as `` `buys ${TAG}` ``, is reported once, where it is written.
+- The example in the `missingReason` message is written on one line, also when the call is split over lines.
+- With `requireReasonForConditional`, a comment above the declaration of a constant that picks a test function,
+  as `const posixTest = isWindows ? test.skip : test`, or at the end of its line, is the reason for every test
+  that uses it.
+- A link whose `id` query is zero, such as `https://www.wrike.com/open.htm?id=0`, is a placeholder, as any ticket
+  numbered 0 is. Other zero queries, such as `?page=0`, are left alone.
+- A placeholder written with a leading `#`, such as `#TBD`, also matches `TBD`: a leading `#` is ignored on both
+  the ticket and the placeholder.
+- A link whose scheme isn't in lowercase, such as `HTTPS://...`, is read as a link.
+- Linear, Trello, Shortcut and YouTrack links that end in a slash after the title, as
+  `.../ENG-1/fix-rounding/`, are accepted.
+- A lowercase Jira or Plane project in `projects` is reported once instead of twice.
+- `numeric` with a `minLength` above its `maxLength`, and a `pattern` or `flags` that isn't a valid regex, are
+  reported in the list of invalid options. Without `maxLength`, the message names its default of 20.
+- The ticket format of a state that is off, or that the framework doesn't have, such as `states.fixme.ticket`
+  with Jest, is checked too, so a mistake in it shows up at once.
+
 ## [0.13.0] - 2026-11-05
 
 ### Added
@@ -507,7 +598,9 @@ 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.13.0...HEAD
+[Unreleased]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.13.2...HEAD
+[0.13.2]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.13.1...v0.13.2
+[0.13.1]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.13.0...v0.13.1
 [0.13.0]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.12.1...v0.13.0
 [0.12.1]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.12.0...v0.12.1
 [0.12.0]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.11.1...v0.12.0

package/README.md

@@ -242,7 +242,7 @@ and markers. To turn a rule off, set it to `'off'` as usual.
 | ----------------------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `framework`                   | `'playwright' \| 'jest' \| 'vitest' \| 'mocha' \| 'cypress' \| 'webdriverio' \| 'node-test' \| 'jasmine'` | required                          | The test framework of the files the config applies to. Each framework's config, such as `configs.playwright`, sets 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.                                                                                                                                                                                                                                                                                                                                                                                                  |
+| `placeholders`                | `string[]`                                                                                                | see above                         | Tickets rejected as placeholders. `*` matches any characters. Case-insensitive, and a leading `#` on the ticket or the placeholder 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 `quarantined` (`@quarantined`) states.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
 | `states`                      | `{ [state]: boolean \| { enabled?, tag?, marker?, ticket? } }`                                            | `skip`, `fixme` and `todo` on     | Turns built-in states (`skip`, `fixme`, `fail`, `slow`, `todo`, `retry`, `new`, `quarantined`) on or off, renames their tag or marker, or gives them their own ticket format. `fail`, `slow` and `retry` are off by default; a setting for `new` or `quarantined` here wins over `lifecycleTags`. Only `new` and `quarantined` have a tag to rename; see [Tag names](#tag-names). `fixme` and `slow` exist only in Playwright, `todo` in every framework but Playwright, `fail` in Playwright, Jest, Vitest and node:test, and `retry` in every framework but node:test and Jasmine, so turning one on elsewhere has no effect. |
 | `customStates`                | `{ [name]: { when, marker, ticket? } }`                                                                   | `{}`                              | Adds a state for a tag, e.g. `{ 'needs-data': { when: '@needs-data', marker: 'NEEDS-DATA' } }`. `when` is a tag and `marker` an uppercase keyword; neither can be shared with another state.                                                                                                                                                                                                                                                                                                                                                                                                                                    |
@@ -253,7 +253,7 @@ and markers. To turn a rule off, set it to `'off'` as usual.
 | `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.                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | `annotations`                 | `false \| { type?: string, only?: boolean }`                                                              | `{ type: 'issue' }`               | Accept the ticket from a test annotation as well: Playwright's `annotation` of the given type or Vitest's `meta` key of that name. One valid annotation covers every state the test is in, and a describe's covers its tests. `only: true` makes it the only place for a test's or describe's ticket. See [Tickets from annotations](#tickets-from-annotations).                                                                                                                                                                                                                                                                |
-| `testFunctions`               | `string[]`                                                                                                | `['test']`                        | Names treated as the framework's `test`. Jest and Vitest default to `['test', 'it']`, Mocha, Cypress and WebdriverIO to `['it', 'specify', 'test']`, and Jasmine to `['it']`. Your list replaces the default one, so include those names if you still need them. See below.                                                                                                                                                                                                                                                                                                                                                     |
+| `testFunctions`               | `string[]`                                                                                                | `['test']`                        | Names treated as the framework's `test`. Jest, Vitest and node:test default to `['test', 'it']`, Mocha, Cypress and WebdriverIO to `['it', 'specify', 'test']`, and Jasmine to `['it']`. Your list replaces the default one, so include those names if you still need them. See below.                                                                                                                                                                                                                                                                                                                                          |
 | `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.                                                                                                                                                                                                                                                                                                                                                                                                                                |
 
 ### Tag names
@@ -330,8 +330,9 @@ run on their own servers.
 
 For a tracker without a preset, use `url` with its host, for example
 `{ preset: 'url', hosts: ['www.wrike.com'] }` for Wrike links such as
-`https://www.wrike.com/open.htm?id=4821`. It works the same for Microsoft Planner (`tasks.office.com`),
-Airtable (`airtable.com`), Smartsheet (`app.smartsheet.com`) and trackers of your own. For another
+`https://www.wrike.com/open.htm?id=4821`; a link with `?id=0`, or a path that ends in `/0`, is a
+placeholder. It works the same for Microsoft Planner (`tasks.office.com`), Airtable (`airtable.com`),
+Smartsheet (`app.smartsheet.com`) and trackers of your own. For another
 tracker's keys, such as `WEB-12`, `any` or `pattern` works. Gitea, Forgejo and Codeberg use GitHub's link layout,
 so the `github` preset with their `host` covers them. Bitbucket has no issue tracker since August 2026,
 so it has no preset.

package/dist/index.js

@@ -32,6 +32,28 @@ const plugin = {
     configs: {},
     configure,
 };
+/** `ticket` as a list, so ESLint replaces it whole when it merges two configs' settings. */
+function ticketAsList(options) {
+    const { ticket } = options;
+    return ticket === undefined || Array.isArray(ticket) ? options : { ...options, ticket: [ticket] };
+}
+/**
+ * ESLint merges the settings of configs that apply to the same file key by key and replaces arrays. Merged
+ * key by key, a later config's `{ preset: 'github' }` would keep an earlier `projects` that github doesn't take,
+ * so every ticket format goes in a list.
+ */
+function ticketsAsLists(options) {
+    const { states, customStates } = options;
+    return {
+        ...ticketAsList(options),
+        ...(states && {
+            states: Object.fromEntries(Object.entries(states).map(([name, state]) => [name, typeof state === 'object' ? ticketAsList(state) : state])),
+        }),
+        ...(customStates && {
+            customStates: Object.fromEntries(Object.entries(customStates).map(([name, state]) => [name, ticketAsList(state)])),
+        }),
+    };
+}
 /**
  * Returns the config of `options.framework` with shared options in `settings['test-governance']`,
  * so all rules read the same ticket formats and states.
@@ -42,7 +64,7 @@ export function configure(options) {
         name: `${PLUGIN_NAME}/${options.framework}`,
         plugins: { [PLUGIN_NAME]: plugin },
         rules: { ...configRules },
-        settings: { [SETTINGS_KEY]: options },
+        settings: { [SETTINGS_KEY]: ticketsAsLists(options) },
     };
 }
 // Each sets its framework, so it wins over a `configure()` that applies to all files when listed after it.

package/dist/rules/marker-matches-state.js

@@ -1,6 +1,6 @@
 import { appliesTo, describeSubject, directiveOf, isStateMarker, missingStates, strayMarkers, } from "../utils/analyze.js";
 import { createRule } from "../utils/create-rule.js";
-import { indentOf, keywordRange } from "../utils/fix.js";
+import { indentOf, keywordRange, lineBreakAfter } from "../utils/fix.js";
 export default createRule({
     meta: {
         type: 'problem',
@@ -39,7 +39,7 @@ export default createRule({
                     suggest: missing.map((state) => ({
                         messageId: 'renameMarker',
                         data: { expected: state.marker },
-                        fix: (fixer) => fixer.replaceTextRange(keywordRange(sourceCode, marker.comment, marker.keyword), state.marker),
+                        fix: (fixer) => fixer.replaceTextRange(keywordRange(marker), state.marker),
                     })),
                 });
             }
@@ -75,9 +75,12 @@ export default createRule({
                             {
                                 messageId: 'addMarker',
                                 data: { expected: state.marker, tickets },
-                                fix: (fixer) => directive
-                                    ? fixer.insertTextBeforeRange(present.comment.range, `${added}\n${indent}`)
-                                    : fixer.insertTextAfterRange(present.comment.range, `\n${indent}${added}`),
+                                fix: (fixer) => {
+                                    const lineBreak = lineBreakAfter(sourceCode, present.comment);
+                                    return directive
+                                        ? fixer.insertTextBeforeRange(present.comment.range, `${added}${lineBreak}${indent}`)
+                                        : fixer.insertTextAfterRange(present.comment.range, `${lineBreak}${indent}${added}`);
+                                },
                             },
                         ]
                         : [],

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

@@ -24,6 +24,7 @@ export default createRule({
         const checkedTags = [...options.states.filter(isTagState).map((s) => s.tag), ...options.knownTags];
         const newTag = options.states.find((s) => s.name === 'new')?.tag;
         const quarantinedTag = options.states.find((s) => s.name === 'quarantined')?.tag;
+        const spelled = new Set();
         for (const subject of analysis.subjects) {
             for (const occurrence of subject.tags)
                 checkSpelling(occurrence);
@@ -52,6 +53,11 @@ export default createRule({
         }
         function checkSpelling(occurrence) {
             const { tag, range } = occurrence;
+            // A constant used in several titles, as `` `buys ${TAG}` ``, is one place to fix, so one report.
+            const key = `${occurrence.node.range[0]}:${range?.[0]}:${tag}`;
+            if (spelled.has(key))
+                return;
+            spelled.add(key);
             // 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 (checkedTags.includes(tag))

package/dist/rules/no-orphaned-marker.d.ts

@@ -1,2 +1,2 @@
-declare const _default: import("../utils/create-rule.ts").Rule<"orphaned" | "detached" | "removeMarker">;
+declare const _default: import("../utils/create-rule.ts").Rule<"orphaned" | "orphanedRegion" | "detached" | "removeMarker">;
 export default _default;

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

@@ -13,6 +13,7 @@ export default createRule({
         schema: [],
         messages: {
             orphaned: "`{{marker}}:` is left over: {{subject}} is not in the '{{state}}' state.",
+            orphanedRegion: "`{{marker}}:` is left over: no test up to the `eslint-enable` of this comment is in the '{{state}}' state.",
             detached: '`{{marker}}:` is not directly above a test, describe or skip call, so it has no effect.',
             removeMarker: 'Remove this comment.',
         },
@@ -29,17 +30,21 @@ export default createRule({
                 continue;
             markers.push({ marker, messageId: 'detached', subject: '' });
         }
+        // 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.
+        const trackedNote = (marker) => marker.state.name === 'todo' && options.workCommentKeywords.has(marker.keyword.toUpperCase());
+        for (const marker of analysis.idleRegionMarkers) {
+            if (!trackedNote(marker))
+                markers.push({ marker, messageId: 'orphanedRegion', subject: '' });
+        }
         for (const subject of analysis.subjects) {
             // A stray marker next to a missing one is a mismatch, reported by marker-matches-state.
             if (missingStates(subject, options).length > 0)
                 continue;
             const name = describeSubject(subject).replace(/^This/, 'this');
             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.toUpperCase()))
-                    continue;
-                markers.push({ marker, messageId: 'orphaned', subject: name });
+                if (!trackedNote(marker))
+                    markers.push({ marker, messageId: 'orphaned', subject: name });
             }
         }
         for (const { marker, messageId, subject } of markers) {
@@ -50,7 +55,7 @@ export default createRule({
                 loc: marker.comment.loc,
                 messageId,
                 data: { marker: marker.keyword, state: marker.state.name, subject },
-                suggest: [{ messageId: 'removeMarker', fix: () => removeMarkerComment(sourceCode, marker.comment) }],
+                suggest: [{ messageId: 'removeMarker', fix: () => removeMarkerComment(sourceCode, marker) }],
             });
         }
     },

package/dist/rules/require-ticket-in-comments.js

@@ -34,10 +34,10 @@ export default createRule({
         // in the wrong case.
         const owned = new Set();
         for (const subject of analysis.subjects) {
-            for (const marker of subject.markers) {
+            for (const marker of [...subject.markers, ...subject.regionMarkers]) {
                 const state = marker.state ?? marker.caseOf;
                 if (state && appliesTo(subject, state.name))
-                    owned.add(marker.comment);
+                    owned.add(marker.keywordStart);
             }
         }
         // `TODO`/`FIXME` in capitals counts with or without a colon. Other casings need the colon, so a
@@ -62,13 +62,13 @@ export default createRule({
             return { ...parsed, extra: { text: note, range: [start + close, start + line.trimEnd().length] } };
         }
         for (const comment of sourceCode.getAllComments()) {
-            if (owned.has(comment))
-                continue;
             for (const { text: line, start } of commentLines(comment)) {
                 const match = keywordRe.exec(line);
                 if (!match)
                     continue;
                 const [whole, indent, keyword] = match;
+                if (owned.has(start + indent.length))
+                    continue;
                 // The parenthesised group is optional, so it can be undefined despite RegExpExecArray's typing.
                 const inParens = match[3];
                 const upper = keyword.toUpperCase();

package/dist/rules/require-ticket.js

@@ -70,7 +70,7 @@ export default createRule({
         const reportReason = (subject, state) => {
             if (evaluate(subject, state).kind === 'ok' || hasAnnotationTicket(subject, state, options))
                 return;
-            const callee = context.sourceCode.getText(subject.node.callee);
+            const callee = context.sourceCode.getText(subject.node.callee).replace(/\s+/g, '');
             const first = subject.node.arguments.at(0);
             const where = options.framework.reasonArgument;
             // Vitest's `context.skip()` takes either a reason alone or a condition and then the reason.

package/dist/utils/analyze.d.ts

@@ -22,6 +22,10 @@ export interface Marker {
         text: string;
         range: TSESTree.Range;
     };
+    /** The index of the marker's line in `commentLines(comment)`. */
+    line: number;
+    /** Where the keyword starts in the source. */
+    keywordStart: number;
 }
 /** A marker whose keyword is exactly a state's marker. */
 export type StateMarker = Marker & {
@@ -87,6 +91,11 @@ export interface Subject {
      * Vitest's option states when its options object can't. Includes those of enclosing describes.
      */
     unknownStates: Set<string>;
+    /**
+     * States of other subjects whose comment block is this one's, as a test that is the arrow body of a
+     * describe, `describe('d', () => test.skip(...))`, so a marker for them isn't left over here.
+     */
+    sharedStates: 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;
@@ -115,6 +124,8 @@ export interface Analysis {
     subjects: Subject[];
     /** Markers that are not in the comment block of any test, describe or runtime call. */
     detachedMarkers: StateMarker[];
+    /** Markers of `eslint-disable` regions that cover tests, none of them in the marker's state. */
+    idleRegionMarkers: StateMarker[];
     /** Commented-out tests; their comments are left out of the comment blocks of the tests around them. */
     commentedOutTests: CommentedOutTest[];
     /** Whether the file uses the test framework at all: an import from it or a call to a test function. */