@t0.labs/daxta 0.4.19 → 0.4.21

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/README.md CHANGED
@@ -12,7 +12,7 @@ DAxTA docs — recorded request, response, Try-it
12
12
  | After tests | On the app |
13
13
  | ------------------------------------- | -------------------------------------------------------- |
14
14
  | OpenAPI + HTML from real hits | `/docs` on the same port as Nest |
15
- | Success / validation / auth scenarios | Send + Copy cURL from recorded calls |
15
+ | POSITIVE / INVALID / SEMANTIC / AUTH scenarios | Example picker uses the `when` clause only |
16
16
  | DTO field map (required vs optional) | `DAXTA_DOCS=true|false` gate (like Swagger’s prod check) |
17
17
 
18
18
 
@@ -192,9 +192,16 @@ Suggested titles (method + path, never `:id` as a name):
192
192
 
193
193
  Old `{path} [METHOD] (integration)` still parses. `daxta titles --yes` rewrites to the new form.
194
194
 
195
- - `it()`: `{outcome} when {condition}` — e.g. `creates mock tbs when payload is valid`
196
- - `daxta titles` / `--yes` / `y` / `a` as before
197
- - **Before tests:** install, `daxta test`, and Jest `globalSetup` (TTY). `--yes` / `CI=1` skip questions.
195
+ `it()` keeps a unique sentence; `/docs` examples take the part after `when` (groups match describe: POSITIVE CASES, SEMANTIC ERROR CASES, …):
196
+
197
+ | Layer | Rule | Example |
198
+ | --- | --- | --- |
199
+ | Positive `it()` | `{creates\|returns\|updates\|…} … when {diff}` | `creates mock tbs TRNC record when cyprus payload shape` |
200
+ | Error `it()` | `returns error when {diff}` | `returns error when tax id already exists in mock TBS` |
201
+ | Invalid fields | leave interpolated | `` `${property} - should not be ${description}` `` |
202
+ | Docs / Postman | `{status} — {after when}` | `201 — cyprus payload shape` |
203
+
204
+ `--yes` / `a` rewrite **this case’s own text**, not one shared template. Interpolated `it(\`${…}\`)` is never rewritten.
198
205
 
199
206
  ```bash
200
207
  daxta titles # interactive (y = this recommended, a = all remaining)
@@ -2429,7 +2429,19 @@
2429
2429
 
2430
2430
  const HTTP = ["get", "post", "put", "patch", "delete"];
2431
2431
  const STATUS = { 200: "OK", 201: "Created", 204: "No Content", 400: "Bad Request", 401: "Unauthorized", 404: "Not Found", 409: "Conflict", 422: "Unprocessable Entity" };
2432
- const GROUP_ORDER = ["Success", "Business errors", "Invalid input", "Missing fields", "Auth", "Other"];
2432
+ const GROUP_ORDER = [
2433
+ "POSITIVE CASES",
2434
+ "SEMANTIC ERROR CASES",
2435
+ "INVALID CASES",
2436
+ "OMITTED CASES",
2437
+ "SEMANTIC ERROR CASES - AUTH",
2438
+ "Success",
2439
+ "Business errors",
2440
+ "Invalid input",
2441
+ "Missing fields",
2442
+ "Auth",
2443
+ "Other",
2444
+ ];
2433
2445
  const METHOD_ORDER = { get: 0, post: 1, put: 2, patch: 3, delete: 4 };
2434
2446
 
2435
2447
  const ops = [];
@@ -349,13 +349,7 @@ function securityForHits(opHits) {
349
349
  return [requirement];
350
350
  }
351
351
  function scenarioDisplayName(hit) {
352
- const cas = (0, catalog_1.caseName)(hit.test);
353
- const title = (0, catalog_1.apiTitle)(hit.test);
354
- const style = (0, config_1.getConfig)().exampleLabelStyle ?? 'status-title-case';
355
- if ((style === 'status-title-case' || style === 'full') && title) {
356
- return `${title} — ${cas}`;
357
- }
358
- return cas;
352
+ return (0, catalog_1.docsScenarioClause)((0, catalog_1.caseName)(hit.test));
359
353
  }
360
354
  function toScenario(hit) {
361
355
  return {
@@ -371,7 +365,7 @@ function toScenario(hit) {
371
365
  }
372
366
  function sortScenarios(scenarios) {
373
367
  const groupRank = (group) => {
374
- const order = ['Success', 'Business errors', 'Invalid input', 'Missing fields', 'Auth', 'Other'];
368
+ const order = [...catalog_1.CASE_GROUP_ORDER];
375
369
  const index = order.indexOf(group);
376
370
  return index === -1 ? order.length : index;
377
371
  };
@@ -1,6 +1,6 @@
1
1
  import { type TreeLayout } from '../config';
2
2
  export { parseOperationLabel, suggestOperationTitles, suggestOperationTitleResult, formatTestTitle } from './test-title';
3
- export { isValidItCase, suggestItCases, parseCaseSection, type CaseSection } from './it-case';
3
+ export { isValidItCase, suggestItCases, docsScenarioClause, parseCaseSection, type CaseSection } from './it-case';
4
4
  export type { TreeLayout };
5
5
  export type FieldDoc = {
6
6
  name: string;
@@ -32,6 +32,7 @@ export declare function viewerTreeConfig(): {
32
32
  };
33
33
  export declare function operationTag(pathTemplate: string, method: string): string;
34
34
  export declare function defaultTitle(method: string, pathTemplate: string): string;
35
+ export declare const CASE_GROUP_ORDER: string[];
35
36
  export declare function caseGroup(test?: string): string;
36
37
  export declare function caseSectionLabel(test?: string): string;
37
38
  /**
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.STATUS_TEXT = exports.parseCaseSection = exports.suggestItCases = exports.isValidItCase = exports.formatTestTitle = exports.suggestOperationTitleResult = exports.suggestOperationTitles = exports.parseOperationLabel = void 0;
3
+ exports.CASE_GROUP_ORDER = exports.STATUS_TEXT = exports.parseCaseSection = exports.docsScenarioClause = exports.suggestItCases = exports.isValidItCase = exports.formatTestTitle = exports.suggestOperationTitleResult = exports.suggestOperationTitles = exports.parseOperationLabel = void 0;
4
4
  exports.declaredMethods = declaredMethods;
5
5
  exports.pathSegments = pathSegments;
6
6
  exports.treePathSegments = treePathSegments;
@@ -15,15 +15,17 @@ exports.exampleLabel = exampleLabel;
15
15
  exports.operationSummary = operationSummary;
16
16
  const config_1 = require("../config");
17
17
  const test_title_1 = require("./test-title");
18
+ const it_case_1 = require("./it-case");
18
19
  var test_title_2 = require("./test-title");
19
20
  Object.defineProperty(exports, "parseOperationLabel", { enumerable: true, get: function () { return test_title_2.parseOperationLabel; } });
20
21
  Object.defineProperty(exports, "suggestOperationTitles", { enumerable: true, get: function () { return test_title_2.suggestOperationTitles; } });
21
22
  Object.defineProperty(exports, "suggestOperationTitleResult", { enumerable: true, get: function () { return test_title_2.suggestOperationTitleResult; } });
22
23
  Object.defineProperty(exports, "formatTestTitle", { enumerable: true, get: function () { return test_title_2.formatTestTitle; } });
23
- var it_case_1 = require("./it-case");
24
- Object.defineProperty(exports, "isValidItCase", { enumerable: true, get: function () { return it_case_1.isValidItCase; } });
25
- Object.defineProperty(exports, "suggestItCases", { enumerable: true, get: function () { return it_case_1.suggestItCases; } });
26
- Object.defineProperty(exports, "parseCaseSection", { enumerable: true, get: function () { return it_case_1.parseCaseSection; } });
24
+ var it_case_2 = require("./it-case");
25
+ Object.defineProperty(exports, "isValidItCase", { enumerable: true, get: function () { return it_case_2.isValidItCase; } });
26
+ Object.defineProperty(exports, "suggestItCases", { enumerable: true, get: function () { return it_case_2.suggestItCases; } });
27
+ Object.defineProperty(exports, "docsScenarioClause", { enumerable: true, get: function () { return it_case_2.docsScenarioClause; } });
28
+ Object.defineProperty(exports, "parseCaseSection", { enumerable: true, get: function () { return it_case_2.parseCaseSection; } });
27
29
  exports.STATUS_TEXT = {
28
30
  '200': 'OK',
29
31
  '201': 'Created',
@@ -39,6 +41,9 @@ exports.STATUS_TEXT = {
39
41
  const METHOD_ALIASES = {
40
42
  update: ['patch', 'put'],
41
43
  upsert: ['put', 'post', 'patch'],
44
+ insert: ['post'],
45
+ merge: ['post', 'put', 'patch'],
46
+ replace: ['put'],
42
47
  };
43
48
  const CASE_SECTION_RE = /^(POSITIVE CASES|SEMANTIC ERROR CASES(?:\s*-\s*AUTH)?|INVALID CASES|OMITTED(?: FIELD)? CASES)\s+/i;
44
49
  function declaredMethods(test) {
@@ -49,7 +54,7 @@ function declaredMethods(test) {
49
54
  const method = fromLabel.method.toLowerCase();
50
55
  return METHOD_ALIASES[method] ?? [method];
51
56
  }
52
- const declared = test.match(/\[(GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT)\]/i);
57
+ const declared = test.match(new RegExp(`\\[(${test_title_1.HTTP_VERBS})\\]`, 'i'));
53
58
  if (!declared)
54
59
  return null;
55
60
  const method = declared[1].toLowerCase();
@@ -125,19 +130,27 @@ function defaultTitle(method, pathTemplate) {
125
130
  return custom;
126
131
  return pathTemplate;
127
132
  }
133
+ exports.CASE_GROUP_ORDER = [
134
+ 'POSITIVE CASES',
135
+ 'SEMANTIC ERROR CASES',
136
+ 'INVALID CASES',
137
+ 'OMITTED CASES',
138
+ 'SEMANTIC ERROR CASES - AUTH',
139
+ 'Other',
140
+ ];
128
141
  function caseGroup(test) {
129
142
  if (!test)
130
143
  return 'Other';
131
144
  if (/SEMANTIC ERROR CASES\s*-\s*AUTH/i.test(test))
132
- return 'Auth';
145
+ return 'SEMANTIC ERROR CASES - AUTH';
133
146
  if (/POSITIVE CASES/i.test(test))
134
- return 'Success';
147
+ return 'POSITIVE CASES';
135
148
  if (/SEMANTIC ERROR CASES/i.test(test))
136
- return 'Business errors';
149
+ return 'SEMANTIC ERROR CASES';
137
150
  if (/INVALID CASES/i.test(test))
138
- return 'Invalid input';
151
+ return 'INVALID CASES';
139
152
  if (/OMITTED/i.test(test))
140
- return 'Missing fields';
153
+ return 'OMITTED CASES';
141
154
  return 'Other';
142
155
  }
143
156
  function caseSectionLabel(test) {
@@ -157,10 +170,10 @@ function apiTitle(test) {
157
170
  if (fromLabel)
158
171
  return fromLabel;
159
172
  const patterns = [
160
- /^(.+?\bAPI)\s*[-–—]\s*(?:GET|POST|PUT|PATCH|DELETE)\b/i,
173
+ /^(.+?\bAPI)\s*[-–—]\s*(?:GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT|INSERT|MERGE|REPLACE)\b/i,
161
174
  /\]\s*(?:\([^)]*\)\s*)?(.+?\bAPI)\s+(?:POSITIVE|SEMANTIC|INVALID|OMITTED)\b/i,
162
175
  /^(.+?\bAPI)\s+\/\S+\s+\[(?:GET|POST|PUT|PATCH|DELETE)/i,
163
- /\[(?:GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT)\]\s*(?:\([^)]*\)\s*)?(.+?\bAPI)\b/i,
176
+ new RegExp(`\\[(?:${test_title_1.HTTP_VERBS})\\]\\s*(?:\\([^)]*\\)\\s*)?(.+?\\bAPI)\\b`, 'i'),
164
177
  ];
165
178
  for (const re of patterns) {
166
179
  const match = test.match(re);
@@ -174,8 +187,8 @@ function caseName(test) {
174
187
  if (!test)
175
188
  return 'example';
176
189
  let rest = test
177
- .replace(/^.+?\s+[—–-]\s+(?:GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT)\s+\S+\s*/i, '')
178
- .replace(/^.*?\[(?:GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT)\]\s*(?:\(integration\))?\s*/i, '')
190
+ .replace(new RegExp(`^.+?\\s+[—–-]\\s+(?:${test_title_1.HTTP_VERBS})\\s+\\S+\\s*`, 'i'), '')
191
+ .replace(new RegExp(`^.*?\\[(?:${test_title_1.HTTP_VERBS})\\]\\s*(?:\\(integration\\))?\\s*`, 'i'), '')
179
192
  .replace(CASE_SECTION_RE, '')
180
193
  .trim();
181
194
  // "Admin Find One Basket By Id API - GET /path POSITIVE CASES returns…"
@@ -193,7 +206,7 @@ function caseName(test) {
193
206
  /** OpenAPI example summary / scenario display name. */
194
207
  function exampleLabel(hit) {
195
208
  const style = (0, config_1.getConfig)().exampleLabelStyle ?? 'status-title-case';
196
- const cas = caseName(hit.test);
209
+ const cas = (0, it_case_1.docsScenarioClause)(caseName(hit.test));
197
210
  const title = apiTitle(hit.test);
198
211
  const method = (hit.method || 'get').toUpperCase();
199
212
  const section = caseSectionLabel(hit.test);
@@ -1,7 +1,26 @@
1
1
  export type CaseSection = 'positive' | 'semantic' | 'invalid' | 'omitted' | 'auth';
2
2
  export declare function parseCaseSection(raw?: string): CaseSection | undefined;
3
+ export declare function isDynamicItName(name?: string): boolean;
4
+ export declare function isGenericItName(name?: string): boolean;
3
5
  export declare function isValidItCase(name?: string): boolean;
4
6
  /**
5
- * Deterministic it() suggestions: `{outcome} when {condition}`.
7
+ * Keep the unique clause from `should …` / existing it() text.
8
+ * Never collapse many cases into one generic sentence.
6
9
  */
7
- export declare function suggestItCases(section: CaseSection | undefined, method?: string, pathTemplate?: string): string[];
10
+ export declare function rewriteItFromOriginal(raw: string, section?: CaseSection, method?: string, pathTemplate?: string): string | undefined;
11
+ /**
12
+ * Docs / Postman example line: the unique condition only.
13
+ * Test keeps `creates mock tbs when cyprus payload shape` → docs `cyprus payload shape`.
14
+ */
15
+ export declare function docsScenarioClause(raw?: string): string;
16
+ export type ItSuggestion = {
17
+ names: string[];
18
+ /** Safe for --yes / `a` — rewritten from this case's own text. */
19
+ auto: boolean;
20
+ };
21
+ /**
22
+ * Prefer a unique rewrite of the current it() name.
23
+ * Generic section templates are never auto-applied.
24
+ */
25
+ export declare function suggestItCases(section: CaseSection | undefined, method?: string, pathTemplate?: string, original?: string): string[];
26
+ export declare function suggestItCaseResult(section: CaseSection | undefined, method?: string, pathTemplate?: string, original?: string): ItSuggestion;
@@ -1,10 +1,28 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
3
  exports.parseCaseSection = parseCaseSection;
4
+ exports.isDynamicItName = isDynamicItName;
5
+ exports.isGenericItName = isGenericItName;
4
6
  exports.isValidItCase = isValidItCase;
7
+ exports.rewriteItFromOriginal = rewriteItFromOriginal;
8
+ exports.docsScenarioClause = docsScenarioClause;
5
9
  exports.suggestItCases = suggestItCases;
10
+ exports.suggestItCaseResult = suggestItCaseResult;
6
11
  const test_title_1 = require("./test-title");
7
- const CASE_START = /^(returns|creates|updates|deletes|lists|rejects|conflicts)\b/i;
12
+ const CASE_START = /^(returns|creates|updates|upserts|inserts|merges|replaces|deletes|lists|rejects|conflicts)\b/i;
13
+ const GENERIC_IT = new Set([
14
+ 'returns resource list when query is valid',
15
+ 'returns resource when payload is valid',
16
+ 'returns resource when request is valid',
17
+ 'rejects when resource already exists',
18
+ 'rejects when payload is invalid',
19
+ 'rejects when a required field is omitted',
20
+ 'rejects when unauthorized',
21
+ 'returns error when resource already exists',
22
+ 'returns error when payload is invalid',
23
+ 'returns error when a required field is omitted',
24
+ 'returns error when unauthorized',
25
+ ]);
8
26
  function parseCaseSection(raw) {
9
27
  if (!raw)
10
28
  return undefined;
@@ -20,13 +38,30 @@ function parseCaseSection(raw) {
20
38
  return 'omitted';
21
39
  return undefined;
22
40
  }
41
+ function isDynamicItName(name) {
42
+ return Boolean(name && /\$\{/.test(name));
43
+ }
44
+ function isGenericItName(name) {
45
+ const value = name?.trim().toLowerCase() ?? '';
46
+ if (GENERIC_IT.has(value))
47
+ return true;
48
+ if (/^rejects when (resource|payload) (already exists|is invalid)$/i.test(value))
49
+ return true;
50
+ if (/^returns error when (resource|payload) (already exists|is invalid)$/i.test(value))
51
+ return true;
52
+ if (/^returns [\w\s]+ list when query is valid$/i.test(value))
53
+ return true;
54
+ if (/^returns resource\b/i.test(value))
55
+ return true;
56
+ return false;
57
+ }
23
58
  function isValidItCase(name) {
24
59
  const value = name?.trim() ?? '';
25
- if (value.length < 12 || value.length > 100)
60
+ if (value.length < 12 || value.length > 120)
26
61
  return false;
27
62
  if (value.startsWith('/'))
28
63
  return false;
29
- if (/\[(GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT)\]/i.test(value))
64
+ if (/\[(GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT|INSERT|MERGE|REPLACE)\]/i.test(value))
30
65
  return false;
31
66
  if (/(POSITIVE CASES|SEMANTIC ERROR CASES|INVALID CASES|OMITTED)/i.test(value))
32
67
  return false;
@@ -36,57 +71,137 @@ function isValidItCase(name) {
36
71
  return false;
37
72
  return true;
38
73
  }
39
- function resourcePhrase(pathTemplate) {
40
- if (!pathTemplate)
41
- return 'resource';
42
- return (0, test_title_1.resourceLabel)(pathTemplate).toLowerCase();
74
+ function stemVerb(raw) {
75
+ const v = raw.toLowerCase().replace(/s$/, '');
76
+ if (v === 'create')
77
+ return 'creates';
78
+ if (v === 'update')
79
+ return 'updates';
80
+ if (v === 'delete')
81
+ return 'deletes';
82
+ if (v === 'insert')
83
+ return 'inserts';
84
+ if (v === 'upsert')
85
+ return 'upserts';
86
+ if (v === 'merge')
87
+ return 'merges';
88
+ if (v === 'replace')
89
+ return 'replaces';
90
+ if (v === 'return')
91
+ return 'returns';
92
+ if (v === 'list')
93
+ return 'lists';
94
+ if (v === 'reject')
95
+ return 'rejects';
96
+ return `${v}s`;
97
+ }
98
+ function outcomeVerb(section, method) {
99
+ if (section === 'auth' || section === 'invalid' || section === 'omitted' || section === 'semantic') {
100
+ return 'returns error';
101
+ }
102
+ const m = (method || 'get').toLowerCase();
103
+ if (m === 'post')
104
+ return 'creates';
105
+ if (m === 'upsert')
106
+ return 'upserts';
107
+ if (m === 'insert')
108
+ return 'inserts';
109
+ if (m === 'merge')
110
+ return 'merges';
111
+ if (m === 'replace')
112
+ return 'replaces';
113
+ if (m === 'delete')
114
+ return 'deletes';
115
+ if (m === 'put' || m === 'patch' || m === 'update')
116
+ return 'updates';
117
+ return 'returns';
118
+ }
119
+ function fitItName(value) {
120
+ let next = value.replace(/\s+/g, ' ').trim().replace(/[.,;:]+$/, '');
121
+ if (next.length > 120) {
122
+ next = next.slice(0, 117).replace(/\s+\S*$/, '').trim();
123
+ }
124
+ if (!isValidItCase(next) || isGenericItName(next))
125
+ return undefined;
126
+ return next;
43
127
  }
44
128
  /**
45
- * Deterministic it() suggestions: `{outcome} when {condition}`.
129
+ * Keep the unique clause from `should …` / existing it() text.
130
+ * Never collapse many cases into one generic sentence.
46
131
  */
47
- function suggestItCases(section, method, pathTemplate) {
48
- const res = resourcePhrase(pathTemplate);
49
- const m = (method || 'get').toLowerCase();
50
- const hasParam = Boolean(pathTemplate?.split('/').some((part) => (0, test_title_1.isPathParam)(part)));
51
- const out = [];
52
- const add = (value) => {
53
- const next = value.replace(/\s+/g, ' ').trim();
54
- if (next && !out.includes(next))
55
- out.push(next);
56
- };
57
- if (section === 'auth') {
58
- add('rejects when unauthorized');
59
- add('rejects when authorization is missing');
60
- return out;
132
+ function rewriteItFromOriginal(raw, section, method, pathTemplate) {
133
+ if (isDynamicItName(raw))
134
+ return undefined;
135
+ let s = raw.trim().replace(/\s+/g, ' ').replace(/[.,;:]+$/, '');
136
+ if (!s)
137
+ return undefined;
138
+ s = s.replace(/^should\s+/i, '');
139
+ const res = pathTemplate ? (0, test_title_1.resourceLabel)(pathTemplate).toLowerCase() : 'resource';
140
+ const outcome = outcomeVerb(section, method);
141
+ s = s
142
+ .replace(/^rejects\s+/i, 'returns error ')
143
+ .replace(/^returns?\s+unauthorized\s+/i, 'returns error ')
144
+ .replace(/^returns?\s+conflict\s+/i, 'returns error ')
145
+ .replace(/^returns?\s+error\s+/i, 'returns error ')
146
+ .replace(/^returns?\s+bad request\s+/i, 'returns error ')
147
+ .replace(/^returns?\s+not found\s+/i, 'returns error ');
148
+ if (/^not\s+/i.test(s)) {
149
+ const beforeWhen = s.replace(/^not\s+/i, '').split(/\bwhen\b/i)[0].trim();
150
+ return fitItName(`${outcome} ${res} when not ${beforeWhen}`);
61
151
  }
62
- if (section === 'invalid') {
63
- add('rejects when payload is invalid');
64
- add(`rejects when ${res} payload is invalid`);
65
- return out;
152
+ const withMatch = s.match(/^(create|update|delete|insert|upsert|merge|replace)s?\s+(.+?)\s+with\s+(.+)$/i);
153
+ if (withMatch) {
154
+ return fitItName(`${stemVerb(withMatch[1])} ${withMatch[2]} when ${withMatch[3]}`);
66
155
  }
67
- if (section === 'omitted') {
68
- add('rejects when a required field is omitted');
69
- add(`rejects when ${res} field is omitted`);
70
- return out;
156
+ if (!/\bwhen\b/i.test(s)) {
157
+ s = s.replace(/\bwith\b/i, 'when');
71
158
  }
72
- if (section === 'semantic') {
73
- add(`rejects when ${res} already exists`);
74
- add(`rejects when ${res} is not found`);
75
- return out;
159
+ if (CASE_START.test(s) && /\bwhen\b/i.test(s))
160
+ return fitItName(s);
161
+ const led = s.match(/^(create|update|delete|insert|upsert|merge|replace|return)s?\s+(.+)$/i);
162
+ if (led) {
163
+ const rest = led[2];
164
+ if (/\bwhen\b/i.test(rest))
165
+ return fitItName(`${stemVerb(led[1])} ${rest}`);
166
+ return fitItName(`${stemVerb(led[1])} ${rest.replace(/\bwith\b/i, 'when')}`);
76
167
  }
77
- // positive / unknown
78
- if (m === 'post')
79
- add(`creates ${res} when payload is valid`);
80
- else if (m === 'delete')
81
- add(`deletes ${res} when it exists`);
82
- else if (m === 'put' || m === 'patch' || m === 'update')
83
- add(`updates ${res} when payload is valid`);
84
- else if (m === 'get' && hasParam)
85
- add(`returns ${res} when found by id`);
86
- else if (m === 'get')
87
- add(`returns ${res} list when query is valid`);
88
- else
89
- add(`returns ${res} when request is valid`);
90
- add(`returns ${res} when payload is valid`);
91
- return out.slice(0, 3);
168
+ if (/\bwhen\b/i.test(s)) {
169
+ if (/^when\s+/i.test(s))
170
+ return fitItName(`${outcome} ${s}`);
171
+ return fitItName(`${outcome} when ${s}`);
172
+ }
173
+ return fitItName(`${outcome} when ${s}`);
174
+ }
175
+ const OUTCOME_PREFIX = /^(returns|creates|updates|upserts|inserts|merges|replaces|deletes|lists|rejects|conflicts)\s+/i;
176
+ /**
177
+ * Docs / Postman example line: the unique condition only.
178
+ * Test keeps `creates mock tbs when cyprus payload shape` → docs `cyprus payload shape`.
179
+ */
180
+ function docsScenarioClause(raw) {
181
+ if (!raw)
182
+ return 'example';
183
+ let s = raw.trim().replace(/\s+/g, ' ');
184
+ const field = s.match(/^([A-Za-z0-9_.]+)\s+-\s+(should not be\s+.+)$/i);
185
+ if (field)
186
+ return `${field[1]} ${field[2]}`.trim();
187
+ const when = s.match(/\bwhen\s+(.+)$/i);
188
+ if (when?.[1])
189
+ return when[1].trim();
190
+ s = s.replace(OUTCOME_PREFIX, '').replace(/^resource\s+/i, '').trim();
191
+ return s || 'example';
192
+ }
193
+ /**
194
+ * Prefer a unique rewrite of the current it() name.
195
+ * Generic section templates are never auto-applied.
196
+ */
197
+ function suggestItCases(section, method, pathTemplate, original) {
198
+ return suggestItCaseResult(section, method, pathTemplate, original).names;
199
+ }
200
+ function suggestItCaseResult(section, method, pathTemplate, original) {
201
+ if (original && isDynamicItName(original))
202
+ return { names: [], auto: false };
203
+ const fromOriginal = original ? rewriteItFromOriginal(original, section, method, pathTemplate) : undefined;
204
+ if (fromOriginal)
205
+ return { names: [fromOriginal], auto: true };
206
+ return { names: [], auto: false };
92
207
  }
@@ -1,3 +1,5 @@
1
+ /** Verbs that appear in TEST_TITLE `[METHOD]` / `— METHOD path`. */
2
+ export declare const HTTP_VERBS = "GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT|INSERT|MERGE|REPLACE";
1
3
  export type ParsedOperationLabel = {
2
4
  title?: string;
3
5
  path: string;
@@ -1,5 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.HTTP_VERBS = void 0;
3
4
  exports.isPathParam = isPathParam;
4
5
  exports.titleCaseToken = titleCaseToken;
5
6
  exports.isHumanOperationTitle = isHumanOperationTitle;
@@ -8,7 +9,9 @@ exports.formatTestTitle = formatTestTitle;
8
9
  exports.resourceLabel = resourceLabel;
9
10
  exports.suggestOperationTitleResult = suggestOperationTitleResult;
10
11
  exports.suggestOperationTitles = suggestOperationTitles;
11
- const METHODS = 'GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT';
12
+ /** Verbs that appear in TEST_TITLE `[METHOD]` / `— METHOD path`. */
13
+ exports.HTTP_VERBS = 'GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT|INSERT|MERGE|REPLACE';
14
+ const METHODS = exports.HTTP_VERBS;
12
15
  const PATH_ONLY_BRACKET_RE = new RegExp(`^(?<path>\\/\\S+)\\s+\\[(?<method>${METHODS})\\](?:\\s+\\(integration\\))?\\s*$`, 'i');
13
16
  const TITLE_BRACKET_RE = new RegExp(`^(?<title>.+?)\\s+(?<path>\\/\\S+)\\s+\\[(?<method>${METHODS})\\](?:\\s+\\(integration\\))?\\s*$`, 'i');
14
17
  /** `Create Mock Tbs — POST /v1/admin/mock-tbs` */
@@ -223,6 +226,22 @@ function parentParam(pathTemplate) {
223
226
  }
224
227
  return undefined;
225
228
  }
229
+ function collectionAll(rest, leafAll) {
230
+ const last = rest[rest.length - 1];
231
+ const prev = rest[rest.length - 2];
232
+ if (prev && /^(items?|entries)$/i.test(last || '')) {
233
+ return `${titleCaseToken(prev)} ${titleCaseToken(last)}`;
234
+ }
235
+ return leafAll;
236
+ }
237
+ function collectionOne(rest, leafOne) {
238
+ const last = rest[rest.length - 1];
239
+ const prev = rest[rest.length - 2];
240
+ if (prev && /^(items?|entries)$/i.test(last || '')) {
241
+ return `${titleCaseToken(prev)} ${titleCaseToken(singularStem(last))}`;
242
+ }
243
+ return leafOne;
244
+ }
226
245
  /**
227
246
  * POST /v1/admin/mock-tbs → Create Mock Tbs
228
247
  * GET /v1/me/branches → Find All Branches
@@ -235,8 +254,8 @@ function suggestOperationTitleResult(method, pathTemplate) {
235
254
  const rest = operationSegments(pathTemplate);
236
255
  const last = lastSegment(pathTemplate);
237
256
  const prev = rest.length >= 2 ? rest[rest.length - 2] : undefined;
238
- const leafAll = last ? titleCaseToken(last) : resourceLabel(pathTemplate);
239
- const leafOne = last ? titleCaseToken(singularStem(last)) : leafAll;
257
+ const leafAll = collectionAll(rest, last ? titleCaseToken(last) : resourceLabel(pathTemplate));
258
+ const leafOne = collectionOne(rest, last ? titleCaseToken(singularStem(last)) : leafAll);
240
259
  const m = method.toLowerCase();
241
260
  const endParam = trailingParam(pathTemplate);
242
261
  const nested = parentParam(pathTemplate);
@@ -311,6 +330,14 @@ function suggestOperationTitleResult(method, pathTemplate) {
311
330
  add(`Find All ${leafAll}`);
312
331
  else if (m === 'post')
313
332
  add(`Create ${leafOne}`);
333
+ else if (m === 'upsert')
334
+ add(`Upsert ${leafAll}`);
335
+ else if (m === 'insert')
336
+ add(`Insert ${leafOne}`);
337
+ else if (m === 'merge')
338
+ add(`Merge ${leafAll}`);
339
+ else if (m === 'replace')
340
+ add(`Replace ${leafOne}`);
314
341
  else if (m === 'delete' && endParam)
315
342
  add(`Delete One ${leafOne} ${byEnd}`);
316
343
  else if (m === 'delete')
@@ -320,7 +347,7 @@ function suggestOperationTitleResult(method, pathTemplate) {
320
347
  else if (m === 'put' || m === 'patch' || m === 'update')
321
348
  add(`Update ${leafAll}`);
322
349
  else
323
- return { titles: out.slice(0, 3), auto: false };
350
+ add(`${titleCaseToken(m)} ${leafAll}`);
324
351
  return { titles: out.slice(0, 3), auto: out.length > 0 };
325
352
  }
326
353
  function suggestOperationTitles(method, pathTemplate) {
@@ -56,6 +56,8 @@ function writeTitle(cwd, finding) {
56
56
  return (0, scan_1.applyTitle)(cwd, finding, name);
57
57
  }
58
58
  function writeIt(cwd, finding) {
59
+ if (!finding.auto)
60
+ return false;
59
61
  const name = finding.suggestions[0];
60
62
  if (!name || !(0, it_case_1.isValidItCase)(name))
61
63
  return false;
@@ -79,6 +81,10 @@ function applyAllRecommended(cwd, titles, cases, fromTitleIndex, fromCaseIndex)
79
81
  }
80
82
  const caseStart = fromTitleIndex < titles.length ? 0 : fromCaseIndex;
81
83
  for (let i = caseStart; i < cases.length; i += 1) {
84
+ if (!cases[i].auto || !cases[i].suggestions[0]) {
85
+ skipped += 1;
86
+ continue;
87
+ }
82
88
  if (writeIt(cwd, cases[i])) {
83
89
  console.log(` ${ui_1.c.mint('✔')} ${cases[i].suggestions[0]} ${ui_1.c.dim(cases[i].file + ':' + cases[i].line)}`);
84
90
  written += 1;
@@ -124,7 +130,9 @@ async function runTitleCheck(options) {
124
130
  }
125
131
  (0, ui_1.banner)('Test naming', 'runs before Jest — docs / Postman labels');
126
132
  console.log(` ${ui_1.c.dim('Title')} Create Mock Tbs — POST /v1/admin/mock-tbs`);
127
- console.log(` ${ui_1.c.dim('it()')} creates mock tbs when payload is valid`);
133
+ console.log(` ${ui_1.c.dim('it()+')} creates mock tbs when cyprus payload shape`);
134
+ console.log(` ${ui_1.c.dim('it()-')} returns error when tax id already exists`);
135
+ console.log(` ${ui_1.c.dim('docs')} 201 — cyprus payload shape`);
128
136
  console.log(` ${ui_1.c.gold(String(total))} to review — ${ui_1.c.ice('y')} one recommended, ${ui_1.c.ice('a')} all remaining, ${ui_1.c.ice('s')} skip.`);
129
137
  let written = 0;
130
138
  let skipped = 0;
package/dist/cli/tree.js CHANGED
@@ -119,11 +119,11 @@ async function pickExampleStyle(current) {
119
119
  console.log('');
120
120
  console.log(` ${ui_1.c.bold('Example / scenario labels')}`);
121
121
  console.log(` ${ui_1.c.ice('1')} status-title-case`);
122
- console.log(` ${ui_1.c.dim('200 — Admin Find One Basket By Id API — returns basket when found')}`);
122
+ console.log(` ${ui_1.c.dim('201 — cyprus payload shape')}`);
123
123
  console.log(` ${ui_1.c.ice('2')} status-case`);
124
- console.log(` ${ui_1.c.dim('200 — returns basket when found')}`);
124
+ console.log(` ${ui_1.c.dim('201 — cyprus payload shape')}`);
125
125
  console.log(` ${ui_1.c.ice('3')} full`);
126
- console.log(` ${ui_1.c.dim('200 — Admin Find… API - GET /v1/admin/baskets/{id} POSITIVE CASES returns…')}`);
126
+ console.log(` ${ui_1.c.dim('201 — Create Mock Tbs - POST /v1/admin/mock-tbs POSITIVE CASES cyprus payload shape')}`);
127
127
  console.log(` ${ui_1.c.ice('4')} keep ${ui_1.c.dim(`(${current})`)}`);
128
128
  const answer = await (0, ui_1.readlineAsk)(` ${ui_1.c.gold('?')} Choose\n ${ui_1.c.ice('›')} `);
129
129
  if (!answer || answer === '4' || /^k(eep)?$/i.test(answer))
package/dist/config.d.ts CHANGED
@@ -39,9 +39,10 @@ export type DaxtaConfig = {
39
39
  treePathOverrides?: Record<string, string[]>;
40
40
  /**
41
41
  * OpenAPI example + scenario labels:
42
- * - status-case → `200 — returns basket when found`
43
- * - status-title-case → `200 — Admin Find One Basket By Id API — returns…`
44
- * - full → `200 — Admin Find… API - GET /v1/admin/baskets/{id} POSITIVE CASES returns…`
42
+ * - status-case → `201 — cyprus payload shape`
43
+ * - status-title-case → `201 — Create Mock Tbs — cyprus payload shape`
44
+ * - full → includes path + POSITIVE CASES + clause
45
+ * Test it() stays `creates mock tbs when cyprus payload shape`; docs take the `when` clause.
45
46
  */
46
47
  exampleLabelStyle?: ExampleLabelStyle;
47
48
  port?: number;
package/dist/index.d.ts CHANGED
@@ -6,5 +6,5 @@ export { dtoRequired, type FieldLocation } from './fields/dto-fields';
6
6
  export { buildFieldsFile, writeFieldsFile, readFieldsFile, type FieldsFile } from './fields/export-fields';
7
7
  export { apiDocs, apiDocsHandler, serveApiDocs, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath, type ApiDocsHandler, type ApiDocsOptions, } from './serve';
8
8
  export { runInteractiveCall, runFileCall, executeCall, type CallValues } from './call';
9
- export { apiTitle, parseOperationLabel, suggestOperationTitles, suggestOperationTitleResult, formatTestTitle, isValidItCase, suggestItCases, type FieldDoc, type OperationDoc, } from './catalog';
9
+ export { apiTitle, parseOperationLabel, suggestOperationTitles, suggestOperationTitleResult, formatTestTitle, isValidItCase, suggestItCases, docsScenarioClause, type FieldDoc, type OperationDoc, } from './catalog';
10
10
  export { installDaxta, type InstallOptions } from './cli/install';
package/dist/index.js CHANGED
@@ -1,6 +1,6 @@
1
1
  "use strict";
2
2
  Object.defineProperty(exports, "__esModule", { value: true });
3
- exports.installDaxta = exports.suggestItCases = exports.isValidItCase = exports.formatTestTitle = exports.suggestOperationTitleResult = exports.suggestOperationTitles = exports.parseOperationLabel = exports.apiTitle = exports.executeCall = exports.runFileCall = exports.runInteractiveCall = exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.serveApiDocs = exports.apiDocsHandler = exports.apiDocs = exports.readFieldsFile = exports.writeFieldsFile = exports.buildFieldsFile = exports.dtoRequired = exports.getHits = exports.clearWorkerHits = exports.flush = exports.install = exports.touchPartialMarker = exports.clearPartialMarker = exports.flushAndRebuild = exports.rebuildFromDisk = exports.loadHits = exports.buildOpenApi = exports.buildDaxtaSpec = exports.normalizeTreeLayout = exports.resolveConfig = exports.getConfig = exports.defineConfig = void 0;
3
+ exports.installDaxta = exports.docsScenarioClause = exports.suggestItCases = exports.isValidItCase = exports.formatTestTitle = exports.suggestOperationTitleResult = exports.suggestOperationTitles = exports.parseOperationLabel = exports.apiTitle = exports.executeCall = exports.runFileCall = exports.runInteractiveCall = exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.serveApiDocs = exports.apiDocsHandler = exports.apiDocs = exports.readFieldsFile = exports.writeFieldsFile = exports.buildFieldsFile = exports.dtoRequired = exports.getHits = exports.clearWorkerHits = exports.flush = exports.install = exports.touchPartialMarker = exports.clearPartialMarker = exports.flushAndRebuild = exports.rebuildFromDisk = exports.loadHits = exports.buildOpenApi = exports.buildDaxtaSpec = exports.normalizeTreeLayout = exports.resolveConfig = exports.getConfig = exports.defineConfig = void 0;
4
4
  var config_1 = require("./config");
5
5
  Object.defineProperty(exports, "defineConfig", { enumerable: true, get: function () { return config_1.defineConfig; } });
6
6
  Object.defineProperty(exports, "getConfig", { enumerable: true, get: function () { return config_1.getConfig; } });
@@ -46,5 +46,6 @@ Object.defineProperty(exports, "suggestOperationTitleResult", { enumerable: true
46
46
  Object.defineProperty(exports, "formatTestTitle", { enumerable: true, get: function () { return catalog_1.formatTestTitle; } });
47
47
  Object.defineProperty(exports, "isValidItCase", { enumerable: true, get: function () { return catalog_1.isValidItCase; } });
48
48
  Object.defineProperty(exports, "suggestItCases", { enumerable: true, get: function () { return catalog_1.suggestItCases; } });
49
+ Object.defineProperty(exports, "docsScenarioClause", { enumerable: true, get: function () { return catalog_1.docsScenarioClause; } });
49
50
  var install_1 = require("./cli/install");
50
51
  Object.defineProperty(exports, "installDaxta", { enumerable: true, get: function () { return install_1.installDaxta; } });
package/dist/path.util.js CHANGED
@@ -10,6 +10,7 @@ exports.pathParamNames = pathParamNames;
10
10
  exports.extractPathParams = extractPathParams;
11
11
  exports.materializePath = materializePath;
12
12
  const config_1 = require("./config");
13
+ const test_title_1 = require("./catalog/test-title");
13
14
  const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
14
15
  const NUMERIC_ID_RE = /^-?\d+(\.\d+)?$/;
15
16
  const TOKENISH_RE = /^[A-Za-z0-9_-]{16,}$/;
@@ -51,7 +52,7 @@ function toOpenApiTemplate(path) {
51
52
  function templateFromTestName(test) {
52
53
  if (!test)
53
54
  return null;
54
- const match = test.match(/^\/?(\S+)\s+\[(?:GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT)\]/i);
55
+ const match = test.match(new RegExp(`^/?(\\S+)\\s+\\[(?:${test_title_1.HTTP_VERBS})\\]`, 'i'));
55
56
  if (!match)
56
57
  return null;
57
58
  const raw = `/${match[1].replace(/^\/+/, '')}`.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}/g, ':$1').replace(/\/+$/, '') || '/';
@@ -28,6 +28,7 @@ export type ItFinding = {
28
28
  path?: string;
29
29
  method?: string;
30
30
  suggestions: string[];
31
+ auto: boolean;
31
32
  };
32
33
  export type NamingReport = {
33
34
  titles: TitleFinding[];
@@ -215,9 +215,14 @@ function scanFileCases(rel, text) {
215
215
  const section = [...describes].reverse().find((entry) => entry.index < index && entry.section)?.section;
216
216
  if (!section)
217
217
  continue;
218
- if ((0, it_case_1.isValidItCase)(body))
218
+ if ((0, it_case_1.isDynamicItName)(body))
219
219
  continue;
220
220
  const label = [...labels].reverse().find((entry) => entry.index < index);
221
+ const suggestion = (0, it_case_1.suggestItCaseResult)(section, label?.method, label?.path, body);
222
+ if (!suggestion.names.length)
223
+ continue;
224
+ if (suggestion.auto && suggestion.names[0] === body.replace(/\s+/g, ' ').trim().replace(/[.,;:]+$/, ''))
225
+ continue;
221
226
  const { line, column } = indexToLineCol(text, index);
222
227
  findings.push({
223
228
  file: rel,
@@ -228,7 +233,8 @@ function scanFileCases(rel, text) {
228
233
  section,
229
234
  path: label?.path,
230
235
  method: label?.method,
231
- suggestions: (0, it_case_1.suggestItCases)(section, label?.method, label?.path),
236
+ suggestions: suggestion.names,
237
+ auto: suggestion.auto,
232
238
  });
233
239
  }
234
240
  return findings;
@@ -277,8 +283,8 @@ function printNamingFindings(report, paint) {
277
283
  // spacer already from titles
278
284
  }
279
285
  console.log('');
280
- console.log(` ${paint.yellow('!')} ${paint.bold(`${report.cases.length} it() case(s) off format`)} ${paint.dim('{outcome} when {condition}')}`);
281
- console.log(` ${paint.dim('Format:')} ${paint.cyan('creates mock tbs when payload is valid')}`);
286
+ console.log(` ${paint.yellow('!')} ${paint.bold(`${report.cases.length} it() case(s) to rewrite`)} ${paint.dim('keep unique when-clause')}`);
287
+ console.log(` ${paint.dim('Positive')} ${paint.cyan('creates … when …')} ${paint.dim('errors')} ${paint.cyan('returns error when …')} ${paint.dim('docs = after when')}`);
282
288
  for (const item of report.cases) {
283
289
  console.log('');
284
290
  console.log(` ${paint.cyan(item.file)}${paint.dim(`:${item.line}:${item.column}`)}`);
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@t0.labs/daxta",
3
- "version": "0.4.19",
3
+ "version": "0.4.21",
4
4
  "description": "DAxTA \u2014 docs from Nest integration traffic + DTO field CLI / Try-it",
5
5
  "license": "MIT",
6
6
  "repository": {