@t0.labs/daxta 0.4.3 → 0.4.5
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 +16 -10
- package/assets/viewer.html +53 -15
- package/dist/build/build-spec.js +16 -7
- package/dist/catalog/index.d.ts +24 -1
- package/dist/catalog/index.js +105 -10
- package/dist/cli/install.js +9 -1
- package/dist/cli/main.js +2 -1
- package/dist/cli/migrate.d.ts +1 -0
- package/dist/cli/migrate.js +1 -0
- package/dist/cli/tree.d.ts +8 -2
- package/dist/cli/tree.js +156 -91
- package/dist/config.d.ts +31 -7
- package/dist/config.js +17 -1
- package/dist/index.d.ts +1 -1
- package/dist/index.js +2 -1
- package/dist/serve/spec-utils.d.ts +5 -0
- package/dist/serve/spec-utils.js +54 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -87,27 +87,33 @@ DAXTA_DOCS=false # no-op (must still be set)
|
|
|
87
87
|
## Commands
|
|
88
88
|
|
|
89
89
|
```bash
|
|
90
|
-
daxta install # one-shot setup
|
|
91
|
-
daxta migrate # after a package bump
|
|
90
|
+
daxta install # one-shot setup (+ sidebar layout prompts)
|
|
91
|
+
daxta migrate # after a package bump (+ same sidebar prompts)
|
|
92
92
|
daxta build # rebuild OpenAPI/HTML from recorded hits
|
|
93
93
|
daxta serve # optional standalone viewer (prefer apiDocs on the app)
|
|
94
|
-
daxta tree #
|
|
94
|
+
daxta tree # re-run sidebar folder prompts anytime
|
|
95
95
|
daxta fields … # export field map for an operation
|
|
96
96
|
daxta call … # CLI Try-it
|
|
97
97
|
```
|
|
98
98
|
|
|
99
|
-
###
|
|
99
|
+
### Docs presentation (`daxta install` / `daxta migrate` / `daxta tree`)
|
|
100
100
|
|
|
101
|
-
|
|
101
|
+
Company-wide choices (saved in `daxta.config.ts`):
|
|
102
|
+
|
|
103
|
+
| Option | Meaning |
|
|
104
|
+
| --- | --- |
|
|
105
|
+
| `treeLayout` | `role-resource` (`v1 › admin › baskets`) or `resource-role` (`v1 › baskets › admin`) |
|
|
106
|
+
| `treeSkipParams` | Don’t nest folders under `{id}` (recommended `true`) |
|
|
107
|
+
| `treeMaxDepth` | Optional max folder depth (e.g. `3`) |
|
|
108
|
+
| `exampleLabelStyle` | OpenAPI example labels: `status-title-case` / `status-case` / `full` |
|
|
109
|
+
|
|
110
|
+
Example label (`status-title-case`):
|
|
102
111
|
|
|
103
112
|
```text
|
|
104
|
-
|
|
105
|
-
1) URL order v1 › admin › baskets
|
|
106
|
-
2) Resource-first v1 › baskets › admin
|
|
107
|
-
3) Custom …
|
|
113
|
+
200 — Admin Find One Basket By Id API — returns basket with items when found by id
|
|
108
114
|
```
|
|
109
115
|
|
|
110
|
-
|
|
116
|
+
Then `daxta build` to refresh `/docs` and export.
|
|
111
117
|
|
|
112
118
|
|
|
113
119
|
|
package/assets/viewer.html
CHANGED
|
@@ -300,7 +300,13 @@
|
|
|
300
300
|
}
|
|
301
301
|
.btn.primary:hover { opacity: 0.92; color: var(--white); }
|
|
302
302
|
.btn.primary:disabled { opacity: 0.45; cursor: default; }
|
|
303
|
-
.live-err {
|
|
303
|
+
.live-err {
|
|
304
|
+
color: #8a2e2e;
|
|
305
|
+
font-size: 13px;
|
|
306
|
+
line-height: 1.5;
|
|
307
|
+
padding: 14px 16px;
|
|
308
|
+
white-space: pre-wrap;
|
|
309
|
+
}
|
|
304
310
|
|
|
305
311
|
.app {
|
|
306
312
|
display: grid;
|
|
@@ -664,7 +670,7 @@
|
|
|
664
670
|
.s { color: #2e6b2e; }
|
|
665
671
|
.n { color: #8a4b12; }
|
|
666
672
|
.p { color: #6b3fa0; }
|
|
667
|
-
.empty { color: var(--stone); font-size: 13px; padding:
|
|
673
|
+
.empty { color: var(--stone); font-size: 13px; padding: 14px 16px; }
|
|
668
674
|
.code {
|
|
669
675
|
font: 500 12px/1 var(--mono);
|
|
670
676
|
padding: 4px 8px;
|
|
@@ -1237,23 +1243,55 @@
|
|
|
1237
1243
|
renderEnvPop();
|
|
1238
1244
|
|
|
1239
1245
|
const VIEWER_EXTENSIONS = new Set(["x-viewer", "x-docs", "x-scenarios", "x-tree-segments", "x-workspace"]);
|
|
1246
|
+
const HTTP_EXPORT = ["get", "post", "put", "patch", "delete", "options", "head", "trace"];
|
|
1240
1247
|
|
|
1248
|
+
const stripExt = (value) => {
|
|
1249
|
+
if (Array.isArray(value)) return value.map(stripExt);
|
|
1250
|
+
if (!value || typeof value !== "object") return value;
|
|
1251
|
+
const out = {};
|
|
1252
|
+
for (const [key, child] of Object.entries(value)) {
|
|
1253
|
+
if (VIEWER_EXTENSIONS.has(key)) continue;
|
|
1254
|
+
out[key] = stripExt(child);
|
|
1255
|
+
}
|
|
1256
|
+
return out;
|
|
1257
|
+
};
|
|
1258
|
+
|
|
1259
|
+
/** Real URL paths + tags from sidebar tree segments. */
|
|
1241
1260
|
const toExportSpec = (source) => {
|
|
1242
|
-
const
|
|
1243
|
-
|
|
1244
|
-
|
|
1245
|
-
|
|
1246
|
-
|
|
1247
|
-
|
|
1248
|
-
|
|
1261
|
+
const pathsIn = source.paths || {};
|
|
1262
|
+
const pathsOut = {};
|
|
1263
|
+
const tagNames = new Set();
|
|
1264
|
+
|
|
1265
|
+
for (const [urlPath, pathItem] of Object.entries(pathsIn)) {
|
|
1266
|
+
if (!pathItem || typeof pathItem !== "object") continue;
|
|
1267
|
+
const itemOut = {};
|
|
1268
|
+
for (const [method, operation] of Object.entries(pathItem)) {
|
|
1269
|
+
if (!HTTP_EXPORT.includes(method) || !operation || typeof operation !== "object") {
|
|
1270
|
+
if (!HTTP_EXPORT.includes(method)) itemOut[method] = stripExt(operation);
|
|
1271
|
+
continue;
|
|
1272
|
+
}
|
|
1273
|
+
const segments = operation["x-tree-segments"] || urlPath.split("/").filter(Boolean);
|
|
1274
|
+
const cleaned = stripExt(operation);
|
|
1275
|
+
const tagParts = segments.filter((part) => !String(part).startsWith("{"));
|
|
1276
|
+
const tag = tagParts.length ? tagParts.join(" / ") : "API";
|
|
1277
|
+
cleaned.tags = [tag];
|
|
1278
|
+
tagNames.add(tag);
|
|
1279
|
+
itemOut[method] = cleaned;
|
|
1249
1280
|
}
|
|
1250
|
-
|
|
1281
|
+
pathsOut[urlPath] = itemOut;
|
|
1282
|
+
}
|
|
1283
|
+
|
|
1284
|
+
const ordered = {};
|
|
1285
|
+
for (const key of Object.keys(pathsOut).sort((a, b) => a.localeCompare(b))) ordered[key] = pathsOut[key];
|
|
1286
|
+
|
|
1287
|
+
return {
|
|
1288
|
+
openapi: source.openapi || "3.0.3",
|
|
1289
|
+
info: stripExt(source.info) || { title: title, version: "0.0.0" },
|
|
1290
|
+
...(source.servers ? { servers: stripExt(source.servers) } : {}),
|
|
1291
|
+
tags: [...tagNames].sort((a, b) => a.localeCompare(b)).map((name) => ({ name })),
|
|
1292
|
+
paths: ordered,
|
|
1293
|
+
...(source.components ? { components: stripExt(source.components) } : {}),
|
|
1251
1294
|
};
|
|
1252
|
-
const exported = walk(source);
|
|
1253
|
-
exported.openapi = exported.openapi || "3.0.3";
|
|
1254
|
-
if (!exported.info) exported.info = { title: title, version: "0.0.0" };
|
|
1255
|
-
if (!exported.paths) exported.paths = {};
|
|
1256
|
-
return exported;
|
|
1257
1295
|
};
|
|
1258
1296
|
|
|
1259
1297
|
const downloadOpenApi = () => {
|
package/dist/build/build-spec.js
CHANGED
|
@@ -162,7 +162,7 @@ function valueFingerprint(value) {
|
|
|
162
162
|
}
|
|
163
163
|
/** Stable shared key so request + response examples from the same hit stay paired. */
|
|
164
164
|
function exampleKeyForHit(hit, index) {
|
|
165
|
-
const base = slug(exampleLabel(hit), index);
|
|
165
|
+
const base = slug((0, catalog_1.exampleLabel)(hit), index);
|
|
166
166
|
return `${base}-${index}`;
|
|
167
167
|
}
|
|
168
168
|
function putExample(store, key, summary, value) {
|
|
@@ -324,7 +324,10 @@ function inferDocs(method, pathTemplate, opHits) {
|
|
|
324
324
|
collectBodyFields(hit.reqBody, '', add);
|
|
325
325
|
}
|
|
326
326
|
}
|
|
327
|
-
return {
|
|
327
|
+
return {
|
|
328
|
+
title: (0, catalog_1.operationSummary)(method, pathTemplate, opHits.map((hit) => hit.test)),
|
|
329
|
+
fields,
|
|
330
|
+
};
|
|
328
331
|
}
|
|
329
332
|
function securityForHits(opHits) {
|
|
330
333
|
const headers = new Set();
|
|
@@ -342,12 +345,18 @@ function securityForHits(opHits) {
|
|
|
342
345
|
requirement[schemeIdFromHeader(header)] = [];
|
|
343
346
|
return [requirement];
|
|
344
347
|
}
|
|
345
|
-
function
|
|
346
|
-
|
|
348
|
+
function scenarioDisplayName(hit) {
|
|
349
|
+
const cas = (0, catalog_1.caseName)(hit.test);
|
|
350
|
+
const title = (0, catalog_1.apiTitle)(hit.test);
|
|
351
|
+
const style = (0, config_1.getConfig)().exampleLabelStyle ?? 'status-title-case';
|
|
352
|
+
if ((style === 'status-title-case' || style === 'full') && title) {
|
|
353
|
+
return `${title} — ${cas}`;
|
|
354
|
+
}
|
|
355
|
+
return cas;
|
|
347
356
|
}
|
|
348
357
|
function toScenario(hit) {
|
|
349
358
|
return {
|
|
350
|
-
name: (
|
|
359
|
+
name: scenarioDisplayName(hit),
|
|
351
360
|
group: (0, catalog_1.caseGroup)(hit.test),
|
|
352
361
|
status: hit.status,
|
|
353
362
|
pathParams: pathParamsFromHit(hit),
|
|
@@ -465,7 +474,7 @@ function buildSpec(hits) {
|
|
|
465
474
|
const pathItem = (paths[pathTemplate] ??= {});
|
|
466
475
|
const operation = (pathItem[method] ??= {
|
|
467
476
|
tags: [tag],
|
|
468
|
-
summary:
|
|
477
|
+
summary: (0, catalog_1.operationSummary)(method, pathTemplate, opHits.map((hit) => hit.test)),
|
|
469
478
|
security,
|
|
470
479
|
responses: {},
|
|
471
480
|
'x-docs': docs,
|
|
@@ -477,7 +486,7 @@ function buildSpec(hits) {
|
|
|
477
486
|
operation.parameters = parameters;
|
|
478
487
|
for (let index = 0; index < opHits.length; index += 1) {
|
|
479
488
|
const hit = opHits[index];
|
|
480
|
-
const label = exampleLabel(hit);
|
|
489
|
+
const label = (0, catalog_1.exampleLabel)(hit);
|
|
481
490
|
const exampleKey = exampleKeyForHit(hit, index);
|
|
482
491
|
if (hit.reqBody !== undefined) {
|
|
483
492
|
operation.requestBody ??= { required: method === 'post' || method === 'put', content: { 'application/json': { schema: inferSchema(hit.reqBody), examples: {} } } };
|
package/dist/catalog/index.d.ts
CHANGED
|
@@ -13,15 +13,38 @@ export type OperationDoc = {
|
|
|
13
13
|
export declare const STATUS_TEXT: Record<string, string>;
|
|
14
14
|
export declare function declaredMethods(test?: string): string[] | null;
|
|
15
15
|
export declare function pathSegments(pathTemplate: string): string[];
|
|
16
|
+
/**
|
|
17
|
+
* Sidebar / export-tag folder segments for a path.
|
|
18
|
+
* Honors treeLayout, treeSkipParams, treeMaxDepth, and per-path overrides.
|
|
19
|
+
*/
|
|
16
20
|
export declare function treePathSegments(pathTemplate: string): string[];
|
|
17
21
|
export declare function viewerTreeConfig(): {
|
|
18
22
|
workspace: string;
|
|
19
23
|
baseUrl: string;
|
|
20
24
|
docsPath: string;
|
|
21
|
-
treeLayout:
|
|
25
|
+
treeLayout: TreeLayout;
|
|
26
|
+
treeSkipParams: boolean;
|
|
27
|
+
treeMaxDepth: number | null;
|
|
22
28
|
treePathOverrides: Record<string, string[]>;
|
|
29
|
+
exampleLabelStyle: "status-case" | "status-title-case" | "full";
|
|
23
30
|
};
|
|
24
31
|
export declare function operationTag(pathTemplate: string, method: string): string;
|
|
25
32
|
export declare function defaultTitle(method: string, pathTemplate: string): string;
|
|
26
33
|
export declare function caseGroup(test?: string): string;
|
|
34
|
+
export declare function caseSectionLabel(test?: string): string;
|
|
35
|
+
/**
|
|
36
|
+
* Human-readable API title from Jest test name, e.g.
|
|
37
|
+
* "Admin Find One Basket By Id API".
|
|
38
|
+
*/
|
|
39
|
+
export declare function apiTitle(test?: string): string | undefined;
|
|
27
40
|
export declare function caseName(test?: string): string;
|
|
41
|
+
export type ExampleLabelHit = {
|
|
42
|
+
status: number;
|
|
43
|
+
method: string;
|
|
44
|
+
path: string;
|
|
45
|
+
test?: string;
|
|
46
|
+
};
|
|
47
|
+
/** OpenAPI example summary / scenario display name. */
|
|
48
|
+
export declare function exampleLabel(hit: ExampleLabelHit): string;
|
|
49
|
+
/** Prefer human API title from hits; else path. */
|
|
50
|
+
export declare function operationSummary(method: string, pathTemplate: string, tests: Array<string | undefined>): string;
|
package/dist/catalog/index.js
CHANGED
|
@@ -8,7 +8,11 @@ exports.viewerTreeConfig = viewerTreeConfig;
|
|
|
8
8
|
exports.operationTag = operationTag;
|
|
9
9
|
exports.defaultTitle = defaultTitle;
|
|
10
10
|
exports.caseGroup = caseGroup;
|
|
11
|
+
exports.caseSectionLabel = caseSectionLabel;
|
|
12
|
+
exports.apiTitle = apiTitle;
|
|
11
13
|
exports.caseName = caseName;
|
|
14
|
+
exports.exampleLabel = exampleLabel;
|
|
15
|
+
exports.operationSummary = operationSummary;
|
|
12
16
|
const config_1 = require("../config");
|
|
13
17
|
exports.STATUS_TEXT = {
|
|
14
18
|
'200': 'OK',
|
|
@@ -26,6 +30,7 @@ const METHOD_ALIASES = {
|
|
|
26
30
|
update: ['patch', 'put'],
|
|
27
31
|
upsert: ['put', 'post', 'patch'],
|
|
28
32
|
};
|
|
33
|
+
const CASE_SECTION_RE = /^(POSITIVE CASES|SEMANTIC ERROR CASES(?:\s*-\s*AUTH)?|INVALID CASES|OMITTED(?: FIELD)? CASES)\s+/i;
|
|
29
34
|
function declaredMethods(test) {
|
|
30
35
|
if (!test)
|
|
31
36
|
return null;
|
|
@@ -38,6 +43,28 @@ function declaredMethods(test) {
|
|
|
38
43
|
function pathSegments(pathTemplate) {
|
|
39
44
|
return pathTemplate.split('/').filter((part) => part && !part.startsWith('{'));
|
|
40
45
|
}
|
|
46
|
+
function applyLayout(parts, layout) {
|
|
47
|
+
if (parts.length >= 3 && /^v\d+$/i.test(parts[0]) && layout === 'resource-role') {
|
|
48
|
+
return [parts[0], parts[2], parts[1], ...parts.slice(3)];
|
|
49
|
+
}
|
|
50
|
+
return parts;
|
|
51
|
+
}
|
|
52
|
+
function applyFold(parts, skipParams, maxDepth) {
|
|
53
|
+
let next = parts;
|
|
54
|
+
if (skipParams) {
|
|
55
|
+
const paramIdx = next.findIndex((part) => part.startsWith('{'));
|
|
56
|
+
if (paramIdx >= 0)
|
|
57
|
+
next = next.slice(0, paramIdx);
|
|
58
|
+
}
|
|
59
|
+
if (typeof maxDepth === 'number' && maxDepth > 0) {
|
|
60
|
+
next = next.slice(0, maxDepth);
|
|
61
|
+
}
|
|
62
|
+
return next;
|
|
63
|
+
}
|
|
64
|
+
/**
|
|
65
|
+
* Sidebar / export-tag folder segments for a path.
|
|
66
|
+
* Honors treeLayout, treeSkipParams, treeMaxDepth, and per-path overrides.
|
|
67
|
+
*/
|
|
41
68
|
function treePathSegments(pathTemplate) {
|
|
42
69
|
const config = (0, config_1.getConfig)();
|
|
43
70
|
const custom = config.treePathSegments?.(pathTemplate);
|
|
@@ -46,11 +73,9 @@ function treePathSegments(pathTemplate) {
|
|
|
46
73
|
const exact = config.treePathOverrides[pathTemplate];
|
|
47
74
|
if (exact?.length)
|
|
48
75
|
return exact;
|
|
49
|
-
const
|
|
50
|
-
|
|
51
|
-
|
|
52
|
-
}
|
|
53
|
-
return parts;
|
|
76
|
+
const layout = (0, config_1.normalizeTreeLayout)(config.treeLayout);
|
|
77
|
+
const parts = applyLayout(pathTemplate.split('/').filter(Boolean), layout);
|
|
78
|
+
return applyFold(parts, config.treeSkipParams !== false, config.treeMaxDepth);
|
|
54
79
|
}
|
|
55
80
|
function viewerTreeConfig() {
|
|
56
81
|
const config = (0, config_1.getConfig)();
|
|
@@ -58,8 +83,11 @@ function viewerTreeConfig() {
|
|
|
58
83
|
workspace: config.workspace,
|
|
59
84
|
baseUrl: config.baseUrl,
|
|
60
85
|
docsPath: config.docsPath,
|
|
61
|
-
treeLayout: config.treeLayout,
|
|
86
|
+
treeLayout: (0, config_1.normalizeTreeLayout)(config.treeLayout),
|
|
87
|
+
treeSkipParams: config.treeSkipParams !== false,
|
|
88
|
+
treeMaxDepth: config.treeMaxDepth ?? null,
|
|
62
89
|
treePathOverrides: config.treePathOverrides,
|
|
90
|
+
exampleLabelStyle: config.exampleLabelStyle ?? 'status-title-case',
|
|
63
91
|
};
|
|
64
92
|
}
|
|
65
93
|
function titleCase(value) {
|
|
@@ -73,7 +101,7 @@ function operationTag(pathTemplate, method) {
|
|
|
73
101
|
const custom = (0, config_1.getConfig)().operationTag?.(pathTemplate, method);
|
|
74
102
|
if (custom)
|
|
75
103
|
return custom;
|
|
76
|
-
const parts =
|
|
104
|
+
const parts = treePathSegments(pathTemplate).filter((part) => !part.startsWith('{') && !/^v\d+$/i.test(part));
|
|
77
105
|
if (!parts.length)
|
|
78
106
|
return 'API';
|
|
79
107
|
if (parts.length === 1)
|
|
@@ -101,11 +129,78 @@ function caseGroup(test) {
|
|
|
101
129
|
return 'Missing fields';
|
|
102
130
|
return 'Other';
|
|
103
131
|
}
|
|
132
|
+
function caseSectionLabel(test) {
|
|
133
|
+
if (!test)
|
|
134
|
+
return '';
|
|
135
|
+
const match = test.match(/(POSITIVE CASES|SEMANTIC ERROR CASES(?:\s*-\s*AUTH)?|INVALID CASES|OMITTED(?: FIELD)? CASES)/i);
|
|
136
|
+
return match?.[1]?.toUpperCase() ?? '';
|
|
137
|
+
}
|
|
138
|
+
/**
|
|
139
|
+
* Human-readable API title from Jest test name, e.g.
|
|
140
|
+
* "Admin Find One Basket By Id API".
|
|
141
|
+
*/
|
|
142
|
+
function apiTitle(test) {
|
|
143
|
+
if (!test)
|
|
144
|
+
return undefined;
|
|
145
|
+
const patterns = [
|
|
146
|
+
/^(.+?\bAPI)\s*[-–—]\s*(?:GET|POST|PUT|PATCH|DELETE)\b/i,
|
|
147
|
+
/\]\s*(?:\([^)]*\)\s*)?(.+?\bAPI)\s+(?:POSITIVE|SEMANTIC|INVALID|OMITTED)\b/i,
|
|
148
|
+
/^(.+?\bAPI)\s+\/\S+\s+\[(?:GET|POST|PUT|PATCH|DELETE)/i,
|
|
149
|
+
/\[(?:GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT)\]\s*(?:\([^)]*\)\s*)?(.+?\bAPI)\b/i,
|
|
150
|
+
];
|
|
151
|
+
for (const re of patterns) {
|
|
152
|
+
const match = test.match(re);
|
|
153
|
+
const title = match?.[1]?.trim();
|
|
154
|
+
if (title && title.length < 120)
|
|
155
|
+
return title;
|
|
156
|
+
}
|
|
157
|
+
return undefined;
|
|
158
|
+
}
|
|
104
159
|
function caseName(test) {
|
|
105
160
|
if (!test)
|
|
106
161
|
return 'example';
|
|
107
|
-
|
|
162
|
+
let rest = test
|
|
108
163
|
.replace(/^.*?\[(?:GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT)\]\s*(?:\(integration\))?\s*/i, '')
|
|
109
|
-
.replace(
|
|
110
|
-
.trim()
|
|
164
|
+
.replace(CASE_SECTION_RE, '')
|
|
165
|
+
.trim();
|
|
166
|
+
// "Admin Find One Basket By Id API - GET /path POSITIVE CASES returns…"
|
|
167
|
+
rest = rest
|
|
168
|
+
.replace(/^.+?\bAPI\s*[-–—]\s*(?:GET|POST|PUT|PATCH|DELETE)\s+\S+\s+/i, '')
|
|
169
|
+
.replace(CASE_SECTION_RE, '')
|
|
170
|
+
.trim();
|
|
171
|
+
// Drop leading human title if still present before the case text
|
|
172
|
+
const title = apiTitle(test);
|
|
173
|
+
if (title && rest.startsWith(title)) {
|
|
174
|
+
rest = rest.slice(title.length).replace(/^[-–—\s]+/, '').replace(CASE_SECTION_RE, '').trim();
|
|
175
|
+
}
|
|
176
|
+
return rest || test;
|
|
177
|
+
}
|
|
178
|
+
/** OpenAPI example summary / scenario display name. */
|
|
179
|
+
function exampleLabel(hit) {
|
|
180
|
+
const style = (0, config_1.getConfig)().exampleLabelStyle ?? 'status-title-case';
|
|
181
|
+
const cas = caseName(hit.test);
|
|
182
|
+
const title = apiTitle(hit.test);
|
|
183
|
+
const method = (hit.method || 'get').toUpperCase();
|
|
184
|
+
const section = caseSectionLabel(hit.test);
|
|
185
|
+
if (style === 'full') {
|
|
186
|
+
const head = title ? `${title} - ${method} ${hit.path}` : `${method} ${hit.path}`;
|
|
187
|
+
const tail = [section, cas].filter(Boolean).join(' ');
|
|
188
|
+
return `${hit.status} — ${head}${tail ? ` ${tail}` : ''}`;
|
|
189
|
+
}
|
|
190
|
+
if (style === 'status-title-case' && title) {
|
|
191
|
+
return `${hit.status} — ${title} — ${cas}`;
|
|
192
|
+
}
|
|
193
|
+
return `${hit.status} — ${cas}`;
|
|
194
|
+
}
|
|
195
|
+
/** Prefer human API title from hits; else path. */
|
|
196
|
+
function operationSummary(method, pathTemplate, tests) {
|
|
197
|
+
const custom = (0, config_1.getConfig)().operationTitle?.(method, pathTemplate);
|
|
198
|
+
if (custom)
|
|
199
|
+
return custom;
|
|
200
|
+
for (const test of tests) {
|
|
201
|
+
const title = apiTitle(test);
|
|
202
|
+
if (title)
|
|
203
|
+
return title;
|
|
204
|
+
}
|
|
205
|
+
return defaultTitle(method, pathTemplate);
|
|
111
206
|
}
|
package/dist/cli/install.js
CHANGED
|
@@ -40,6 +40,7 @@ const child_process_1 = require("child_process");
|
|
|
40
40
|
const inject_main_1 = require("./inject-main");
|
|
41
41
|
const discover_test_1 = require("./discover-test");
|
|
42
42
|
const jest_hooks_1 = require("./jest-hooks");
|
|
43
|
+
const tree_1 = require("./tree");
|
|
43
44
|
const ui_1 = require("./ui");
|
|
44
45
|
function readJson(filePath) {
|
|
45
46
|
return JSON.parse((0, fs_1.readFileSync)(filePath, 'utf8'));
|
|
@@ -113,7 +114,10 @@ export default defineConfig({
|
|
|
113
114
|
controllersRoot: 'src',
|
|
114
115
|
outDir: 'daxta/out',
|
|
115
116
|
docsPath: '/docs',
|
|
116
|
-
treeLayout: 'resource
|
|
117
|
+
treeLayout: 'role-resource',
|
|
118
|
+
treeSkipParams: true,
|
|
119
|
+
treeMaxDepth: null,
|
|
120
|
+
exampleLabelStyle: 'status-title-case',
|
|
117
121
|
fieldsFile: 'daxta/out/daxta.fields.json',
|
|
118
122
|
});
|
|
119
123
|
`;
|
|
@@ -291,10 +295,14 @@ async function installDaxta(options = {}) {
|
|
|
291
295
|
else {
|
|
292
296
|
await (0, ui_1.step)('Attach test hooks', () => 'skipped', { paceMs });
|
|
293
297
|
}
|
|
298
|
+
if (!dryRun) {
|
|
299
|
+
await (0, tree_1.runTreeWizard)({ embedded: true, yes: Boolean(options.yes) });
|
|
300
|
+
}
|
|
294
301
|
(0, ui_1.box)('Done', [
|
|
295
302
|
`${ui_1.c.green('✔')} DAxTA wired for ${ui_1.c.bold(project)}`,
|
|
296
303
|
`${ui_1.c.dim('env')} ${ui_1.c.cyan('DAXTA_DOCS=true')} or ${ui_1.c.cyan('false')}`,
|
|
297
304
|
`${ui_1.c.dim('tests')} run your usual script — Docs ready prints when Jest finishes`,
|
|
305
|
+
`${ui_1.c.dim('sidebar')} ${ui_1.c.cyan('daxta tree')} anytime to re-arrange folders`,
|
|
298
306
|
]);
|
|
299
307
|
const wired = testScript && pkg.scripts?.[testScript] ? testScript : null;
|
|
300
308
|
(0, ui_1.nextSteps)([
|
package/dist/cli/main.js
CHANGED
|
@@ -15,7 +15,7 @@ function usage() {
|
|
|
15
15
|
Usage:
|
|
16
16
|
daxta install [--dry-run] [--skip-dep] [--skip-main] [--yes] [--main <path>] [--fast]
|
|
17
17
|
daxta init (alias of install)
|
|
18
|
-
daxta migrate
|
|
18
|
+
daxta migrate [--yes] (force upgrade + sidebar prompts)
|
|
19
19
|
daxta test [--script <name>] [--config <jest.json>] [--serve] [--port <n>] [--yes]
|
|
20
20
|
daxta build
|
|
21
21
|
daxta serve [--port <n>]
|
|
@@ -77,6 +77,7 @@ async function main() {
|
|
|
77
77
|
else {
|
|
78
78
|
(0, migrate_1.reportMigration)({ ...migration, skipped: false });
|
|
79
79
|
}
|
|
80
|
+
await (0, tree_1.runTreeWizard)({ embedded: true, yes: Boolean(flags.yes) });
|
|
80
81
|
return;
|
|
81
82
|
}
|
|
82
83
|
(0, migrate_1.reportMigration)((0, migrate_1.migrateProject)());
|
package/dist/cli/migrate.d.ts
CHANGED
|
@@ -9,6 +9,7 @@ export type MigrateResult = {
|
|
|
9
9
|
/**
|
|
10
10
|
* Migrate only when package version ≠ daxta.config `daxtaVersion`
|
|
11
11
|
* (or when `daxtaVersion` is missing). Otherwise no-op.
|
|
12
|
+
* Interactive sidebar prompts run from `daxta migrate` / `daxta install` (CLI), not here.
|
|
12
13
|
*/
|
|
13
14
|
export declare function migrateProject(cwd?: string, options?: {
|
|
14
15
|
force?: boolean;
|
package/dist/cli/migrate.js
CHANGED
|
@@ -193,6 +193,7 @@ function migrateConfigDefaults(configPath, configText) {
|
|
|
193
193
|
/**
|
|
194
194
|
* Migrate only when package version ≠ daxta.config `daxtaVersion`
|
|
195
195
|
* (or when `daxtaVersion` is missing). Otherwise no-op.
|
|
196
|
+
* Interactive sidebar prompts run from `daxta migrate` / `daxta install` (CLI), not here.
|
|
196
197
|
*/
|
|
197
198
|
function migrateProject(cwd = process.cwd(), options = {}) {
|
|
198
199
|
const toVersion = packageVersion();
|
package/dist/cli/tree.d.ts
CHANGED
|
@@ -1,4 +1,10 @@
|
|
|
1
|
-
export
|
|
1
|
+
export type TreeWizardOptions = {
|
|
2
2
|
path?: string;
|
|
3
3
|
layout?: string;
|
|
4
|
-
|
|
4
|
+
embedded?: boolean;
|
|
5
|
+
yes?: boolean;
|
|
6
|
+
};
|
|
7
|
+
/**
|
|
8
|
+
* Company docs presentation wizard — install / migrate / `daxta tree`.
|
|
9
|
+
*/
|
|
10
|
+
export declare function runTreeWizard(options?: TreeWizardOptions): Promise<void>;
|
package/dist/cli/tree.js
CHANGED
|
@@ -23,31 +23,20 @@ function normalizePathInput(raw) {
|
|
|
23
23
|
return trimmed;
|
|
24
24
|
return trimmed.startsWith('/') ? trimmed.replace(/\/+$/, '') || '/' : `/${trimmed.replace(/\/+$/, '')}`;
|
|
25
25
|
}
|
|
26
|
-
function
|
|
27
|
-
|
|
28
|
-
|
|
29
|
-
|
|
30
|
-
|
|
31
|
-
if (
|
|
32
|
-
|
|
26
|
+
function layoutSegments(pathTemplate, layout, skipParams, maxDepth) {
|
|
27
|
+
let parts = pathTemplate.split('/').filter(Boolean);
|
|
28
|
+
if (parts.length >= 3 && /^v\d+$/i.test(parts[0]) && layout === 'resource-role') {
|
|
29
|
+
parts = [parts[0], parts[2], parts[1], ...parts.slice(3)];
|
|
30
|
+
}
|
|
31
|
+
if (skipParams) {
|
|
32
|
+
const idx = parts.findIndex((part) => part.startsWith('{'));
|
|
33
|
+
if (idx >= 0)
|
|
34
|
+
parts = parts.slice(0, idx);
|
|
33
35
|
}
|
|
36
|
+
if (typeof maxDepth === 'number' && maxDepth > 0)
|
|
37
|
+
parts = parts.slice(0, maxDepth);
|
|
34
38
|
return parts;
|
|
35
39
|
}
|
|
36
|
-
/** Put known "area" segments (admin/device/…) right after version. */
|
|
37
|
-
function areaFirstSegments(pathTemplate) {
|
|
38
|
-
const parts = urlOrderSegments(pathTemplate);
|
|
39
|
-
if (parts.length < 3 || !/^v\d+$/i.test(parts[0]))
|
|
40
|
-
return parts;
|
|
41
|
-
const areas = new Set(['admin', 'device', 'devices', 'user', 'users', 'me', 'internal', 'public']);
|
|
42
|
-
const version = parts[0];
|
|
43
|
-
const rest = parts.slice(1);
|
|
44
|
-
const areaIdx = rest.findIndex((part) => areas.has(part.toLowerCase()) && !part.startsWith('{'));
|
|
45
|
-
if (areaIdx <= 0)
|
|
46
|
-
return parts;
|
|
47
|
-
const area = rest[areaIdx];
|
|
48
|
-
const without = [...rest.slice(0, areaIdx), ...rest.slice(areaIdx + 1)];
|
|
49
|
-
return [version, area, ...without];
|
|
50
|
-
}
|
|
51
40
|
function listKnownPaths() {
|
|
52
41
|
const fromSpec = new Set();
|
|
53
42
|
try {
|
|
@@ -61,13 +50,18 @@ function listKnownPaths() {
|
|
|
61
50
|
catch {
|
|
62
51
|
// ignore
|
|
63
52
|
}
|
|
64
|
-
|
|
65
|
-
|
|
53
|
+
try {
|
|
54
|
+
for (const pathTemplate of (0, dto_fields_1.listControllerPathTemplates)())
|
|
55
|
+
fromSpec.add(pathTemplate);
|
|
56
|
+
}
|
|
57
|
+
catch {
|
|
58
|
+
// ignore
|
|
59
|
+
}
|
|
66
60
|
return [...fromSpec].sort((a, b) => a.localeCompare(b));
|
|
67
61
|
}
|
|
68
62
|
function printPathChoices(paths, limit = 12) {
|
|
69
63
|
if (!paths.length) {
|
|
70
|
-
console.log(` ${ui_1.c.dim('
|
|
64
|
+
console.log(` ${ui_1.c.dim('tip')} type a path like ${ui_1.c.cyan('/v1/admin/baskets')}`);
|
|
71
65
|
return;
|
|
72
66
|
}
|
|
73
67
|
console.log(` ${ui_1.c.dim('known paths')}`);
|
|
@@ -82,8 +76,7 @@ async function pickPath(flagPath) {
|
|
|
82
76
|
return normalizePathInput(flagPath);
|
|
83
77
|
const known = listKnownPaths();
|
|
84
78
|
printPathChoices(known);
|
|
85
|
-
const answer = await prompt(` ${ui_1.c.yellow('?')} ${ui_1.c.bold('Path')}
|
|
86
|
-
` ${ui_1.c.dim('number, full path, or n to skip')}\n ${ui_1.c.cyan('›')} `);
|
|
79
|
+
const answer = await prompt(` ${ui_1.c.yellow('?')} ${ui_1.c.bold('Path')} override ${ui_1.c.dim('(number · path · n skip)')}\n ${ui_1.c.cyan('›')} `);
|
|
87
80
|
if (!answer || /^n(o)?$/i.test(answer))
|
|
88
81
|
return null;
|
|
89
82
|
if (/^\d+$/.test(answer)) {
|
|
@@ -94,98 +87,170 @@ async function pickPath(flagPath) {
|
|
|
94
87
|
}
|
|
95
88
|
return normalizePathInput(answer);
|
|
96
89
|
}
|
|
97
|
-
async function
|
|
90
|
+
async function pickLayout(current) {
|
|
91
|
+
const sample = '/v1/admin/baskets/{id}/lock';
|
|
98
92
|
console.log('');
|
|
99
|
-
console.log(` ${ui_1.c.bold('
|
|
100
|
-
console.log(`
|
|
101
|
-
console.log(
|
|
102
|
-
console.log(` ${ui_1.c.cyan('
|
|
103
|
-
|
|
93
|
+
console.log(` ${ui_1.c.bold('Folder order')} ${ui_1.c.dim('(company default)')}`);
|
|
94
|
+
console.log(` ${ui_1.c.dim('sample')} ${ui_1.c.cyan(sample)}`);
|
|
95
|
+
console.log('');
|
|
96
|
+
console.log(` ${ui_1.c.cyan('1')} role → resource ${ui_1.c.dim('recommended')}`);
|
|
97
|
+
console.log(` ${(0, config_edit_1.previewTree)(layoutSegments(sample, 'role-resource', true, null))}`);
|
|
98
|
+
console.log(` ${ui_1.c.dim('v1 › admin › baskets (ops under baskets, not under {id})')}`);
|
|
99
|
+
console.log('');
|
|
100
|
+
console.log(` ${ui_1.c.cyan('2')} resource → role`);
|
|
101
|
+
console.log(` ${(0, config_edit_1.previewTree)(layoutSegments(sample, 'resource-role', true, null))}`);
|
|
102
|
+
console.log(` ${ui_1.c.dim('v1 › baskets › admin')}`);
|
|
103
|
+
console.log('');
|
|
104
|
+
console.log(` ${ui_1.c.cyan('3')} keep ${ui_1.c.dim(`(${current})`)}`);
|
|
105
|
+
const answer = await prompt(` ${ui_1.c.yellow('?')} Choose\n ${ui_1.c.cyan('›')} `);
|
|
104
106
|
if (!answer || answer === '3' || /^k(eep)?$/i.test(answer))
|
|
107
|
+
return current;
|
|
108
|
+
if (answer === '1' || /^role/i.test(answer))
|
|
109
|
+
return 'role-resource';
|
|
110
|
+
if (answer === '2' || /^resource/i.test(answer))
|
|
111
|
+
return 'resource-role';
|
|
112
|
+
throw new Error(`Unknown layout: ${answer}`);
|
|
113
|
+
}
|
|
114
|
+
async function pickSkipParams(current) {
|
|
115
|
+
console.log('');
|
|
116
|
+
console.log(` ${ui_1.c.bold('Stop folders at path params')}`);
|
|
117
|
+
console.log(` ${ui_1.c.dim('Avoid')} ${ui_1.c.cyan('{id}')} ${ui_1.c.dim('→ complete / lock / pay as nested folders')}`);
|
|
118
|
+
console.log(` ${ui_1.c.cyan('1')} yes — fold under resource ${ui_1.c.dim('(recommended)')}`);
|
|
119
|
+
console.log(` ${ui_1.c.cyan('2')} no — nest full path`);
|
|
120
|
+
console.log(` ${ui_1.c.cyan('3')} keep ${ui_1.c.dim(`(${current ? 'yes' : 'no'})`)}`);
|
|
121
|
+
const answer = await prompt(` ${ui_1.c.yellow('?')} Choose\n ${ui_1.c.cyan('›')} `);
|
|
122
|
+
if (!answer || answer === '3' || /^k(eep)?$/i.test(answer))
|
|
123
|
+
return current;
|
|
124
|
+
if (answer === '1' || /^y/i.test(answer))
|
|
125
|
+
return true;
|
|
126
|
+
if (answer === '2' || /^n/i.test(answer))
|
|
127
|
+
return false;
|
|
128
|
+
throw new Error(`Unknown choice: ${answer}`);
|
|
129
|
+
}
|
|
130
|
+
async function pickMaxDepth(current) {
|
|
131
|
+
console.log('');
|
|
132
|
+
console.log(` ${ui_1.c.bold('Max folder depth')} ${ui_1.c.dim('(optional)')}`);
|
|
133
|
+
console.log(` ${ui_1.c.dim('Counts version. Empty = no limit beyond param fold.')}`);
|
|
134
|
+
console.log(` ${ui_1.c.dim('e.g. 3 → v1 / admin / baskets')}`);
|
|
135
|
+
const hint = current == null ? 'none' : String(current);
|
|
136
|
+
const answer = await prompt(` ${ui_1.c.yellow('?')} Depth ${ui_1.c.dim(`[${hint}]`)}\n ${ui_1.c.cyan('›')} `);
|
|
137
|
+
if (!answer)
|
|
138
|
+
return current ?? null;
|
|
139
|
+
if (/^(none|null|n)$/i.test(answer))
|
|
105
140
|
return null;
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
141
|
+
const n = Number(answer);
|
|
142
|
+
if (!Number.isFinite(n) || n < 1)
|
|
143
|
+
throw new Error(`Invalid depth: ${answer}`);
|
|
144
|
+
return Math.floor(n);
|
|
145
|
+
}
|
|
146
|
+
async function pickExampleStyle(current) {
|
|
147
|
+
console.log('');
|
|
148
|
+
console.log(` ${ui_1.c.bold('Example / scenario labels')}`);
|
|
149
|
+
console.log(` ${ui_1.c.cyan('1')} status-title-case`);
|
|
150
|
+
console.log(` ${ui_1.c.dim('200 — Admin Find One Basket By Id API — returns basket when found')}`);
|
|
151
|
+
console.log(` ${ui_1.c.cyan('2')} status-case`);
|
|
152
|
+
console.log(` ${ui_1.c.dim('200 — returns basket when found')}`);
|
|
153
|
+
console.log(` ${ui_1.c.cyan('3')} full`);
|
|
154
|
+
console.log(` ${ui_1.c.dim('200 — Admin Find… API - GET /v1/admin/baskets/{id} POSITIVE CASES returns…')}`);
|
|
155
|
+
console.log(` ${ui_1.c.cyan('4')} keep ${ui_1.c.dim(`(${current})`)}`);
|
|
156
|
+
const answer = await prompt(` ${ui_1.c.yellow('?')} Choose\n ${ui_1.c.cyan('›')} `);
|
|
157
|
+
if (!answer || answer === '4' || /^k(eep)?$/i.test(answer))
|
|
158
|
+
return current;
|
|
159
|
+
if (answer === '1' || /title/i.test(answer))
|
|
160
|
+
return 'status-title-case';
|
|
161
|
+
if (answer === '2' || /status-case/i.test(answer))
|
|
162
|
+
return 'status-case';
|
|
163
|
+
if (answer === '3' || /^full/i.test(answer))
|
|
164
|
+
return 'full';
|
|
165
|
+
throw new Error(`Unknown style: ${answer}`);
|
|
111
166
|
}
|
|
112
|
-
function layoutChoicesFor(pathTemplate) {
|
|
113
|
-
const
|
|
114
|
-
const resource =
|
|
115
|
-
const area = areaFirstSegments(pathTemplate);
|
|
167
|
+
function layoutChoicesFor(pathTemplate, layout, skipParams, maxDepth) {
|
|
168
|
+
const role = layoutSegments(pathTemplate, 'role-resource', skipParams, maxDepth);
|
|
169
|
+
const resource = layoutSegments(pathTemplate, 'resource-role', skipParams, maxDepth);
|
|
116
170
|
const choices = [
|
|
117
|
-
{ id: '
|
|
118
|
-
{ id: 'resource', label: '
|
|
171
|
+
{ id: 'role', label: 'role → resource', segments: role },
|
|
172
|
+
{ id: 'resource', label: 'resource → role', segments: resource },
|
|
173
|
+
{ id: 'custom', label: 'Custom segments', segments: role },
|
|
119
174
|
];
|
|
120
|
-
if (area.join('/') !== url.join('/') && area.join('/') !== resource.join('/')) {
|
|
121
|
-
choices.push({ id: 'area', label: 'Area-first (admin/device/…)', segments: area });
|
|
122
|
-
}
|
|
123
|
-
choices.push({ id: 'custom', label: 'Custom segments', segments: url });
|
|
124
175
|
return choices;
|
|
125
176
|
}
|
|
126
|
-
async function pickSegments(pathTemplate) {
|
|
127
|
-
const choices = layoutChoicesFor(pathTemplate);
|
|
177
|
+
async function pickSegments(pathTemplate, layout, skipParams, maxDepth) {
|
|
178
|
+
const choices = layoutChoicesFor(pathTemplate, layout, skipParams, maxDepth);
|
|
128
179
|
console.log('');
|
|
129
|
-
console.log(` ${ui_1.c.bold('
|
|
180
|
+
console.log(` ${ui_1.c.bold('Override')} ${ui_1.c.cyan(pathTemplate)}`);
|
|
130
181
|
choices.forEach((choice, index) => {
|
|
131
|
-
|
|
132
|
-
console.log(` ${mark} ${ui_1.c.bold(choice.label)}`);
|
|
182
|
+
console.log(` ${ui_1.c.cyan(String(index + 1))} ${ui_1.c.bold(choice.label)}`);
|
|
133
183
|
console.log(` ${(0, config_edit_1.previewTree)(choice.segments)}`);
|
|
134
184
|
});
|
|
135
|
-
const answer = await prompt(` ${ui_1.c.yellow('?')}
|
|
185
|
+
const answer = await prompt(` ${ui_1.c.yellow('?')} Choose\n ${ui_1.c.cyan('›')} `);
|
|
136
186
|
if (!answer || /^n(o)?$/i.test(answer))
|
|
137
187
|
return null;
|
|
138
|
-
const index = /^\d+$/.test(answer) ? Number(answer) - 1 :
|
|
188
|
+
const index = /^\d+$/.test(answer) ? Number(answer) - 1 : -1;
|
|
139
189
|
const selected = choices[index];
|
|
140
190
|
if (!selected)
|
|
141
191
|
throw new Error(`Unknown choice: ${answer}`);
|
|
142
192
|
if (selected.id !== 'custom')
|
|
143
193
|
return selected.segments;
|
|
144
|
-
const typed = await prompt(` ${ui_1.c.yellow('?')} Segments
|
|
145
|
-
` ${ui_1.c.dim(`e.g. v1 baskets admin`)}\n ${ui_1.c.cyan('›')} `);
|
|
194
|
+
const typed = await prompt(` ${ui_1.c.yellow('?')} Segments ${ui_1.c.dim('(space separated)')}\n ${ui_1.c.cyan('›')} `);
|
|
146
195
|
if (!typed)
|
|
147
196
|
return null;
|
|
148
|
-
return typed
|
|
149
|
-
.split(/›|>|,|\s+/)
|
|
150
|
-
.map((part) => part.trim())
|
|
151
|
-
.filter(Boolean);
|
|
197
|
+
return typed.split(/›|>|,|\s+/).map((part) => part.trim()).filter(Boolean);
|
|
152
198
|
}
|
|
199
|
+
/**
|
|
200
|
+
* Company docs presentation wizard — install / migrate / `daxta tree`.
|
|
201
|
+
*/
|
|
153
202
|
async function runTreeWizard(options = {}) {
|
|
154
|
-
(
|
|
203
|
+
if (options.yes || !process.stdin.isTTY) {
|
|
204
|
+
if (!options.embedded)
|
|
205
|
+
console.log(` ${ui_1.c.dim('tree wizard skipped (non-interactive)')}`);
|
|
206
|
+
return;
|
|
207
|
+
}
|
|
208
|
+
if (!options.embedded)
|
|
209
|
+
(0, ui_1.banner)('DAxTA tree', 'docs presentation');
|
|
155
210
|
const configPath = (0, config_edit_1.findDaxtaConfigPath)();
|
|
156
|
-
if (!configPath)
|
|
211
|
+
if (!configPath)
|
|
157
212
|
throw new Error('No daxta.config.ts found. Run `daxta install` first.');
|
|
158
|
-
}
|
|
159
213
|
(0, config_1.resetConfig)();
|
|
160
214
|
const config = (0, config_1.getConfig)(true);
|
|
161
|
-
|
|
162
|
-
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
|
|
166
|
-
|
|
167
|
-
|
|
168
|
-
|
|
169
|
-
|
|
215
|
+
console.log('');
|
|
216
|
+
console.log(` ${ui_1.c.yellow(ui_1.c.bold('?'))} ${ui_1.c.bold('Docs presentation')} ${ui_1.c.dim('— sidebar + OpenAPI export')}`);
|
|
217
|
+
let layout = (0, config_1.normalizeTreeLayout)(options.layout === 'resource-first' || options.layout === 'resource-role'
|
|
218
|
+
? 'resource-role'
|
|
219
|
+
: options.layout === 'url-order' || options.layout === 'role-resource'
|
|
220
|
+
? 'role-resource'
|
|
221
|
+
: config.treeLayout);
|
|
222
|
+
if (!options.layout)
|
|
223
|
+
layout = await pickLayout(layout);
|
|
224
|
+
(0, config_edit_1.upsertConfigValue)(configPath, 'treeLayout', (0, config_edit_1.formatTsString)(layout));
|
|
225
|
+
console.log(` ${ui_1.c.green('✔')} treeLayout → ${ui_1.c.cyan(layout)}`);
|
|
226
|
+
const skipParams = await pickSkipParams(config.treeSkipParams !== false);
|
|
227
|
+
(0, config_edit_1.upsertConfigValue)(configPath, 'treeSkipParams', skipParams ? 'true' : 'false');
|
|
228
|
+
console.log(` ${ui_1.c.green('✔')} treeSkipParams → ${ui_1.c.cyan(String(skipParams))}`);
|
|
229
|
+
const maxDepth = await pickMaxDepth(config.treeMaxDepth ?? null);
|
|
230
|
+
(0, config_edit_1.upsertConfigValue)(configPath, 'treeMaxDepth', maxDepth == null ? 'null' : String(maxDepth));
|
|
231
|
+
console.log(` ${ui_1.c.green('✔')} treeMaxDepth → ${ui_1.c.cyan(maxDepth == null ? 'null' : String(maxDepth))}`);
|
|
232
|
+
const exampleStyle = await pickExampleStyle(config.exampleLabelStyle ?? 'status-title-case');
|
|
233
|
+
(0, config_edit_1.upsertConfigValue)(configPath, 'exampleLabelStyle', (0, config_edit_1.formatTsString)(exampleStyle));
|
|
234
|
+
console.log(` ${ui_1.c.green('✔')} exampleLabelStyle → ${ui_1.c.cyan(exampleStyle)}`);
|
|
235
|
+
const customize = options.path
|
|
236
|
+
? 'y'
|
|
237
|
+
: await prompt(` ${ui_1.c.yellow('?')} Per-path override now?\n` +
|
|
238
|
+
` ${ui_1.c.dim('Y')} yes · ${ui_1.c.dim('n')} later\n ${ui_1.c.cyan('›')} `);
|
|
239
|
+
if (customize && !/^n(o)?$/i.test(customize)) {
|
|
240
|
+
const pathTemplate = await pickPath(options.path);
|
|
241
|
+
if (pathTemplate) {
|
|
242
|
+
const segments = await pickSegments(pathTemplate, layout, skipParams, maxDepth);
|
|
243
|
+
if (segments?.length) {
|
|
244
|
+
const overrides = (0, config_edit_1.readTreePathOverrides)();
|
|
245
|
+
overrides[pathTemplate] = segments;
|
|
246
|
+
(0, config_edit_1.upsertConfigValue)(configPath, 'treePathOverrides', (0, config_edit_1.formatTsStringRecord)(overrides));
|
|
247
|
+
console.log(` ${ui_1.c.green('✔')} ${ui_1.c.cyan(pathTemplate)} → ${(0, config_edit_1.previewTree)(segments)}`);
|
|
248
|
+
}
|
|
170
249
|
}
|
|
171
250
|
}
|
|
172
|
-
|
|
173
|
-
|
|
174
|
-
console.log(` ${ui_1.c.dim('
|
|
175
|
-
|
|
251
|
+
if (!options.embedded) {
|
|
252
|
+
console.log(` ${ui_1.c.dim('saved')} ${configPath}`);
|
|
253
|
+
console.log(` ${ui_1.c.dim('refresh')} ${ui_1.c.cyan('daxta build')}`);
|
|
254
|
+
console.log('');
|
|
176
255
|
}
|
|
177
|
-
const segments = await pickSegments(pathTemplate);
|
|
178
|
-
if (!segments?.length) {
|
|
179
|
-
console.log(` ${ui_1.c.dim('skipped path override')}`);
|
|
180
|
-
return;
|
|
181
|
-
}
|
|
182
|
-
const overrides = (0, config_edit_1.readTreePathOverrides)();
|
|
183
|
-
overrides[pathTemplate] = segments;
|
|
184
|
-
(0, config_edit_1.upsertConfigValue)(configPath, 'treePathOverrides', (0, config_edit_1.formatTsStringRecord)(overrides));
|
|
185
|
-
console.log('');
|
|
186
|
-
console.log(` ${ui_1.c.green('✔')} ${ui_1.c.cyan(pathTemplate)}`);
|
|
187
|
-
console.log(` ${(0, config_edit_1.previewTree)(segments)}`);
|
|
188
|
-
console.log(` ${ui_1.c.dim('saved to')} ${configPath}`);
|
|
189
|
-
console.log(` ${ui_1.c.dim('refresh docs:')} ${ui_1.c.cyan('daxta build')}`);
|
|
190
|
-
console.log('');
|
|
191
256
|
}
|
package/dist/config.d.ts
CHANGED
|
@@ -1,4 +1,8 @@
|
|
|
1
|
-
|
|
1
|
+
/** role→resource (URL order) vs resource→role (swap after version) */
|
|
2
|
+
export type TreeLayout = 'role-resource' | 'resource-role';
|
|
3
|
+
/** @deprecated use role-resource / resource-role */
|
|
4
|
+
export type LegacyTreeLayout = 'url-order' | 'resource-first';
|
|
5
|
+
export type ExampleLabelStyle = 'status-case' | 'status-title-case' | 'full';
|
|
2
6
|
export type SpecInfo = {
|
|
3
7
|
title?: string;
|
|
4
8
|
version?: string;
|
|
@@ -9,18 +13,37 @@ export type DaxtaConfig = {
|
|
|
9
13
|
baseUrl?: string;
|
|
10
14
|
controllersRoot?: string;
|
|
11
15
|
outDir?: string;
|
|
12
|
-
|
|
16
|
+
/**
|
|
17
|
+
* Sidebar / tag folder order after version:
|
|
18
|
+
* - role-resource → v1 › admin › baskets (URL order, recommended)
|
|
19
|
+
* - resource-role → v1 › baskets › admin
|
|
20
|
+
*/
|
|
21
|
+
treeLayout?: TreeLayout | LegacyTreeLayout;
|
|
22
|
+
/**
|
|
23
|
+
* Do not create sidebar folders for `{param}` segments (and anything after).
|
|
24
|
+
* Ops like POST …/{id}/lock sit under the parent resource. Default true.
|
|
25
|
+
*/
|
|
26
|
+
treeSkipParams?: boolean;
|
|
27
|
+
/**
|
|
28
|
+
* Max folder segments after (and including) version.
|
|
29
|
+
* e.g. 3 → v1 / admin / baskets — deeper segments are not folders.
|
|
30
|
+
* null/undefined = no extra limit (treeSkipParams still applies).
|
|
31
|
+
*/
|
|
32
|
+
treeMaxDepth?: number | null;
|
|
13
33
|
treePathOverrides?: Record<string, string[]>;
|
|
34
|
+
/**
|
|
35
|
+
* OpenAPI example + scenario labels:
|
|
36
|
+
* - status-case → `200 — returns basket when found`
|
|
37
|
+
* - status-title-case → `200 — Admin Find One Basket By Id API — returns…`
|
|
38
|
+
* - full → `200 — Admin Find… API - GET /v1/admin/baskets/{id} POSITIVE CASES returns…`
|
|
39
|
+
*/
|
|
40
|
+
exampleLabelStyle?: ExampleLabelStyle;
|
|
14
41
|
port?: number;
|
|
15
42
|
fieldsFile?: string;
|
|
16
43
|
docsPath?: string;
|
|
17
|
-
/** package.json script name wired to DAxTA (e.g. test:integration) */
|
|
18
44
|
testScript?: string;
|
|
19
|
-
/** Original test command before wrap (e.g. jest --config …) */
|
|
20
45
|
testCommand?: string;
|
|
21
|
-
/** Last auto-migrated @t0.labs/daxta version */
|
|
22
46
|
daxtaVersion?: string;
|
|
23
|
-
/** Optional explicit Jest JSON config path */
|
|
24
47
|
jestConfig?: string;
|
|
25
48
|
templatize?: (pathname: string, test?: string) => string | null | undefined;
|
|
26
49
|
operationTag?: (pathTemplate: string, method: string) => string | undefined;
|
|
@@ -31,8 +54,9 @@ export type DaxtaConfig = {
|
|
|
31
54
|
includeHit?: (method: string, pathTemplate: string, test?: string) => boolean;
|
|
32
55
|
treePathSegments?: (pathTemplate: string) => string[] | undefined;
|
|
33
56
|
};
|
|
34
|
-
export type ResolvedDaxtaConfig = Required<Pick<DaxtaConfig, 'workspace' | 'baseUrl' | 'controllersRoot' | 'outDir' | 'treeLayout' | 'treePathOverrides' | 'port' | 'fieldsFile' | 'docsPath'>> & DaxtaConfig;
|
|
57
|
+
export type ResolvedDaxtaConfig = Required<Pick<DaxtaConfig, 'workspace' | 'baseUrl' | 'controllersRoot' | 'outDir' | 'treeLayout' | 'treePathOverrides' | 'treeSkipParams' | 'exampleLabelStyle' | 'port' | 'fieldsFile' | 'docsPath'>> & DaxtaConfig;
|
|
35
58
|
export declare function defineConfig(config: DaxtaConfig): DaxtaConfig;
|
|
59
|
+
export declare function normalizeTreeLayout(layout: TreeLayout | LegacyTreeLayout | undefined): TreeLayout;
|
|
36
60
|
export declare function resolveConfig(cwd?: string, overrides?: DaxtaConfig): ResolvedDaxtaConfig;
|
|
37
61
|
export declare function getConfig(forceReload?: boolean): ResolvedDaxtaConfig;
|
|
38
62
|
export declare function setConfig(config: ResolvedDaxtaConfig): void;
|
package/dist/config.js
CHANGED
|
@@ -34,6 +34,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
36
|
exports.defineConfig = defineConfig;
|
|
37
|
+
exports.normalizeTreeLayout = normalizeTreeLayout;
|
|
37
38
|
exports.resolveConfig = resolveConfig;
|
|
38
39
|
exports.getConfig = getConfig;
|
|
39
40
|
exports.setConfig = setConfig;
|
|
@@ -45,8 +46,11 @@ const DEFAULTS = {
|
|
|
45
46
|
baseUrl: 'http://localhost:3000',
|
|
46
47
|
controllersRoot: 'src',
|
|
47
48
|
outDir: 'daxta/out',
|
|
48
|
-
treeLayout: 'resource
|
|
49
|
+
treeLayout: 'role-resource',
|
|
50
|
+
treeSkipParams: true,
|
|
51
|
+
treeMaxDepth: null,
|
|
49
52
|
treePathOverrides: {},
|
|
53
|
+
exampleLabelStyle: 'status-title-case',
|
|
50
54
|
port: 5199,
|
|
51
55
|
fieldsFile: 'daxta.fields.json',
|
|
52
56
|
docsPath: '/docs',
|
|
@@ -55,6 +59,13 @@ let cached = null;
|
|
|
55
59
|
function defineConfig(config) {
|
|
56
60
|
return config;
|
|
57
61
|
}
|
|
62
|
+
function normalizeTreeLayout(layout) {
|
|
63
|
+
if (layout === 'resource-first' || layout === 'resource-role')
|
|
64
|
+
return 'resource-role';
|
|
65
|
+
if (layout === 'url-order' || layout === 'role-resource')
|
|
66
|
+
return 'role-resource';
|
|
67
|
+
return 'role-resource';
|
|
68
|
+
}
|
|
58
69
|
function loadConfigFile(cwd) {
|
|
59
70
|
const candidates = ['daxta.config.ts', 'daxta.config.js', 'daxta.config.mjs', 'daxta.config.cjs'];
|
|
60
71
|
for (const name of candidates) {
|
|
@@ -86,6 +97,11 @@ function resolveConfig(cwd = process.cwd(), overrides) {
|
|
|
86
97
|
...(overrides?.treePathOverrides ?? {}),
|
|
87
98
|
},
|
|
88
99
|
};
|
|
100
|
+
merged.treeLayout = normalizeTreeLayout(merged.treeLayout);
|
|
101
|
+
if (merged.treeSkipParams == null)
|
|
102
|
+
merged.treeSkipParams = DEFAULTS.treeSkipParams;
|
|
103
|
+
if (merged.exampleLabelStyle == null)
|
|
104
|
+
merged.exampleLabelStyle = DEFAULTS.exampleLabelStyle;
|
|
89
105
|
merged.controllersRoot = path.isAbsolute(merged.controllersRoot)
|
|
90
106
|
? merged.controllersRoot
|
|
91
107
|
: path.join(cwd, merged.controllersRoot);
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export { defineConfig, getConfig, resolveConfig, type DaxtaConfig, type TreeLayout, type SpecInfo } from './config';
|
|
1
|
+
export { defineConfig, getConfig, resolveConfig, normalizeTreeLayout, type DaxtaConfig, type TreeLayout, type ExampleLabelStyle, type SpecInfo } from './config';
|
|
2
2
|
export { buildDaxtaSpec, buildOpenApi, loadHits, type BuildResult, type Scenario } from './build/build-spec';
|
|
3
3
|
export { rebuildFromDisk, flushAndRebuild, clearPartialMarker, touchPartialMarker } from './build/incremental';
|
|
4
4
|
export { install, flush, clearWorkerHits, getHits, type RecordedHit } from './recorder';
|
package/dist/index.js
CHANGED
|
@@ -1,10 +1,11 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.installDaxta = 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.resolveConfig = exports.getConfig = exports.defineConfig = void 0;
|
|
3
|
+
exports.installDaxta = 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; } });
|
|
7
7
|
Object.defineProperty(exports, "resolveConfig", { enumerable: true, get: function () { return config_1.resolveConfig; } });
|
|
8
|
+
Object.defineProperty(exports, "normalizeTreeLayout", { enumerable: true, get: function () { return config_1.normalizeTreeLayout; } });
|
|
8
9
|
var build_spec_1 = require("./build/build-spec");
|
|
9
10
|
Object.defineProperty(exports, "buildDaxtaSpec", { enumerable: true, get: function () { return build_spec_1.buildDaxtaSpec; } });
|
|
10
11
|
Object.defineProperty(exports, "buildOpenApi", { enumerable: true, get: function () { return build_spec_1.buildOpenApi; } });
|
|
@@ -1,2 +1,7 @@
|
|
|
1
1
|
export declare function stripViewerExtensions(value: unknown): unknown;
|
|
2
|
+
/**
|
|
3
|
+
* Export OpenAPI with real URL paths (correct for clients) and tags/folders
|
|
4
|
+
* matching the docs sidebar (`x-tree-segments`).
|
|
5
|
+
*/
|
|
6
|
+
export declare function toTreeOrderedOpenApi(raw: Record<string, unknown>): Record<string, unknown>;
|
|
2
7
|
export declare function readStrippedOpenApiJson(): string | null;
|
package/dist/serve/spec-utils.js
CHANGED
|
@@ -1,10 +1,12 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
3
|
exports.stripViewerExtensions = stripViewerExtensions;
|
|
4
|
+
exports.toTreeOrderedOpenApi = toTreeOrderedOpenApi;
|
|
4
5
|
exports.readStrippedOpenApiJson = readStrippedOpenApiJson;
|
|
5
6
|
const fs_1 = require("fs");
|
|
6
7
|
const paths_1 = require("./paths");
|
|
7
8
|
const VIEWER_EXTENSION_KEYS = new Set(['x-viewer', 'x-docs', 'x-scenarios', 'x-tree-segments', 'x-workspace']);
|
|
9
|
+
const HTTP_METHODS = new Set(['get', 'post', 'put', 'patch', 'delete', 'options', 'head', 'trace']);
|
|
8
10
|
function stripViewerExtensions(value) {
|
|
9
11
|
if (Array.isArray(value))
|
|
10
12
|
return value.map(stripViewerExtensions);
|
|
@@ -18,10 +20,61 @@ function stripViewerExtensions(value) {
|
|
|
18
20
|
}
|
|
19
21
|
return out;
|
|
20
22
|
}
|
|
23
|
+
function treeSegmentsForOperation(urlPath, operation) {
|
|
24
|
+
const fromExt = operation['x-tree-segments'];
|
|
25
|
+
if (Array.isArray(fromExt) && fromExt.every((part) => typeof part === 'string')) {
|
|
26
|
+
return fromExt;
|
|
27
|
+
}
|
|
28
|
+
return urlPath.split('/').filter(Boolean);
|
|
29
|
+
}
|
|
30
|
+
/**
|
|
31
|
+
* Export OpenAPI with real URL paths (correct for clients) and tags/folders
|
|
32
|
+
* matching the docs sidebar (`x-tree-segments`).
|
|
33
|
+
*/
|
|
34
|
+
function toTreeOrderedOpenApi(raw) {
|
|
35
|
+
const sourcePaths = (raw.paths ?? {});
|
|
36
|
+
const exportPaths = {};
|
|
37
|
+
const tagNames = new Set();
|
|
38
|
+
for (const [urlPath, pathItem] of Object.entries(sourcePaths)) {
|
|
39
|
+
if (!pathItem || typeof pathItem !== 'object')
|
|
40
|
+
continue;
|
|
41
|
+
const exportPathItem = {};
|
|
42
|
+
for (const [key, value] of Object.entries(pathItem)) {
|
|
43
|
+
if (!HTTP_METHODS.has(key) || !value || typeof value !== 'object') {
|
|
44
|
+
if (!HTTP_METHODS.has(key))
|
|
45
|
+
exportPathItem[key] = stripViewerExtensions(value);
|
|
46
|
+
continue;
|
|
47
|
+
}
|
|
48
|
+
const operation = value;
|
|
49
|
+
const segments = treeSegmentsForOperation(urlPath, operation);
|
|
50
|
+
const cleaned = stripViewerExtensions(operation);
|
|
51
|
+
const tagParts = segments.filter((part) => !part.startsWith('{'));
|
|
52
|
+
const tag = tagParts.length ? tagParts.join(' / ') : 'API';
|
|
53
|
+
cleaned.tags = [tag];
|
|
54
|
+
tagNames.add(tag);
|
|
55
|
+
exportPathItem[key] = cleaned;
|
|
56
|
+
}
|
|
57
|
+
exportPaths[urlPath] = exportPathItem;
|
|
58
|
+
}
|
|
59
|
+
const orderedPaths = {};
|
|
60
|
+
for (const key of Object.keys(exportPaths).sort((a, b) => a.localeCompare(b))) {
|
|
61
|
+
orderedPaths[key] = exportPaths[key];
|
|
62
|
+
}
|
|
63
|
+
const info = stripViewerExtensions(raw.info ?? { title: 'API', version: '0.0.0' });
|
|
64
|
+
const tags = [...tagNames].sort((a, b) => a.localeCompare(b)).map((name) => ({ name }));
|
|
65
|
+
return {
|
|
66
|
+
openapi: raw.openapi || '3.0.3',
|
|
67
|
+
info,
|
|
68
|
+
...(raw.servers ? { servers: stripViewerExtensions(raw.servers) } : {}),
|
|
69
|
+
tags,
|
|
70
|
+
paths: orderedPaths,
|
|
71
|
+
...(raw.components ? { components: stripViewerExtensions(raw.components) } : {}),
|
|
72
|
+
};
|
|
73
|
+
}
|
|
21
74
|
function readStrippedOpenApiJson() {
|
|
22
75
|
const specPath = (0, paths_1.getSpecJsonPath)();
|
|
23
76
|
if (!(0, fs_1.existsSync)(specPath))
|
|
24
77
|
return null;
|
|
25
78
|
const raw = JSON.parse((0, fs_1.readFileSync)(specPath, 'utf8'));
|
|
26
|
-
return `${JSON.stringify(
|
|
79
|
+
return `${JSON.stringify(toTreeOrderedOpenApi(raw), null, 2)}\n`;
|
|
27
80
|
}
|