eslint-plugin-test-governance 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -6,6 +6,49 @@ All notable changes to this project are documented here. The format follows
 
 ## [Unreleased]
 
+## [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
+
+- A `funding` link in `package.json`, so `npm fund` points to
+  [GitHub Sponsors](https://github.com/sponsors/Huldoser).
+
+### Fixed
+
+- A `pattern` ticket preset with the `g` or `y` flag no longer rejects every other valid ticket. Those
+  flags are now ignored, since a ticket is always matched whole.
+- A marker directly above a test that is the body of an arrow function, such as
+  `rows.forEach((row) =>` followed by `// SKIP: WEB-1` and `test.skip(...)`, is found. It was
+  reported both as missing and as a stray marker.
+
 ## [0.2.0] - 2026-10-01
 
 0.1.1 was published with these changes by mistake and is deprecated. Use 0.2.0, or stay on 0.1.0
@@ -78,7 +121,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.0...HEAD
+[Unreleased]: https://github.com/Huldoser/eslint-plugin-test-governance/compare/v0.3.0...HEAD
+[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
 [0.1.0]: https://github.com/Huldoser/eslint-plugin-test-governance/releases/tag/v0.1.0

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
 

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

@@ -1,4 +1,4 @@
-import { describeSubject, isStateMarker, missingStates, strayMarkers } from '../utils/analyze.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({
@@ -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.js

@@ -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/require-ticket-in-comments.js

@@ -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.
         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|$))`, '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, indent.length + keyword.length, inParens);
                 const loc = {
                     start: sourceCode.getLocFromIndex(start + indent.length),
                     end: sourceCode.getLocFromIndex(start + line.trimEnd().length),

package/dist/utils/analyze.js

@@ -183,7 +183,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 +254,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 +280,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;
 }
@@ -297,6 +317,10 @@ function runAnalysis(sourceCode, options) {
         const parent = stack.at(-1);
         const anchor = anchorOf(call);
         const block = commentBlock(sourceCode, anchor, options.allowBlankLine);
+        // `rows.forEach((row) =>\n  // SKIP: WEB-1\n  test.skip(...))`: the marker sits above the call itself.
+        if (call.parent.type === 'ArrowFunctionExpression' && call.parent.body === call) {
+            block.push(...commentBlock(sourceCode, call, options.allowBlankLine));
+        }
         for (const comment of block)
             claimed.add(comment);
         const ownTags = new Set(tagInfo.tags.map((t) => t.tag));
@@ -459,10 +483,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/options.js

@@ -1,4 +1,4 @@
-import { DEFAULT_COMMENT_KEYWORDS } from './constants.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';
@@ -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.js

@@ -1,12 +1,15 @@
 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

@@ -139,7 +139,9 @@ function compilePreset(spec) {
             }
             let re;
             try {
-                re = new RegExp(`^(?:${spec.pattern})$`, spec.flags);
+                // `g` and `y` make `test()` resume from the last match, so the same ticket would pass and fail
+                // in turn. A ticket is matched whole, so they never change what matches; drop them.
+                re = new RegExp(`^(?:${spec.pattern})$`, spec.flags?.replace(/[gy]/g, ''));
             }
             catch (error) {
                 throw new ConfigError(`invalid ticket pattern "${spec.pattern}": ${error.message}`);

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 straight after the keyword, `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.0",
+  "version": "0.3.0",
   "description": "ESLint rules that require a ticket comment above skipped, fixme and tagged Playwright tests.",
   "keywords": [
     "eslint",
@@ -13,6 +13,10 @@
   "bugs": {
     "url": "https://github.com/Huldoser/eslint-plugin-test-governance/issues"
   },
+  "funding": {
+    "type": "github",
+    "url": "https://github.com/sponsors/Huldoser"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Huldoser/eslint-plugin-test-governance.git"