eslint-plugin-test-governance 0.3.1 → 0.5.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +114 -1
- package/README.md +202 -83
- package/dist/index.d.ts +12 -11
- package/dist/index.js +28 -14
- package/dist/rules/marker-matches-state.d.ts +0 -1
- package/dist/rules/marker-matches-state.js +4 -4
- package/dist/rules/no-conflicting-states.d.ts +0 -1
- package/dist/rules/no-conflicting-states.js +17 -19
- package/dist/rules/no-orphaned-marker.d.ts +0 -1
- package/dist/rules/no-orphaned-marker.js +12 -7
- package/dist/rules/require-ticket-in-comments.d.ts +0 -1
- package/dist/rules/require-ticket-in-comments.js +8 -13
- package/dist/rules/require-ticket.d.ts +1 -2
- package/dist/rules/require-ticket.js +22 -10
- package/dist/utils/analyze.d.ts +29 -12
- package/dist/utils/analyze.js +526 -181
- package/dist/utils/constants.d.ts +5 -3
- package/dist/utils/constants.js +4 -3
- package/dist/utils/create-rule.d.ts +7 -8
- package/dist/utils/create-rule.js +3 -9
- package/dist/utils/distance.d.ts +0 -1
- package/dist/utils/distance.js +0 -1
- package/dist/utils/errors.d.ts +0 -1
- package/dist/utils/errors.js +0 -1
- package/dist/utils/fix.d.ts +0 -3
- package/dist/utils/fix.js +0 -8
- package/dist/utils/frameworks.d.ts +68 -0
- package/dist/utils/frameworks.js +108 -0
- package/dist/utils/options.d.ts +33 -12
- package/dist/utils/options.js +9 -5
- package/dist/utils/schema.d.ts +0 -1
- package/dist/utils/schema.js +9 -3
- package/dist/utils/tickets.d.ts +0 -1
- package/dist/utils/tickets.js +3 -3
- package/dist/utils/validate.d.ts +4 -1
- package/dist/utils/validate.js +9 -4
- package/docs/rules/marker-matches-state.md +19 -11
- package/docs/rules/no-conflicting-states.md +18 -10
- package/docs/rules/no-orphaned-marker.md +59 -18
- package/docs/rules/require-ticket-in-comments.md +27 -23
- package/docs/rules/require-ticket.md +135 -49
- package/docs/upgrading.md +131 -0
- package/package.json +5 -4
|
@@ -2,9 +2,11 @@
|
|
|
2
2
|
export declare const MARKER_RE: RegExp;
|
|
3
3
|
/** A tag as written in options: `@` followed by letters, digits, `-` and `_`. */
|
|
4
4
|
export declare const TAG_RE: RegExp;
|
|
5
|
-
export declare const BUILTIN_STATE_NAMES: readonly ["skip", "fixme", "fail", "slow", "new", "unstable"];
|
|
5
|
+
export declare const BUILTIN_STATE_NAMES: readonly ["skip", "fixme", "fail", "slow", "todo", "new", "unstable"];
|
|
6
6
|
export type BuiltinStateName = (typeof BUILTIN_STATE_NAMES)[number];
|
|
7
|
+
/** The test frameworks the rules understand. */
|
|
8
|
+
export declare const FRAMEWORK_NAMES: readonly ["playwright", "jest", "vitest"];
|
|
9
|
+
export type FrameworkName = (typeof FRAMEWORK_NAMES)[number];
|
|
7
10
|
export declare const TICKET_PRESETS: readonly ["any", "jira", "github", "gitlab", "linear", "azure-devops", "numeric", "pattern"];
|
|
8
|
-
/** Comment keywords that must reference a ticket by default (`// TODO:
|
|
11
|
+
/** Comment keywords that must reference a ticket by default (`// TODO: TRADE-123`). */
|
|
9
12
|
export declare const DEFAULT_COMMENT_KEYWORDS: string[];
|
|
10
|
-
//# sourceMappingURL=constants.d.ts.map
|
package/dist/utils/constants.js
CHANGED
|
@@ -2,7 +2,9 @@
|
|
|
2
2
|
export const MARKER_RE = /^[A-Z][A-Z0-9_-]*$/;
|
|
3
3
|
/** A tag as written in options: `@` followed by letters, digits, `-` and `_`. */
|
|
4
4
|
export const TAG_RE = /^@[\w-]+$/;
|
|
5
|
-
export const BUILTIN_STATE_NAMES = ['skip', 'fixme', 'fail', 'slow', 'new', 'unstable'];
|
|
5
|
+
export const BUILTIN_STATE_NAMES = ['skip', 'fixme', 'fail', 'slow', 'todo', 'new', 'unstable'];
|
|
6
|
+
/** The test frameworks the rules understand. */
|
|
7
|
+
export const FRAMEWORK_NAMES = ['playwright', 'jest', 'vitest'];
|
|
6
8
|
export const TICKET_PRESETS = [
|
|
7
9
|
'any',
|
|
8
10
|
'jira',
|
|
@@ -13,6 +15,5 @@ export const TICKET_PRESETS = [
|
|
|
13
15
|
'numeric',
|
|
14
16
|
'pattern',
|
|
15
17
|
];
|
|
16
|
-
/** Comment keywords that must reference a ticket by default (`// TODO:
|
|
18
|
+
/** Comment keywords that must reference a ticket by default (`// TODO: TRADE-123`). */
|
|
17
19
|
export const DEFAULT_COMMENT_KEYWORDS = ['FIXME', 'TODO'];
|
|
18
|
-
//# sourceMappingURL=constants.js.map
|
|
@@ -1,10 +1,9 @@
|
|
|
1
1
|
import type { TSESLint } from '@typescript-eslint/utils';
|
|
2
2
|
import { type Analysis } from './analyze.ts';
|
|
3
3
|
import { type ResolvedOptions } from './options.ts';
|
|
4
|
-
export declare const REPO_URL = "https://github.com/Huldoser/eslint-plugin-test-governance";
|
|
5
4
|
/** Rules take no options of their own: everything is shared through `settings['test-governance']`. */
|
|
6
|
-
|
|
7
|
-
|
|
5
|
+
type RuleOptions = [];
|
|
6
|
+
interface RuleDocs {
|
|
8
7
|
description: string;
|
|
9
8
|
recommended: 'error' | 'warn';
|
|
10
9
|
url: string;
|
|
@@ -15,15 +14,15 @@ export type Rule<MessageIds extends string> = TSESLint.RuleModule<MessageIds, Ru
|
|
|
15
14
|
};
|
|
16
15
|
};
|
|
17
16
|
export interface RuleDefinition<MessageIds extends string> {
|
|
18
|
-
name: string;
|
|
19
17
|
meta: Omit<TSESLint.RuleMetaData<MessageIds, RuleDocs>, 'docs' | 'schema' | 'defaultOptions'> & {
|
|
20
|
-
docs:
|
|
18
|
+
docs: RuleDocs;
|
|
19
|
+
schema: [];
|
|
21
20
|
};
|
|
22
|
-
|
|
21
|
+
create(context: Readonly<TSESLint.RuleContext<MessageIds, RuleOptions>>, analysis: Analysis, options: ResolvedOptions): void;
|
|
23
22
|
}
|
|
24
23
|
/**
|
|
25
24
|
* Builds a rule that reads its options from `settings['test-governance']`.
|
|
26
|
-
* `
|
|
25
|
+
* `create` runs once per file, at the end, with the shared analysis.
|
|
27
26
|
*/
|
|
28
27
|
export declare function createRule<MessageIds extends string>(definition: RuleDefinition<MessageIds>): Rule<MessageIds>;
|
|
29
|
-
|
|
28
|
+
export {};
|
|
@@ -1,26 +1,20 @@
|
|
|
1
1
|
import { analyze } from "./analyze.js";
|
|
2
2
|
import { resolveOptions } from "./options.js";
|
|
3
|
-
export const REPO_URL = 'https://github.com/Huldoser/eslint-plugin-test-governance';
|
|
4
3
|
/**
|
|
5
4
|
* Builds a rule that reads its options from `settings['test-governance']`.
|
|
6
|
-
* `
|
|
5
|
+
* `create` runs once per file, at the end, with the shared analysis.
|
|
7
6
|
*/
|
|
8
7
|
export function createRule(definition) {
|
|
9
8
|
return {
|
|
10
|
-
meta:
|
|
11
|
-
...definition.meta,
|
|
12
|
-
docs: { ...definition.meta.docs, url: `${REPO_URL}/blob/main/docs/rules/${definition.name}.md` },
|
|
13
|
-
schema: [],
|
|
14
|
-
},
|
|
9
|
+
meta: definition.meta,
|
|
15
10
|
defaultOptions: [],
|
|
16
11
|
create(context) {
|
|
17
12
|
const options = resolveOptions(context.settings);
|
|
18
13
|
return {
|
|
19
14
|
'Program:exit'() {
|
|
20
|
-
definition.
|
|
15
|
+
definition.create(context, analyze(context.sourceCode, options), options);
|
|
21
16
|
},
|
|
22
17
|
};
|
|
23
18
|
},
|
|
24
19
|
};
|
|
25
20
|
}
|
|
26
|
-
//# sourceMappingURL=create-rule.js.map
|
package/dist/utils/distance.d.ts
CHANGED
package/dist/utils/distance.js
CHANGED
package/dist/utils/errors.d.ts
CHANGED
package/dist/utils/errors.js
CHANGED
package/dist/utils/fix.d.ts
CHANGED
|
@@ -6,7 +6,4 @@ export declare function keywordRange(sourceCode: SourceCode, comment: TSESTree.C
|
|
|
6
6
|
export declare function removeComment(sourceCode: SourceCode, comment: TSESTree.Comment): TSESLint.RuleFix;
|
|
7
7
|
/** Indentation of the line `comment` starts on. */
|
|
8
8
|
export declare function indentOf(sourceCode: SourceCode, comment: TSESTree.Comment): string;
|
|
9
|
-
/** Range of the `index`-th occurrence of `tag` in the source text of `node`. */
|
|
10
|
-
export declare function tagRange(sourceCode: SourceCode, node: TSESTree.Node, tag: string, index: number): TSESTree.Range | undefined;
|
|
11
9
|
export {};
|
|
12
|
-
//# sourceMappingURL=fix.d.ts.map
|
package/dist/utils/fix.js
CHANGED
|
@@ -24,11 +24,3 @@ export function indentOf(sourceCode, comment) {
|
|
|
24
24
|
const line = sourceCode.lines[comment.loc.start.line - 1];
|
|
25
25
|
return line.slice(0, line.length - line.trimStart().length);
|
|
26
26
|
}
|
|
27
|
-
/** Range of the `index`-th occurrence of `tag` in the source text of `node`. */
|
|
28
|
-
export function tagRange(sourceCode, node, tag, index) {
|
|
29
|
-
const text = sourceCode.getText(node);
|
|
30
|
-
const re = new RegExp(`(?<![\\w@])${escapeRegExp(tag)}(?![\\w-])`, 'g');
|
|
31
|
-
const match = [...text.matchAll(re)].at(index);
|
|
32
|
-
return match === undefined ? undefined : [node.range[0] + match.index, node.range[0] + match.index + tag.length];
|
|
33
|
-
}
|
|
34
|
-
//# sourceMappingURL=fix.js.map
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
import type { BuiltinStateName, FrameworkName } from './constants.ts';
|
|
2
|
+
/** A state a test enters through its own code, as opposed to a tag. */
|
|
3
|
+
export type Modifier = 'skip' | 'fixme' | 'fail' | 'slow' | 'todo';
|
|
4
|
+
/**
|
|
5
|
+
* What a name from a framework stands for: `xit` is a test with `skip`, `suite` a describe block, and
|
|
6
|
+
* Vitest's `beforeEach` a hook whose callback gets the test context.
|
|
7
|
+
*/
|
|
8
|
+
export interface Root {
|
|
9
|
+
kind: 'test' | 'describe' | 'hook';
|
|
10
|
+
modifiers: readonly string[];
|
|
11
|
+
}
|
|
12
|
+
/**
|
|
13
|
+
* The state a member puts a test in. A member called with a condition, like Vitest's `skipIf(...)`, puts it
|
|
14
|
+
* in that state only when the condition is `when`: `skipIf(true)` always skips, `skipIf(false)` never does,
|
|
15
|
+
* and `skipIf(isMobile)` sometimes does.
|
|
16
|
+
*/
|
|
17
|
+
interface Effect {
|
|
18
|
+
modifier: Modifier;
|
|
19
|
+
when?: boolean;
|
|
20
|
+
}
|
|
21
|
+
/** How a test framework declares tests and puts them in states. */
|
|
22
|
+
export interface Framework {
|
|
23
|
+
name: FrameworkName;
|
|
24
|
+
/** Whether `source` is one of the framework's own modules. */
|
|
25
|
+
ownsModule(source: string): boolean;
|
|
26
|
+
/** Test functions the framework's modules export, by exported name. */
|
|
27
|
+
exports: ReadonlyMap<string, Root>;
|
|
28
|
+
/** What a default import from the framework's module is. */
|
|
29
|
+
defaultExport?: Root;
|
|
30
|
+
/** Test functions that exist without an import, besides `testFunctions`. */
|
|
31
|
+
globals: ReadonlyMap<string, Root>;
|
|
32
|
+
/** The default `testFunctions`. */
|
|
33
|
+
testFunctions: readonly string[];
|
|
34
|
+
/**
|
|
35
|
+
* Members a test or describe call may have, as in `test.skip(...)`. A member that is called to build
|
|
36
|
+
* the function, as in `test.each(table)('buys %s', fn)`, is written with parentheses: `each()`.
|
|
37
|
+
*/
|
|
38
|
+
testMembers: ReadonlySet<string>;
|
|
39
|
+
describeMembers: ReadonlySet<string>;
|
|
40
|
+
/** Members that are called to build the function that declares the tests. */
|
|
41
|
+
factories: ReadonlySet<string>;
|
|
42
|
+
/** The state each member puts a test in. */
|
|
43
|
+
effects: ReadonlyMap<string, Effect>;
|
|
44
|
+
/** Keys of an options object that put a test in a state, as in Vitest's `{ skip: true }`. */
|
|
45
|
+
optionEffects: ReadonlyMap<string, Modifier>;
|
|
46
|
+
/** The key of the details or options object that holds tags. */
|
|
47
|
+
tagKey?: string;
|
|
48
|
+
/** Whether that key holds names without their `@`, as Vitest's `tags: ['flaky']`, which stand for `@flaky`. */
|
|
49
|
+
plainTags: boolean;
|
|
50
|
+
/**
|
|
51
|
+
* The parameter of a test's body that can change its state at runtime, such as Playwright's
|
|
52
|
+
* `testInfo` or Vitest's test context, and the methods it has for that.
|
|
53
|
+
*/
|
|
54
|
+
info?: {
|
|
55
|
+
param: number;
|
|
56
|
+
methods: ReadonlySet<string>;
|
|
57
|
+
};
|
|
58
|
+
/** Built-in states a test can be put in with this framework. */
|
|
59
|
+
states: ReadonlySet<BuiltinStateName>;
|
|
60
|
+
/** Playwright's own API on `test`: `test.describe`, `test.step`, `test.info()` and runtime `test.skip()`. */
|
|
61
|
+
playwright: boolean;
|
|
62
|
+
}
|
|
63
|
+
/** Methods on `testInfo` and on `test` itself that change a test's state at runtime. */
|
|
64
|
+
export declare const RUNTIME_MODIFIERS: ReadonlySet<string>;
|
|
65
|
+
export declare const FRAMEWORKS: Record<FrameworkName, Framework>;
|
|
66
|
+
/** Whether `source` belongs to a test runner other than `framework`, so its names are never tests here. */
|
|
67
|
+
export declare function isOtherRunner(framework: Framework, source: string): boolean;
|
|
68
|
+
export {};
|
|
@@ -0,0 +1,108 @@
|
|
|
1
|
+
const TEST = { kind: 'test', modifiers: [] };
|
|
2
|
+
const DESCRIBE = { kind: 'describe', modifiers: [] };
|
|
3
|
+
const HOOK = { kind: 'hook', modifiers: [] };
|
|
4
|
+
const PLAYWRIGHT_MODULES = new Set(['@playwright/test', 'playwright/test']);
|
|
5
|
+
/** Test runners besides Playwright. A name imported from one of them belongs to that runner. */
|
|
6
|
+
const OTHER_RUNNERS = new Set(['vitest', '@jest/globals', 'node:test', 'bun:test', 'mocha', 'ava', 'tap', 'uvu']);
|
|
7
|
+
/** `@playwright/test` and the component-testing packages such as `@playwright/experimental-ct-react`. */
|
|
8
|
+
function isPlaywrightModule(source) {
|
|
9
|
+
return PLAYWRIGHT_MODULES.has(source) || source.startsWith('@playwright/experimental-ct-');
|
|
10
|
+
}
|
|
11
|
+
/** Methods on `testInfo` and on `test` itself that change a test's state at runtime. */
|
|
12
|
+
export const RUNTIME_MODIFIERS = new Set(['skip', 'fixme', 'fail', 'slow']);
|
|
13
|
+
const effects = (entries) => new Map(entries.map(([member, modifier, when]) => [member, { modifier, when }]));
|
|
14
|
+
const playwright = {
|
|
15
|
+
name: 'playwright',
|
|
16
|
+
ownsModule: isPlaywrightModule,
|
|
17
|
+
exports: new Map([['test', TEST]]),
|
|
18
|
+
defaultExport: TEST,
|
|
19
|
+
globals: new Map(),
|
|
20
|
+
testFunctions: ['test'],
|
|
21
|
+
testMembers: new Set(['only', 'skip', 'fixme', 'fail', 'slow']),
|
|
22
|
+
describeMembers: new Set(['only', 'skip', 'fixme', 'serial', 'parallel']),
|
|
23
|
+
factories: new Set(),
|
|
24
|
+
effects: effects([
|
|
25
|
+
['skip', 'skip'],
|
|
26
|
+
['fixme', 'fixme'],
|
|
27
|
+
['fail', 'fail'],
|
|
28
|
+
['slow', 'slow'],
|
|
29
|
+
]),
|
|
30
|
+
optionEffects: new Map(),
|
|
31
|
+
tagKey: 'tag',
|
|
32
|
+
plainTags: false,
|
|
33
|
+
info: { param: 1, methods: RUNTIME_MODIFIERS },
|
|
34
|
+
states: new Set(['skip', 'fixme', 'fail', 'slow', 'new', 'unstable']),
|
|
35
|
+
playwright: true,
|
|
36
|
+
};
|
|
37
|
+
const JEST_FUNCTIONS = new Map([
|
|
38
|
+
['test', TEST],
|
|
39
|
+
['it', TEST],
|
|
40
|
+
['xtest', { kind: 'test', modifiers: ['skip'] }],
|
|
41
|
+
['xit', { kind: 'test', modifiers: ['skip'] }],
|
|
42
|
+
['fit', { kind: 'test', modifiers: ['only'] }],
|
|
43
|
+
['describe', DESCRIBE],
|
|
44
|
+
['xdescribe', { kind: 'describe', modifiers: ['skip'] }],
|
|
45
|
+
['fdescribe', { kind: 'describe', modifiers: ['only'] }],
|
|
46
|
+
]);
|
|
47
|
+
const jest = {
|
|
48
|
+
name: 'jest',
|
|
49
|
+
ownsModule: (source) => source === '@jest/globals',
|
|
50
|
+
exports: JEST_FUNCTIONS,
|
|
51
|
+
globals: new Map([...JEST_FUNCTIONS].filter(([name]) => name !== 'test' && name !== 'it')),
|
|
52
|
+
testFunctions: ['test', 'it'],
|
|
53
|
+
testMembers: new Set(['only', 'skip', 'todo', 'failing', 'concurrent', 'each()']),
|
|
54
|
+
describeMembers: new Set(['only', 'skip', 'each()']),
|
|
55
|
+
factories: new Set(['each']),
|
|
56
|
+
effects: effects([
|
|
57
|
+
['skip', 'skip'],
|
|
58
|
+
['todo', 'todo'],
|
|
59
|
+
['failing', 'fail'],
|
|
60
|
+
]),
|
|
61
|
+
optionEffects: new Map(),
|
|
62
|
+
plainTags: false,
|
|
63
|
+
states: new Set(['skip', 'todo', 'fail', 'new', 'unstable']),
|
|
64
|
+
playwright: false,
|
|
65
|
+
};
|
|
66
|
+
const VITEST_FACTORIES = ['each()', 'for()', 'skipIf()', 'runIf()'];
|
|
67
|
+
const vitest = {
|
|
68
|
+
name: 'vitest',
|
|
69
|
+
ownsModule: (source) => source === 'vitest',
|
|
70
|
+
exports: new Map([
|
|
71
|
+
['test', TEST],
|
|
72
|
+
['it', TEST],
|
|
73
|
+
['describe', DESCRIBE],
|
|
74
|
+
['suite', DESCRIBE],
|
|
75
|
+
['beforeEach', HOOK],
|
|
76
|
+
]),
|
|
77
|
+
globals: new Map([
|
|
78
|
+
['describe', DESCRIBE],
|
|
79
|
+
['suite', DESCRIBE],
|
|
80
|
+
['beforeEach', HOOK],
|
|
81
|
+
]),
|
|
82
|
+
testFunctions: ['test', 'it'],
|
|
83
|
+
testMembers: new Set(['only', 'skip', 'todo', 'fails', 'concurrent', 'sequential', ...VITEST_FACTORIES]),
|
|
84
|
+
describeMembers: new Set(['only', 'skip', 'todo', 'concurrent', 'sequential', 'shuffle', ...VITEST_FACTORIES]),
|
|
85
|
+
factories: new Set(['each', 'for', 'skipIf', 'runIf']),
|
|
86
|
+
effects: effects([
|
|
87
|
+
['skip', 'skip'],
|
|
88
|
+
['todo', 'todo'],
|
|
89
|
+
['fails', 'fail'],
|
|
90
|
+
['skipIf()', 'skip', true],
|
|
91
|
+
['runIf()', 'skip', false],
|
|
92
|
+
]),
|
|
93
|
+
optionEffects: new Map([
|
|
94
|
+
['skip', 'skip'],
|
|
95
|
+
['todo', 'todo'],
|
|
96
|
+
['fails', 'fail'],
|
|
97
|
+
]),
|
|
98
|
+
tagKey: 'tags',
|
|
99
|
+
plainTags: true,
|
|
100
|
+
info: { param: 0, methods: new Set(['skip']) },
|
|
101
|
+
states: new Set(['skip', 'todo', 'fail', 'new', 'unstable']),
|
|
102
|
+
playwright: false,
|
|
103
|
+
};
|
|
104
|
+
export const FRAMEWORKS = { playwright, jest, vitest };
|
|
105
|
+
/** Whether `source` belongs to a test runner other than `framework`, so its names are never tests here. */
|
|
106
|
+
export function isOtherRunner(framework, source) {
|
|
107
|
+
return (isPlaywrightModule(source) || OTHER_RUNNERS.has(source)) && !framework.ownsModule(source);
|
|
108
|
+
}
|
package/dist/utils/options.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
|
-
import { type BuiltinStateName } from './constants.ts';
|
|
1
|
+
import { type BuiltinStateName, type FrameworkName } from './constants.ts';
|
|
2
|
+
import { type Framework, type Modifier } from './frameworks.ts';
|
|
2
3
|
import { type TicketMatcher, type TicketSpec } from './tickets.ts';
|
|
3
4
|
export declare const SETTINGS_KEY = "test-governance";
|
|
4
5
|
/** A state override in `states`. `false` turns a state off, `true` turns it on. */
|
|
@@ -14,36 +15,56 @@ export interface CustomState {
|
|
|
14
15
|
marker: string;
|
|
15
16
|
ticket?: TicketSpec | TicketSpec[];
|
|
16
17
|
}
|
|
17
|
-
export type { BuiltinStateName } from './constants.ts';
|
|
18
18
|
/** Options shared by every rule. Set them once in `settings['test-governance']`. */
|
|
19
19
|
export interface GovernanceOptions {
|
|
20
|
-
/**
|
|
20
|
+
/**
|
|
21
|
+
* The test framework of the files the config applies to: `'playwright'`, `'jest'` or `'vitest'`. Required;
|
|
22
|
+
* `configs.playwright`, `configs.jest` and `configs.vitest` set it.
|
|
23
|
+
*/
|
|
24
|
+
framework: FrameworkName;
|
|
25
|
+
/**
|
|
26
|
+
* Names that are treated as the framework's `test` function. Defaults to `['test']` for Playwright and
|
|
27
|
+
* `['test', 'it']` for Jest and Vitest. Your list replaces the default one, so include those names if
|
|
28
|
+
* you still need them.
|
|
29
|
+
*/
|
|
21
30
|
testFunctions?: string[];
|
|
22
31
|
/** Accepted ticket formats. Defaults to `{ preset: 'any' }`. */
|
|
23
32
|
ticket?: TicketSpec | TicketSpec[];
|
|
24
|
-
/**
|
|
33
|
+
/**
|
|
34
|
+
* Tickets that are rejected as placeholders. `*` matches any characters. Your list replaces the default
|
|
35
|
+
* one (`TODO`, `TBD`, `XXX-*`, ...); tickets numbered 0 are always rejected.
|
|
36
|
+
*/
|
|
25
37
|
placeholders?: string[];
|
|
26
38
|
/** Turns on the `@new` and `@unstable` states. */
|
|
27
39
|
lifecycleTags?: boolean;
|
|
40
|
+
/**
|
|
41
|
+
* Turns built-in states on or off, renames their marker or gives them their own ticket format. `skip`,
|
|
42
|
+
* `fixme` and `todo` are on by default, `fail` and `slow` off; a setting for `new` or `unstable` wins over
|
|
43
|
+
* `lifecycleTags`. `fixme` and `slow` exist only in Playwright and `todo` only in Jest and Vitest.
|
|
44
|
+
*/
|
|
28
45
|
states?: Partial<Record<BuiltinStateName, boolean | StateOverride>>;
|
|
46
|
+
/** Adds a state for a tag, e.g. `{ quarantine: { when: '@quarantine', marker: 'QUARANTINE' } }`. */
|
|
29
47
|
customStates?: Record<string, CustomState>;
|
|
30
48
|
/** Require a ticket for conditional skips such as `test.skip(browserName === 'webkit')`. */
|
|
31
49
|
requireTicketForConditional?: boolean;
|
|
32
50
|
/** Let blank lines separate a marker from the test it belongs to. */
|
|
33
51
|
allowBlankLine?: boolean;
|
|
34
52
|
/**
|
|
35
|
-
* Comment keywords that must start with a ticket anywhere in a test file, e.g. `// TODO:
|
|
36
|
-
* Defaults to `{ keywords: ['FIXME', 'TODO'] }
|
|
53
|
+
* Comment keywords that must start with a ticket anywhere in a test file, e.g. `// TODO: TRADE-123`.
|
|
54
|
+
* Defaults to `{ keywords: ['FIXME', 'TODO'] }`, and your keywords replace those; `false` allows free-form
|
|
55
|
+
* comments.
|
|
37
56
|
*/
|
|
38
57
|
comments?: false | {
|
|
39
58
|
keywords?: string[];
|
|
40
59
|
};
|
|
41
|
-
/** Allow free text after the tickets, e.g. `// SKIP:
|
|
60
|
+
/** Allow free text after the tickets, e.g. `// SKIP: TRADE-1 flaky on CI`. Off by default: details belong in the ticket. */
|
|
42
61
|
allowNotes?: boolean;
|
|
43
|
-
/**
|
|
44
|
-
|
|
62
|
+
/**
|
|
63
|
+
* When a tag state is on, report tags that can't be read: titles that aren't static text, and tags or
|
|
64
|
+
* details objects imported from another module.
|
|
65
|
+
*/
|
|
66
|
+
reportUnreadableTags?: boolean;
|
|
45
67
|
}
|
|
46
|
-
export type Modifier = 'skip' | 'fixme' | 'fail' | 'slow';
|
|
47
68
|
interface StateBase {
|
|
48
69
|
name: string;
|
|
49
70
|
marker: string;
|
|
@@ -62,12 +83,13 @@ export type TagStateDef = Extract<StateDef, {
|
|
|
62
83
|
}>;
|
|
63
84
|
export declare function isTagState(state: StateDef): state is TagStateDef;
|
|
64
85
|
export interface ResolvedOptions {
|
|
86
|
+
framework: Framework;
|
|
65
87
|
testFunctions: Set<string>;
|
|
66
88
|
states: StateDef[];
|
|
67
89
|
requireTicketForConditional: boolean;
|
|
68
90
|
allowBlankLine: boolean;
|
|
69
91
|
allowNotes: boolean;
|
|
70
|
-
|
|
92
|
+
reportUnreadableTags: boolean;
|
|
71
93
|
/** Keywords checked by `require-ticket-in-comments`; empty when `comments: false`. */
|
|
72
94
|
commentKeywords: string[];
|
|
73
95
|
/**
|
|
@@ -85,4 +107,3 @@ export { ConfigError } from './errors.ts';
|
|
|
85
107
|
*/
|
|
86
108
|
export declare function resolveOptions(settings: unknown): ResolvedOptions;
|
|
87
109
|
export declare function compileOptions(options: GovernanceOptions): ResolvedOptions;
|
|
88
|
-
//# sourceMappingURL=options.d.ts.map
|
package/dist/utils/options.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
|
-
import { BUILTIN_STATE_NAMES, DEFAULT_COMMENT_KEYWORDS } from "./constants.js";
|
|
1
|
+
import { BUILTIN_STATE_NAMES, DEFAULT_COMMENT_KEYWORDS, } from "./constants.js";
|
|
2
2
|
import { ConfigError } from "./errors.js";
|
|
3
|
+
import { FRAMEWORKS } from "./frameworks.js";
|
|
3
4
|
import { optionsSchema } from "./schema.js";
|
|
4
5
|
import { compileTicketSpec, DEFAULT_PLACEHOLDERS } from "./tickets.js";
|
|
5
6
|
import { validate } from "./validate.js";
|
|
@@ -12,6 +13,7 @@ const BUILTIN_STATES = {
|
|
|
12
13
|
fixme: { marker: 'FIXME', modifier: 'fixme', enabled: true },
|
|
13
14
|
fail: { marker: 'FAIL', modifier: 'fail', enabled: false },
|
|
14
15
|
slow: { marker: 'SLOW', modifier: 'slow', enabled: false },
|
|
16
|
+
todo: { marker: 'TODO', modifier: 'todo', enabled: true },
|
|
15
17
|
new: { marker: 'NEW', tag: '@new', lifecycle: true, enabled: false },
|
|
16
18
|
unstable: { marker: 'UNSTABLE', tag: '@unstable', lifecycle: true, enabled: false },
|
|
17
19
|
};
|
|
@@ -82,6 +84,7 @@ export function compileOptions(options) {
|
|
|
82
84
|
if (problems.length > 0) {
|
|
83
85
|
throw new ConfigError(`invalid options:\n${problems.map((problem) => ` - ${problem}`).join('\n')}`);
|
|
84
86
|
}
|
|
87
|
+
const framework = FRAMEWORKS[options.framework];
|
|
85
88
|
const placeholders = options.placeholders ?? DEFAULT_PLACEHOLDERS;
|
|
86
89
|
const defaultTicket = toSpecs(options.ticket ?? { preset: 'any' });
|
|
87
90
|
const compile = (spec) => compileTicketSpec(spec === undefined ? defaultTicket : toSpecs(spec), placeholders);
|
|
@@ -92,7 +95,8 @@ export function compileOptions(options) {
|
|
|
92
95
|
const raw = overrides[name];
|
|
93
96
|
const override = typeof raw === 'boolean' ? { enabled: raw } : (raw ?? {});
|
|
94
97
|
const enabled = override.enabled ?? (def.lifecycle ? (options.lifecycleTags ?? def.enabled) : def.enabled);
|
|
95
|
-
|
|
98
|
+
// A state the framework has no way to enter, such as `fixme` in Jest, stays off.
|
|
99
|
+
if (!enabled || !framework.states.has(name))
|
|
96
100
|
continue;
|
|
97
101
|
const base = {
|
|
98
102
|
name,
|
|
@@ -123,15 +127,15 @@ export function compileOptions(options) {
|
|
|
123
127
|
}
|
|
124
128
|
const commentKeywords = options.comments === false ? [] : (options.comments?.keywords ?? DEFAULT_COMMENT_KEYWORDS);
|
|
125
129
|
return {
|
|
126
|
-
|
|
130
|
+
framework,
|
|
131
|
+
testFunctions: new Set(options.testFunctions ?? framework.testFunctions),
|
|
127
132
|
states,
|
|
128
133
|
requireTicketForConditional: options.requireTicketForConditional ?? false,
|
|
129
134
|
allowBlankLine: options.allowBlankLine ?? false,
|
|
130
135
|
allowNotes: options.allowNotes ?? false,
|
|
131
|
-
|
|
136
|
+
reportUnreadableTags: options.reportUnreadableTags ?? false,
|
|
132
137
|
commentKeywords,
|
|
133
138
|
workCommentKeywords: new Set([...DEFAULT_COMMENT_KEYWORDS, ...commentKeywords]),
|
|
134
139
|
commentTicket: defaultMatcher,
|
|
135
140
|
};
|
|
136
141
|
}
|
|
137
|
-
//# sourceMappingURL=options.js.map
|
package/dist/utils/schema.d.ts
CHANGED
package/dist/utils/schema.js
CHANGED
|
@@ -1,9 +1,12 @@
|
|
|
1
|
-
import { BUILTIN_STATE_NAMES, MARKER_RE, TAG_RE, TICKET_PRESETS } from "./constants.js";
|
|
1
|
+
import { BUILTIN_STATE_NAMES, FRAMEWORK_NAMES, MARKER_RE, TAG_RE, TICKET_PRESETS } from "./constants.js";
|
|
2
2
|
const MARKER_HINT = 'an uppercase keyword such as NEEDS-DATA (letters, digits, "-" and "_")';
|
|
3
3
|
const TAG_HINT = 'a tag such as @needs-data';
|
|
4
4
|
/** Jira project and Linear team keys, as they appear in tickets: `WEB` in `WEB-123`. */
|
|
5
5
|
const KEY_PATTERN = '^[A-Z][A-Z0-9_]+$';
|
|
6
6
|
const KEY_HINT = 'an uppercase key as it appears in tickets, such as WEB for WEB-123';
|
|
7
|
+
/** `['"a"', '"b"', '"c"']` as `"a", "b" or "c"`. */
|
|
8
|
+
const orList = (items) => `${items.slice(0, -1).join(', ')} or ${items.slice(-1).join('')}`;
|
|
9
|
+
const FRAMEWORK_HINT = `set it to ${orList(FRAMEWORK_NAMES.map((name) => `"${name}"`))}, or use ${orList(FRAMEWORK_NAMES.map((name) => `configs.${name}`))}`;
|
|
7
10
|
const ticketSpecSchema = {
|
|
8
11
|
type: 'object',
|
|
9
12
|
properties: {
|
|
@@ -40,6 +43,7 @@ const stateOverrideSchema = {
|
|
|
40
43
|
export const optionsSchema = {
|
|
41
44
|
type: 'object',
|
|
42
45
|
properties: {
|
|
46
|
+
framework: { type: 'string', enum: [...FRAMEWORK_NAMES], requiredHint: FRAMEWORK_HINT },
|
|
43
47
|
testFunctions: { type: 'array', items: { type: 'string' } },
|
|
44
48
|
ticket: ticketSchema,
|
|
45
49
|
placeholders: { type: 'array', items: { type: 'string' } },
|
|
@@ -77,8 +81,10 @@ export const optionsSchema = {
|
|
|
77
81
|
requireTicketForConditional: { type: 'boolean' },
|
|
78
82
|
allowBlankLine: { type: 'boolean' },
|
|
79
83
|
allowNotes: { type: 'boolean' },
|
|
80
|
-
|
|
84
|
+
reportUnreadableTags: { type: 'boolean' },
|
|
81
85
|
},
|
|
86
|
+
// Each framework declares and skips tests its own way, so there is no default.
|
|
87
|
+
required: ['framework'],
|
|
82
88
|
additionalProperties: false,
|
|
89
|
+
renamed: { reportDynamicTitles: 'reportUnreadableTags' },
|
|
83
90
|
};
|
|
84
|
-
//# sourceMappingURL=schema.js.map
|
package/dist/utils/tickets.d.ts
CHANGED
package/dist/utils/tickets.js
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { ConfigError } from "./errors.js";
|
|
2
|
-
export const DEFAULT_PLACEHOLDERS = ['TODO', 'TBD', 'XXX-*', '0'
|
|
2
|
+
export const DEFAULT_PLACEHOLDERS = ['TODO', 'TBD', 'XXX-*', '0'];
|
|
3
3
|
// Every pattern below is anchored and has no nested or overlapping quantifiers, so matching is
|
|
4
4
|
// linear in the token length. URLs are parsed with `new URL` rather than a regex.
|
|
5
5
|
const KEY_RE = /^([A-Z][A-Z0-9_]+)-\d+$/;
|
|
@@ -8,7 +8,8 @@ const GITHUB_REF_RE = /^[A-Za-z0-9][A-Za-z0-9-]*\/[\w.-]+#\d+$/;
|
|
|
8
8
|
const GITLAB_REF_RE = /^[\w.-]+(?:\/[\w.-]+)+#\d+$/;
|
|
9
9
|
const AZURE_REF_RE = /^AB#\d+$/;
|
|
10
10
|
const DIGITS_RE = /^\d+$/;
|
|
11
|
-
|
|
11
|
+
// Jira Server and Data Center can run under a path, as in https://issues.example.com/jira/browse/TRADE-1.
|
|
12
|
+
const JIRA_PATH_RE = /\/browse\/([A-Z][A-Z0-9_]+-\d+)\/?$/;
|
|
12
13
|
const GITHUB_PATH_RE = /^\/[^/]+\/[^/]+\/(?:issues|pull)\/\d+\/?$/;
|
|
13
14
|
const GITLAB_PATH_RE = /\/-\/(?:issues|merge_requests|work_items)\/\d+\/?$/;
|
|
14
15
|
const LINEAR_PATH_RE = /^\/[^/]+\/issue\/([A-Z][A-Z0-9]*-\d+)(?:\/[^/]*)?$/;
|
|
@@ -171,4 +172,3 @@ export function compileTicketSpec(specs, placeholders) {
|
|
|
171
172
|
example: presets[0].example,
|
|
172
173
|
};
|
|
173
174
|
}
|
|
174
|
-
//# sourceMappingURL=tickets.js.map
|
package/dist/utils/validate.d.ts
CHANGED
|
@@ -5,6 +5,8 @@ export interface Schema {
|
|
|
5
5
|
pattern?: string;
|
|
6
6
|
/** How to describe `pattern` in messages, e.g. "an uppercase keyword such as NEEDS-DATA". */
|
|
7
7
|
patternHint?: string;
|
|
8
|
+
/** What to tell a user who left out this value when it is required, e.g. which values it takes. */
|
|
9
|
+
requiredHint?: string;
|
|
8
10
|
minimum?: number;
|
|
9
11
|
minItems?: number;
|
|
10
12
|
items?: Schema;
|
|
@@ -12,10 +14,11 @@ export interface Schema {
|
|
|
12
14
|
additionalProperties?: boolean | Schema;
|
|
13
15
|
required?: readonly string[];
|
|
14
16
|
anyOf?: readonly Schema[];
|
|
17
|
+
/** Old property names, with the name each one has now, so a config that uses one says what to change. */
|
|
18
|
+
renamed?: Readonly<Record<string, string>>;
|
|
15
19
|
}
|
|
16
20
|
/**
|
|
17
21
|
* Validates `value` against the subset of JSON Schema that the options schema uses and returns
|
|
18
22
|
* readable problems such as `ticket.preset must be one of "any", "jira", … (got "jria")`.
|
|
19
23
|
*/
|
|
20
24
|
export declare function validate(value: unknown, schema: Schema, path?: string): string[];
|
|
21
|
-
//# sourceMappingURL=validate.d.ts.map
|
package/dist/utils/validate.js
CHANGED
|
@@ -29,7 +29,8 @@ const toJson = JSON.stringify;
|
|
|
29
29
|
function show(value) {
|
|
30
30
|
if (typeof value === 'function')
|
|
31
31
|
return 'a function';
|
|
32
|
-
|
|
32
|
+
// JSON shows a regex as `{}`.
|
|
33
|
+
const text = value instanceof RegExp ? String(value) : (toJson(value) ?? String(value));
|
|
33
34
|
return text.length > 40 ? `${text.slice(0, 37)}...` : text;
|
|
34
35
|
}
|
|
35
36
|
function join(path, key) {
|
|
@@ -100,8 +101,10 @@ export function validate(value, schema, path = '') {
|
|
|
100
101
|
const known = Object.keys(properties);
|
|
101
102
|
const problems = [];
|
|
102
103
|
for (const key of schema.required ?? []) {
|
|
103
|
-
if (object[key]
|
|
104
|
-
|
|
104
|
+
if (object[key] !== undefined)
|
|
105
|
+
continue;
|
|
106
|
+
const hint = properties[key].requiredHint;
|
|
107
|
+
problems.push(`${join(path, key)} is required${hint ? `: ${hint}` : ''}`);
|
|
105
108
|
}
|
|
106
109
|
for (const [key, item] of Object.entries(object)) {
|
|
107
110
|
if (item === undefined)
|
|
@@ -110,6 +113,9 @@ export function validate(value, schema, path = '') {
|
|
|
110
113
|
if (typeof propertySchema === 'object') {
|
|
111
114
|
problems.push(...validate(item, propertySchema, join(path, key)));
|
|
112
115
|
}
|
|
116
|
+
else if (schema.renamed && Object.hasOwn(schema.renamed, key)) {
|
|
117
|
+
problems.push(`${join(path, key)} was renamed to "${schema.renamed[key]}"`);
|
|
118
|
+
}
|
|
113
119
|
else if (propertySchema === false) {
|
|
114
120
|
const hint = suggest(key, known);
|
|
115
121
|
problems.push(`${join(path, key)} is not a known option${hint ? `; did you mean "${hint}"?` : ` (expected one of: ${known.join(', ')})`}`);
|
|
@@ -119,4 +125,3 @@ export function validate(value, schema, path = '') {
|
|
|
119
125
|
}
|
|
120
126
|
return [];
|
|
121
127
|
}
|
|
122
|
-
//# sourceMappingURL=validate.js.map
|