eslint-plugin-test-governance 0.2.1 → 0.3.1

package/CHANGELOG.md

@@ -6,6 +6,47 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [0.3.1] - 2026-10-06
+
+### Fixed
+
+- A `test` bound to another test runner without an import, as in `const test = require('node:test')`,
+  `const test = require('ava')` or `const test = anyTest as TestFn<Context>`, is no longer mistaken
+  for Playwright's `test`. Before, skipped tests in those files were reported as missing a ticket.
+- `require-ticket-in-comments` reads a ticket in parentheses after a space, as in `// TODO (WEB-123)`.
+  Before, such comments were reported as having no ticket at all.
+- A test or describe whose body is not written inline, such as `test.skip('pays', payWithCard)` or
+  `test('pays @new', withPage(async () => {}))`, is checked like any other. Before, it was ignored,
+  so a skipped test written this way needed no ticket.
+
+## [0.3.0] - 2026-10-06
+
+### Added
+
+- `require-ticket-in-comments` accepts the ticket in parentheses: `// TODO(WEB-123)`. A name in
+  parentheses, as in `// TODO(alice): refactor`, is not a ticket and is reported. Before, comments
+  written this way were never checked.
+- Configuration mistakes that used to be accepted silently now fail with a clear message: lowercase
+  Jira `projects` or Linear `teams` (`'web'` never matches a ticket like `WEB-1`), options that belong
+  to another ticket preset (such as `host` on the `any` preset), and a custom state that reuses a
+  built-in state's name (`customStates: { fixme: ... }`).
+
+### Fixed
+
+- A skip in a `catch` block (`catch { test.skip(true, 'Mail server is down') }`) or after an early
+  exit such as `if (ready) return;` counts as conditional, like one under an `if`, so it no longer
+  needs a ticket by default.
+- A plain `// FIXME: some text` above `test.skip(...)` no longer gets a confusing `marker-matches-state`
+  error claiming the test is also in the `fixme` state. `require-ticket-in-comments` and
+  `require-ticket` report what is actually wrong. The `marker-matches-state` message for a test in
+  two states now starts its second sentence with a capital letter.
+- `@stable`, `@untestable` and other tags two or more letters longer or shorter than `@unstable`
+  (or any other state tag) are no longer reported as typos of it.
+- A broken marker next to a valid one for the same state, as in `// SKIP: WEB-1` followed by
+  `// SKIP: nope`, is reported. Before, the valid marker hid it.
+- A full stop or colon after the last ticket, as in `// SKIP: WEB-1.`, is no longer reported as
+  extra text.
+
 ## [0.2.1] - 2026-10-03
 
 ### Added
@@ -93,7 +134,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.2.1...HEAD
+[Unreleased]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.3.1...HEAD
+[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
 [0.2.1]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.2.0...v0.2.1
 [0.2.0]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.1.1...v0.2.0
 [0.1.1]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.1.0...v0.1.1

package/README.md

@@ -47,7 +47,7 @@ Any flat config file works. The package is ESM, and `require('eslint-plugin-test
 [`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 four rules read:
+stored in `settings['test-governance']`, which all the rules read:
 
 ```js
 export default [
@@ -100,20 +100,20 @@ eslint-plugin-test-governance: invalid options:
 
 The defaults follow how most teams already work, so `recommended` is useful with no options.
 
-| Setting                                                                                | Default                                                                                                   | Why                                                                                                                      |
-| -------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| States that need a ticket                                                              | `skip`, `fixme`                                                                                           | Every team skips tests. Chromium, 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()`) | no ticket needed                                                                                          | These are usually permanent platform limits, not bugs. `requireTicketForConditional: true` changes this.                 |
-| `test.fail`, `test.slow`                                                               | off                                                                                                       | They don't remove coverage. Turn them on with `states: { fail: true, slow: true }`.                                      |
-| Marker format                                                                          | `// SKIP: WEB-123` or `// SKIP: WEB-123, WEB-124`                                                         | Uppercase keyword and colon, like `TODO:`. Easy to grep.                                                                 |
-| Notes after the ticket                                                                 | not allowed; `allowNotes: true` allows them                                                               | The ticket is the source of truth. A note in a comment goes stale while the ticket stays current.                        |
-| `FIXME` / `TODO` comments                                                              | must start with a ticket, e.g. `// TODO: WEB-123`                                                         | The ticket is the source of truth; an untracked `TODO` is never done. `comments: false` turns this off.                  |
-| Placement                                                                              | comment block directly above; other comments allowed; a blank line breaks it                              | Survives `eslint-disable-next-line` and Prettier.                                                                        |
-| Ticket format                                                                          | `any`: `PROJ-123`, `#123`, `owner/repo#123`, or an http(s) URL                                            | Works for Jira, Linear, GitHub and GitLab out of the box. Narrow it with a preset.                                       |
-| Placeholder tickets                                                                    | rejected: `TODO`, `TBD`, `XXX-*`, `0`, `123`, `1234`, `12345`, and any ticket numbered 0 (`PROJ-0`, `#0`) | A fake ticket is worse than none, and no tracker issues number 0.                                                        |
-| Describe blocks                                                                        | a marker on a skipped or tagged describe covers its tests                                                 | One ticket per skipped suite.                                                                                            |
-| Severity                                                                               | `require-ticket`, `marker-matches-state`, `no-orphaned-marker`: error; `no-conflicting-states`: warn      | A marker must always match a real state, so a missing, wrong or leftover marker fails the lint. Tag spelling is cleanup. |
+| Setting                                                                                                   | Default                                                                                                   | Why                                                                                                                      |
+| --------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| States that need a ticket                                                                                 | `skip`, `fixme`                                                                                           | Every team skips tests. Chromium, 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`                                                                                  | off                                                                                                       | They don't remove coverage. Turn them on with `states: { fail: true, slow: true }`.                                      |
+| Marker format                                                                                             | `// SKIP: WEB-123` or `// SKIP: WEB-123, WEB-124`                                                         | Uppercase keyword and colon, like `TODO:`. Easy to grep.                                                                 |
+| Notes after the ticket                                                                                    | not allowed; `allowNotes: true` allows them                                                               | The ticket is the source of truth. A note in a comment goes stale while the ticket stays current.                        |
+| `FIXME` / `TODO` comments                                                                                 | must start with a ticket, e.g. `// TODO: WEB-123` or `// TODO(WEB-123)`                                   | The ticket is the source of truth; an untracked `TODO` is never done. `comments: false` turns this off.                  |
+| Placement                                                                                                 | comment block directly above; other comments allowed; a blank line breaks it                              | Survives `eslint-disable-next-line` and Prettier.                                                                        |
+| Ticket format                                                                                             | `any`: `PROJ-123`, `#123`, `owner/repo#123`, or an http(s) URL                                            | Works for Jira, Linear, GitHub and GitLab out of the box. Narrow it with a preset.                                       |
+| Placeholder tickets                                                                                       | rejected: `TODO`, `TBD`, `XXX-*`, `0`, `123`, `1234`, `12345`, and any ticket numbered 0 (`PROJ-0`, `#0`) | A fake ticket is worse than none, and no tracker issues number 0.                                                        |
+| Describe blocks                                                                                           | a marker on a skipped or tagged describe covers its tests                                                 | One ticket per skipped suite.                                                                                            |
+| Severity                                                                                                  | `require-ticket`, `marker-matches-state`, `no-orphaned-marker`: error; `no-conflicting-states`: warn      | A marker must always match a real state, so a missing, wrong or leftover marker fails the lint. Tag spelling is cleanup. |
 
 ## Options
 
@@ -172,8 +172,9 @@ so keep it free of nested quantifiers.
 - Any name in `testFunctions`, for fixtures imported from your own modules. The default `['test']`
   covers the common `import { test } from './fixtures'`.
 
-A name imported from another test runner (`vitest`, `@jest/globals`, `node:test`, `bun:test`,
-`mocha`, `ava`, `tap`, `uvu`) is never treated as Playwright's `test`, and neither is a local
+A name imported or required from another test runner (`vitest`, `@jest/globals`, `node:test`,
+`bun:test`, `mocha`, `ava`, `tap`, `uvu`), or a variable set from one such as
+`const test = require('ava')`, is never treated as Playwright's `test`, and neither is a local
 variable declared inside a function that happens to be called `test`.
 
 ### Syntax the rules understand

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import type { ESLint, Rule } from 'eslint';
-import { type GovernanceOptions } from './utils/options.js';
-export type { CustomState, GovernanceOptions, StateOverride } from './utils/options.js';
-export type { TicketSpec } from './utils/tickets.js';
+import { type GovernanceOptions } from './utils/options.ts';
+export type { CustomState, GovernanceOptions, StateOverride } from './utils/options.ts';
+export type { TicketSpec } from './utils/tickets.ts';
 export type RuleName = 'require-ticket' | 'marker-matches-state' | 'no-orphaned-marker' | 'no-conflicting-states' | 'require-ticket-in-comments';
 export declare const rules: Record<RuleName, Rule.RuleModule>;
 export interface FlatConfig {

package/dist/index.js

@@ -1,10 +1,10 @@
 import { createRequire } from 'node:module';
-import markerMatchesState from './rules/marker-matches-state.js';
-import noConflictingStates from './rules/no-conflicting-states.js';
-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 { compileOptions, SETTINGS_KEY } from './utils/options.js';
+import markerMatchesState from "./rules/marker-matches-state.js";
+import noConflictingStates from "./rules/no-conflicting-states.js";
+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 { 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.
 const { version: VERSION } = createRequire(import.meta.url)('../package.json');

package/dist/rules/marker-matches-state.d.ts

@@ -1,3 +1,3 @@
-declare const _default: import("../utils/create-rule.js").Rule<"wrongMarker" | "sharedMarker" | "renameMarker" | "addMarker">;
+declare const _default: import("../utils/create-rule.ts").Rule<"wrongMarker" | "sharedMarker" | "renameMarker" | "addMarker">;
 export default _default;
 //# sourceMappingURL=marker-matches-state.d.ts.map

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

@@ -1,6 +1,6 @@
-import { describeSubject, isStateMarker, missingStates, strayMarkers } from '../utils/analyze.js';
-import { createRule } from '../utils/create-rule.js';
-import { indentOf, keywordRange } from '../utils/fix.js';
+import { appliesTo, describeSubject, isStateMarker, missingStates, strayMarkers } from "../utils/analyze.js";
+import { createRule } from "../utils/create-rule.js";
+import { indentOf, keywordRange } from "../utils/fix.js";
 export default createRule({
     name: 'marker-matches-state',
     meta: {
@@ -24,12 +24,17 @@ export default createRule({
             if (missing.length === 0)
                 continue;
             const stray = strayMarkers(subject, options);
-            const subjectName = describeSubject(subject).replace(/^This/, 'this');
+            const subjectName = describeSubject(subject);
             for (const marker of stray) {
                 context.report({
                     loc: marker.comment.loc,
                     messageId: 'wrongMarker',
-                    data: { found: marker.keyword, expected: missing[0].marker, state: missing[0].name, subject: subjectName },
+                    data: {
+                        found: marker.keyword,
+                        expected: missing[0].marker,
+                        state: missing[0].name,
+                        subject: subjectName.replace(/^This/, 'this'),
+                    },
                     suggest: missing.map((state) => ({
                         messageId: 'renameMarker',
                         data: { expected: state.marker },
@@ -39,8 +44,12 @@ export default createRule({
             }
             if (stray.length > 0)
                 continue;
-            // One marker written for a test that is in two states.
-            const present = subject.markers.filter(isStateMarker).find((m) => m.state !== missing[0]);
+            // One marker written for a test that is in two states. A marker for a state the test isn't in
+            // is not "shared": with no stray markers left, it can only be a work comment such as
+            // `// FIXME: flaky` above `test.skip(...)`, which require-ticket-in-comments reports.
+            const present = subject.markers
+                .filter(isStateMarker)
+                .find((m) => m.state !== missing[0] && appliesTo(subject, m.state.name));
             if (!present)
                 continue;
             for (const state of missing) {

package/dist/rules/no-conflicting-states.d.ts

@@ -1,3 +1,3 @@
-declare const _default: import("../utils/create-rule.js").Rule<"newAndUnstable" | "newSkipped" | "tagCase" | "tagTypo">;
+declare const _default: import("../utils/create-rule.ts").Rule<"newAndUnstable" | "newSkipped" | "tagCase" | "tagTypo">;
 export default _default;
 //# sourceMappingURL=no-conflicting-states.d.ts.map

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

@@ -1,8 +1,8 @@
-import { headLoc } from '../utils/analyze.js';
-import { createRule } from '../utils/create-rule.js';
-import { isTagState } from '../utils/options.js';
-import { editDistance, typoThreshold } from '../utils/distance.js';
-import { tagRange } from '../utils/fix.js';
+import { headLoc } from "../utils/analyze.js";
+import { createRule } from "../utils/create-rule.js";
+import { isTagState } from "../utils/options.js";
+import { editDistance, typoThreshold } from "../utils/distance.js";
+import { tagRange } from "../utils/fix.js";
 export default createRule({
     name: 'no-conflicting-states',
     meta: {
@@ -71,9 +71,12 @@ export default createRule({
                 });
                 return;
             }
+            // A typo changes, adds, drops or swaps a letter or two. A tag that is two or more letters
+            // shorter or longer, like `@stable` or `@untestable` next to `@unstable`, is a different word.
             const near = tagStates.find((s) => {
                 const expected = s.tag.toLowerCase();
-                return editDistance(lower, expected) <= typoThreshold(expected.length - 1);
+                return (Math.abs(lower.length - expected.length) < 2 &&
+                    editDistance(lower, expected) <= typoThreshold(expected.length - 1));
             });
             if (near) {
                 context.report({ node: occurrence.node, messageId: 'tagTypo', data: { found: tag, expected: near.tag } });

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

@@ -1,3 +1,3 @@
-declare const _default: import("../utils/create-rule.js").Rule<"orphaned" | "detached" | "removeMarker">;
+declare const _default: import("../utils/create-rule.ts").Rule<"orphaned" | "detached" | "removeMarker">;
 export default _default;
 //# sourceMappingURL=no-orphaned-marker.d.ts.map

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

@@ -1,6 +1,6 @@
-import { describeSubject, isProse, missingStates, strayMarkers } from '../utils/analyze.js';
-import { createRule } from '../utils/create-rule.js';
-import { removeComment } from '../utils/fix.js';
+import { describeSubject, isProse, missingStates, strayMarkers } from "../utils/analyze.js";
+import { createRule } from "../utils/create-rule.js";
+import { removeComment } from "../utils/fix.js";
 export default createRule({
     name: 'no-orphaned-marker',
     meta: {

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

@@ -1,3 +1,3 @@
-declare const _default: import("../utils/create-rule.js").Rule<"missingTicket" | "invalidTicket" | "placeholderTicket" | "extraText" | "removeExtraText">;
+declare const _default: import("../utils/create-rule.ts").Rule<"missingTicket" | "invalidTicket" | "placeholderTicket" | "extraText" | "removeExtraText">;
 export default _default;
 //# sourceMappingURL=require-ticket-in-comments.d.ts.map

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

@@ -1,6 +1,6 @@
-import { appliesTo, isStateMarker, parseTickets } from '../utils/analyze.js';
-import { createRule } from '../utils/create-rule.js';
-import { compileTicketSpec } from '../utils/tickets.js';
+import { appliesTo, isStateMarker, parseTickets } from "../utils/analyze.js";
+import { createRule } from "../utils/create-rule.js";
+import { compileTicketSpec } from "../utils/tickets.js";
 /** Recognises anything shaped like a ticket, to tell a wrong-format ticket from plain prose. */
 const ticketShape = compileTicketSpec([{ preset: 'any' }], []);
 function escapeRegExp(text) {
@@ -38,9 +38,26 @@ export default createRule({
             }
         }
         // `TODO`/`FIXME` in capitals counts with or without a colon. Other casings need the colon, so a
-        // sentence that happens to start with "Todo" is not mistaken for a work comment.
+        // sentence that happens to start with "Todo" is not mistaken for a work comment. The keyword can
+        // carry its ticket in parentheses, `TODO(WEB-123): ...`, a common style that tools also use for
+        // a name, `TODO(alice)`, which is not a ticket. Some teams put a space before the parenthesis.
         const alternatives = keywords.map(escapeRegExp).join('|');
-        const keywordRe = new RegExp(`^(\\s*\\*?\\s*)(${alternatives})(?:\\s*:|(?=\\s|$))`, 'i');
+        const keywordRe = new RegExp(`^(\\s*\\*?\\s*)(${alternatives})(?:\\s*\\(([^)]*)\\))?(?:\\s*:|(?=\\s|$))`, 'i');
+        /**
+         * `TODO(WEB-1, WEB-2): text`: the tickets are in the parentheses, and anything after them, from the
+         * closing parenthesis on, is a note.
+         */
+        function parseParenthesized(line, start, open, inParens) {
+            const parsed = parseTickets(inParens, start + open + 1, matcher);
+            const close = open + inParens.length + 2;
+            const note = line
+                .slice(close)
+                .replace(/^\s*:?/, '')
+                .trim();
+            if (note === '' || parsed.extra)
+                return parsed;
+            return { ...parsed, extra: { text: note, range: [start + close, start + line.trimEnd().length] } };
+        }
         for (const comment of sourceCode.getAllComments()) {
             if (owned.has(comment))
                 continue;
@@ -54,10 +71,14 @@ export default createRule({
                 if (!match)
                     continue;
                 const [whole, indent, keyword] = match;
+                // The parenthesised group is optional, so it can be undefined despite RegExpExecArray's typing.
+                const inParens = match[3];
                 const upper = keyword.toUpperCase();
                 if (keyword !== upper && !whole.endsWith(':'))
                     continue;
-                const { tickets, extra } = parseTickets(line.slice(whole.length), start + whole.length, matcher);
+                const { tickets, extra } = inParens === undefined
+                    ? parseTickets(line.slice(whole.length), start + whole.length, matcher)
+                    : parseParenthesized(line, start, whole.indexOf('(', indent.length + keyword.length), inParens);
                 const loc = {
                     start: sourceCode.getLocFromIndex(start + indent.length),
                     end: sourceCode.getLocFromIndex(start + line.trimEnd().length),

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

@@ -1,3 +1,3 @@
-declare const _default: import("../utils/create-rule.js").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">;
 export default _default;
 //# sourceMappingURL=require-ticket.d.ts.map

package/dist/rules/require-ticket.js

@@ -1,5 +1,5 @@
-import { appliesTo, describeSubject, evaluate, headLoc } from '../utils/analyze.js';
-import { createRule } from '../utils/create-rule.js';
+import { appliesTo, describeSubject, evaluate, headLoc } from "../utils/analyze.js";
+import { createRule } from "../utils/create-rule.js";
 export default createRule({
     name: 'require-ticket',
     meta: {

package/dist/utils/analyze.d.ts

@@ -1,6 +1,6 @@
 import type { TSESLint, TSESTree } from '@typescript-eslint/utils';
-import type { ResolvedOptions, StateDef } from './options.js';
-import type { TicketCheck, TicketMatcher } from './tickets.js';
+import type { ResolvedOptions, StateDef } from './options.ts';
+import type { TicketCheck, TicketMatcher } from './tickets.ts';
 type Node = TSESTree.Node;
 type Comment = TSESTree.Comment;
 type SourceCode = Readonly<TSESLint.SourceCode>;

package/dist/utils/analyze.js

@@ -49,6 +49,8 @@ function isFunction(node) {
 function collectTestNames(program, configured) {
     const names = new Set(configured);
     const mergeTests = new Set();
+    /** Names bound to another test runner, such as `ava` in `import ava from 'ava'`. */
+    const others = new Set();
     const isTestExpression = (node) => {
         const target = unwrap(node);
         if (target.type === 'Identifier')
@@ -62,12 +64,24 @@ function collectTestNames(program, configured) {
             return false;
         return memberName(target.callee) === 'extend' && isTestExpression(target.callee.object);
     };
+    // require('node:test'), ava, ava.serial or `ava as TestFn<Context>`
+    const isOtherFramework = (node) => {
+        const target = unwrap(node);
+        const source = requireSource(target);
+        if (source !== undefined)
+            return OTHER_FRAMEWORKS.has(source);
+        if (target.type === 'Identifier')
+            return others.has(target.name);
+        return target.type === 'MemberExpression' && isOtherFramework(target.object);
+    };
     for (const statement of program.body) {
         if (statement.type === 'ImportDeclaration') {
             const source = statement.source.value;
             if (OTHER_FRAMEWORKS.has(source)) {
-                for (const spec of statement.specifiers)
+                for (const spec of statement.specifiers) {
                     names.delete(spec.local.name);
+                    others.add(spec.local.name);
+                }
             }
             else if (isPlaywrightModule(source)) {
                 for (const spec of statement.specifiers) {
@@ -91,6 +105,11 @@ function collectTestNames(program, configured) {
             if (declarator.id.type === 'Identifier' && init.type === 'CallExpression' && isTestExpression(init)) {
                 names.add(declarator.id.name);
             }
+            else if (declarator.id.type === 'Identifier' && isOtherFramework(init)) {
+                // `const test = require('node:test')` is another runner's `test`, like an import from it.
+                names.delete(declarator.id.name);
+                others.add(declarator.id.name);
+            }
             else if (declarator.id.type === 'ObjectPattern') {
                 const source = requireSource(init);
                 if (source === undefined)
@@ -98,8 +117,10 @@ function collectTestNames(program, configured) {
                 for (const prop of declarator.id.properties) {
                     if (prop.type !== 'Property' || prop.key.type !== 'Identifier' || prop.value.type !== 'Identifier')
                         continue;
-                    if (OTHER_FRAMEWORKS.has(source))
+                    if (OTHER_FRAMEWORKS.has(source)) {
                         names.delete(prop.value.name);
+                        others.add(prop.value.name);
+                    }
                     else if (isPlaywrightModule(source) && prop.key.name === 'test')
                         names.add(prop.value.name);
                 }
@@ -183,7 +204,8 @@ export function parseTickets(text, offset, matcher) {
         index += separator.length;
     }
     const rest = text.slice(lastEnd).trimEnd();
-    if (tickets.length === 0 || rest.trim() === '')
+    // A sentence-ending `WEB-1.` has nothing after the ticket; `WEB-1: flaky` has a note.
+    if (tickets.length === 0 || /^[.:;]*$/.test(rest.trim()))
         return { tickets };
     return { tickets, extra: { text: rest.trim(), range: [offset + lastEnd, offset + lastEnd + rest.length] } };
 }
@@ -253,10 +275,22 @@ function isUnconditional(call) {
     return (first === undefined || (first.type === 'Literal' && first.value === true)) && !isGuarded(call);
 }
 const FUNCTIONS = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression']);
+/** Whether a statement always leaves the function or block: `return`, `throw`, or a block containing one. */
+function exits(statement) {
+    if (statement.type === 'ReturnStatement' || statement.type === 'ThrowStatement')
+        return true;
+    return statement.type === 'BlockStatement' && statement.body.some(exits);
+}
+/** `if (ready) return;` or `if (!ok) { throw error; }`: code after it only runs on some paths. */
+function isEarlyExit(statement) {
+    return (statement.type === 'IfStatement' &&
+        (exits(statement.consequent) || (statement.alternate !== null && exits(statement.alternate))));
+}
 /**
- * Whether the call only runs on some paths of its function: under an `if`, a `switch` case, a ternary
- * or the right side of `&&`, `||` or `??`. `if (!enabled) test.skip()` is the same as
- * `test.skip(!enabled)`.
+ * Whether the call only runs on some paths of its function: under an `if`, a `switch` case, a ternary,
+ * the right side of `&&`, `||` or `??`, in a `catch` block, or after an early exit such as
+ * `if (ready) return;`. `if (!enabled) test.skip()` is the same as `test.skip(!enabled)`, and
+ * `catch { test.skip(true, 'service is down') }` only skips when the service is down.
  */
 function isGuarded(call) {
     let child = call;
@@ -267,6 +301,13 @@ function isGuarded(call) {
             return true;
         if (node.type === 'LogicalExpression' && child === node.right)
             return true;
+        if (node.type === 'CatchClause')
+            return true;
+        if (node.type === 'BlockStatement') {
+            const index = node.body.indexOf(child);
+            if (node.body.slice(0, index).some(isEarlyExit))
+                return true;
+        }
     }
     return false;
 }
@@ -354,11 +395,16 @@ function runAnalysis(sourceCode, options) {
                 if (param?.type === 'Identifier')
                     testInfo = param.name;
             }
-            const isDeclaration = args.length >= 2 && isFunction(last) && !isFunction(args[0]);
+            // The body is usually written inline, but can be a function defined elsewhere:
+            // `test.skip('pays', payWithCard)`. A string title tells that apart from `test.skip(cond, 'why')`.
+            const titled = args.length >= 2 && isStaticText(args[0]);
+            const isDeclaration = args.length >= 2 && !isFunction(args[0]) && (isFunction(last) || titled);
             if (path.every((p) => TEST_MODIFIERS.has(p)) && isDeclaration) {
                 return { subject: makeSubject('test', call, path, collectTags(call, true)), testInfo };
             }
-            if (path[0] === 'describe' && path.slice(1).every((p) => DESCRIBE_MODIFIERS.has(p)) && isFunction(last)) {
+            if (path[0] === 'describe' &&
+                path.slice(1).every((p) => DESCRIBE_MODIFIERS.has(p)) &&
+                (isFunction(last) || titled)) {
                 const tagInfo = collectTags(call, args.length >= 2);
                 return { subject: makeSubject('describe', call, path.slice(1), tagInfo), testInfo };
             }
@@ -413,7 +459,7 @@ function runAnalysis(sourceCode, options) {
             }
         }
         // Parsers provide visitor keys for every node type they produce; the fallback is only defensive.
-        /* v8 ignore next */
+        /* node:coverage ignore next */
         for (const key of keys[node.type] ?? []) {
             const child = node[key];
             if (Array.isArray(child)) {
@@ -463,10 +509,15 @@ export function evaluate(subject, state) {
         const marker = subject.markers.find((m) => m.caseOf === state);
         return marker ? { kind: 'case', marker } : { kind: 'missing' };
     }
-    if (markers.some((m) => m.tickets.length > 0 && m.tickets.every((t) => t.result === 'ok')))
+    const isValid = (m) => m.tickets.length > 0 && m.tickets.every((t) => t.result === 'ok');
+    // A broken marker in the subject's own block is reported even when another marker is valid: in
+    // `// SKIP: WEB-1` + `// SKIP: nope`, the second line is still wrong. Broken markers further up
+    // are reported for the test or describe they sit above.
+    const brokenOwn = markers.find((m) => subject.markers.includes(m) && !isValid(m));
+    if (!brokenOwn && markers.some(isValid))
         return { kind: 'ok' };
-    // Report the problem with the closest marker.
-    const [marker] = markers;
+    // Report the problem with the closest broken marker.
+    const marker = brokenOwn ?? markers[0];
     const bad = marker.tickets.find((t) => t.result !== 'ok');
     return bad ? { kind: 'bad-ticket', marker, ticket: bad } : { kind: 'no-ticket', marker };
 }

package/dist/utils/create-rule.d.ts

@@ -1,6 +1,6 @@
 import type { TSESLint } from '@typescript-eslint/utils';
-import { type Analysis } from './analyze.js';
-import { type ResolvedOptions } from './options.js';
+import { type Analysis } from './analyze.ts';
+import { type ResolvedOptions } from './options.ts';
 export declare const REPO_URL = "https://github.com/Huldoser/eslint-plugin-test-governance";
 /** Rules take no options of their own: everything is shared through `settings['test-governance']`. */
 export type RuleOptions = [];

package/dist/utils/create-rule.js

@@ -1,5 +1,5 @@
-import { analyze } from './analyze.js';
-import { resolveOptions } from './options.js';
+import { analyze } from "./analyze.js";
+import { resolveOptions } from "./options.js";
 export const REPO_URL = 'https://github.com/Huldoser/eslint-plugin-test-governance';
 /**
  * Builds a rule that reads its options from `settings['test-governance']`.

package/dist/utils/options.d.ts

@@ -1,5 +1,5 @@
-import { type BuiltinStateName } from './constants.js';
-import { type TicketMatcher, type TicketSpec } from './tickets.js';
+import { type BuiltinStateName } from './constants.ts';
+import { type TicketMatcher, type TicketSpec } from './tickets.ts';
 export declare const SETTINGS_KEY = "test-governance";
 /** A state override in `states`. `false` turns a state off, `true` turns it on. */
 export interface StateOverride {
@@ -14,7 +14,7 @@ export interface CustomState {
     marker: string;
     ticket?: TicketSpec | TicketSpec[];
 }
-export type { BuiltinStateName } from './constants.js';
+export type { BuiltinStateName } from './constants.ts';
 /** Options shared by every rule. Set them once in `settings['test-governance']`. */
 export interface GovernanceOptions {
     /** Names that are treated as the Playwright `test` function. Defaults to `['test']`. */
@@ -78,7 +78,7 @@ export interface ResolvedOptions {
     /** Ticket format for comments: the shared default format. */
     commentTicket: TicketMatcher;
 }
-export { ConfigError } from './errors.js';
+export { ConfigError } from './errors.ts';
 /**
  * Compiles `settings['test-governance']`. Every rule reads the same settings, so they always agree,
  * and the result is cached per settings object, so the rules share one compile.

package/dist/utils/options.js

@@ -1,8 +1,8 @@
-import { DEFAULT_COMMENT_KEYWORDS } from './constants.js';
-import { ConfigError } from './errors.js';
-import { optionsSchema } from './schema.js';
-import { compileTicketSpec, DEFAULT_PLACEHOLDERS } from './tickets.js';
-import { validate } from './validate.js';
+import { BUILTIN_STATE_NAMES, DEFAULT_COMMENT_KEYWORDS } from "./constants.js";
+import { ConfigError } from "./errors.js";
+import { optionsSchema } from "./schema.js";
+import { compileTicketSpec, DEFAULT_PLACEHOLDERS } from "./tickets.js";
+import { validate } from "./validate.js";
 export const SETTINGS_KEY = 'test-governance';
 export function isTagState(state) {
     return state.tag !== undefined;
@@ -15,7 +15,7 @@ const BUILTIN_STATES = {
     new: { marker: 'NEW', tag: '@new', lifecycle: true, enabled: false },
     unstable: { marker: 'UNSTABLE', tag: '@unstable', lifecycle: true, enabled: false },
 };
-export { ConfigError } from './errors.js';
+export { ConfigError } from "./errors.js";
 function toSpecs(spec) {
     return Array.isArray(spec) ? spec : [spec];
 }
@@ -34,8 +34,51 @@ export function resolveOptions(settings) {
     }
     return resolved;
 }
+/** The options each ticket preset takes besides `preset`. */
+const PRESET_OPTIONS = {
+    any: [],
+    jira: ['projects', 'host'],
+    github: ['host'],
+    gitlab: ['host'],
+    linear: ['teams'],
+    'azure-devops': ['host'],
+    numeric: ['minLength', 'maxLength'],
+    pattern: ['pattern', 'flags'],
+};
+/** Options set on a ticket spec that its preset ignores, such as `host` on the `any` preset. */
+function presetProblems(ticket, path) {
+    if (ticket === undefined)
+        return [];
+    const specs = Array.isArray(ticket) ? ticket : [ticket];
+    return specs.flatMap((spec, index) => {
+        const at = Array.isArray(ticket) ? `${path}[${index}]` : path;
+        const allowed = PRESET_OPTIONS[spec.preset];
+        return Object.keys(spec)
+            .filter((key) => key !== 'preset' && spec[key] !== undefined && !allowed.includes(key))
+            .map((key) => {
+            const presets = Object.entries(PRESET_OPTIONS).filter(([, keys]) => keys.includes(key));
+            return `${at}.${key} is not an option of the "${spec.preset}" preset (it applies to ${presets.map(([name]) => `"${name}"`).join(', ')})`;
+        });
+    });
+}
+/** Problems the schema can't express: options that belong to another preset, and reused state names. */
+function crossFieldProblems(options) {
+    const problems = presetProblems(options.ticket, 'ticket');
+    for (const [name, override] of Object.entries(options.states ?? {})) {
+        if (typeof override === 'object')
+            problems.push(...presetProblems(override.ticket, `states.${name}.ticket`));
+    }
+    for (const [name, custom] of Object.entries(options.customStates ?? {})) {
+        if (BUILTIN_STATE_NAMES.includes(name)) {
+            problems.push(`customStates.${name} reuses the name of the built-in "${name}" state; give it another name, or use states.${name} to change the built-in`);
+        }
+        problems.push(...presetProblems(custom.ticket, `customStates.${name}.ticket`));
+    }
+    return problems;
+}
 export function compileOptions(options) {
-    const problems = validate(options, optionsSchema);
+    const schemaProblems = validate(options, optionsSchema);
+    const problems = schemaProblems.length > 0 ? schemaProblems : crossFieldProblems(options);
     if (problems.length > 0) {
         throw new ConfigError(`invalid options:\n${problems.map((problem) => `  - ${problem}`).join('\n')}`);
     }

package/dist/utils/schema.d.ts

@@ -1,4 +1,4 @@
-import type { Schema } from './validate.js';
+import type { Schema } from './validate.ts';
 /** The shape of `settings['test-governance']`, the options of `configure()`. */
 export declare const optionsSchema: Schema;
 //# sourceMappingURL=schema.d.ts.map

package/dist/utils/schema.js

@@ -1,12 +1,15 @@
-import { BUILTIN_STATE_NAMES, MARKER_RE, TAG_RE, TICKET_PRESETS } from './constants.js';
+import { BUILTIN_STATE_NAMES, MARKER_RE, TAG_RE, TICKET_PRESETS } from "./constants.js";
 const MARKER_HINT = 'an uppercase keyword such as NEEDS-DATA (letters, digits, "-" and "_")';
 const TAG_HINT = 'a tag such as @needs-data';
+/** Jira project and Linear team keys, as they appear in tickets: `WEB` in `WEB-123`. */
+const KEY_PATTERN = '^[A-Z][A-Z0-9_]+$';
+const KEY_HINT = 'an uppercase key as it appears in tickets, such as WEB for WEB-123';
 const ticketSpecSchema = {
     type: 'object',
     properties: {
         preset: { type: 'string', enum: [...TICKET_PRESETS] },
-        projects: { type: 'array', items: { type: 'string' } },
-        teams: { type: 'array', items: { type: 'string' } },
+        projects: { type: 'array', items: { type: 'string', pattern: KEY_PATTERN, patternHint: KEY_HINT } },
+        teams: { type: 'array', items: { type: 'string', pattern: KEY_PATTERN, patternHint: KEY_HINT } },
         host: { type: 'string' },
         minLength: { type: 'integer', minimum: 1 },
         maxLength: { type: 'integer', minimum: 1 },

package/dist/utils/tickets.js

@@ -1,4 +1,4 @@
-import { ConfigError } from './errors.js';
+import { ConfigError } from "./errors.js";
 export const DEFAULT_PLACEHOLDERS = ['TODO', 'TBD', 'XXX-*', '0', '123', '1234', '12345'];
 // Every pattern below is anchored and has no nested or overlapping quantifiers, so matching is
 // linear in the token length. URLs are parsed with `new URL` rather than a regex.

package/dist/utils/validate.js

@@ -1,4 +1,4 @@
-import { editDistance } from './distance.js';
+import { editDistance } from "./distance.js";
 function kindOf(value) {
     if (value === null)
         return 'null';

package/docs/rules/no-orphaned-marker.md

@@ -16,8 +16,15 @@ A leftover marker makes searches for open tickets lie. This rule reports:
 
 `FIXME:` and `TODO:` are also everyday work comments, so this rule leaves them to
 [`require-ticket-in-comments`](require-ticket-in-comments.md), which requires a ticket in them anywhere
-in a test file. A `// FIXME: WEB-12` above a helper is a tracked work comment, not a stray marker. A
-`// FIXME: refactor this` gets one clear error from that rule rather than a confusing one from this.
+in a test file. A `// FIXME: refactor this` gets one clear error from that rule rather than a confusing
+one from this.
+
+A `FIXME:` or `TODO:` comment that starts with a valid ticket is treated by where it sits:
+
+- Above a helper or any other code that isn't a test, it is a tracked work comment and is allowed.
+- Above a test, describe or skip call that is not in the `fixme` state, it reads as a leftover marker
+  and is reported, since `// FIXME: WEB-12` above a test usually means the test was fixed and the
+  marker forgotten. Move a work comment into the test body, or onto the line of code it is about.
 
 Other markers that read as a sentence, such as `// SKIP: this one is flaky`, are left alone too: the rule
 counts a comment as prose when its first word is not a valid ticket and more text follows.

package/docs/rules/require-ticket-in-comments.md

@@ -15,6 +15,8 @@ source of truth and nothing is forgotten in a comment.
 ```ts
 // TODO: WEB-512                 ✓
 // FIXME: WEB-77, WEB-78         ✓ several tickets, separated by commas
+// TODO(WEB-512)                 ✓ the ticket can go in parentheses
+// TODO(alice): refactor this    ✖ a name is not a ticket
 // TODO: refactor this           ✖ no ticket
 // FIXME: WEB-77 flaky locator   ✖ only tickets are allowed (allowNotes: true allows the note)
 ```
@@ -24,6 +26,8 @@ How comments are read:
 - The keyword starts the comment (or a line of a block comment). `TODO` and `FIXME` in capitals
   count with or without a colon. Other casings, such as `todo:`, need the colon, so a sentence that
   happens to start with "Todo" is left alone.
+- The tickets can also go in parentheses after the keyword, `TODO(WEB-512)` or `TODO (WEB-512)`, a
+  style many teams already use. Anything after the parentheses is a note, as it would be after `TODO: WEB-512`.
 - The tickets follow the same rules as markers: the shared ticket format, placeholders such as `TBD`
   rejected, and no text after the tickets unless `allowNotes` is set.
 - A `// FIXME:` marker directly above a `test.fixme(...)` is checked by

package/docs/rules/require-ticket.md

@@ -53,7 +53,8 @@ How ticket lists are read:
 | `// SKIP:   WEB-1  ,  WEB-2  `                                                  | two tickets; extra spaces are fine                        |
 | `// SKIP: https://acme.atlassian.net/browse/WEB-1?focusedCommentId=5#comment-5` | one ticket; query strings and fragments are part of a URL |
 | `// SKIP: WEB-1 flaky on CI`, `// SKIP: WEB-1: flaky`                           | extra text `flaky on CI` / `: flaky`                      |
-| `// SKIP: WEB-1,` or `// SKIP: WEB-1.`                                          | extra text `,` / `.`                                      |
+| `// SKIP: WEB-1.` or `// SKIP: WEB-1:`                                          | one ticket; a full stop or colon at the end is fine       |
+| `// SKIP: WEB-1,`                                                               | extra text `,`                                            |
 | `// SKIP: WEB-1 and WEB-2`                                                      | extra text `and WEB-2`; separate tickets with commas      |
 | `// SKIP: WEB-1;WEB-2`, `// SKIP: WEB-1/WEB-2`                                  | invalid ticket, since only commas separate tickets        |
 | `// SKIP: flaky on CI`                                                          | invalid ticket `flaky`: the first word must be a ticket   |
@@ -64,7 +65,12 @@ lines. Extra text is reported only once the tickets on that line are valid.
 Conditional skips such as `test.skip(browserName === 'webkit', 'Not supported')` usually describe a
 permanent platform limit, so they need no ticket unless you set `requireTicketForConditional: true`.
 A runtime skip under an `if`, a `switch` case, a ternary or `&&` counts as conditional too, since
-`if (!enabled) test.skip()` does the same as `test.skip(!enabled)`.
+`if (!enabled) test.skip()` does the same as `test.skip(!enabled)`. So does a skip in a `catch` block,
+such as `catch { test.skip(true, 'Mail server is down') }`, and a skip after an early exit such as
+`if (ready) return;` or `if (!ok) throw error;` earlier in the same function.
+
+If one test or describe has several markers for the same state, each must be valid: in
+`// SKIP: WEB-1` followed by `// SKIP: nope`, the second line is reported.
 
 ## Examples
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-test-governance",
-  "version": "0.2.1",
+  "version": "0.3.1",
   "description": "ESLint rules that require a ticket comment above skipped, fixme and tagged Playwright tests.",
   "keywords": [
     "eslint",
@@ -45,8 +45,8 @@
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
     "typecheck": "tsc -p tsconfig.json",
-    "test": "vitest run",
-    "test:coverage": "vitest run --coverage",
+    "test": "node --test 'tests/**/*.test.ts'",
+    "test:coverage": "node --test --experimental-test-coverage --test-coverage-include='src/rules/**' --test-coverage-include='src/utils/**' --test-coverage-branches=100 --test-coverage-functions=100 --test-coverage-lines=100 'tests/**/*.test.ts'",
     "test:pack": "node scripts/pack-smoke.mjs",
     "docs": "npm run build && eslint-doc-generator",
     "docs:check": "npm run build && eslint-doc-generator --check",
@@ -63,15 +63,11 @@
     "@types/node": "^26.6.3",
     "@typescript-eslint/parser": "^8.71.0",
     "@typescript-eslint/utils": "^8.71.0",
-    "@vitest/coverage-v8": "^5.0.2",
     "eslint": "^10.11.0",
-    "eslint-config-prettier": "^10.1.8",
     "eslint-doc-generator": "^3.7.1",
     "eslint-plugin-eslint-plugin": "^7.6.2",
-    "globals": "^17.13.0",
     "prettier": "^3.9.9",
     "typescript": "6.0",
-    "typescript-eslint": "^8.71.0",
-    "vitest": "^5.0.2"
+    "typescript-eslint": "^8.71.0"
   }
 }