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.
Files changed (43) hide show
  1. package/CHANGELOG.md +114 -1
  2. package/README.md +202 -83
  3. package/dist/index.d.ts +12 -11
  4. package/dist/index.js +28 -14
  5. package/dist/rules/marker-matches-state.d.ts +0 -1
  6. package/dist/rules/marker-matches-state.js +4 -4
  7. package/dist/rules/no-conflicting-states.d.ts +0 -1
  8. package/dist/rules/no-conflicting-states.js +17 -19
  9. package/dist/rules/no-orphaned-marker.d.ts +0 -1
  10. package/dist/rules/no-orphaned-marker.js +12 -7
  11. package/dist/rules/require-ticket-in-comments.d.ts +0 -1
  12. package/dist/rules/require-ticket-in-comments.js +8 -13
  13. package/dist/rules/require-ticket.d.ts +1 -2
  14. package/dist/rules/require-ticket.js +22 -10
  15. package/dist/utils/analyze.d.ts +29 -12
  16. package/dist/utils/analyze.js +526 -181
  17. package/dist/utils/constants.d.ts +5 -3
  18. package/dist/utils/constants.js +4 -3
  19. package/dist/utils/create-rule.d.ts +7 -8
  20. package/dist/utils/create-rule.js +3 -9
  21. package/dist/utils/distance.d.ts +0 -1
  22. package/dist/utils/distance.js +0 -1
  23. package/dist/utils/errors.d.ts +0 -1
  24. package/dist/utils/errors.js +0 -1
  25. package/dist/utils/fix.d.ts +0 -3
  26. package/dist/utils/fix.js +0 -8
  27. package/dist/utils/frameworks.d.ts +68 -0
  28. package/dist/utils/frameworks.js +108 -0
  29. package/dist/utils/options.d.ts +33 -12
  30. package/dist/utils/options.js +9 -5
  31. package/dist/utils/schema.d.ts +0 -1
  32. package/dist/utils/schema.js +9 -3
  33. package/dist/utils/tickets.d.ts +0 -1
  34. package/dist/utils/tickets.js +3 -3
  35. package/dist/utils/validate.d.ts +4 -1
  36. package/dist/utils/validate.js +9 -4
  37. package/docs/rules/marker-matches-state.md +19 -11
  38. package/docs/rules/no-conflicting-states.md +18 -10
  39. package/docs/rules/no-orphaned-marker.md +59 -18
  40. package/docs/rules/require-ticket-in-comments.md +27 -23
  41. package/docs/rules/require-ticket.md +135 -49
  42. package/docs/upgrading.md +131 -0
  43. 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: WEB-123`). */
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
@@ -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: WEB-123`). */
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
- export type RuleOptions = [];
7
- export interface RuleDocs {
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: Omit<RuleDocs, 'url'>;
18
+ docs: RuleDocs;
19
+ schema: [];
21
20
  };
22
- check(context: Readonly<TSESLint.RuleContext<MessageIds, RuleOptions>>, analysis: Analysis, options: ResolvedOptions): void;
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
- * `check` runs once per file with the shared analysis.
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
- //# sourceMappingURL=create-rule.d.ts.map
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
- * `check` runs once per file with the shared analysis.
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.check(context, analyze(context.sourceCode, options), options);
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
@@ -2,4 +2,3 @@
2
2
  export declare function editDistance(a: string, b: string): number;
3
3
  /** How many edits still count as a typo for a tag of this length (without the `@`). */
4
4
  export declare function typoThreshold(length: number): number;
5
- //# sourceMappingURL=distance.d.ts.map
@@ -20,4 +20,3 @@ export function typoThreshold(length) {
20
20
  return 2;
21
21
  return length >= 5 ? 1 : 0;
22
22
  }
23
- //# sourceMappingURL=distance.js.map
@@ -2,4 +2,3 @@
2
2
  export declare class ConfigError extends Error {
3
3
  constructor(message: string);
4
4
  }
5
- //# sourceMappingURL=errors.d.ts.map
@@ -5,4 +5,3 @@ export class ConfigError extends Error {
5
5
  this.name = 'ConfigError';
6
6
  }
7
7
  }
8
- //# sourceMappingURL=errors.js.map
@@ -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
+ }
@@ -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
- /** Names that are treated as the Playwright `test` function. Defaults to `['test']`. */
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
- /** Tickets that are rejected as placeholders. `*` matches any characters. */
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: WEB-123`.
36
- * Defaults to `{ keywords: ['FIXME', 'TODO'] }`; `false` allows free-form comments.
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: WEB-1 flaky on CI`. Off by default: details belong in the ticket. */
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
- /** Report titles that aren't static text when a tag state is on, because their tags can't be read. */
44
- reportDynamicTitles?: boolean;
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
- reportDynamicTitles: boolean;
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
@@ -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
- if (!enabled)
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
- testFunctions: new Set(options.testFunctions ?? ['test']),
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
- reportDynamicTitles: options.reportDynamicTitles ?? false,
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
@@ -1,4 +1,3 @@
1
1
  import type { Schema } from './validate.ts';
2
2
  /** The shape of `settings['test-governance']`, the options of `configure()`. */
3
3
  export declare const optionsSchema: Schema;
4
- //# sourceMappingURL=schema.d.ts.map
@@ -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
- reportDynamicTitles: { type: 'boolean' },
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
@@ -35,4 +35,3 @@ export interface TicketMatcher {
35
35
  }
36
36
  export declare const DEFAULT_PLACEHOLDERS: string[];
37
37
  export declare function compileTicketSpec(specs: TicketSpec[], placeholders: string[]): TicketMatcher;
38
- //# sourceMappingURL=tickets.d.ts.map
@@ -1,5 +1,5 @@
1
1
  import { ConfigError } from "./errors.js";
2
- export const DEFAULT_PLACEHOLDERS = ['TODO', 'TBD', 'XXX-*', '0', '123', '1234', '12345'];
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
- const JIRA_PATH_RE = /^\/browse\/([A-Z][A-Z0-9_]+-\d+)\/?$/;
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
@@ -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
@@ -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
- const text = toJson(value) ?? String(value);
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] === undefined)
104
- problems.push(`${join(path, key)} is required`);
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