eslint-plugin-test-governance 0.1.0 → 0.2.0

package/dist/rules/require-ticket.js

@@ -1,4 +1,4 @@
-import { appliesTo, describeSubject, evaluate } from '../utils/analyze.js';
+import { appliesTo, describeSubject, evaluate, headLoc } from '../utils/analyze.js';
 import { createRule } from '../utils/create-rule.js';
 export default createRule({
     name: 'require-ticket',
@@ -33,7 +33,9 @@ export default createRule({
                 if (!required)
                     continue;
                 const result = evaluate(subject, state);
-                if (result.kind !== 'ok' && result.kind !== 'missing' && !reportOnce(`${result.marker.comment.range[0]}:${state.name}`)) {
+                if (result.kind !== 'ok' &&
+                    result.kind !== 'missing' &&
+                    !reportOnce(`${result.marker.comment.range[0]}:${state.name}`)) {
                     continue;
                 }
                 const data = { state: state.name, marker: state.marker, example: state.ticket.example };
@@ -42,7 +44,7 @@ export default createRule({
                         break;
                     case 'missing':
                         context.report({
-                            node: subject.node,
+                            loc: headLoc(subject),
                             messageId: 'missingMarker',
                             data: { ...data, subject: describeSubject(subject) },
                         });

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 } from './tickets.js';
+import type { TicketCheck, TicketMatcher } from './tickets.js';
 type Node = TSESTree.Node;
 type Comment = TSESTree.Comment;
 type SourceCode = Readonly<TSESLint.SourceCode>;
@@ -23,6 +23,11 @@ export interface Marker {
         range: TSESTree.Range;
     };
 }
+/** A marker whose keyword is exactly a state's marker. */
+export type StateMarker = Marker & {
+    state: StateDef;
+};
+export declare function isStateMarker(marker: Marker): marker is StateMarker;
 export interface TagOccurrence {
     tag: string;
     node: TSESTree.Literal | TSESTree.TemplateLiteral;
@@ -57,7 +62,9 @@ export interface Subject {
 export interface Analysis {
     subjects: Subject[];
     /** Markers that are not in the comment block of any test, describe or runtime call. */
-    detachedMarkers: Marker[];
+    detachedMarkers: StateMarker[];
+    /** Whether the file uses Playwright at all: a Playwright import or a call to a test function. */
+    isTestFile: boolean;
 }
 export type Evaluation = {
     kind: 'ok';
@@ -74,14 +81,37 @@ export type Evaluation = {
     marker: Marker;
     ticket: MarkerTicket;
 };
+/**
+ * Parses `TICKET[, TICKET...]` from the text after a marker's colon. `offset` is the source position
+ * of `text[0]`. Anything after the last ticket, including a trailing comma, is returned as `extra`.
+ */
+export declare function parseTickets(text: string, offset: number, matcher: TicketMatcher): Pick<Marker, 'tickets' | 'extra'>;
 export declare function analyze(sourceCode: SourceCode, options: ResolvedOptions): Analysis;
 /** Whether `subject` is in `stateName` at all, required or not, including inherited and runtime states. */
 export declare function appliesTo(subject: Subject, stateName: string): boolean;
 export declare function evaluate(subject: Subject, state: StateDef): Evaluation;
 /** Required states on `subject` that have no marker at all (not even a broken one). */
 export declare function missingStates(subject: Subject): StateDef[];
-/** Markers in the subject's own block for states that don't apply to it. */
-export declare function strayMarkers(subject: Subject): Marker[];
+/**
+ * Whether a marker reads as an ordinary comment rather than a ticket reference, such as
+ * `// FIXME: this breaks on slow machines`: it starts with something that is not a ticket and goes on
+ * after it.
+ */
+export declare function isProse(marker: Marker): boolean;
+/**
+ * Whether a marker is really an ordinary work comment such as `// FIXME: refactor this`: its keyword
+ * is also a work-comment keyword and it doesn't start with a valid ticket. `require-ticket-in-comments`
+ * reports those; the marker rules leave them alone.
+ */
+export declare function isWorkComment(marker: Marker, options: ResolvedOptions): boolean;
+/** Markers in the subject's own block for states that don't apply to it, leaving out work comments. */
+export declare function strayMarkers(subject: Subject, options: ResolvedOptions): StateMarker[];
+/**
+ * Where to report a problem with a test or describe: from the callee to the end of the title
+ * (`test.skip('pays with PayPal'`), so editors underline the declaration rather than the whole body.
+ * Runtime calls such as `test.skip()` are short, so they are reported whole.
+ */
+export declare function headLoc(subject: Subject): TSESTree.SourceLocation;
 export declare function describeSubject(subject: Subject): string;
 export {};
 //# sourceMappingURL=analyze.d.ts.map

package/dist/utils/analyze.js

@@ -1,10 +1,19 @@
 const PLAYWRIGHT_MODULES = new Set(['@playwright/test', 'playwright/test']);
+/** Other test runners. A name imported from one of these is never Playwright's `test`. */
+const OTHER_FRAMEWORKS = new Set(['vitest', '@jest/globals', 'node:test', 'bun:test', 'mocha', 'ava', 'tap', 'uvu']);
+/** `@playwright/test` and the component-testing packages such as `@playwright/experimental-ct-react`. */
+function isPlaywrightModule(source) {
+    return PLAYWRIGHT_MODULES.has(source) || source.startsWith('@playwright/experimental-ct-');
+}
 const TEST_MODIFIERS = new Set(['only', 'skip', 'fixme', 'fail', 'slow']);
 const DESCRIBE_MODIFIERS = new Set(['only', 'skip', 'fixme', 'serial', 'parallel']);
 const RUNTIME_MODIFIERS = new Set(['skip', 'fixme', 'fail', 'slow']);
 const SKIPPING_MODIFIERS = new Set(['skip', 'fixme']);
 const MARKER_LINE_RE = /^\s*\*?\s*([A-Za-z][\w-]*)\s*:(.*)$/;
 const TAG_RE = /(?<![\w@])@[\w-]+/g;
+export function isStateMarker(marker) {
+    return marker.state !== undefined;
+}
 function memberName(node) {
     if (!node.computed && node.property.type === 'Identifier')
         return node.property.name;
@@ -22,7 +31,7 @@ function chainOf(node) {
         path.unshift(name);
         current = current.object;
     }
-    return current.type === 'Identifier' ? { root: current.name, path } : undefined;
+    return current.type === 'Identifier' ? { root: current, path } : undefined;
 }
 function unwrap(node) {
     let current = node;
@@ -36,26 +45,39 @@ function unwrap(node) {
 function isFunction(node) {
     return node?.type === 'ArrowFunctionExpression' || node?.type === 'FunctionExpression';
 }
-/** Collects the local names that refer to Playwright's `test`. */
+/** Collects the top-level names that refer to Playwright's `test`. */
 function collectTestNames(program, configured) {
     const names = new Set(configured);
+    const mergeTests = new Set();
     const isTestExpression = (node) => {
         const target = unwrap(node);
         if (target.type === 'Identifier')
             return names.has(target.name);
-        if (target.type !== 'CallExpression' || target.callee.type !== 'MemberExpression')
+        if (target.type !== 'CallExpression')
+            return false;
+        // mergeTests(dbTest, a11yTest)
+        if (target.callee.type === 'Identifier')
+            return mergeTests.has(target.callee.name);
+        if (target.callee.type !== 'MemberExpression')
             return false;
         return memberName(target.callee) === 'extend' && isTestExpression(target.callee.object);
     };
     for (const statement of program.body) {
         if (statement.type === 'ImportDeclaration') {
-            if (!PLAYWRIGHT_MODULES.has(statement.source.value))
-                continue;
-            for (const spec of statement.specifiers) {
-                if (spec.type === 'ImportDefaultSpecifier')
-                    names.add(spec.local.name);
-                else if (spec.type === 'ImportSpecifier' && importedName(spec) === 'test')
-                    names.add(spec.local.name);
+            const source = statement.source.value;
+            if (OTHER_FRAMEWORKS.has(source)) {
+                for (const spec of statement.specifiers)
+                    names.delete(spec.local.name);
+            }
+            else if (isPlaywrightModule(source)) {
+                for (const spec of statement.specifiers) {
+                    if (spec.type === 'ImportDefaultSpecifier')
+                        names.add(spec.local.name);
+                    else if (spec.type === 'ImportSpecifier' && importedName(spec) === 'test')
+                        names.add(spec.local.name);
+                    else if (spec.type === 'ImportSpecifier' && importedName(spec) === 'mergeTests')
+                        mergeTests.add(spec.local.name);
+                }
             }
             continue;
         }
@@ -69,11 +91,17 @@ function collectTestNames(program, configured) {
             if (declarator.id.type === 'Identifier' && init.type === 'CallExpression' && isTestExpression(init)) {
                 names.add(declarator.id.name);
             }
-            else if (declarator.id.type === 'ObjectPattern' && isPlaywrightRequire(init)) {
+            else if (declarator.id.type === 'ObjectPattern') {
+                const source = requireSource(init);
+                if (source === undefined)
+                    continue;
                 for (const prop of declarator.id.properties) {
-                    if (prop.type === 'Property' && prop.key.type === 'Identifier' && prop.key.name === 'test' && prop.value.type === 'Identifier') {
+                    if (prop.type !== 'Property' || prop.key.type !== 'Identifier' || prop.value.type !== 'Identifier')
+                        continue;
+                    if (OTHER_FRAMEWORKS.has(source))
+                        names.delete(prop.value.name);
+                    else if (isPlaywrightModule(source) && prop.key.name === 'test')
                         names.add(prop.value.name);
-                    }
                 }
             }
         }
@@ -81,19 +109,36 @@ function collectTestNames(program, configured) {
     return names;
 }
 function importedName(spec) {
-    return spec.imported.type === 'Identifier' ? spec.imported.name : String(spec.imported.value);
+    return spec.imported.type === 'Identifier' ? spec.imported.name : spec.imported.value;
+}
+/** The module name of `require('...')`, or undefined for anything else. */
+function requireSource(node) {
+    if (node.type !== 'CallExpression' || node.callee.type !== 'Identifier' || node.callee.name !== 'require')
+        return undefined;
+    const first = node.arguments.at(0);
+    return first?.type === 'Literal' && typeof first.value === 'string' ? first.value : undefined;
 }
-function isPlaywrightRequire(node) {
-    return (node.type === 'CallExpression' &&
-        node.callee.type === 'Identifier' &&
-        node.callee.name === 'require' &&
-        node.arguments[0]?.type === 'Literal' &&
-        PLAYWRIGHT_MODULES.has(String(node.arguments[0].value)));
+/**
+ * Whether `id` refers to a variable declared inside a function or block, such as a local helper that
+ * happens to be called `test`. Top-level variables, imports, parameters and globals still count.
+ */
+function isLocalVariable(sourceCode, id) {
+    for (let scope = sourceCode.getScope(id); scope; scope = scope.upper) {
+        const variable = scope.set.get(id.name);
+        if (!variable)
+            continue;
+        if (scope.type === 'module' || scope.type === 'global')
+            return false;
+        return variable.defs.some((def) => def.type === 'Variable');
+    }
+    return false;
 }
 const STATEMENT_CONTAINERS = new Set(['Program', 'BlockStatement', 'StaticBlock', 'SwitchCase', 'TSModuleBlock']);
 /** The statement a call belongs to; its marker block sits above that statement. */
 function anchorOf(call) {
     let node = call;
+    // A call always sits inside a statement container, so the walk stops before it runs out of parents.
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- see above
     while (!STATEMENT_CONTAINERS.has(node.parent.type))
         node = node.parent;
     return node;
@@ -108,7 +153,7 @@ function commentBlock(sourceCode, anchor, allowBlankLine) {
         if (!allowBlankLine && nextLine - comment.loc.end.line > 1)
             break;
         const before = sourceCode.getTokenBefore(comment, { includeComments: false });
-        if (before && before.loc.end.line === comment.loc.start.line)
+        if (before?.loc.end.line === comment.loc.start.line)
             break;
         block.unshift(comment);
         nextLine = comment.loc.start.line;
@@ -119,7 +164,7 @@ function commentBlock(sourceCode, anchor, allowBlankLine) {
  * Parses `TICKET[, TICKET...]` from the text after a marker's colon. `offset` is the source position
  * of `text[0]`. Anything after the last ticket, including a trailing comma, is returned as `extra`.
  */
-function parseTickets(text, offset, state) {
+export function parseTickets(text, offset, matcher) {
     const tickets = [];
     let index = text.length - text.trimStart().length;
     let lastEnd = 0;
@@ -129,7 +174,7 @@ function parseTickets(text, offset, state) {
             break;
         // Punctuation right after a ticket (`WEB-1:` or `WEB-1.`) is not part of it.
         const ticket = token.replace(/[.:;]+$/, '');
-        tickets.push({ text: ticket, result: state.ticket.check(ticket) });
+        tickets.push({ text: ticket, result: matcher.check(ticket) });
         index += ticket.length;
         lastEnd = index;
         const separator = /^\s*,\s*/.exec(text.slice(index))?.[0];
@@ -156,7 +201,7 @@ function parseMarkers(comment, states) {
         const state = states.find((s) => s.marker === keyword);
         if (state) {
             const restOffset = start + match[0].length - rest.length;
-            markers.push({ comment, keyword, state, ...parseTickets(rest, restOffset, state) });
+            markers.push({ comment, keyword, state, ...parseTickets(rest, restOffset, state.ticket) });
             continue;
         }
         const caseOf = states.find((s) => s.marker === keyword.toUpperCase());
@@ -166,8 +211,11 @@ function parseMarkers(comment, states) {
     return markers;
 }
 function scanTags(node, out) {
-    // `cooked` is only null in tagged templates, which are never titles.
-    const texts = node.type === 'Literal' ? [String(node.value)] : node.quasis.map((quasi) => quasi.value.cooked);
+    const texts = node.type === 'Literal'
+        ? [String(node.value)]
+        : // `cooked` is only null in tagged templates, which are never titles.
+            // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- see above
+            node.quasis.map((quasi) => quasi.value.cooked);
     for (const text of texts) {
         for (const match of text.matchAll(TAG_RE))
             out.push({ tag: match[0], node });
@@ -201,8 +249,26 @@ function collectTags(call, hasTitle) {
     return { tags, dynamic };
 }
 function isUnconditional(call) {
-    const [first] = call.arguments;
-    return first === undefined || (first.type === 'Literal' && first.value === true);
+    const first = call.arguments.at(0);
+    return (first === undefined || (first.type === 'Literal' && first.value === true)) && !isGuarded(call);
+}
+const FUNCTIONS = new Set(['FunctionDeclaration', 'FunctionExpression', 'ArrowFunctionExpression']);
+/**
+ * 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)`.
+ */
+function isGuarded(call) {
+    let child = call;
+    for (let node = call.parent; node && !FUNCTIONS.has(node.type); child = node, node = node.parent) {
+        if ((node.type === 'IfStatement' || node.type === 'ConditionalExpression') && child !== node.test)
+            return true;
+        if (node.type === 'SwitchCase' && child !== node.test)
+            return true;
+        if (node.type === 'LogicalExpression' && child === node.right)
+            return true;
+    }
+    return false;
 }
 const cache = new WeakMap();
 export function analyze(sourceCode, options) {
@@ -221,6 +287,7 @@ export function analyze(sourceCode, options) {
 function runAnalysis(sourceCode, options) {
     const { states } = options;
     const testNames = collectTestNames(sourceCode.ast, options.testFunctions);
+    let usesTest = sourceCode.ast.body.some((statement) => statement.type === 'ImportDeclaration' && isPlaywrightModule(statement.source.value));
     const subjects = [];
     const claimed = new Set();
     const stack = [];
@@ -275,10 +342,11 @@ function runAnalysis(sourceCode, options) {
         const args = call.arguments;
         const last = args.at(-1);
         let testInfo;
-        if (chain && testNames.has(chain.root)) {
+        if (chain && testNames.has(chain.root.name) && !isLocalVariable(sourceCode, chain.root)) {
+            usesTest = true;
             const { path } = chain;
             if (isFunction(last)) {
-                const param = last.params[1];
+                const param = last.params.at(1);
                 if (param?.type === 'Identifier')
                     testInfo = param.name;
             }
@@ -304,7 +372,7 @@ function runAnalysis(sourceCode, options) {
                     (object.type === 'CallExpression' &&
                         (() => {
                             const inner = chainOf(object.callee);
-                            return inner !== undefined && testNames.has(inner.root) && inner.path.join('.') === 'info';
+                            return inner !== undefined && testNames.has(inner.root.name) && inner.path.join('.') === 'info';
                         })());
                 if (isTestInfo)
                     return { subject: runtimeSubject(call, name) };
@@ -363,8 +431,8 @@ function runAnalysis(sourceCode, options) {
         .getAllComments()
         .filter((comment) => !claimed.has(comment))
         .flatMap((comment) => parseMarkers(comment, states))
-        .filter((marker) => marker.state !== undefined);
-    return { subjects, detachedMarkers };
+        .filter(isStateMarker);
+    return { subjects, detachedMarkers, isTestFile: usesTest };
 }
 /** Whether `subject` is in `stateName` at all, required or not, including inherited and runtime states. */
 export function appliesTo(subject, stateName) {
@@ -391,24 +459,50 @@ export function evaluate(subject, state) {
         const marker = subject.markers.find((m) => m.caseOf === state);
         return marker ? { kind: 'case', marker } : { kind: 'missing' };
     }
-    let firstProblem;
-    for (const marker of markers) {
-        const bad = marker.tickets.find((t) => t.result !== 'ok');
-        if (marker.tickets.length > 0 && !bad)
-            return { kind: 'ok' };
-        firstProblem ??= bad ? { kind: 'bad-ticket', marker, ticket: bad } : { kind: 'no-ticket', marker };
-    }
-    return firstProblem;
+    if (markers.some((m) => m.tickets.length > 0 && m.tickets.every((t) => t.result === 'ok')))
+        return { kind: 'ok' };
+    // Report the problem with the closest marker.
+    const [marker] = markers;
+    const bad = marker.tickets.find((t) => t.result !== 'ok');
+    return bad ? { kind: 'bad-ticket', marker, ticket: bad } : { kind: 'no-ticket', marker };
 }
 /** Required states on `subject` that have no marker at all (not even a broken one). */
 export function missingStates(subject) {
-    return subject.states
-        .filter((s) => s.required && evaluate(subject, s.state).kind === 'missing')
-        .map((s) => s.state);
+    return subject.states.filter((s) => s.required && evaluate(subject, s.state).kind === 'missing').map((s) => s.state);
 }
-/** Markers in the subject's own block for states that don't apply to it. */
-export function strayMarkers(subject) {
-    return subject.markers.filter((m) => m.state !== undefined && !appliesTo(subject, m.state.name));
+/**
+ * Whether a marker reads as an ordinary comment rather than a ticket reference, such as
+ * `// FIXME: this breaks on slow machines`: it starts with something that is not a ticket and goes on
+ * after it.
+ */
+export function isProse(marker) {
+    return marker.extra !== undefined && marker.tickets[0].result !== 'ok';
+}
+/**
+ * Whether a marker is really an ordinary work comment such as `// FIXME: refactor this`: its keyword
+ * is also a work-comment keyword and it doesn't start with a valid ticket. `require-ticket-in-comments`
+ * reports those; the marker rules leave them alone.
+ */
+export function isWorkComment(marker, options) {
+    return options.workCommentKeywords.has(marker.keyword.toUpperCase()) && marker.tickets.at(0)?.result !== 'ok';
+}
+/** Markers in the subject's own block for states that don't apply to it, leaving out work comments. */
+export function strayMarkers(subject, options) {
+    return subject.markers
+        .filter(isStateMarker)
+        .filter((m) => !appliesTo(subject, m.state.name) && !isWorkComment(m, options));
+}
+/**
+ * Where to report a problem with a test or describe: from the callee to the end of the title
+ * (`test.skip('pays with PayPal'`), so editors underline the declaration rather than the whole body.
+ * Runtime calls such as `test.skip()` are short, so they are reported whole.
+ */
+export function headLoc(subject) {
+    const { node } = subject;
+    if (subject.kind === 'runtime')
+        return node.loc;
+    const title = node.arguments.length > 1 ? node.arguments[0] : undefined;
+    return { start: node.callee.loc.start, end: (title ?? node.callee).loc.end };
 }
 export function describeSubject(subject) {
     if (subject.kind === 'describe')

package/dist/utils/constants.d.ts

@@ -0,0 +1,10 @@
+/** Marker keywords: uppercase letters, digits, `-` and `_`, starting with a letter. */
+export declare const MARKER_RE: RegExp;
+/** A tag as written in options: `@` followed by letters, digits, `-` and `_`. */
+export declare const TAG_RE: RegExp;
+export declare const BUILTIN_STATE_NAMES: readonly ["skip", "fixme", "fail", "slow", "new", "unstable"];
+export type BuiltinStateName = (typeof BUILTIN_STATE_NAMES)[number];
+export declare const TICKET_PRESETS: readonly ["any", "jira", "github", "gitlab", "linear", "azure-devops", "numeric", "pattern"];
+/** Comment keywords that must reference a ticket by default (`// TODO: WEB-123`). */
+export declare const DEFAULT_COMMENT_KEYWORDS: string[];
+//# sourceMappingURL=constants.d.ts.map

package/dist/utils/constants.js

@@ -0,0 +1,18 @@
+/** Marker keywords: uppercase letters, digits, `-` and `_`, starting with a letter. */
+export const MARKER_RE = /^[A-Z][A-Z0-9_-]*$/;
+/** A tag as written in options: `@` followed by letters, digits, `-` and `_`. */
+export const TAG_RE = /^@[\w-]+$/;
+export const BUILTIN_STATE_NAMES = ['skip', 'fixme', 'fail', 'slow', 'new', 'unstable'];
+export const TICKET_PRESETS = [
+    'any',
+    'jira',
+    'github',
+    'gitlab',
+    'linear',
+    'azure-devops',
+    'numeric',
+    'pattern',
+];
+/** Comment keywords that must reference a ticket by default (`// TODO: WEB-123`). */
+export const DEFAULT_COMMENT_KEYWORDS = ['FIXME', 'TODO'];
+//# sourceMappingURL=constants.js.map

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

@@ -1,23 +1,28 @@
 import type { TSESLint } from '@typescript-eslint/utils';
 import { type Analysis } from './analyze.js';
-import { type GovernanceOptions, type ResolvedOptions } from './options.js';
+import { type ResolvedOptions } from './options.js';
 export declare const REPO_URL = "https://github.com/Huldoser/eslint-plugin-test-governance";
-export type RuleOptions = [GovernanceOptions?];
+/** Rules take no options of their own: everything is shared through `settings['test-governance']`. */
+export type RuleOptions = [];
 export interface RuleDocs {
     description: string;
     recommended: 'error' | 'warn';
     url: string;
 }
-export type Rule<MessageIds extends string> = TSESLint.RuleModule<MessageIds, RuleOptions, RuleDocs>;
+export type Rule<MessageIds extends string> = TSESLint.RuleModule<MessageIds, RuleOptions, RuleDocs> & {
+    meta: {
+        docs: RuleDocs;
+    };
+};
 export interface RuleDefinition<MessageIds extends string> {
     name: string;
-    meta: Omit<TSESLint.RuleMetaData<MessageIds, RuleDocs, RuleOptions>, 'docs' | 'schema' | 'defaultOptions'> & {
+    meta: Omit<TSESLint.RuleMetaData<MessageIds, RuleDocs>, 'docs' | 'schema' | 'defaultOptions'> & {
         docs: Omit<RuleDocs, 'url'>;
     };
     check(context: Readonly<TSESLint.RuleContext<MessageIds, RuleOptions>>, analysis: Analysis, options: ResolvedOptions): void;
 }
 /**
- * Builds a rule whose options are merged over `settings['test-governance']`.
+ * Builds a rule that reads its options from `settings['test-governance']`.
  * `check` runs once per file with the shared analysis.
  */
 export declare function createRule<MessageIds extends string>(definition: RuleDefinition<MessageIds>): Rule<MessageIds>;

package/dist/utils/create-rule.js

@@ -1,9 +1,8 @@
 import { analyze } from './analyze.js';
 import { resolveOptions } from './options.js';
-import { optionsSchema } from './schema.js';
 export const REPO_URL = 'https://github.com/Huldoser/eslint-plugin-test-governance';
 /**
- * Builds a rule whose options are merged over `settings['test-governance']`.
+ * Builds a rule that reads its options from `settings['test-governance']`.
  * `check` runs once per file with the shared analysis.
  */
 export function createRule(definition) {
@@ -11,11 +10,11 @@ export function createRule(definition) {
         meta: {
             ...definition.meta,
             docs: { ...definition.meta.docs, url: `${REPO_URL}/blob/main/docs/rules/${definition.name}.md` },
-            schema: optionsSchema,
+            schema: [],
         },
         defaultOptions: [],
         create(context) {
-            const options = resolveOptions(context.settings, context.options[0]);
+            const options = resolveOptions(context.settings);
             return {
                 'Program:exit'() {
                     definition.check(context, analyze(context.sourceCode, options), options);

package/dist/utils/errors.d.ts

@@ -0,0 +1,5 @@
+/** A problem with the plugin's options, thrown when the config loads or on the first lint. */
+export declare class ConfigError extends Error {
+    constructor(message: string);
+}
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.js

@@ -0,0 +1,8 @@
+/** A problem with the plugin's options, thrown when the config loads or on the first lint. */
+export class ConfigError extends Error {
+    constructor(message) {
+        super(`eslint-plugin-test-governance: ${message}`);
+        this.name = 'ConfigError';
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/fix.js

@@ -4,6 +4,8 @@ function escapeRegExp(text) {
 /** Range of `keyword` where it is used as a marker (`KEYWORD:`) inside `comment`. */
 export function keywordRange(sourceCode, comment, keyword) {
     const text = sourceCode.getText(comment);
+    // Only called with a keyword that was parsed from this comment, so it always matches.
+    // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- see above
     const match = new RegExp(`(^|[^\\w-])(${escapeRegExp(keyword)})\\s*:`).exec(text);
     const start = comment.range[0] + match.index + match[1].length;
     return [start, start + keyword.length];
@@ -20,13 +22,13 @@ export function removeComment(sourceCode, comment) {
 /** Indentation of the line `comment` starts on. */
 export function indentOf(sourceCode, comment) {
     const line = sourceCode.lines[comment.loc.start.line - 1];
-    return /^\s*/.exec(line)[0];
+    return line.slice(0, line.length - line.trimStart().length);
 }
 /** Range of the `index`-th occurrence of `tag` in the source text of `node`. */
 export function tagRange(sourceCode, node, tag, index) {
     const text = sourceCode.getText(node);
     const re = new RegExp(`(?<![\\w@])${escapeRegExp(tag)}(?![\\w-])`, 'g');
-    const match = [...text.matchAll(re)][index];
+    const match = [...text.matchAll(re)].at(index);
     return match === undefined ? undefined : [node.range[0] + match.index, node.range[0] + match.index + tag.length];
 }
 //# sourceMappingURL=fix.js.map

package/dist/utils/options.d.ts

@@ -1,3 +1,4 @@
+import { type BuiltinStateName } from './constants.js';
 import { type TicketMatcher, type TicketSpec } from './tickets.js';
 export declare const SETTINGS_KEY = "test-governance";
 /** A state override in `states`. `false` turns a state off, `true` turns it on. */
@@ -13,7 +14,7 @@ export interface CustomState {
     marker: string;
     ticket?: TicketSpec | TicketSpec[];
 }
-export type BuiltinStateName = 'skip' | 'fixme' | 'fail' | 'slow' | 'new' | 'unstable';
+export type { BuiltinStateName } from './constants.js';
 /** 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']`. */
@@ -30,20 +31,36 @@ export interface GovernanceOptions {
     requireTicketForConditional?: boolean;
     /** Let blank lines separate a marker from the test it belongs to. */
     allowBlankLine?: boolean;
+    /**
+     * Comment keywords that must start with a ticket anywhere in a test file, e.g. `// TODO: WEB-123`.
+     * Defaults to `{ keywords: ['FIXME', 'TODO'] }`; `false` allows free-form comments.
+     */
+    comments?: false | {
+        keywords?: string[];
+    };
     /** Allow free text after the tickets, e.g. `// SKIP: WEB-1 flaky on CI`. Off by default: details belong in the ticket. */
     allowNotes?: boolean;
     /** Report titles that aren't static text when a tag state is on, because their tags can't be read. */
     reportDynamicTitles?: boolean;
 }
-export interface StateDef {
+export type Modifier = 'skip' | 'fixme' | 'fail' | 'slow';
+interface StateBase {
     name: string;
     marker: string;
-    /** Modifier (`test.skip`) for modifier states. */
-    modifier?: 'skip' | 'fixme' | 'fail' | 'slow';
-    /** Tag (`@new`) for tag states. */
-    tag?: string;
     ticket: TicketMatcher;
 }
+/** A state is entered either through a modifier (`test.skip`) or through a tag (`@new`), never both. */
+export type StateDef = StateBase & ({
+    modifier: Modifier;
+    tag?: undefined;
+} | {
+    tag: string;
+    modifier?: undefined;
+});
+export type TagStateDef = Extract<StateDef, {
+    tag: string;
+}>;
+export declare function isTagState(state: StateDef): state is TagStateDef;
 export interface ResolvedOptions {
     testFunctions: Set<string>;
     states: StateDef[];
@@ -51,25 +68,21 @@ export interface ResolvedOptions {
     allowBlankLine: boolean;
     allowNotes: boolean;
     reportDynamicTitles: boolean;
+    /** Keywords checked by `require-ticket-in-comments`; empty when `comments: false`. */
+    commentKeywords: string[];
+    /**
+     * Keywords that are ordinary work comments as well as markers (`FIXME`, `TODO` and any configured
+     * comment keywords). A `// FIXME: refactor` with no ticket is a work comment, never a stray marker.
+     */
+    workCommentKeywords: Set<string>;
+    /** Ticket format for comments: the shared default format. */
+    commentTicket: TicketMatcher;
 }
-interface BuiltinDef {
-    marker: string;
-    modifier?: StateDef['modifier'];
-    tag?: string;
-    lifecycle?: boolean;
-    enabled: boolean;
-}
-export declare const BUILTIN_STATES: Record<BuiltinStateName, BuiltinDef>;
-export declare const MARKER_RE: RegExp;
-export declare const TAG_RE: RegExp;
-export declare class ConfigError extends Error {
-    constructor(message: string);
-}
+export { ConfigError } from './errors.js';
 /**
- * Merges rule options over `settings['test-governance']` and compiles the result.
- * The result is cached per settings object, so all four rules share one compile.
+ * 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.
  */
-export declare function resolveOptions(settings: unknown, ruleOptions: GovernanceOptions | undefined): ResolvedOptions;
+export declare function resolveOptions(settings: unknown): ResolvedOptions;
 export declare function compileOptions(options: GovernanceOptions): ResolvedOptions;
-export {};
 //# sourceMappingURL=options.d.ts.map