eslint-plugin-test-governance 0.3.0 → 0.4.0

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

@@ -1,17 +1,17 @@
-import { headLoc } from '../utils/analyze.js';
-import { createRule } from '../utils/create-rule.js';
-import { isTagState } from '../utils/options.js';
-import { editDistance, typoThreshold } from '../utils/distance.js';
-import { tagRange } from '../utils/fix.js';
+import { headLoc } from "../utils/analyze.js";
+import { createRule } from "../utils/create-rule.js";
+import { isTagState } from "../utils/options.js";
+import { editDistance, typoThreshold } from "../utils/distance.js";
 export default createRule({
-    name: 'no-conflicting-states',
     meta: {
         type: 'problem',
-        fixable: 'code',
         docs: {
             description: 'Disallow state tags that contradict each other, differ in case or look like typos',
             recommended: 'warn',
+            url: 'https://github.com/Huldoser/eslint-plugin-test-governance/blob/main/docs/rules/no-conflicting-states.md',
         },
+        fixable: 'code',
+        schema: [],
         messages: {
             newAndUnstable: '`{{new}}` and `{{unstable}}` are separate stages; a test should be in only one of them.',
             newSkipped: "`{{new}}` on a skipped test: a new test that doesn't run can't be promoted. Fix the test or drop the tag.",
@@ -19,19 +19,13 @@ export default createRule({
             tagTypo: '`{{found}}` looks like a typo of `{{expected}}`.',
         },
     },
-    check(context, analysis, options) {
-        const { sourceCode } = context;
+    create(context, analysis, options) {
         const tagStates = options.states.filter(isTagState);
         const newTag = options.states.find((s) => s.name === 'new')?.tag;
         const unstableTag = options.states.find((s) => s.name === 'unstable')?.tag;
         for (const subject of analysis.subjects) {
-            const ownIndex = new Map();
-            for (const occurrence of subject.tags) {
-                const key = `${occurrence.tag}\0${occurrence.node.range[0]}`;
-                const index = ownIndex.get(key) ?? 0;
-                ownIndex.set(key, index + 1);
-                checkSpelling(occurrence, index);
-            }
+            for (const occurrence of subject.tags)
+                checkSpelling(occurrence);
             if (newTag === undefined)
                 continue;
             const own = (tag) => subject.tags.find((t) => t.tag === tag);
@@ -55,14 +49,13 @@ export default createRule({
                 });
             }
         }
-        function checkSpelling(occurrence, index) {
-            const { tag } = occurrence;
+        function checkSpelling(occurrence) {
+            const { tag, range } = occurrence;
             if (tagStates.some((s) => s.tag === tag))
                 return;
             const lower = tag.toLowerCase();
             const sameLetters = tagStates.find((s) => s.tag.toLowerCase() === lower);
             if (sameLetters) {
-                const range = tagRange(sourceCode, occurrence.node, tag, index);
                 context.report({
                     node: occurrence.node,
                     messageId: 'tagCase',
@@ -84,4 +77,3 @@ export default createRule({
         }
     },
 });
-//# sourceMappingURL=no-conflicting-states.js.map

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

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

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

@@ -1,29 +1,30 @@
-import { describeSubject, isProse, missingStates, strayMarkers } from '../utils/analyze.js';
-import { createRule } from '../utils/create-rule.js';
-import { removeComment } from '../utils/fix.js';
+import { describeSubject, isProse, missingStates, strayMarkers } from "../utils/analyze.js";
+import { createRule } from "../utils/create-rule.js";
+import { removeComment } from "../utils/fix.js";
 export default createRule({
-    name: 'no-orphaned-marker',
     meta: {
         type: 'problem',
-        hasSuggestions: true,
         docs: {
             description: 'Disallow marker comments that no longer match a test state',
             recommended: 'error',
+            url: 'https://github.com/Huldoser/eslint-plugin-test-governance/blob/main/docs/rules/no-orphaned-marker.md',
         },
+        hasSuggestions: true,
+        schema: [],
         messages: {
             orphaned: "`{{marker}}:` is left over: {{subject}} is not in the '{{state}}' state.",
             detached: '`{{marker}}:` is not directly above a test, describe or skip call, so it has no effect.',
             removeMarker: 'Remove this comment.',
         },
     },
-    check(context, analysis, options) {
-        // Files without Playwright tests, such as application code, have no markers to check.
+    create(context, analysis, options) {
+        // Files without tests, such as application code, have no markers to check.
         if (!analysis.isTestFile)
             return;
         const { sourceCode } = context;
         const markers = [];
         for (const marker of analysis.detachedMarkers) {
-            // `// FIXME: WEB-12` above a helper is a tracked work comment, checked by require-ticket-in-comments.
+            // `// FIXME: TRADE-12` above a helper is a tracked work comment, checked by require-ticket-in-comments.
             if (options.workCommentKeywords.has(marker.keyword))
                 continue;
             markers.push({ marker, messageId: 'detached', subject: '' });
@@ -33,8 +34,13 @@ export default createRule({
             if (missingStates(subject).length > 0)
                 continue;
             const name = describeSubject(subject).replace(/^This/, 'this');
-            for (const marker of strayMarkers(subject, options))
+            for (const marker of strayMarkers(subject, options)) {
+                // TODO is the everyday work-comment keyword, so `// TODO: TRADE-12` above a test that isn't a todo
+                // is a tracked note about it far more often than a todo test's forgotten marker.
+                if (marker.state.name === 'todo' && options.workCommentKeywords.has(marker.keyword))
+                    continue;
                 markers.push({ marker, messageId: 'orphaned', subject: name });
+            }
         }
         for (const { marker, messageId, subject } of markers) {
             // `// SKIP: this is flaky` is prose, not a leftover ticket.
@@ -49,4 +55,3 @@ export default createRule({
         }
     },
 });
-//# sourceMappingURL=no-orphaned-marker.js.map

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

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

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

@@ -1,20 +1,21 @@
-import { appliesTo, isStateMarker, parseTickets } from '../utils/analyze.js';
-import { createRule } from '../utils/create-rule.js';
-import { compileTicketSpec } from '../utils/tickets.js';
+import { appliesTo, commentLines, isStateMarker, parseTickets } from "../utils/analyze.js";
+import { createRule } from "../utils/create-rule.js";
+import { compileTicketSpec } from "../utils/tickets.js";
 /** Recognises anything shaped like a ticket, to tell a wrong-format ticket from plain prose. */
 const ticketShape = compileTicketSpec([{ preset: 'any' }], []);
 function escapeRegExp(text) {
     return text.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
 export default createRule({
-    name: 'require-ticket-in-comments',
     meta: {
         type: 'suggestion',
-        hasSuggestions: true,
         docs: {
             description: 'Require FIXME and TODO comments in test files to start with a ticket',
             recommended: 'error',
+            url: 'https://github.com/Huldoser/eslint-plugin-test-governance/blob/main/docs/rules/require-ticket-in-comments.md',
         },
+        hasSuggestions: true,
+        schema: [],
         messages: {
             missingTicket: '`{{keyword}}` comments must start with a ticket, e.g. `// {{upper}}: {{example}}`. Put the details in the ticket.',
             invalidTicket: "'{{ticket}}' is not a valid ticket. Expected {{expected}}.",
@@ -23,7 +24,7 @@ export default createRule({
             removeExtraText: 'Remove `{{text}}`.',
         },
     },
-    check(context, analysis, options) {
+    create(context, analysis, options) {
         const keywords = options.commentKeywords;
         if (keywords.length === 0 || !analysis.isTestFile)
             return;
@@ -39,12 +40,12 @@ export default createRule({
         }
         // `TODO`/`FIXME` in capitals counts with or without a colon. Other casings need the colon, so a
         // sentence that happens to start with "Todo" is not mistaken for a work comment. The keyword can
-        // carry its ticket in parentheses, `TODO(WEB-123): ...`, a common style that tools also use for
-        // a name, `TODO(alice)`, which is not a ticket.
+        // carry its ticket in parentheses, `TODO(TRADE-123): ...`, a common style that tools also use for
+        // a name, `TODO(alice)`, which is not a ticket. Some teams put a space before the parenthesis.
         const alternatives = keywords.map(escapeRegExp).join('|');
-        const keywordRe = new RegExp(`^(\\s*\\*?\\s*)(${alternatives})(?:\\(([^)]*)\\))?(?:\\s*:|(?=\\s|$))`, 'i');
+        const keywordRe = new RegExp(`^(\\s*\\*?\\s*)(${alternatives})(?:\\s*\\(([^)]*)\\))?(?:\\s*:|(?=\\s|$))`, 'i');
         /**
-         * `TODO(WEB-1, WEB-2): text`: the tickets are in the parentheses, and anything after them, from the
+         * `TODO(TRADE-1, TRADE-2): text`: the tickets are in the parentheses, and anything after them, from the
          * closing parenthesis on, is a note.
          */
         function parseParenthesized(line, start, open, inParens) {
@@ -61,12 +62,7 @@ export default createRule({
         for (const comment of sourceCode.getAllComments()) {
             if (owned.has(comment))
                 continue;
-            // `//` and `/*` are both two characters, so the comment's value starts two characters in.
-            let lineStart = comment.range[0] + 2;
-            for (const rawLine of comment.value.split('\n')) {
-                const line = rawLine.replace(/\r$/, '');
-                const start = lineStart;
-                lineStart += rawLine.length + 1;
+            for (const { text: line, start } of commentLines(comment)) {
                 const match = keywordRe.exec(line);
                 if (!match)
                     continue;
@@ -78,7 +74,7 @@ export default createRule({
                     continue;
                 const { tickets, extra } = inParens === undefined
                     ? parseTickets(line.slice(whole.length), start + whole.length, matcher)
-                    : parseParenthesized(line, start, indent.length + keyword.length, inParens);
+                    : parseParenthesized(line, start, whole.indexOf('(', indent.length + keyword.length), inParens);
                 const loc = {
                     start: sourceCode.getLocFromIndex(start + indent.length),
                     end: sourceCode.getLocFromIndex(start + line.trimEnd().length),
@@ -114,4 +110,3 @@ export default createRule({
         }
     },
 });
-//# sourceMappingURL=require-ticket-in-comments.js.map

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

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

package/dist/rules/require-ticket.js

@@ -1,14 +1,15 @@
-import { appliesTo, describeSubject, evaluate, headLoc } from '../utils/analyze.js';
-import { createRule } from '../utils/create-rule.js';
+import { appliesTo, describeSubject, evaluate, headLoc } from "../utils/analyze.js";
+import { createRule } from "../utils/create-rule.js";
 export default createRule({
-    name: 'require-ticket',
     meta: {
         type: 'problem',
-        hasSuggestions: true,
         docs: {
             description: 'Require a ticket marker comment above skipped, fixme and tagged tests',
             recommended: 'error',
+            url: 'https://github.com/Huldoser/eslint-plugin-test-governance/blob/main/docs/rules/require-ticket.md',
         },
+        hasSuggestions: true,
+        schema: [],
         messages: {
             missingMarker: "{{subject}} is in the '{{state}}' state but has no `// {{marker}}: <ticket>` comment directly above it, e.g. `// {{marker}}: {{example}}`.",
             missingTicket: '`{{marker}}:` needs a ticket right after the colon, e.g. `// {{marker}}: {{example}}`.',
@@ -20,7 +21,7 @@ export default createRule({
             dynamicTitle: "This title isn't static text, so its tags can't be checked. Use a string or template literal.",
         },
     },
-    check(context, analysis, options) {
+    create(context, analysis, options) {
         const hasTagStates = options.states.some((s) => s.tag !== undefined);
         // A broken marker on a describe can be reached from several tests; report it once.
         const reported = new Set();
@@ -38,7 +39,6 @@ export default createRule({
                     !reportOnce(`${result.marker.comment.range[0]}:${state.name}`)) {
                     continue;
                 }
-                const data = { state: state.name, marker: state.marker, example: state.ticket.example };
                 switch (result.kind) {
                     case 'ok':
                         break;
@@ -46,7 +46,12 @@ export default createRule({
                         context.report({
                             loc: headLoc(subject),
                             messageId: 'missingMarker',
-                            data: { ...data, subject: describeSubject(subject) },
+                            data: {
+                                subject: describeSubject(subject),
+                                state: state.name,
+                                marker: state.marker,
+                                example: state.ticket.example,
+                            },
                         });
                         break;
                     case 'case':
@@ -57,13 +62,17 @@ export default createRule({
                         });
                         break;
                     case 'no-ticket':
-                        context.report({ loc: result.marker.comment.loc, messageId: 'missingTicket', data });
+                        context.report({
+                            loc: result.marker.comment.loc,
+                            messageId: 'missingTicket',
+                            data: { marker: state.marker, example: state.ticket.example },
+                        });
                         break;
                     case 'bad-ticket':
                         context.report({
                             loc: result.marker.comment.loc,
                             messageId: result.ticket.result === 'placeholder' ? 'placeholderTicket' : 'invalidTicket',
-                            data: { ...data, ticket: result.ticket.text, expected: state.ticket.expected },
+                            data: { ticket: result.ticket.text, state: state.name, expected: state.ticket.expected },
                         });
                         break;
                 }
@@ -97,4 +106,3 @@ export default createRule({
         }
     },
 });
-//# sourceMappingURL=require-ticket.js.map

package/dist/utils/analyze.d.ts

@@ -1,10 +1,10 @@
 import type { TSESLint, TSESTree } from '@typescript-eslint/utils';
-import type { ResolvedOptions, StateDef } from './options.js';
-import type { TicketCheck, TicketMatcher } from './tickets.js';
+import type { ResolvedOptions, StateDef } from './options.ts';
+import type { TicketCheck, TicketMatcher } from './tickets.ts';
 type Node = TSESTree.Node;
 type Comment = TSESTree.Comment;
 type SourceCode = Readonly<TSESLint.SourceCode>;
-export interface MarkerTicket {
+interface MarkerTicket {
     text: string;
     result: TicketCheck;
 }
@@ -31,14 +31,19 @@ export declare function isStateMarker(marker: Marker): marker is StateMarker;
 export interface TagOccurrence {
     tag: string;
     node: TSESTree.Literal | TSESTree.TemplateLiteral;
+    /**
+     * Where the tag is written in the source. Unset when an escape such as `\u002D` comes before the
+     * tag or inside it, since the source then no longer lines up with the title.
+     */
+    range?: TSESTree.Range;
 }
-export interface StateSource {
+interface StateSource {
     state: StateDef;
     /** False for conditional skips unless `requireTicketForConditional` is set. */
     required: boolean;
 }
 export interface Subject {
-    kind: 'test' | 'describe' | 'runtime';
+    kind: 'test' | 'describe' | 'step' | 'runtime';
     node: TSESTree.CallExpression;
     /** The node the marker comment block sits above. */
     anchor: Node;
@@ -63,7 +68,7 @@ export interface Analysis {
     subjects: Subject[];
     /** Markers that are not in the comment block of any test, describe or runtime call. */
     detachedMarkers: StateMarker[];
-    /** Whether the file uses Playwright at all: a Playwright import or a call to a test function. */
+    /** Whether the file uses the test framework at all: an import from it or a call to a test function. */
     isTestFile: boolean;
 }
 export type Evaluation = {
@@ -86,6 +91,11 @@ export type Evaluation = {
  * 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'>;
+/** The lines of a comment and where each starts in the source, split at every line break JavaScript has. */
+export declare function commentLines(comment: Comment): {
+    text: string;
+    start: number;
+}[];
 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;
@@ -98,20 +108,13 @@ export declare function missingStates(subject: Subject): StateDef[];
  * 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.
+ * (`test.skip('places a limit order'`), 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