@t0.labs/daxta 0.4.4 → 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 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 # choose sidebar folder order for a path
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
- ### Sidebar order (`daxta tree`)
99
+ ### Docs presentation (`daxta install` / `daxta migrate` / `daxta tree`)
100
100
 
101
- Pick a path and how it should nest under `/docs`:
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
- /v1/admin/baskets
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
- Saves `treeLayout` / `treePathOverrides` in `daxta.config.ts`. Then `daxta build`.
116
+ Then `daxta build` to refresh `/docs` and export.
111
117
 
112
118
 
113
119
 
@@ -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 { color: #8a2e2e; font-size: 13px; padding: 8px 0; white-space: pre-wrap; }
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: 8px 0; }
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 walk = (value) => {
1243
- if (Array.isArray(value)) return value.map(walk);
1244
- if (!value || typeof value !== "object") return value;
1245
- const out = {};
1246
- for (const [key, child] of Object.entries(value)) {
1247
- if (VIEWER_EXTENSIONS.has(key)) continue;
1248
- out[key] = walk(child);
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
- return out;
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 = () => {
@@ -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 { title: (0, catalog_1.defaultTitle)(method, pathTemplate), fields };
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 exampleLabel(hit) {
346
- return `${hit.status} - ${(0, catalog_1.caseName)(hit.test)}`;
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: (0, catalog_1.caseName)(hit.test),
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: docs.title,
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: {} } } };
@@ -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: "resource-first" | "url-order";
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;
@@ -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 parts = pathTemplate.split('/').filter(Boolean);
50
- if (parts.length >= 3 && /^v\d+$/i.test(parts[0]) && config.treeLayout === 'resource-first') {
51
- return [parts[0], parts[2], parts[1], ...parts.slice(3)];
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 = pathSegments(pathTemplate).filter((part) => !/^v\d+$/i.test(part));
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
- return (test
162
+ let rest = test
108
163
  .replace(/^.*?\[(?:GET|POST|PUT|PATCH|DELETE|UPDATE|UPSERT)\]\s*(?:\(integration\))?\s*/i, '')
109
- .replace(/^(POSITIVE CASES|SEMANTIC ERROR CASES(?:\s*-\s*AUTH)?|INVALID CASES|OMITTED(?: FIELD)? CASES)\s+/i, '')
110
- .trim() || test);
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
  }
@@ -114,7 +114,10 @@ export default defineConfig({
114
114
  controllersRoot: 'src',
115
115
  outDir: 'daxta/out',
116
116
  docsPath: '/docs',
117
- treeLayout: 'resource-first',
117
+ treeLayout: 'role-resource',
118
+ treeSkipParams: true,
119
+ treeMaxDepth: null,
120
+ exampleLabelStyle: 'status-title-case',
118
121
  fieldsFile: 'daxta/out/daxta.fields.json',
119
122
  });
120
123
  `;
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 (force project upgrade)
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)());
@@ -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;
@@ -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();
@@ -1,12 +1,10 @@
1
1
  export type TreeWizardOptions = {
2
2
  path?: string;
3
3
  layout?: string;
4
- /** Called from install — no extra banner, always ask layout when TTY */
5
4
  embedded?: boolean;
6
5
  yes?: boolean;
7
6
  };
8
7
  /**
9
- * Interactive sidebar layout wizard.
10
- * Also used at the end of `daxta install` so the question is not a hidden separate command.
8
+ * Company docs presentation wizard — install / migrate / `daxta tree`.
11
9
  */
12
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 urlOrderSegments(pathTemplate) {
27
- return pathTemplate.split('/').filter(Boolean);
28
- }
29
- function resourceFirstSegments(pathTemplate) {
30
- const parts = urlOrderSegments(pathTemplate);
31
- if (parts.length >= 3 && /^v\d+$/i.test(parts[0])) {
32
- return [parts[0], parts[2], parts[1], ...parts.slice(3)];
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 {
@@ -66,7 +55,7 @@ function listKnownPaths() {
66
55
  fromSpec.add(pathTemplate);
67
56
  }
68
57
  catch {
69
- // controllers may not parse yet
58
+ // ignore
70
59
  }
71
60
  return [...fromSpec].sort((a, b) => a.localeCompare(b));
72
61
  }
@@ -87,8 +76,7 @@ async function pickPath(flagPath) {
87
76
  return normalizePathInput(flagPath);
88
77
  const known = listKnownPaths();
89
78
  printPathChoices(known);
90
- const answer = await prompt(` ${ui_1.c.yellow('?')} ${ui_1.c.bold('Path')} to arrange in the sidebar\n` +
91
- ` ${ui_1.c.dim('number · /v1/admin/baskets · 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('›')} `);
92
80
  if (!answer || /^n(o)?$/i.test(answer))
93
81
  return null;
94
82
  if (/^\d+$/.test(answer)) {
@@ -99,136 +87,170 @@ async function pickPath(flagPath) {
99
87
  }
100
88
  return normalizePathInput(answer);
101
89
  }
102
- async function pickGlobalLayout(current) {
103
- const sample = '/v1/admin/baskets';
90
+ async function pickLayout(current) {
91
+ const sample = '/v1/admin/baskets/{id}/lock';
104
92
  console.log('');
105
- console.log(` ${ui_1.c.bold('Docs sidebar layout')}`);
106
- console.log(` ${ui_1.c.dim('Example')} ${ui_1.c.cyan(sample)}`);
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)}`);
107
95
  console.log('');
108
- console.log(` ${ui_1.c.cyan('1')} resource-first`);
109
- console.log(` ${(0, config_edit_1.previewTree)(resourceFirstSegments(sample))}`);
110
- console.log(` ${ui_1.c.dim('v1 → baskets → admin')}`);
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})')}`);
111
99
  console.log('');
112
- console.log(` ${ui_1.c.cyan('2')} url-order`);
113
- console.log(` ${(0, config_edit_1.previewTree)(urlOrderSegments(sample))}`);
114
- console.log(` ${ui_1.c.dim('v1 → admin → baskets')}`);
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')}`);
115
103
  console.log('');
116
104
  console.log(` ${ui_1.c.cyan('3')} keep ${ui_1.c.dim(`(${current})`)}`);
117
- const answer = await prompt(` ${ui_1.c.yellow('?')} How should folders nest under /docs?\n ${ui_1.c.cyan('›')} `);
105
+ const answer = await prompt(` ${ui_1.c.yellow('?')} Choose\n ${ui_1.c.cyan('›')} `);
118
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))
119
140
  return null;
120
- if (answer === '1' || /^resource/i.test(answer))
121
- return 'resource-first';
122
- if (answer === '2' || /^url/i.test(answer))
123
- return 'url-order';
124
- throw new Error(`Unknown layout choice: ${answer}`);
141
+ const n = Number(answer);
142
+ if (!Number.isFinite(n) || n < 1)
143
+ throw new Error(`Invalid depth: ${answer}`);
144
+ return Math.floor(n);
125
145
  }
126
- function layoutChoicesFor(pathTemplate) {
127
- const url = urlOrderSegments(pathTemplate);
128
- const resource = resourceFirstSegments(pathTemplate);
129
- const area = areaFirstSegments(pathTemplate);
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}`);
166
+ }
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);
130
170
  const choices = [
131
- { id: 'url', label: 'URL order', segments: url },
132
- { id: 'resource', label: 'Resource-first', segments: resource },
171
+ { id: 'role', label: 'role → resource', segments: role },
172
+ { id: 'resource', label: 'resource → role', segments: resource },
173
+ { id: 'custom', label: 'Custom segments', segments: role },
133
174
  ];
134
- if (area.join('/') !== url.join('/') && area.join('/') !== resource.join('/')) {
135
- choices.push({ id: 'area', label: 'Area-first (admin/device/…)', segments: area });
136
- }
137
- choices.push({ id: 'custom', label: 'Custom segments', segments: url });
138
175
  return choices;
139
176
  }
140
- async function pickSegments(pathTemplate) {
141
- const choices = layoutChoicesFor(pathTemplate);
177
+ async function pickSegments(pathTemplate, layout, skipParams, maxDepth) {
178
+ const choices = layoutChoicesFor(pathTemplate, layout, skipParams, maxDepth);
142
179
  console.log('');
143
- console.log(` ${ui_1.c.bold('Sidebar for')} ${ui_1.c.cyan(pathTemplate)}`);
144
- console.log(` ${ui_1.c.dim('Which nesting do you want?')}`);
180
+ console.log(` ${ui_1.c.bold('Override')} ${ui_1.c.cyan(pathTemplate)}`);
145
181
  choices.forEach((choice, index) => {
146
- const mark = ui_1.c.cyan(String(index + 1));
147
- 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)}`);
148
183
  console.log(` ${(0, config_edit_1.previewTree)(choice.segments)}`);
149
184
  });
150
185
  const answer = await prompt(` ${ui_1.c.yellow('?')} Choose\n ${ui_1.c.cyan('›')} `);
151
186
  if (!answer || /^n(o)?$/i.test(answer))
152
187
  return null;
153
- const index = /^\d+$/.test(answer)
154
- ? Number(answer) - 1
155
- : choices.findIndex((choice) => choice.id === answer || choice.label.toLowerCase().startsWith(answer.toLowerCase()));
188
+ const index = /^\d+$/.test(answer) ? Number(answer) - 1 : -1;
156
189
  const selected = choices[index];
157
190
  if (!selected)
158
191
  throw new Error(`Unknown choice: ${answer}`);
159
192
  if (selected.id !== 'custom')
160
193
  return selected.segments;
161
- const typed = await prompt(` ${ui_1.c.yellow('?')} Segments in order ${ui_1.c.dim('(space or › separated)')}\n` +
162
- ` ${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('›')} `);
163
195
  if (!typed)
164
196
  return null;
165
- return typed
166
- .split(/›|>|,|\s+/)
167
- .map((part) => part.trim())
168
- .filter(Boolean);
169
- }
170
- function saveLayout(configPath, layout) {
171
- (0, config_edit_1.upsertConfigValue)(configPath, 'treeLayout', (0, config_edit_1.formatTsString)(layout));
172
- }
173
- function saveOverride(configPath, pathTemplate, segments) {
174
- const overrides = (0, config_edit_1.readTreePathOverrides)();
175
- overrides[pathTemplate] = segments;
176
- (0, config_edit_1.upsertConfigValue)(configPath, 'treePathOverrides', (0, config_edit_1.formatTsStringRecord)(overrides));
197
+ return typed.split(/›|>|,|\s+/).map((part) => part.trim()).filter(Boolean);
177
198
  }
178
199
  /**
179
- * Interactive sidebar layout wizard.
180
- * Also used at the end of `daxta install` so the question is not a hidden separate command.
200
+ * Company docs presentation wizard — install / migrate / `daxta tree`.
181
201
  */
182
202
  async function runTreeWizard(options = {}) {
183
203
  if (options.yes || !process.stdin.isTTY) {
184
- if (!options.embedded) {
204
+ if (!options.embedded)
185
205
  console.log(` ${ui_1.c.dim('tree wizard skipped (non-interactive)')}`);
186
- }
187
206
  return;
188
207
  }
189
208
  if (!options.embedded)
190
- (0, ui_1.banner)('DAxTA tree', 'sidebar folder order');
209
+ (0, ui_1.banner)('DAxTA tree', 'docs presentation');
191
210
  const configPath = (0, config_edit_1.findDaxtaConfigPath)();
192
- if (!configPath) {
211
+ if (!configPath)
193
212
  throw new Error('No daxta.config.ts found. Run `daxta install` first.');
194
- }
195
213
  (0, config_1.resetConfig)();
196
214
  const config = (0, config_1.getConfig)(true);
197
215
  console.log('');
198
- console.log(` ${ui_1.c.yellow(ui_1.c.bold('?'))} ${ui_1.c.bold('Sidebar')} ${ui_1.c.dim('— how /docs folders nest')}`);
199
- if (options.layout === 'resource-first' || options.layout === 'url-order') {
200
- saveLayout(configPath, options.layout);
201
- console.log(` ${ui_1.c.green('✔')} treeLayout → ${ui_1.c.cyan(options.layout)}`);
202
- }
203
- else {
204
- const layout = await pickGlobalLayout(config.treeLayout);
205
- if (layout) {
206
- saveLayout(configPath, layout);
207
- console.log(` ${ui_1.c.green('✔')} treeLayout → ${ui_1.c.cyan(layout)}`);
208
- }
209
- else {
210
- console.log(` ${ui_1.c.dim('kept')} treeLayout ${ui_1.c.cyan(config.treeLayout)}`);
211
- }
212
- }
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)}`);
213
235
  const customize = options.path
214
236
  ? 'y'
215
- : await prompt(` ${ui_1.c.yellow('?')} Customize a specific path now?\n` +
216
- ` ${ui_1.c.dim('Y')} yes · ${ui_1.c.dim('n')} later ${ui_1.c.dim('(daxta tree)')}\n ${ui_1.c.cyan('›')} `);
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('›')} `);
217
239
  if (customize && !/^n(o)?$/i.test(customize)) {
218
240
  const pathTemplate = await pickPath(options.path);
219
241
  if (pathTemplate) {
220
- const segments = await pickSegments(pathTemplate);
242
+ const segments = await pickSegments(pathTemplate, layout, skipParams, maxDepth);
221
243
  if (segments?.length) {
222
- saveOverride(configPath, pathTemplate, segments);
223
- console.log('');
224
- console.log(` ${ui_1.c.green('✔')} ${ui_1.c.cyan(pathTemplate)}`);
225
- console.log(` ${(0, config_edit_1.previewTree)(segments)}`);
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)}`);
226
248
  }
227
249
  }
228
250
  }
229
251
  if (!options.embedded) {
230
- console.log(` ${ui_1.c.dim('saved to')} ${configPath}`);
231
- console.log(` ${ui_1.c.dim('refresh docs:')} ${ui_1.c.cyan('daxta build')}`);
252
+ console.log(` ${ui_1.c.dim('saved')} ${configPath}`);
253
+ console.log(` ${ui_1.c.dim('refresh')} ${ui_1.c.cyan('daxta build')}`);
232
254
  console.log('');
233
255
  }
234
256
  }
package/dist/config.d.ts CHANGED
@@ -1,4 +1,8 @@
1
- export type TreeLayout = 'resource-first' | 'url-order';
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
- treeLayout?: TreeLayout;
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-first',
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;
@@ -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(stripViewerExtensions(raw), null, 2)}\n`;
79
+ return `${JSON.stringify(toTreeOrderedOpenApi(raw), null, 2)}\n`;
27
80
  }
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@t0.labs/daxta",
3
- "version": "0.4.4",
3
+ "version": "0.4.5",
4
4
  "description": "DAxTA \u2014 docs from Nest integration traffic + DTO field CLI / Try-it",
5
5
  "license": "MIT",
6
6
  "repository": {