eslint-plugin-test-governance 0.4.0 → 0.5.1

package/dist/utils/analyze.js

@@ -1,5 +1,6 @@
 import { isOtherRunner, RUNTIME_MODIFIERS } from "./frameworks.js";
 const TEST = { kind: 'test', modifiers: [] };
+const DESCRIBE = { kind: 'describe', modifiers: [] };
 /** Modifiers that keep a test from running. */
 const SKIPPING_MODIFIERS = new Set(['skip', 'fixme', 'todo']);
 /** What a step's `TestStepInfo` can do at runtime: `step.skip()`. */
@@ -36,6 +37,7 @@ function memberName(node) {
  */
 function chainOf(node, factories) {
     const path = [];
+    const args = new Map();
     let current = node;
     for (;;) {
         if (current.type === 'MemberExpression') {
@@ -57,9 +59,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;
@@ -170,6 +174,15 @@ function collectTestNames(program, framework, configured) {
                 }
             }
             else if (declarator.id.type === 'ObjectPattern') {
+                // Playwright's `const { describe } = test`, used as `describe.skip(...)`.
+                if (framework.playwright && resolve(init)) {
+                    for (const prop of declarator.id.properties) {
+                        if (prop.type === 'Property' && prop.value.type === 'Identifier' && propertyName(prop) === 'describe') {
+                            roots.set(prop.value.name, DESCRIBE);
+                        }
+                    }
+                    continue;
+                }
                 const source = requireSource(init);
                 if (source === undefined)
                     continue;
@@ -206,8 +219,8 @@ function requireSource(node) {
     return first?.type === 'Literal' && typeof first.value === 'string' ? first.value : undefined;
 }
 /**
- * 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.
+ * Whether `id` refers to a variable or function 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) {
@@ -218,7 +231,7 @@ function isLocalVariable(sourceCode, id) {
         // wraps the module.
         if (scope.block.type === 'Program')
             return false;
-        return variable.defs.some((def) => def.type === 'Variable');
+        return variable.defs.some((def) => def.type === 'Variable' || def.type === 'FunctionName');
     }
     return false;
 }
@@ -301,22 +314,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,67 +339,187 @@ 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 detailsOf(call) {
+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 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);
     }
-    return { tags, dynamic };
+    for (const found of values.texts) {
+        const plain = framework.plainTags ? plainTag(source, found) : undefined;
+        if (plain)
+            tags.push(plain);
+        else
+            scanTags(source, found, tags);
+    }
+    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
- * `test('title', details, fn)`, a static title with a body defined elsewhere, as in
- * `test.skip('pays', payWithCard)`, a describe with only a body, or a `todo` with only a title. A string
- * title tells `test.skip('pays', payWithCard)` apart from a runtime `test.skip(isMobile, 'why')`.
+ * Whether a call declares a test or describe block: a title and a body, as in `test('title', fn)`,
+ * `test('title', details, fn)` or `test.skip(title, payWithCard)` with the body defined elsewhere, a
+ * describe with only a body, or a `todo` with only a title, and in Vitest a `skip` with only a title.
+ * Only Playwright has a runtime `test.skip(isMobile, 'why')`; there a title, written out or held in a
+ * constant, or a body written in place tells the two apart.
  */
-function isDeclaration(kind, args, todo) {
+function isDeclaration(sourceCode, framework, kind, args, members) {
     const first = args.at(0);
     if (isFunction(first))
         return kind === 'describe';
     if (first === undefined)
         return false;
     if (args.length === 1)
-        return todo;
-    return isStaticText(first) || args.slice(1).some(isFunction);
+        return members.includes('todo') || (framework.skipWithoutBody && members.includes('skip'));
+    if (!framework.playwright)
+        return true;
+    const title = unwrap(first);
+    const value = constantValue(sourceCode, title);
+    return isStaticText(title) || (value !== undefined && isStaticText(unwrap(value))) || 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) {
+/**
+ * Whether a runtime call always applies: it has no condition, or `true`, or with `notes` only a note, as
+ * Vitest's `context.skip('Broker sandbox is down')`, and nothing around it makes it conditional.
+ */
+function isUnconditional(call, notes) {
     const first = call.arguments.at(0);
-    return (first === undefined || (first.type === 'Literal' && first.value === true)) && !isGuarded(call);
+    const always = first === undefined || booleanOf(first) === true || (notes && isStaticText(first));
+    return always && !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 +595,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 +610,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 +639,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 +673,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 +683,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 +695,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 +734,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) };
@@ -593,10 +756,14 @@ function runAnalysis(sourceCode, options) {
         }
         const members = [...root.modifiers, ...path];
         const allowed = kind === 'test' ? framework.testMembers : framework.describeMembers;
-        if (members.every((m) => allowed.has(m)) && isDeclaration(kind, args, members.includes('todo'))) {
+        if (members.every((m) => allowed.has(m)) && isDeclaration(sourceCode, framework, kind, args, members)) {
             // 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 +798,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, framework.skipNotes)]]), 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 +896,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.
@@ -46,6 +55,13 @@ export interface Framework {
         param: number;
         methods: ReadonlySet<string>;
     };
+    /** Whether `skip` with only a title declares a skipped test or describe, as Vitest's `test.skip('title')`. */
+    skipWithoutBody: boolean;
+    /**
+     * Whether a runtime skip with only text always skips, the text being a note, as Vitest's
+     * `context.skip('why')`. In Playwright the first argument is always a condition.
+     */
+    skipNotes: boolean;
     /** Built-in states a test can be put in with this framework. */
     states: ReadonlySet<BuiltinStateName>;
     /** Playwright's own API on `test`: `test.describe`, `test.step`, `test.info()` and runtime `test.skip()`. */

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,7 +29,10 @@ const playwright = {
     ]),
     optionEffects: new Map(),
     tagKey: 'tag',
+    plainTags: false,
     info: { param: 1, methods: RUNTIME_MODIFIERS },
+    skipWithoutBody: false,
+    skipNotes: false,
     states: new Set(['skip', 'fixme', 'fail', 'slow', 'new', 'unstable']),
     playwright: true,
 };
@@ -57,6 +61,9 @@ const jest = {
         ['failing', 'fail'],
     ]),
     optionEffects: new Map(),
+    plainTags: false,
+    skipWithoutBody: false,
+    skipNotes: false,
     states: new Set(['skip', 'todo', 'fail', 'new', 'unstable']),
     playwright: false,
 };
@@ -69,10 +76,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 +92,7 @@ const vitest = {
         ['todo', 'todo'],
         ['fails', 'fail'],
         ['skipIf()', 'skip', true],
-        ['runIf()', 'skip', true],
+        ['runIf()', 'skip', false],
     ]),
     optionEffects: new Map([
         ['skip', 'skip'],
@@ -91,7 +100,10 @@ const vitest = {
         ['fails', 'fail'],
     ]),
     tagKey: 'tags',
+    plainTags: true,
     info: { param: 0, methods: new Set(['skip']) },
+    skipWithoutBody: true,
+    skipNotes: true,
     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,