eslint-plugin-test-governance 0.4.0 → 0.5.0

package/dist/utils/analyze.js

@@ -36,6 +36,7 @@ function memberName(node) {
  */
 function chainOf(node, factories) {
     const path = [];
+    const args = new Map();
     let current = node;
     for (;;) {
         if (current.type === 'MemberExpression') {
@@ -57,9 +58,11 @@ function chainOf(node, factories) {
         if (name === undefined || !factories.has(name))
             return undefined;
         path.unshift(`${name}()`);
+        if (current.type === 'CallExpression')
+            args.set(`${name}()`, current.arguments.at(0));
         current = factory.object;
     }
-    return current.type === 'Identifier' ? { root: current, path } : undefined;
+    return current.type === 'Identifier' ? { root: current, path, args } : undefined;
 }
 function unwrap(node) {
     let current = node;
@@ -301,22 +304,22 @@ function parseMarkers(comment, states) {
         if (!match)
             continue;
         const [, keyword, rest] = match;
+        const restOffset = start + match[0].length - rest.length;
         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.ticket) });
             continue;
         }
         const caseOf = states.find((s) => s.marker === keyword.toUpperCase());
         if (caseOf)
-            markers.push({ comment, keyword, caseOf, tickets: [] });
+            markers.push({ comment, keyword, caseOf, ...parseTickets(rest, restOffset, caseOf.ticket) });
     }
     return markers;
 }
-function scanTags(source, node, out) {
+function scanTags(source, { text: node, via }, out) {
     // Each piece of text with where it starts in the source, after its opening quote, backtick or `}`.
     const parts = node.type === 'Literal'
-        ? [{ text: String(node.value), start: node.range[0] + 1 }]
+        ? [{ text: node.value, start: node.range[0] + 1 }]
         : node.quasis.map((quasi) => ({
             // `cooked` is only null in tagged templates, which are never titles.
             // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- see above
@@ -326,47 +329,153 @@ function scanTags(source, node, out) {
     for (const { text, start } of parts) {
         for (const match of text.matchAll(TAG_RE)) {
             const end = match.index + match[0].length;
-            const written = source.slice(start, start + end) === text.slice(0, end);
-            out.push({ tag: match[0], node, ...(written && { range: [start + match.index, start + end] }) });
+            const written = via === undefined && source.slice(start, start + end) === text.slice(0, end);
+            out.push({ tag: match[0], node: via ?? node, ...(written && { range: [start + match.index, start + end] }) });
         }
     }
 }
+const PLAIN_TAG_RE = /^[\w-]+$/;
+/** A Vitest tag name such as `'flaky'` in `tags`, which stands for the `@flaky` tag. */
+function plainTag(source, { text, via }) {
+    if (text.type !== 'Literal' || !PLAIN_TAG_RE.test(text.value))
+        return undefined;
+    const start = text.range[0] + 1;
+    const end = start + text.value.length;
+    const written = via === undefined && source.slice(start, end) === text.value;
+    return { tag: `@${text.value}`, node: via ?? text, plain: true, ...(written && { range: [start, end] }) };
+}
 function isStaticText(node) {
     return (node.type === 'Literal' && typeof node.value === 'string') || node.type === 'TemplateLiteral';
 }
 /**
- * The plain-keyed properties of a test's details or options object, the second argument in
- * `test('title', { tag: '@smoke' }, fn)` or Vitest's `test('title', { skip: true }, fn)`.
+ * The value a `const` or enum declared in this file gives a name: the `'@new'` of `const NEW = '@new'`,
+ * or the enum itself. Undefined for any other name, such as an import, a parameter or a `let`.
+ */
+function declaredValue(sourceCode, id) {
+    for (let scope = sourceCode.getScope(id); scope; scope = scope.upper) {
+        const variable = scope.set.get(id.name);
+        if (!variable)
+            continue;
+        // A name declared more than once, as a merged enum, has no single value.
+        if (variable.defs.length !== 1)
+            return undefined;
+        const [def] = variable.defs;
+        if (def.type === 'TSEnumName')
+            return def.node;
+        const declarator = def.type === 'Variable' && def.parent.kind === 'const' ? def.node : undefined;
+        return declarator?.id.type === 'Identifier' ? (declarator.init ?? undefined) : undefined;
+    }
+    return undefined;
+}
+/** The value of the last property called `key`, or undefined when a spread written after it may replace it. */
+function propertyValue(object, key) {
+    for (let i = object.properties.length - 1; i >= 0; i--) {
+        const prop = object.properties[i];
+        if (prop.type === 'SpreadElement')
+            return undefined;
+        if (propertyName(prop) === key)
+            return prop.value;
+    }
+    return undefined;
+}
+/**
+ * What a name or member stands for when it is a constant declared in this file: the `'@new'` of `NEW`
+ * after `const NEW = '@new'`, or of `Tags.NEW` after `const Tags = { NEW: '@new' }` or
+ * `enum Tags { NEW = '@new' }`.
+ */
+function constantValue(sourceCode, node) {
+    if (node.type === 'Identifier')
+        return declaredValue(sourceCode, node);
+    if (node.type !== 'MemberExpression')
+        return undefined;
+    const key = memberName(node);
+    const value = constantValue(sourceCode, unwrap(node.object));
+    const owner = value && unwrap(value);
+    if (key === undefined || owner === undefined)
+        return undefined;
+    if (owner.type === 'ObjectExpression')
+        return propertyValue(owner, key);
+    if (owner.type !== 'TSEnumDeclaration')
+        return undefined;
+    const member = owner.body.members.find((m) => (m.id.type === 'Identifier' ? m.id.name : m.id.value) === key);
+    return member?.initializer;
+}
+/**
+ * Reads the text a title or tag value is made of: strings, template literals and arrays of them,
+ * following constants declared in this file. What can't be read, such as a name imported from another
+ * file, goes in `unread`: the name the call uses, or the value itself.
  */
-function detailsOf(call) {
+function readTexts(sourceCode, node, out, via, path = []) {
+    const target = unwrap(node);
+    if (isStaticText(target)) {
+        out.texts.push({ text: target, via });
+        return;
+    }
+    if (target.type === 'ArrayExpression') {
+        for (const item of target.elements) {
+            if (item)
+                readTexts(sourceCode, item.type === 'SpreadElement' ? item.argument : item, out, via, path);
+        }
+        return;
+    }
+    const value = constantValue(sourceCode, target);
+    // `path` holds the constants already followed, so `const a = b; const b = a;` ends.
+    if (value === undefined || path.includes(value))
+        out.unread.add(via ?? target);
+    else
+        readTexts(sourceCode, value, out, via ?? target, [...path, value]);
+}
+/**
+ * The details or options object of a declaration, the second argument in
+ * `test('title', { tag: '@smoke' }, fn)` or Vitest's `test('title', { skip: true }, fn)`, also when it
+ * is a constant declared in this file.
+ */
+function detailsOf(sourceCode, call) {
     const details = call.arguments.at(1);
-    if (details?.type !== 'ObjectExpression')
-        return [];
-    return details.properties.flatMap((prop) => {
+    if (details === undefined || isFunction(details))
+        return { entries: [] };
+    const target = unwrap(details);
+    const value = target.type === 'ObjectExpression' ? target : constantValue(sourceCode, target);
+    const object = value && unwrap(value);
+    if (object?.type !== 'ObjectExpression') {
+        // A name that can't be read is the details object only when a body comes after it:
+        // `test.skip('places an order', placeOrder)` has a body defined elsewhere and no details.
+        return call.arguments.slice(2).some(isFunction) ? { entries: [], unread: details } : { entries: [] };
+    }
+    const entries = object.properties.flatMap((prop) => {
         if (prop.type !== 'Property' || prop.computed)
             return [];
         const key = prop.key.type === 'Identifier' ? prop.key.name : String(prop.key.value);
         return [[key, prop.value]];
     });
+    return { entries };
 }
-function collectTags(source, call, hasTitle, tagKey) {
-    const tags = [];
+const NO_TAGS = { tags: [], dynamic: false, unread: [], opaqueDetails: false };
+function collectTags(sourceCode, call, hasTitle, framework, details) {
     if (!hasTitle)
-        return { tags, dynamic: false };
-    const [title] = call.arguments;
-    const dynamic = !isStaticText(title);
-    if (!dynamic)
-        scanTags(source, title, tags);
-    for (const [key, value] of detailsOf(call)) {
-        if (key !== tagKey)
-            continue;
-        const values = value.type === 'ArrayExpression' ? value.elements : [value];
-        for (const item of values) {
-            if (item && isStaticText(item))
-                scanTags(source, item, tags);
-        }
+        return NO_TAGS;
+    const source = sourceCode.text;
+    const tags = [];
+    const title = { texts: [], unread: new Set() };
+    readTexts(sourceCode, call.arguments[0], title);
+    for (const found of title.texts)
+        scanTags(source, found, tags);
+    const values = { texts: [], unread: new Set() };
+    for (const [key, value] of details.entries) {
+        if (key === framework.tagKey)
+            readTexts(sourceCode, value, values);
+    }
+    for (const found of values.texts) {
+        const plain = framework.plainTags ? plainTag(source, found) : undefined;
+        if (plain)
+            tags.push(plain);
+        else
+            scanTags(source, found, tags);
     }
-    return { tags, dynamic };
+    const unread = [...values.unread];
+    if (details.unread && framework.tagKey !== undefined)
+        unread.push(details.unread);
+    return { tags, dynamic: title.unread.size > 0, unread, opaqueDetails: details.unread !== undefined };
 }
 /**
  * Whether a call declares a test or describe block: a title and a body, as in `test('title', fn)` or
@@ -384,9 +493,13 @@ function isDeclaration(kind, args, todo) {
         return todo;
     return isStaticText(first) || args.slice(1).some(isFunction);
 }
+/** The value of a `true` or `false` literal; undefined for anything else. */
+function booleanOf(node) {
+    return node?.type === 'Literal' && typeof node.value === 'boolean' ? node.value : undefined;
+}
 function isUnconditional(call) {
     const first = call.arguments.at(0);
-    return (first === undefined || (first.type === 'Literal' && first.value === true)) && !isGuarded(call);
+    return (first === undefined || booleanOf(first) === 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. */
@@ -462,14 +575,14 @@ function runAnalysis(sourceCode, options) {
     const target = (chain) => {
         if (chain === undefined)
             return undefined;
-        const { root, path } = chain;
+        const { root, path, args } = chain;
         let base = testNames.roots.get(root.name);
         let rest = path;
         if (base === undefined && testNames.modules.has(root.name)) {
             base = framework.exports.get(path[0]);
             rest = path.slice(1);
         }
-        return base !== undefined && !isLocalVariable(sourceCode, root) ? { root: base, path: rest } : undefined;
+        return base !== undefined && !isLocalVariable(sourceCode, root) ? { root: base, path: rest, args } : undefined;
     };
     let usesTest = sourceCode.ast.body.some((statement) => statement.type === 'ImportDeclaration' && framework.ownsModule(statement.source.value));
     const subjects = [];
@@ -477,6 +590,8 @@ function runAnalysis(sourceCode, options) {
     const stack = [];
     const infos = [];
     const keys = sourceCode.visitorKeys;
+    /** States an options object can put a test in, such as `skip` for Vitest's `{ skip: true }`. */
+    const optionModifiers = new Set(framework.optionEffects.values());
     /**
      * `modifiers` maps each state modifier the call has to whether it always applies; a conditional one,
      * like `test.skip(isMobile)` or Vitest's `skipIf(...)`, needs a ticket only with `requireTicketForConditional`.
@@ -504,11 +619,21 @@ function runAnalysis(sourceCode, options) {
         }
         const inherited = new Set();
         const inheritedTags = new Set();
+        const unknownStates = new Set();
         if (parent && kind !== 'runtime') {
             for (const name of parent.inherited)
                 inherited.add(name);
             for (const source of parent.states)
                 inherited.add(source.state.name);
+            for (const name of parent.unknownStates)
+                unknownStates.add(name);
+        }
+        for (const state of states) {
+            const unknown = state.modifier === undefined
+                ? tagInfo.unread.length > 0
+                : tagInfo.opaqueDetails && optionModifiers.has(state.modifier);
+            if (unknown)
+                unknownStates.add(state.name);
         }
         // Tags belong to tests: a step in a `@new` test is not itself new.
         if (parent && (kind === 'test' || kind === 'describe')) {
@@ -528,6 +653,8 @@ function runAnalysis(sourceCode, options) {
             runtimeStates: new Set(),
             tags: tagInfo.tags,
             inheritedTags,
+            unreadTags: tagInfo.unread,
+            unknownStates,
             skipped: ownSkip || (kind !== 'runtime' && parent?.skipped === true),
             ownSkip,
             markers: block.flatMap((comment) => parseMarkers(comment, states)),
@@ -536,8 +663,11 @@ function runAnalysis(sourceCode, options) {
         subjects.push(subject);
         return subject;
     };
-    /** The state modifiers of a declaration, from its members and, in Vitest, its options object. */
-    const modifiersOf = (members, call) => {
+    /**
+     * The state modifiers of a declaration, from its members and, in Vitest, its options object. `args`
+     * holds the conditions of members such as `skipIf()`.
+     */
+    const modifiersOf = (members, details, args) => {
         const modifiers = new Map();
         const add = (modifier, always) => {
             if (!modifiers.get(modifier))
@@ -545,13 +675,23 @@ function runAnalysis(sourceCode, options) {
         };
         for (const member of members) {
             const effect = framework.effects.get(member);
-            if (effect)
-                add(effect.modifier, !effect.conditional);
+            if (!effect)
+                continue;
+            if (effect.when === undefined) {
+                add(effect.modifier, true);
+                continue;
+            }
+            // `skipIf(true)` always skips and `skipIf(false)` never does, like `{ skip: true }` and `{ skip: false }`.
+            const condition = booleanOf(args.get(member));
+            if (condition === undefined)
+                add(effect.modifier, false);
+            else if (condition === effect.when)
+                add(effect.modifier, true);
         }
         // `{ skip: true }` always skips, `{ skip: isMobile }` only sometimes, `{ skip: false }` never.
-        for (const [key, value] of detailsOf(call)) {
+        for (const [key, value] of details) {
             const modifier = framework.optionEffects.get(key);
-            const literal = value.type === 'Literal' ? value.value : undefined;
+            const literal = booleanOf(value);
             if (modifier && literal !== false)
                 add(modifier, literal === true);
         }
@@ -574,12 +714,15 @@ function runAnalysis(sourceCode, options) {
         const args = call.arguments;
         const { root } = callee;
         let { path } = callee;
+        // Vitest's `beforeEach((context) => context.skip())` skips the tests it runs before.
+        if (root.kind === 'hook')
+            return { infos: bodyInfos(args, path) };
         if (framework.playwright) {
             // `test.step('fills the order', async (step) => {...})` or `test.step.skip(...)`. The step's body
             // gets a `TestStepInfo` that can skip the step at runtime.
             const step = path.join('.');
             if ((step === 'step' || step === 'step.skip') && args.length >= 2) {
-                const subject = makeSubject('step', call, modifiersOf(path.slice(1), call), { tags: [], dynamic: false });
+                const subject = makeSubject('step', call, modifiersOf(path.slice(1), [], callee.args), NO_TAGS);
                 const body = args[1];
                 const param = isFunction(body) ? body.params.at(0) : undefined;
                 return { subject, infos: infoNames(param, STEP_INFO_METHODS, subject) };
@@ -595,8 +738,12 @@ function runAnalysis(sourceCode, options) {
         const allowed = kind === 'test' ? framework.testMembers : framework.describeMembers;
         if (members.every((m) => allowed.has(m)) && isDeclaration(kind, args, members.includes('todo'))) {
             // A declaration always has a first argument: its title, or the body of a describe without one.
-            const tagInfo = collectTags(sourceCode.text, call, !isFunction(args[0]), framework.tagKey);
-            return { subject: makeSubject(kind, call, modifiersOf(members, call), tagInfo), infos: bodyInfo };
+            const details = detailsOf(sourceCode, call);
+            const tagInfo = collectTags(sourceCode, call, !isFunction(args[0]), framework, details);
+            return {
+                subject: makeSubject(kind, call, modifiersOf(members, details.entries, callee.args), tagInfo),
+                infos: bodyInfo,
+            };
         }
         // test.skip(), test.fixme(), test.fail() and test.slow() in a test, a describe or a hook.
         if (framework.playwright && path.length === 1 && RUNTIME_MODIFIERS.has(path[0])) {
@@ -631,7 +778,7 @@ function runAnalysis(sourceCode, options) {
     const runtimeSubject = (call, modifier, step) => {
         if (!states.some((s) => s.modifier === modifier))
             return undefined;
-        const subject = makeSubject('runtime', call, new Map([[modifier, isUnconditional(call)]]), { tags: [], dynamic: false }, step ?? stack.findLast((s) => s.kind !== 'step'));
+        const subject = makeSubject('runtime', call, new Map([[modifier, isUnconditional(call)]]), NO_TAGS, step ?? stack.findLast((s) => s.kind !== 'step'));
         const parent = subject.parent;
         if (parent) {
             parent.runtimeStates.add(subject.states[0].state.name);
@@ -729,11 +876,18 @@ export function isProse(marker) {
 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. */
+/**
+ * Markers in the subject's own block for states that don't apply to it, leaving out work comments and
+ * states its code may hide, such as a tag from a constant imported from another file. A marker in the
+ * wrong case, as `// skip: TRADE-1`, counts when it starts with a valid ticket.
+ */
 export function strayMarkers(subject, options) {
-    return subject.markers
-        .filter(isStateMarker)
-        .filter((m) => !appliesTo(subject, m.state.name) && !isWorkComment(m, options));
+    return subject.markers.flatMap((marker) => {
+        const state = marker.state ?? (marker.tickets.at(0)?.result === 'ok' ? marker.caseOf : undefined);
+        if (state === undefined || appliesTo(subject, state.name) || subject.unknownStates.has(state.name))
+            return [];
+        return isWorkComment(marker, options) ? [] : [{ ...marker, state }];
+    });
 }
 /**
  * Where to report a problem with a test or describe: from the callee to the end of the title

package/dist/utils/frameworks.d.ts

@@ -1,15 +1,22 @@
 import type { BuiltinStateName, FrameworkName } from './constants.ts';
 /** A state a test enters through its own code, as opposed to a tag. */
 export type Modifier = 'skip' | 'fixme' | 'fail' | 'slow' | 'todo';
-/** What a name from a framework stands for: `xit` is a test with `skip`, `suite` a describe block. */
+/**
+ * What a name from a framework stands for: `xit` is a test with `skip`, `suite` a describe block, and
+ * Vitest's `beforeEach` a hook whose callback gets the test context.
+ */
 export interface Root {
-    kind: 'test' | 'describe';
+    kind: 'test' | 'describe' | 'hook';
     modifiers: readonly string[];
 }
-/** The state a member puts a test in. A conditional one, like Vitest's `skipIf(...)`, may not apply. */
+/**
+ * The state a member puts a test in. A member called with a condition, like Vitest's `skipIf(...)`, puts it
+ * in that state only when the condition is `when`: `skipIf(true)` always skips, `skipIf(false)` never does,
+ * and `skipIf(isMobile)` sometimes does.
+ */
 interface Effect {
     modifier: Modifier;
-    conditional: boolean;
+    when?: boolean;
 }
 /** How a test framework declares tests and puts them in states. */
 export interface Framework {
@@ -38,6 +45,8 @@ export interface Framework {
     optionEffects: ReadonlyMap<string, Modifier>;
     /** The key of the details or options object that holds tags. */
     tagKey?: string;
+    /** Whether that key holds names without their `@`, as Vitest's `tags: ['flaky']`, which stand for `@flaky`. */
+    plainTags: boolean;
     /**
      * The parameter of a test's body that can change its state at runtime, such as Playwright's
      * `testInfo` or Vitest's test context, and the methods it has for that.

package/dist/utils/frameworks.js

@@ -1,5 +1,6 @@
 const TEST = { kind: 'test', modifiers: [] };
 const DESCRIBE = { kind: 'describe', modifiers: [] };
+const HOOK = { kind: 'hook', modifiers: [] };
 const PLAYWRIGHT_MODULES = new Set(['@playwright/test', 'playwright/test']);
 /** Test runners besides Playwright. A name imported from one of them belongs to that runner. */
 const OTHER_RUNNERS = new Set(['vitest', '@jest/globals', 'node:test', 'bun:test', 'mocha', 'ava', 'tap', 'uvu']);
@@ -9,7 +10,7 @@ function isPlaywrightModule(source) {
 }
 /** Methods on `testInfo` and on `test` itself that change a test's state at runtime. */
 export const RUNTIME_MODIFIERS = new Set(['skip', 'fixme', 'fail', 'slow']);
-const effects = (entries) => new Map(entries.map(([member, modifier, conditional = false]) => [member, { modifier, conditional }]));
+const effects = (entries) => new Map(entries.map(([member, modifier, when]) => [member, { modifier, when }]));
 const playwright = {
     name: 'playwright',
     ownsModule: isPlaywrightModule,
@@ -28,6 +29,7 @@ const playwright = {
     ]),
     optionEffects: new Map(),
     tagKey: 'tag',
+    plainTags: false,
     info: { param: 1, methods: RUNTIME_MODIFIERS },
     states: new Set(['skip', 'fixme', 'fail', 'slow', 'new', 'unstable']),
     playwright: true,
@@ -57,6 +59,7 @@ const jest = {
         ['failing', 'fail'],
     ]),
     optionEffects: new Map(),
+    plainTags: false,
     states: new Set(['skip', 'todo', 'fail', 'new', 'unstable']),
     playwright: false,
 };
@@ -69,10 +72,12 @@ const vitest = {
         ['it', TEST],
         ['describe', DESCRIBE],
         ['suite', DESCRIBE],
+        ['beforeEach', HOOK],
     ]),
     globals: new Map([
         ['describe', DESCRIBE],
         ['suite', DESCRIBE],
+        ['beforeEach', HOOK],
     ]),
     testFunctions: ['test', 'it'],
     testMembers: new Set(['only', 'skip', 'todo', 'fails', 'concurrent', 'sequential', ...VITEST_FACTORIES]),
@@ -83,7 +88,7 @@ const vitest = {
         ['todo', 'todo'],
         ['fails', 'fail'],
         ['skipIf()', 'skip', true],
-        ['runIf()', 'skip', true],
+        ['runIf()', 'skip', false],
     ]),
     optionEffects: new Map([
         ['skip', 'skip'],
@@ -91,6 +96,7 @@ const vitest = {
         ['fails', 'fail'],
     ]),
     tagKey: 'tags',
+    plainTags: true,
     info: { param: 0, methods: new Set(['skip']) },
     states: new Set(['skip', 'todo', 'fail', 'new', 'unstable']),
     playwright: false,

package/dist/utils/options.d.ts

@@ -17,8 +17,11 @@ export interface CustomState {
 }
 /** Options shared by every rule. Set them once in `settings['test-governance']`. */
 export interface GovernanceOptions {
-    /** The test framework of the files the config applies to. Defaults to `'playwright'`. */
-    framework?: FrameworkName;
+    /**
+     * The test framework of the files the config applies to: `'playwright'`, `'jest'` or `'vitest'`. Required;
+     * `configs.playwright`, `configs.jest` and `configs.vitest` set it.
+     */
+    framework: FrameworkName;
     /**
      * Names that are treated as the framework's `test` function. Defaults to `['test']` for Playwright and
      * `['test', 'it']` for Jest and Vitest. Your list replaces the default one, so include those names if
@@ -56,8 +59,11 @@ export interface GovernanceOptions {
     };
     /** Allow free text after the tickets, e.g. `// SKIP: TRADE-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;
+    /**
+     * When a tag state is on, report tags that can't be read: titles that aren't static text, and tags or
+     * details objects imported from another module.
+     */
+    reportUnreadableTags?: boolean;
 }
 interface StateBase {
     name: string;
@@ -83,7 +89,7 @@ export interface ResolvedOptions {
     requireTicketForConditional: boolean;
     allowBlankLine: boolean;
     allowNotes: boolean;
-    reportDynamicTitles: boolean;
+    reportUnreadableTags: boolean;
     /** Keywords checked by `require-ticket-in-comments`; empty when `comments: false`. */
     commentKeywords: string[];
     /**

package/dist/utils/options.js

@@ -84,7 +84,7 @@ export function compileOptions(options) {
     if (problems.length > 0) {
         throw new ConfigError(`invalid options:\n${problems.map((problem) => `  - ${problem}`).join('\n')}`);
     }
-    const framework = FRAMEWORKS[options.framework ?? 'playwright'];
+    const framework = FRAMEWORKS[options.framework];
     const placeholders = options.placeholders ?? DEFAULT_PLACEHOLDERS;
     const defaultTicket = toSpecs(options.ticket ?? { preset: 'any' });
     const compile = (spec) => compileTicketSpec(spec === undefined ? defaultTicket : toSpecs(spec), placeholders);
@@ -133,7 +133,7 @@ export function compileOptions(options) {
         requireTicketForConditional: options.requireTicketForConditional ?? false,
         allowBlankLine: options.allowBlankLine ?? false,
         allowNotes: options.allowNotes ?? false,
-        reportDynamicTitles: options.reportDynamicTitles ?? false,
+        reportUnreadableTags: options.reportUnreadableTags ?? false,
         commentKeywords,
         workCommentKeywords: new Set([...DEFAULT_COMMENT_KEYWORDS, ...commentKeywords]),
         commentTicket: defaultMatcher,

package/dist/utils/schema.js

@@ -4,6 +4,9 @@ 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';
+/** `['"a"', '"b"', '"c"']` as `"a", "b" or "c"`. */
+const orList = (items) => `${items.slice(0, -1).join(', ')} or ${items.slice(-1).join('')}`;
+const FRAMEWORK_HINT = `set it to ${orList(FRAMEWORK_NAMES.map((name) => `"${name}"`))}, or use ${orList(FRAMEWORK_NAMES.map((name) => `configs.${name}`))}`;
 const ticketSpecSchema = {
     type: 'object',
     properties: {
@@ -40,7 +43,7 @@ const stateOverrideSchema = {
 export const optionsSchema = {
     type: 'object',
     properties: {
-        framework: { type: 'string', enum: [...FRAMEWORK_NAMES] },
+        framework: { type: 'string', enum: [...FRAMEWORK_NAMES], requiredHint: FRAMEWORK_HINT },
         testFunctions: { type: 'array', items: { type: 'string' } },
         ticket: ticketSchema,
         placeholders: { type: 'array', items: { type: 'string' } },
@@ -78,7 +81,10 @@ export const optionsSchema = {
         requireTicketForConditional: { type: 'boolean' },
         allowBlankLine: { type: 'boolean' },
         allowNotes: { type: 'boolean' },
-        reportDynamicTitles: { type: 'boolean' },
+        reportUnreadableTags: { type: 'boolean' },
     },
+    // Each framework declares and skips tests its own way, so there is no default.
+    required: ['framework'],
     additionalProperties: false,
+    renamed: { reportDynamicTitles: 'reportUnreadableTags' },
 };

package/dist/utils/validate.d.ts

@@ -5,6 +5,8 @@ export interface Schema {
     pattern?: string;
     /** How to describe `pattern` in messages, e.g. "an uppercase keyword such as NEEDS-DATA". */
     patternHint?: string;
+    /** What to tell a user who left out this value when it is required, e.g. which values it takes. */
+    requiredHint?: string;
     minimum?: number;
     minItems?: number;
     items?: Schema;
@@ -12,6 +14,8 @@ export interface Schema {
     additionalProperties?: boolean | Schema;
     required?: readonly string[];
     anyOf?: readonly Schema[];
+    /** Old property names, with the name each one has now, so a config that uses one says what to change. */
+    renamed?: Readonly<Record<string, string>>;
 }
 /**
  * Validates `value` against the subset of JSON Schema that the options schema uses and returns

package/dist/utils/validate.js

@@ -101,8 +101,10 @@ export function validate(value, schema, path = '') {
         const known = Object.keys(properties);
         const problems = [];
         for (const key of schema.required ?? []) {
-            if (object[key] === undefined)
-                problems.push(`${join(path, key)} is required`);
+            if (object[key] !== undefined)
+                continue;
+            const hint = properties[key].requiredHint;
+            problems.push(`${join(path, key)} is required${hint ? `: ${hint}` : ''}`);
         }
         for (const [key, item] of Object.entries(object)) {
             if (item === undefined)
@@ -111,6 +113,9 @@ export function validate(value, schema, path = '') {
             if (typeof propertySchema === 'object') {
                 problems.push(...validate(item, propertySchema, join(path, key)));
             }
+            else if (schema.renamed && Object.hasOwn(schema.renamed, key)) {
+                problems.push(`${join(path, key)} was renamed to "${schema.renamed[key]}"`);
+            }
             else if (propertySchema === false) {
                 const hint = suggest(key, known);
                 problems.push(`${join(path, key)} is not a known option${hint ? `; did you mean "${hint}"?` : ` (expected one of: ${known.join(', ')})`}`);

package/docs/rules/marker-matches-state.md

@@ -2,7 +2,7 @@
 
 📝 Require the marker keyword to match the test's state.
 
-💼 This rule is enabled in the ✅ `recommended` [config](https://github.com/Huldoser/eslint-plugin-test-governance#usage).
+💼 This rule is enabled in the following [configs](https://github.com/Huldoser/eslint-plugin-test-governance#usage): 🃏 `jest`, 🎭 `playwright`, ⚡ `vitest`.
 
 💡 This rule is manually fixable by [editor suggestions](https://eslint.org/docs/latest/use/core-concepts#rule-suggestions).