@t0.labs/daxta 0.4.24 → 0.5.1
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 +139 -91
- package/assets/empty.html +6 -5
- package/assets/example.html +237 -246
- package/assets/favicon.png +0 -0
- package/assets/favicon.svg +16 -0
- package/assets/logo.png +0 -0
- package/assets/viewer.html +164 -113
- package/dist/build/build-spec.d.ts +3 -1
- package/dist/build/build-spec.js +11 -6
- package/dist/cli/install.js +16 -13
- package/dist/cli/main.js +15 -15
- package/dist/cli/migrate.js +2 -2
- package/dist/cli/titles.js +3 -3
- package/dist/cli/tree.d.ts +1 -1
- package/dist/cli/tree.js +4 -4
- package/dist/cli/ui.js +1 -1
- package/dist/cli/uninstall.js +16 -6
- package/dist/config.d.ts +3 -3
- package/dist/config.js +4 -4
- package/dist/index.d.ts +2 -2
- package/dist/index.js +4 -1
- package/dist/jest/global-teardown.d.ts +2 -2
- package/dist/jest/global-teardown.js +3 -3
- package/dist/jest/reporter.d.ts +1 -1
- package/dist/jest/reporter.js +6 -7
- package/dist/serve/index.d.ts +2 -2
- package/dist/serve/index.js +8 -6
- package/dist/serve/middleware.d.ts +4 -4
- package/dist/serve/middleware.js +6 -6
- package/dist/serve/paths.d.ts +8 -0
- package/dist/serve/paths.js +22 -4
- package/package.json +2 -2
package/dist/cli/install.js
CHANGED
|
@@ -110,17 +110,20 @@ function writeConfig(cwd, dryRun) {
|
|
|
110
110
|
const body = `import { defineConfig } from '@t0.labs/daxta';
|
|
111
111
|
|
|
112
112
|
export default defineConfig({
|
|
113
|
+
specInfo: () => ({
|
|
114
|
+
title: 'API',
|
|
115
|
+
version: '1.0.0',
|
|
116
|
+
}),
|
|
113
117
|
workspace: 'API',
|
|
114
118
|
baseUrl: 'http://localhost:3000',
|
|
115
119
|
controllersRoot: 'src',
|
|
116
|
-
outDir: 'daxta/out',
|
|
117
|
-
docsPath: '/docs',
|
|
120
|
+
outDir: '.daxta/out',
|
|
121
|
+
docsPath: '/api-docs',
|
|
118
122
|
treeLayout: 'role-resource',
|
|
119
123
|
treeSkipParams: true,
|
|
120
124
|
exampleLabelStyle: 'status-title-case',
|
|
121
|
-
fieldsFile: 'daxta/out/
|
|
122
|
-
viewerStoreFile: 'daxta/viewer-store.json',
|
|
123
|
-
// Multi-base Try-it presets (docs env picker). Secrets stay in viewer-store / UI.
|
|
125
|
+
fieldsFile: '.daxta/out/fields.json',
|
|
126
|
+
viewerStoreFile: '.daxta/viewer-store.json',
|
|
124
127
|
envPresets: {
|
|
125
128
|
local: { baseUrl: 'http://localhost:3000' },
|
|
126
129
|
staging: { baseUrl: 'https://api.staging.example.com' },
|
|
@@ -134,7 +137,7 @@ export default defineConfig({
|
|
|
134
137
|
}
|
|
135
138
|
function ensureGitignore(cwd, dryRun) {
|
|
136
139
|
const gitignorePath = path.join(cwd, '.gitignore');
|
|
137
|
-
const entries = ['daxta/out/', 'daxta/viewer-store.json', '**/.jest.daxta.runtime.json'];
|
|
140
|
+
const entries = ['.daxta/out/', '.daxta/viewer-store.json', '**/.jest.daxta.runtime.json'];
|
|
138
141
|
if (!(0, fs_1.existsSync)(gitignorePath)) {
|
|
139
142
|
if (!dryRun)
|
|
140
143
|
(0, fs_1.writeFileSync)(gitignorePath, `${entries.join('\n')}\n`);
|
|
@@ -145,7 +148,7 @@ function ensureGitignore(cwd, dryRun) {
|
|
|
145
148
|
const added = [];
|
|
146
149
|
let next = text;
|
|
147
150
|
for (const entry of entries) {
|
|
148
|
-
if (lines.has(entry) || lines.has('daxta/') || (entry === 'daxta/out/' && lines.has('daxta/out')))
|
|
151
|
+
if (lines.has(entry) || lines.has('.daxta/') || lines.has('daxta/') || (entry === '.daxta/out/' && (lines.has('.daxta/out') || lines.has('daxta/out/'))))
|
|
149
152
|
continue;
|
|
150
153
|
next = next.endsWith('\n') ? `${next}${entry}\n` : `${next}\n${entry}\n`;
|
|
151
154
|
added.push(entry);
|
|
@@ -225,7 +228,7 @@ async function installDaxta(options = {}) {
|
|
|
225
228
|
await (0, ui_1.step)('Package dependency', () => 'already installed — skip add', { paceMs, n: 1, of });
|
|
226
229
|
}
|
|
227
230
|
}
|
|
228
|
-
(0, ui_1.phase)(2, of, 'Workspace files', 'config, gitignore, docs env flag');
|
|
231
|
+
(0, ui_1.phase)(2, of, 'Workspace files', 'config, gitignore, API docs env flag');
|
|
229
232
|
await (0, ui_1.step)('Write daxta.config.ts', () => {
|
|
230
233
|
const { created, rel } = writeConfig(cwd, dryRun);
|
|
231
234
|
return created ? `created ${rel}` : `exists · ${rel}`;
|
|
@@ -246,8 +249,8 @@ async function installDaxta(options = {}) {
|
|
|
246
249
|
}, { paceMs, n: 2, of });
|
|
247
250
|
await (0, ui_1.step)('Prepare output dir', () => {
|
|
248
251
|
if (!dryRun)
|
|
249
|
-
(0, fs_1.mkdirSync)(path.join(cwd, 'daxta', 'out'), { recursive: true });
|
|
250
|
-
return 'daxta/out';
|
|
252
|
+
(0, fs_1.mkdirSync)(path.join(cwd, '.daxta', 'out'), { recursive: true });
|
|
253
|
+
return '.daxta/out';
|
|
251
254
|
}, { paceMs, n: 2, of });
|
|
252
255
|
await (0, ui_1.step)('Update .gitignore', () => {
|
|
253
256
|
const notes = ensureGitignore(cwd, dryRun);
|
|
@@ -334,14 +337,14 @@ async function installDaxta(options = {}) {
|
|
|
334
337
|
else {
|
|
335
338
|
await (0, ui_1.step)('Attach test hooks', () => 'skipped', { paceMs, n: 4, of });
|
|
336
339
|
}
|
|
337
|
-
(0, ui_1.phase)(5, of, '
|
|
340
|
+
(0, ui_1.phase)(5, of, 'API docs taste', 'sidebar folders + test titles for the viewer');
|
|
338
341
|
if (!dryRun) {
|
|
339
342
|
await (0, tree_1.runTreeWizard)({ embedded: true, yes: Boolean(options.yes) });
|
|
340
343
|
await (0, titles_1.runTitleCheck)({ cwd, yes: Boolean(options.yes) });
|
|
341
344
|
}
|
|
342
345
|
(0, ui_1.box)('Ready', [
|
|
343
346
|
`${ui_1.c.mint('✔')} ${ui_1.c.bold(project)} · DAxTA ${ui_1.c.gold(`v${version}`)}`,
|
|
344
|
-
`${ui_1.c.dim('docs')}
|
|
347
|
+
`${ui_1.c.dim('api docs')} ${ui_1.c.ice('/api-docs')} · ${ui_1.c.ice('DAXTA_DOCS=true')}`,
|
|
345
348
|
`${ui_1.c.dim('tests')} same script — titles first, spec after`,
|
|
346
349
|
`${ui_1.c.dim('retune')} ${ui_1.c.ice('daxta tree')} · ${ui_1.c.ice('daxta titles')}`,
|
|
347
350
|
]);
|
|
@@ -353,7 +356,7 @@ async function installDaxta(options = {}) {
|
|
|
353
356
|
},
|
|
354
357
|
{
|
|
355
358
|
cmd: `${pm} start:dev`,
|
|
356
|
-
why: 'open /docs (DAXTA_DOCS already in .env)',
|
|
359
|
+
why: 'open /api-docs (DAXTA_DOCS already in .env)',
|
|
357
360
|
},
|
|
358
361
|
]);
|
|
359
362
|
}
|
package/dist/cli/main.js
CHANGED
|
@@ -15,24 +15,24 @@ const ui_1 = require("./ui");
|
|
|
15
15
|
function usage() {
|
|
16
16
|
const cmd = (name) => ui_1.c.bold(ui_1.c.ice(name));
|
|
17
17
|
console.log('');
|
|
18
|
-
console.log(` ${ui_1.c.bold(ui_1.c.ice('DAxTA'))}
|
|
18
|
+
console.log(` ${ui_1.c.bold(ui_1.c.ice('DAxTA'))}`);
|
|
19
|
+
console.log(` ${ui_1.c.dim('Tested behavior. Trusted API docs.')}`);
|
|
19
20
|
console.log('');
|
|
20
21
|
console.log(` ${ui_1.c.gold('Setup')}`);
|
|
21
|
-
console.log(` ${cmd('daxta install')}
|
|
22
|
-
console.log(` ${cmd('daxta
|
|
23
|
-
console.log(` ${cmd('daxta
|
|
24
|
-
console.log(` ${cmd('daxta migrate')} ${ui_1.c.dim('[--yes]')}`);
|
|
22
|
+
console.log(` ${cmd('daxta install')} ${ui_1.c.dim('Install DAxTA in this project')}`);
|
|
23
|
+
console.log(` ${cmd('daxta uninstall')} ${ui_1.c.dim('Remove DAxTA from this project')}`);
|
|
24
|
+
console.log(` ${cmd('daxta migrate')} ${ui_1.c.dim('Upgrade project wiring after a package bump')}`);
|
|
25
25
|
console.log('');
|
|
26
|
-
console.log(` ${ui_1.c.gold('
|
|
27
|
-
console.log(` ${cmd('daxta
|
|
28
|
-
console.log(` ${cmd('daxta
|
|
29
|
-
console.log(` ${cmd('daxta
|
|
30
|
-
console.log(` ${cmd('daxta
|
|
31
|
-
console.log(` ${cmd('daxta
|
|
26
|
+
console.log(` ${ui_1.c.gold('API docs')}`);
|
|
27
|
+
console.log(` ${cmd('daxta generate')} ${ui_1.c.dim('Generate API documentation from test execution')}`);
|
|
28
|
+
console.log(` ${cmd('daxta serve')} ${ui_1.c.dim('Serve API documentation locally')}`);
|
|
29
|
+
console.log(` ${cmd('daxta tree')} ${ui_1.c.dim('Configure API docs sidebar layout')}`);
|
|
30
|
+
console.log(` ${cmd('daxta titles')} ${ui_1.c.dim('Align test titles with API docs examples')}`);
|
|
31
|
+
console.log(` ${cmd('daxta test')} ${ui_1.c.dim('Run the project test script (Jest stays parent)')}`);
|
|
32
32
|
console.log('');
|
|
33
33
|
console.log(` ${ui_1.c.gold('Try-it')}`);
|
|
34
|
-
console.log(` ${cmd('daxta fields')}
|
|
35
|
-
console.log(` ${cmd('daxta call')}
|
|
34
|
+
console.log(` ${cmd('daxta fields')} ${ui_1.c.dim('Export API field map')}`);
|
|
35
|
+
console.log(` ${cmd('daxta call')} ${ui_1.c.dim('Send a Try-it request from the CLI')}`);
|
|
36
36
|
console.log('');
|
|
37
37
|
console.log(` ${ui_1.c.mint('First time')} ${ui_1.c.ice('pnpm dlx @t0.labs/daxta install')}`);
|
|
38
38
|
console.log('');
|
|
@@ -126,8 +126,8 @@ async function main() {
|
|
|
126
126
|
await (0, test_1.runDaxtaTest)({ argv });
|
|
127
127
|
return;
|
|
128
128
|
}
|
|
129
|
-
if (command === 'build') {
|
|
130
|
-
(0, build_spec_1.
|
|
129
|
+
if (command === 'generate' || command === 'build') {
|
|
130
|
+
(0, build_spec_1.generateApiDocs)({ requireHits: true });
|
|
131
131
|
return;
|
|
132
132
|
}
|
|
133
133
|
if (command === 'serve') {
|
package/dist/cli/migrate.js
CHANGED
|
@@ -181,9 +181,9 @@ function migrateMainApiDocs(cwd) {
|
|
|
181
181
|
function migrateConfigDefaults(configPath, configText) {
|
|
182
182
|
const notes = [];
|
|
183
183
|
const fields = readStringField(configText, 'fieldsFile');
|
|
184
|
-
const outDir = readStringField(configText, 'outDir') || 'daxta/out';
|
|
184
|
+
const outDir = readStringField(configText, 'outDir') || '.daxta/out';
|
|
185
185
|
if (fields === 'daxta.fields.json' || fields === './daxta.fields.json') {
|
|
186
|
-
const next = `${outDir.replace(/\\/g, '/').replace(/\/$/, '')}/
|
|
186
|
+
const next = `${outDir.replace(/\\/g, '/').replace(/\/$/, '')}/fields.json`;
|
|
187
187
|
if (upsertConfigField(configPath, 'fieldsFile', next)) {
|
|
188
188
|
notes.push(`fieldsFile → ${next}`);
|
|
189
189
|
}
|
package/dist/cli/titles.js
CHANGED
|
@@ -128,17 +128,17 @@ async function runTitleCheck(options) {
|
|
|
128
128
|
(0, scan_1.printNamingFindings)(report, ui_1.c);
|
|
129
129
|
return options.strict ? 1 : 0;
|
|
130
130
|
}
|
|
131
|
-
(0, ui_1.banner)('Test naming', 'runs before Jest — docs / Postman labels');
|
|
131
|
+
(0, ui_1.banner)('Test naming', 'runs before Jest — API docs / Postman labels');
|
|
132
132
|
console.log(` ${ui_1.c.dim('Title')} Create Mock Tbs — POST /v1/admin/mock-tbs`);
|
|
133
133
|
console.log(` ${ui_1.c.dim('it()+')} creates mock tbs when cyprus payload shape`);
|
|
134
134
|
console.log(` ${ui_1.c.dim('it()-')} returns error when tax id already exists`);
|
|
135
|
-
console.log(` ${ui_1.c.dim('
|
|
135
|
+
console.log(` ${ui_1.c.dim('label')} 201 — cyprus payload shape`);
|
|
136
136
|
console.log(` ${ui_1.c.gold(String(total))} to review — ${ui_1.c.ice('y')} one recommended, ${ui_1.c.ice('a')} all remaining, ${ui_1.c.ice('s')} skip.`);
|
|
137
137
|
let written = 0;
|
|
138
138
|
let skipped = 0;
|
|
139
139
|
for (let i = 0; i < report.titles.length; i += 1) {
|
|
140
140
|
const finding = report.titles[i];
|
|
141
|
-
const choice = await pickFromSuggestions(finding, `docs would show ${finding.path}`, test_title_1.isHumanOperationTitle);
|
|
141
|
+
const choice = await pickFromSuggestions(finding, `API docs would show ${finding.path}`, test_title_1.isHumanOperationTitle);
|
|
142
142
|
if (choice === 'all') {
|
|
143
143
|
const rest = applyAllRecommended(cwd, report.titles, report.cases, i, 0);
|
|
144
144
|
written += rest.written;
|
package/dist/cli/tree.d.ts
CHANGED
|
@@ -5,6 +5,6 @@ export type TreeWizardOptions = {
|
|
|
5
5
|
yes?: boolean;
|
|
6
6
|
};
|
|
7
7
|
/**
|
|
8
|
-
* Company docs presentation wizard — install / migrate / `daxta tree`.
|
|
8
|
+
* Company API docs presentation wizard — install / migrate / `daxta tree`.
|
|
9
9
|
*/
|
|
10
10
|
export declare function runTreeWizard(options?: TreeWizardOptions): Promise<void>;
|
package/dist/cli/tree.js
CHANGED
|
@@ -169,7 +169,7 @@ async function pickSegments(pathTemplate, layout, skipParams) {
|
|
|
169
169
|
return typed.split(/›|>|,|\s+/).map((part) => part.trim()).filter(Boolean);
|
|
170
170
|
}
|
|
171
171
|
/**
|
|
172
|
-
* Company docs presentation wizard — install / migrate / `daxta tree`.
|
|
172
|
+
* Company API docs presentation wizard — install / migrate / `daxta tree`.
|
|
173
173
|
*/
|
|
174
174
|
async function runTreeWizard(options = {}) {
|
|
175
175
|
if (options.yes || !process.stdin.isTTY) {
|
|
@@ -178,14 +178,14 @@ async function runTreeWizard(options = {}) {
|
|
|
178
178
|
return;
|
|
179
179
|
}
|
|
180
180
|
if (!options.embedded)
|
|
181
|
-
(0, ui_1.banner)('DAxTA tree', 'docs presentation');
|
|
181
|
+
(0, ui_1.banner)('DAxTA tree', 'API docs presentation');
|
|
182
182
|
const configPath = (0, config_edit_1.findDaxtaConfigPath)();
|
|
183
183
|
if (!configPath)
|
|
184
184
|
throw new Error('No daxta.config.ts found. Run `daxta install` first.');
|
|
185
185
|
(0, config_1.resetConfig)();
|
|
186
186
|
const config = (0, config_1.getConfig)(true);
|
|
187
187
|
console.log('');
|
|
188
|
-
console.log(` ${ui_1.c.gold(ui_1.c.bold('?'))} ${ui_1.c.bold('
|
|
188
|
+
console.log(` ${ui_1.c.gold(ui_1.c.bold('?'))} ${ui_1.c.bold('API docs presentation')} ${ui_1.c.dim('— sidebar + OpenAPI export')}`);
|
|
189
189
|
let layout = (0, config_1.normalizeTreeLayout)(options.layout === 'resource-first' || options.layout === 'resource-role'
|
|
190
190
|
? 'resource-role'
|
|
191
191
|
: options.layout === 'url-order' || options.layout === 'role-resource'
|
|
@@ -219,7 +219,7 @@ async function runTreeWizard(options = {}) {
|
|
|
219
219
|
}
|
|
220
220
|
if (!options.embedded) {
|
|
221
221
|
console.log(` ${ui_1.c.dim('saved')} ${configPath}`);
|
|
222
|
-
console.log(` ${ui_1.c.dim('refresh')} ${ui_1.c.ice('daxta
|
|
222
|
+
console.log(` ${ui_1.c.dim('refresh')} ${ui_1.c.ice('daxta generate')}`);
|
|
223
223
|
console.log('');
|
|
224
224
|
}
|
|
225
225
|
}
|
package/dist/cli/ui.js
CHANGED
|
@@ -74,7 +74,7 @@ function divider(width = 52) {
|
|
|
74
74
|
}
|
|
75
75
|
function splash(options) {
|
|
76
76
|
const title = 'DAxTA';
|
|
77
|
-
const tag = '
|
|
77
|
+
const tag = 'Tested behavior. Trusted API docs.';
|
|
78
78
|
const meta = `v${options.version} · ${options.project}${options.dryRun ? ' · dry-run' : ''}`;
|
|
79
79
|
const inner = 50;
|
|
80
80
|
const pad = (s) => s + ' '.repeat(Math.max(0, inner - s.length));
|
package/dist/cli/uninstall.js
CHANGED
|
@@ -62,7 +62,15 @@ function stripGitignore(cwd, dryRun) {
|
|
|
62
62
|
const gitignorePath = path.join(cwd, '.gitignore');
|
|
63
63
|
if (!(0, fs_1.existsSync)(gitignorePath))
|
|
64
64
|
return [];
|
|
65
|
-
const remove = new Set([
|
|
65
|
+
const remove = new Set([
|
|
66
|
+
'daxta/out/',
|
|
67
|
+
'daxta/',
|
|
68
|
+
'daxta/viewer-store.json',
|
|
69
|
+
'.daxta/out/',
|
|
70
|
+
'.daxta/',
|
|
71
|
+
'.daxta/viewer-store.json',
|
|
72
|
+
'**/.jest.daxta.runtime.json',
|
|
73
|
+
]);
|
|
66
74
|
const before = (0, fs_1.readFileSync)(gitignorePath, 'utf8');
|
|
67
75
|
const lines = before.split(/\r?\n/);
|
|
68
76
|
const kept = lines.filter((line) => !remove.has(line.trim()));
|
|
@@ -232,11 +240,13 @@ async function uninstallDaxta(options = {}) {
|
|
|
232
240
|
(0, fs_1.rmSync)(configPath, { force: true });
|
|
233
241
|
details.push(path.relative(cwd, configPath));
|
|
234
242
|
}
|
|
235
|
-
const
|
|
236
|
-
|
|
237
|
-
if (
|
|
238
|
-
|
|
239
|
-
|
|
243
|
+
for (const dir of ['daxta', '.daxta']) {
|
|
244
|
+
const outDir = path.join(cwd, dir);
|
|
245
|
+
if ((0, fs_1.existsSync)(outDir)) {
|
|
246
|
+
if (!dryRun)
|
|
247
|
+
(0, fs_1.rmSync)(outDir, { recursive: true, force: true });
|
|
248
|
+
details.push(`${dir}/`);
|
|
249
|
+
}
|
|
240
250
|
}
|
|
241
251
|
if (!details.length)
|
|
242
252
|
return 'already gone';
|
package/dist/config.d.ts
CHANGED
|
@@ -19,7 +19,7 @@ export type DaxtaConfig = {
|
|
|
19
19
|
baseUrl?: string;
|
|
20
20
|
/**
|
|
21
21
|
* Multi-base Try-it presets (local / staging / production, …).
|
|
22
|
-
* Seeded into the docs env picker and
|
|
22
|
+
* Seeded into the API docs env picker and `.daxta/viewer-store.json` on first write.
|
|
23
23
|
* Default: `{ local: { baseUrl } }` from `baseUrl`.
|
|
24
24
|
*/
|
|
25
25
|
envPresets?: Record<string, EnvPreset>;
|
|
@@ -42,14 +42,14 @@ export type DaxtaConfig = {
|
|
|
42
42
|
* - status-case → `201 — cyprus payload shape`
|
|
43
43
|
* - status-title-case → `201 — Create Mock Tbs — cyprus payload shape`
|
|
44
44
|
* - full → includes path + POSITIVE CASES + clause
|
|
45
|
-
* Test it() stays `creates mock tbs when cyprus payload shape`; docs take the `when` clause.
|
|
45
|
+
* Test it() stays `creates mock tbs when cyprus payload shape`; API docs take the `when` clause.
|
|
46
46
|
*/
|
|
47
47
|
exampleLabelStyle?: ExampleLabelStyle;
|
|
48
48
|
port?: number;
|
|
49
49
|
fieldsFile?: string;
|
|
50
50
|
docsPath?: string;
|
|
51
51
|
/**
|
|
52
|
-
* Persisted Try-it env/header store (survives rebuild). Default
|
|
52
|
+
* Persisted Try-it env/header store (survives rebuild). Default `.daxta/viewer-store.json`.
|
|
53
53
|
* Served at `{docsPath}/env.json`. Keep out of git if it holds secrets.
|
|
54
54
|
*/
|
|
55
55
|
viewerStoreFile?: string;
|
package/dist/config.js
CHANGED
|
@@ -45,15 +45,15 @@ const DEFAULTS = {
|
|
|
45
45
|
workspace: 'API',
|
|
46
46
|
baseUrl: 'http://localhost:3000',
|
|
47
47
|
controllersRoot: 'src',
|
|
48
|
-
outDir: 'daxta/out',
|
|
48
|
+
outDir: '.daxta/out',
|
|
49
49
|
treeLayout: 'role-resource',
|
|
50
50
|
treeSkipParams: true,
|
|
51
51
|
treePathOverrides: {},
|
|
52
52
|
exampleLabelStyle: 'status-title-case',
|
|
53
53
|
port: 5199,
|
|
54
|
-
fieldsFile: 'daxta
|
|
55
|
-
docsPath: '/docs',
|
|
56
|
-
viewerStoreFile: 'daxta/viewer-store.json',
|
|
54
|
+
fieldsFile: '.daxta/out/fields.json',
|
|
55
|
+
docsPath: '/api-docs',
|
|
56
|
+
viewerStoreFile: '.daxta/viewer-store.json',
|
|
57
57
|
envPresets: {
|
|
58
58
|
local: { baseUrl: 'http://localhost:3000' },
|
|
59
59
|
},
|
package/dist/index.d.ts
CHANGED
|
@@ -1,10 +1,10 @@
|
|
|
1
1
|
export { defineConfig, getConfig, resolveConfig, normalizeTreeLayout, type DaxtaConfig, type EnvPreset, type TreeLayout, type ExampleLabelStyle, type SpecInfo } from './config';
|
|
2
|
-
export { buildDaxtaSpec, buildOpenApi, loadHits, type BuildResult, type Scenario } from './build/build-spec';
|
|
2
|
+
export { generateApiDocs, 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';
|
|
5
5
|
export { dtoRequired, type FieldLocation } from './fields/dto-fields';
|
|
6
6
|
export { buildFieldsFile, writeFieldsFile, readFieldsFile, type FieldsFile } from './fields/export-fields';
|
|
7
|
-
export { apiDocs, apiDocsHandler, serveApiDocs, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath, type ApiDocsHandler, type ApiDocsOptions, } from './serve';
|
|
7
|
+
export { apiDocs, apiDocsHandler, serveApiDocs, getApiDocs, getApiDocUrl, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath, type ApiDocsHandler, type ApiDocsOptions, } from './serve';
|
|
8
8
|
export { runInteractiveCall, runFileCall, executeCall, type CallValues } from './call';
|
|
9
9
|
export { apiTitle, parseOperationLabel, suggestOperationTitles, suggestOperationTitleResult, formatTestTitle, isValidItCase, suggestItCases, docsScenarioClause, type FieldDoc, type OperationDoc, } from './catalog';
|
|
10
10
|
export { installDaxta, type InstallOptions } from './cli/install';
|
package/dist/index.js
CHANGED
|
@@ -1,12 +1,13 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.installDaxta = exports.docsScenarioClause = exports.suggestItCases = exports.isValidItCase = exports.formatTestTitle = exports.suggestOperationTitleResult = exports.suggestOperationTitles = exports.parseOperationLabel = exports.apiTitle = exports.executeCall = exports.runFileCall = exports.runInteractiveCall = exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.serveApiDocs = exports.apiDocsHandler = exports.apiDocs = exports.readFieldsFile = exports.writeFieldsFile = exports.buildFieldsFile = exports.dtoRequired = exports.getHits = exports.clearWorkerHits = exports.flush = exports.install = exports.touchPartialMarker = exports.clearPartialMarker = exports.flushAndRebuild = exports.rebuildFromDisk = exports.loadHits = exports.buildOpenApi = exports.buildDaxtaSpec = exports.normalizeTreeLayout = exports.resolveConfig = exports.getConfig = exports.defineConfig = void 0;
|
|
3
|
+
exports.installDaxta = exports.docsScenarioClause = exports.suggestItCases = exports.isValidItCase = exports.formatTestTitle = exports.suggestOperationTitleResult = exports.suggestOperationTitles = exports.parseOperationLabel = exports.apiTitle = exports.executeCall = exports.runFileCall = exports.runInteractiveCall = exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.getApiDocUrl = exports.getApiDocs = 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.generateApiDocs = 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
8
|
Object.defineProperty(exports, "normalizeTreeLayout", { enumerable: true, get: function () { return config_1.normalizeTreeLayout; } });
|
|
9
9
|
var build_spec_1 = require("./build/build-spec");
|
|
10
|
+
Object.defineProperty(exports, "generateApiDocs", { enumerable: true, get: function () { return build_spec_1.generateApiDocs; } });
|
|
10
11
|
Object.defineProperty(exports, "buildDaxtaSpec", { enumerable: true, get: function () { return build_spec_1.buildDaxtaSpec; } });
|
|
11
12
|
Object.defineProperty(exports, "buildOpenApi", { enumerable: true, get: function () { return build_spec_1.buildOpenApi; } });
|
|
12
13
|
Object.defineProperty(exports, "loadHits", { enumerable: true, get: function () { return build_spec_1.loadHits; } });
|
|
@@ -30,6 +31,8 @@ var serve_1 = require("./serve");
|
|
|
30
31
|
Object.defineProperty(exports, "apiDocs", { enumerable: true, get: function () { return serve_1.apiDocs; } });
|
|
31
32
|
Object.defineProperty(exports, "apiDocsHandler", { enumerable: true, get: function () { return serve_1.apiDocsHandler; } });
|
|
32
33
|
Object.defineProperty(exports, "serveApiDocs", { enumerable: true, get: function () { return serve_1.serveApiDocs; } });
|
|
34
|
+
Object.defineProperty(exports, "getApiDocs", { enumerable: true, get: function () { return serve_1.getApiDocs; } });
|
|
35
|
+
Object.defineProperty(exports, "getApiDocUrl", { enumerable: true, get: function () { return serve_1.getApiDocUrl; } });
|
|
33
36
|
Object.defineProperty(exports, "getDocsBasePath", { enumerable: true, get: function () { return serve_1.getDocsBasePath; } });
|
|
34
37
|
Object.defineProperty(exports, "getHtmlPath", { enumerable: true, get: function () { return serve_1.getHtmlPath; } });
|
|
35
38
|
Object.defineProperty(exports, "getOutDir", { enumerable: true, get: function () { return serve_1.getOutDir; } });
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Optional jest globalTeardown — silent
|
|
3
|
-
*
|
|
2
|
+
* Optional jest globalTeardown — silent generate only.
|
|
3
|
+
* API docs ready is printed by the Jest reporter so we don't own the test process.
|
|
4
4
|
*/
|
|
5
5
|
export default function daxtaGlobalTeardown(): Promise<void>;
|
|
@@ -4,12 +4,12 @@ exports.default = daxtaGlobalTeardown;
|
|
|
4
4
|
const incremental_1 = require("../build/incremental");
|
|
5
5
|
const build_spec_1 = require("../build/build-spec");
|
|
6
6
|
/**
|
|
7
|
-
* Optional jest globalTeardown — silent
|
|
8
|
-
*
|
|
7
|
+
* Optional jest globalTeardown — silent generate only.
|
|
8
|
+
* API docs ready is printed by the Jest reporter so we don't own the test process.
|
|
9
9
|
*/
|
|
10
10
|
async function daxtaGlobalTeardown() {
|
|
11
11
|
try {
|
|
12
|
-
(0, build_spec_1.
|
|
12
|
+
(0, build_spec_1.generateApiDocs)({ silent: true, html: true });
|
|
13
13
|
(0, incremental_1.clearPartialMarker)();
|
|
14
14
|
}
|
|
15
15
|
catch {
|
package/dist/jest/reporter.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/**
|
|
2
|
-
* Jest reporter — only
|
|
2
|
+
* Jest reporter — only generates API docs when the full run completes.
|
|
3
3
|
* During the run we only record hits (superagent hook + flush); no mid-run rebuilds.
|
|
4
4
|
*/
|
|
5
5
|
declare class DaxtaJestReporter {
|
package/dist/jest/reporter.js
CHANGED
|
@@ -6,15 +6,14 @@ const paths_1 = require("../serve/paths");
|
|
|
6
6
|
function printDocsReady(hits, operations) {
|
|
7
7
|
try {
|
|
8
8
|
(0, config_1.resetConfig)();
|
|
9
|
-
|
|
10
|
-
const
|
|
11
|
-
const url = `${config.baseUrl.replace(/\/$/, '')}${docsBase}`;
|
|
9
|
+
(0, config_1.getConfig)(true);
|
|
10
|
+
const url = (0, paths_1.getApiDocUrl)();
|
|
12
11
|
const cyan = (s) => `\x1b[36m${s}\x1b[0m`;
|
|
13
12
|
const green = (s) => `\x1b[32m${s}\x1b[0m`;
|
|
14
13
|
const dim = (s) => `\x1b[2m${s}\x1b[0m`;
|
|
15
14
|
const bold = (s) => `\x1b[1m${s}\x1b[0m`;
|
|
16
15
|
console.log('');
|
|
17
|
-
console.log(` ${bold('
|
|
16
|
+
console.log(` ${bold('API docs ready')}`);
|
|
18
17
|
console.log(` ${dim('│')} ${green('✔')} ${cyan(url)} ${dim(`(${hits} hits · ${operations} ops)`)}`);
|
|
19
18
|
console.log(` ${dim('│')} ${dim('DAXTA_DOCS=true')} required on app start`);
|
|
20
19
|
console.log('');
|
|
@@ -24,11 +23,11 @@ function printDocsReady(hits, operations) {
|
|
|
24
23
|
console.log('');
|
|
25
24
|
}
|
|
26
25
|
catch {
|
|
27
|
-
console.log(`\nDAxTA docs ready (${hits} hits · ${operations} ops)\n`);
|
|
26
|
+
console.log(`\nDAxTA: API docs ready (${hits} hits · ${operations} ops)\n`);
|
|
28
27
|
}
|
|
29
28
|
}
|
|
30
29
|
/**
|
|
31
|
-
* Jest reporter — only
|
|
30
|
+
* Jest reporter — only generates API docs when the full run completes.
|
|
32
31
|
* During the run we only record hits (superagent hook + flush); no mid-run rebuilds.
|
|
33
32
|
*/
|
|
34
33
|
class DaxtaJestReporter {
|
|
@@ -43,7 +42,7 @@ class DaxtaJestReporter {
|
|
|
43
42
|
printDocsReady(result.hits ?? 0, result.operations ?? 0);
|
|
44
43
|
return;
|
|
45
44
|
}
|
|
46
|
-
const build = (0, build_spec_1.
|
|
45
|
+
const build = (0, build_spec_1.generateApiDocs)({ silent: true, html: true });
|
|
47
46
|
(0, incremental_1.clearPartialMarker)();
|
|
48
47
|
if (!build.skipped)
|
|
49
48
|
printDocsReady(build.hits, build.operations);
|
package/dist/serve/index.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import * as http from 'http';
|
|
2
2
|
export { apiDocs, apiDocsHandler, type ApiDocsHandler, type ApiDocsOptions } from './middleware';
|
|
3
|
-
export { getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath } from './paths';
|
|
4
|
-
/** Standalone docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
|
|
3
|
+
export { getApiDocs, getApiDocUrl, getDocsBasePath, getHtmlPath, getOutDir, getSpecJsonPath } from './paths';
|
|
4
|
+
/** Standalone API docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
|
|
5
5
|
export declare function serveApiDocs(options?: {
|
|
6
6
|
port?: number;
|
|
7
7
|
}): http.Server<typeof http.IncomingMessage, typeof http.ServerResponse>;
|
package/dist/serve/index.js
CHANGED
|
@@ -33,7 +33,7 @@ var __importStar = (this && this.__importStar) || (function () {
|
|
|
33
33
|
};
|
|
34
34
|
})();
|
|
35
35
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
36
|
-
exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.apiDocsHandler = exports.apiDocs = void 0;
|
|
36
|
+
exports.getSpecJsonPath = exports.getOutDir = exports.getHtmlPath = exports.getDocsBasePath = exports.getApiDocUrl = exports.getApiDocs = exports.apiDocsHandler = exports.apiDocs = void 0;
|
|
37
37
|
exports.serveApiDocs = serveApiDocs;
|
|
38
38
|
const fs_1 = require("fs");
|
|
39
39
|
const http = __importStar(require("http"));
|
|
@@ -47,6 +47,8 @@ var middleware_1 = require("./middleware");
|
|
|
47
47
|
Object.defineProperty(exports, "apiDocs", { enumerable: true, get: function () { return middleware_1.apiDocs; } });
|
|
48
48
|
Object.defineProperty(exports, "apiDocsHandler", { enumerable: true, get: function () { return middleware_1.apiDocsHandler; } });
|
|
49
49
|
var paths_2 = require("./paths");
|
|
50
|
+
Object.defineProperty(exports, "getApiDocs", { enumerable: true, get: function () { return paths_2.getApiDocs; } });
|
|
51
|
+
Object.defineProperty(exports, "getApiDocUrl", { enumerable: true, get: function () { return paths_2.getApiDocUrl; } });
|
|
50
52
|
Object.defineProperty(exports, "getDocsBasePath", { enumerable: true, get: function () { return paths_2.getDocsBasePath; } });
|
|
51
53
|
Object.defineProperty(exports, "getHtmlPath", { enumerable: true, get: function () { return paths_2.getHtmlPath; } });
|
|
52
54
|
Object.defineProperty(exports, "getOutDir", { enumerable: true, get: function () { return paths_2.getOutDir; } });
|
|
@@ -61,7 +63,7 @@ async function readBody(req) {
|
|
|
61
63
|
chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
|
|
62
64
|
return Buffer.concat(chunks);
|
|
63
65
|
}
|
|
64
|
-
/** Standalone docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
|
|
66
|
+
/** Standalone API docs HTTP server (CLI: `daxta serve`). Prefer `apiDocs(app)` on the app port. */
|
|
65
67
|
function serveApiDocs(options = {}) {
|
|
66
68
|
const config = (0, config_1.getConfig)();
|
|
67
69
|
const port = options.port ?? Number(process.env.DAXTA_DOCS_PORT || process.env.OPENAPI_DOCS_PORT || config.port);
|
|
@@ -138,7 +140,7 @@ function serveApiDocs(options = {}) {
|
|
|
138
140
|
if (url.pathname === '/openapi.json' || url.pathname === `${docsBase}/openapi.json`) {
|
|
139
141
|
const body = (0, spec_utils_1.readStrippedOpenApiJson)();
|
|
140
142
|
if (!body) {
|
|
141
|
-
send(res, 404, 'openapi.json not found. Run `daxta
|
|
143
|
+
send(res, 404, 'openapi.json not found. Run `daxta generate` first.');
|
|
142
144
|
return;
|
|
143
145
|
}
|
|
144
146
|
send(res, 200, body, {
|
|
@@ -151,9 +153,9 @@ function serveApiDocs(options = {}) {
|
|
|
151
153
|
send(res, 404, 'Not found');
|
|
152
154
|
});
|
|
153
155
|
server.listen(port, '127.0.0.1', () => {
|
|
154
|
-
console.log(`
|
|
155
|
-
console.log(`
|
|
156
|
-
console.log(`
|
|
156
|
+
console.log(`API docs: http://127.0.0.1:${port}${docsBase}`);
|
|
157
|
+
console.log(`API spec: http://127.0.0.1:${port}${docsBase}/openapi.json`);
|
|
158
|
+
console.log(`API docs env: http://127.0.0.1:${port}${docsBase}/env.json`);
|
|
157
159
|
});
|
|
158
160
|
return server;
|
|
159
161
|
}
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
export type ApiDocsOptions = {
|
|
2
|
-
/** URL prefix for the viewer. Default from config (`docsPath`) or `/docs`. */
|
|
2
|
+
/** URL prefix for the API docs viewer. Default from config (`docsPath`) or `/api-docs`. */
|
|
3
3
|
basePath?: string;
|
|
4
4
|
};
|
|
5
5
|
type LooseRequest = {
|
|
@@ -22,16 +22,16 @@ type LooseResponse = {
|
|
|
22
22
|
};
|
|
23
23
|
export type ApiDocsHandler = (req: LooseRequest, res: LooseResponse, next: (error?: unknown) => void) => void | Promise<void>;
|
|
24
24
|
/**
|
|
25
|
-
* Express / Nest handler that serves
|
|
25
|
+
* Express / Nest handler that serves generated API docs under `/api-docs`
|
|
26
26
|
* (or `basePath`), Try-it proxy at `/__proxy`, and env store at `{base}/env.json`.
|
|
27
27
|
*/
|
|
28
28
|
export declare function apiDocsHandler(options?: ApiDocsOptions): ApiDocsHandler;
|
|
29
29
|
/**
|
|
30
|
-
*
|
|
30
|
+
* Mount generated API docs on a Nest / Express app (`app.use(...)`).
|
|
31
31
|
*
|
|
32
32
|
* Requires `DAXTA_DOCS` in the environment:
|
|
33
33
|
* - missing / empty → throws (app must set it explicitly)
|
|
34
|
-
* - `true` | `1` | `yes` | `on` → serve
|
|
34
|
+
* - `true` | `1` | `yes` | `on` → serve API docs
|
|
35
35
|
* - `false` | `0` | `no` | `off` → no-op
|
|
36
36
|
*/
|
|
37
37
|
export declare function apiDocs(app: {
|
package/dist/serve/middleware.js
CHANGED
|
@@ -96,11 +96,11 @@ async function readRequestJson(req) {
|
|
|
96
96
|
}
|
|
97
97
|
}
|
|
98
98
|
/**
|
|
99
|
-
* Express / Nest handler that serves
|
|
99
|
+
* Express / Nest handler that serves generated API docs under `/api-docs`
|
|
100
100
|
* (or `basePath`), Try-it proxy at `/__proxy`, and env store at `{base}/env.json`.
|
|
101
101
|
*/
|
|
102
102
|
function apiDocsHandler(options = {}) {
|
|
103
|
-
const basePath = (options.basePath ?? (0, paths_1.getDocsBasePath)()).replace(/\/$/, '') || '/docs';
|
|
103
|
+
const basePath = (options.basePath ?? (0, paths_1.getDocsBasePath)()).replace(/\/$/, '') || '/api-docs';
|
|
104
104
|
return async (req, res, next) => {
|
|
105
105
|
const method = (req.method || 'GET').toUpperCase();
|
|
106
106
|
const pathname = requestPathname(req);
|
|
@@ -163,7 +163,7 @@ function apiDocsHandler(options = {}) {
|
|
|
163
163
|
if (isDocsSpec) {
|
|
164
164
|
const body = (0, spec_utils_1.readStrippedOpenApiJson)();
|
|
165
165
|
if (!body) {
|
|
166
|
-
write(res, 404, 'openapi.json not found. Run `daxta
|
|
166
|
+
write(res, 404, 'openapi.json not found. Run `daxta generate` first.', { 'content-type': 'text/plain; charset=utf-8' });
|
|
167
167
|
return;
|
|
168
168
|
}
|
|
169
169
|
write(res, 200, body, {
|
|
@@ -190,17 +190,17 @@ function apiDocsHandler(options = {}) {
|
|
|
190
190
|
};
|
|
191
191
|
}
|
|
192
192
|
/**
|
|
193
|
-
*
|
|
193
|
+
* Mount generated API docs on a Nest / Express app (`app.use(...)`).
|
|
194
194
|
*
|
|
195
195
|
* Requires `DAXTA_DOCS` in the environment:
|
|
196
196
|
* - missing / empty → throws (app must set it explicitly)
|
|
197
|
-
* - `true` | `1` | `yes` | `on` → serve
|
|
197
|
+
* - `true` | `1` | `yes` | `on` → serve API docs
|
|
198
198
|
* - `false` | `0` | `no` | `off` → no-op
|
|
199
199
|
*/
|
|
200
200
|
function apiDocs(app, options = {}) {
|
|
201
201
|
const raw = process.env.DAXTA_DOCS;
|
|
202
202
|
if (raw == null || String(raw).trim() === '') {
|
|
203
|
-
throw new Error('DAxTA: DAXTA_DOCS is not set. Set DAXTA_DOCS=true to enable
|
|
203
|
+
throw new Error('DAxTA: DAXTA_DOCS is not set. Set DAXTA_DOCS=true to enable API docs, or DAXTA_DOCS=false to disable.');
|
|
204
204
|
}
|
|
205
205
|
const normalized = String(raw).trim().toLowerCase();
|
|
206
206
|
const enabled = ['1', 'true', 'yes', 'on'].includes(normalized);
|
package/dist/serve/paths.d.ts
CHANGED
|
@@ -9,3 +9,11 @@ export declare function getEmptyViewerAssetPath(): string;
|
|
|
9
9
|
export declare function readEmptyDocsHtml(): Buffer;
|
|
10
10
|
export declare function getFaviconAssetPath(): string;
|
|
11
11
|
export declare function getDocsBasePath(): string;
|
|
12
|
+
/** App-origin URL where generated API docs are served (e.g. `http://localhost:3000/api-docs`). */
|
|
13
|
+
export declare function getApiDocUrl(): string;
|
|
14
|
+
/** Paths and URL for the generated API docs artifact. */
|
|
15
|
+
export declare function getApiDocs(): {
|
|
16
|
+
url: string;
|
|
17
|
+
specPath: string;
|
|
18
|
+
htmlPath: string;
|
|
19
|
+
};
|