@openmoca/moca-convert 0.0.0-stage → 0.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/LICENSE +201 -0
- package/README.md +191 -2
- package/bin/moca-convert.js +198 -0
- package/bin/moca-youtube.js +93 -0
- package/lib/adapters/directory.js +134 -0
- package/lib/adapters/index.js +60 -0
- package/lib/adapters/markdown.js +65 -0
- package/lib/adapters/obsidian.js +206 -0
- package/lib/adapters/openapi/parse.js +143 -0
- package/lib/adapters/openapi/render.js +149 -0
- package/lib/adapters/openapi/suitability.js +41 -0
- package/lib/adapters/openapi.js +79 -0
- package/lib/adapters/pdf.js +309 -0
- package/lib/adapters/youtube.js +259 -0
- package/lib/detect.js +128 -0
- package/lib/frontmatter.js +42 -0
- package/lib/glob.js +33 -0
- package/lib/index.js +4 -0
- package/lib/manifest.js +23 -0
- package/lib/pdf/extract.js +206 -0
- package/lib/pdf/layout.js +270 -0
- package/lib/slug.js +19 -0
- package/lib/target.js +35 -0
- package/lib/text.js +114 -0
- package/lib/walk.js +37 -0
- package/lib/write.js +123 -0
- package/lib/youtube/capture.js +150 -0
- package/lib/youtube/json3-to-vtt.js +109 -0
- package/lib/youtube/ytdlp.js +64 -0
- package/package.json +42 -4
|
@@ -0,0 +1,143 @@
|
|
|
1
|
+
// Parses an OpenAPI 3.x document (JSON or YAML) and walks its operations.
|
|
2
|
+
// Deliberately does not use a full OpenAPI parser/validator: content nodes
|
|
3
|
+
// only need to *display* request/response shapes as fenced code blocks, not
|
|
4
|
+
// machine-validate them, so only a small local (#/...) $ref resolver is
|
|
5
|
+
// implemented -- an external or unresolvable $ref is left as literal
|
|
6
|
+
// {"$ref": "..."} text in the rendered output rather than failing.
|
|
7
|
+
import { readFileSync } from 'node:fs';
|
|
8
|
+
import * as yaml from 'js-yaml';
|
|
9
|
+
import { UsageError } from '../../target.js';
|
|
10
|
+
|
|
11
|
+
export const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
|
|
12
|
+
|
|
13
|
+
/**
|
|
14
|
+
* @param {string} inputPath
|
|
15
|
+
* @returns {object} the parsed OpenAPI 3.x document
|
|
16
|
+
*/
|
|
17
|
+
export function parseOpenApiDocument(inputPath) {
|
|
18
|
+
const raw = readFileSync(inputPath, 'utf8');
|
|
19
|
+
const isYaml = /\.ya?ml$/i.test(inputPath);
|
|
20
|
+
|
|
21
|
+
let doc;
|
|
22
|
+
try {
|
|
23
|
+
doc = isYaml ? yaml.load(raw) : JSON.parse(raw);
|
|
24
|
+
} catch (err) {
|
|
25
|
+
throw new UsageError(`Failed to parse "${inputPath}" as ${isYaml ? 'YAML' : 'JSON'}: ${err.message}`);
|
|
26
|
+
}
|
|
27
|
+
|
|
28
|
+
if (!doc || typeof doc !== 'object' || Array.isArray(doc)) {
|
|
29
|
+
throw new UsageError(`"${inputPath}" does not contain an OpenAPI document object.`);
|
|
30
|
+
}
|
|
31
|
+
if (typeof doc.swagger === 'string') {
|
|
32
|
+
throw new UsageError(`"${inputPath}" is an OpenAPI 2.0 (Swagger) document; only OpenAPI 3.x is supported.`);
|
|
33
|
+
}
|
|
34
|
+
if (typeof doc.openapi !== 'string' || !/^3\.\d+\.\d+/.test(doc.openapi)) {
|
|
35
|
+
throw new UsageError(`"${inputPath}" does not declare a supported "openapi: 3.x.x" version.`);
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
return doc;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* @param {object} doc
|
|
43
|
+
* @returns {Array<{ path: string, method: string, operation: object, parameters: object[] }>}
|
|
44
|
+
* `parameters` are the operation's own and its path's, with local $refs
|
|
45
|
+
* resolved; the operation's own replaces a path parameter with the same
|
|
46
|
+
* name and location.
|
|
47
|
+
* sorted by path (lexicographic), then by a fixed HTTP method order --
|
|
48
|
+
* not object-insertion order, which isn't guaranteed stable across
|
|
49
|
+
* different JSON/YAML parsers.
|
|
50
|
+
*/
|
|
51
|
+
export function collectOperations(doc) {
|
|
52
|
+
const paths = doc.paths ?? {};
|
|
53
|
+
const operations = [];
|
|
54
|
+
|
|
55
|
+
for (const path of Object.keys(paths)) {
|
|
56
|
+
const pathItem = paths[path] ?? {};
|
|
57
|
+
for (const method of HTTP_METHODS) {
|
|
58
|
+
if (pathItem[method]) {
|
|
59
|
+
const operation = pathItem[method];
|
|
60
|
+
operations.push({ path, method, operation, parameters: mergeParameters(doc, pathItem.parameters, operation.parameters) });
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
operations.sort((a, b) => {
|
|
66
|
+
if (a.path !== b.path) return a.path < b.path ? -1 : 1;
|
|
67
|
+
return HTTP_METHODS.indexOf(a.method) - HTTP_METHODS.indexOf(b.method);
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
return operations;
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/** OpenAPI: a path's parameters apply to each of its operations, unless the operation lists one with the same name and `in`. */
|
|
74
|
+
function mergeParameters(doc, pathLevel, operationLevel) {
|
|
75
|
+
const resolve = (list) => (Array.isArray(list) ? list : [])
|
|
76
|
+
.map((p) => (typeof p?.$ref === 'string' ? resolveLocalRef(doc, p.$ref) ?? { name: p.$ref.split('/').pop(), in: '' } : p))
|
|
77
|
+
.filter((p) => p && typeof p === 'object');
|
|
78
|
+
const own = resolve(operationLevel);
|
|
79
|
+
const key = (p) => `${p.name}\u0000${p.in}`;
|
|
80
|
+
const ownKeys = new Set(own.map(key));
|
|
81
|
+
return [...resolve(pathLevel).filter((p) => !ownKeys.has(key(p))), ...own];
|
|
82
|
+
}
|
|
83
|
+
|
|
84
|
+
/**
|
|
85
|
+
* Resolves a local (same-document) JSON Pointer $ref, e.g.
|
|
86
|
+
* "#/components/schemas/Widget". Returns undefined if the ref doesn't
|
|
87
|
+
* resolve within `doc`.
|
|
88
|
+
* @param {object} doc
|
|
89
|
+
* @param {string} ref
|
|
90
|
+
*/
|
|
91
|
+
export function resolveLocalRef(doc, ref) {
|
|
92
|
+
if (typeof ref !== 'string' || !ref.startsWith('#/')) return undefined;
|
|
93
|
+
return ref
|
|
94
|
+
.slice(2)
|
|
95
|
+
.split('/')
|
|
96
|
+
.map(decodeRefSegment)
|
|
97
|
+
.reduce((node, key) => (node == null ? undefined : node[key]), doc);
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
function decodeRefSegment(segment) {
|
|
101
|
+
return segment.replace(/~1/g, '/').replace(/~0/g, '~');
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** The most objects and arrays one rendered schema may hold, however its references fan out. */
|
|
105
|
+
export const MAX_SCHEMA_NODES = 1_000;
|
|
106
|
+
|
|
107
|
+
/**
|
|
108
|
+
* Recursively expands local $ref pointers within a schema/value so rendered
|
|
109
|
+
* code blocks show the actual shape rather than a bare pointer. An external
|
|
110
|
+
* ref (doesn't start with "#/"), an unresolvable ref, or a ref cycle is left
|
|
111
|
+
* as a literal `{ "$ref": "..." }` marker instead of failing.
|
|
112
|
+
*
|
|
113
|
+
* The expansion is bounded: once it has made `maxNodes` objects and arrays,
|
|
114
|
+
* every further reference is left as its `{ "$ref": "..." }` marker and every
|
|
115
|
+
* further object as "…", so references that fan out at each level cannot
|
|
116
|
+
* take exponential time or memory.
|
|
117
|
+
* @param {*} value
|
|
118
|
+
* @param {object} doc
|
|
119
|
+
* @param {{ maxNodes?: number }} [limits]
|
|
120
|
+
* @returns {*} the expanded value; `truncated` is not part of it
|
|
121
|
+
*/
|
|
122
|
+
export function resolveSchema(value, doc, { maxNodes = MAX_SCHEMA_NODES } = {}) {
|
|
123
|
+
const ctx = { doc, nodes: 0, maxNodes };
|
|
124
|
+
return expand(value, ctx, new Set());
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
function expand(value, ctx, seen) {
|
|
128
|
+
if (value === null || typeof value !== 'object') return value;
|
|
129
|
+
if (typeof value.$ref === 'string') {
|
|
130
|
+
if (!value.$ref.startsWith('#/') || seen.has(value.$ref) || ctx.nodes >= ctx.maxNodes) return { $ref: value.$ref };
|
|
131
|
+
const target = resolveLocalRef(ctx.doc, value.$ref);
|
|
132
|
+
if (target === undefined) return { $ref: value.$ref };
|
|
133
|
+
return expand(target, ctx, new Set(seen).add(value.$ref));
|
|
134
|
+
}
|
|
135
|
+
if (++ctx.nodes > ctx.maxNodes) return '…';
|
|
136
|
+
if (Array.isArray(value)) return value.map((item) => expand(item, ctx, seen));
|
|
137
|
+
|
|
138
|
+
const result = {};
|
|
139
|
+
for (const [key, nested] of Object.entries(value)) {
|
|
140
|
+
result[key] = expand(nested, ctx, seen);
|
|
141
|
+
}
|
|
142
|
+
return result;
|
|
143
|
+
}
|
|
@@ -0,0 +1,149 @@
|
|
|
1
|
+
// Renders parsed OpenAPI operations into content nodes: either one node per
|
|
2
|
+
// operation, or one node per tag with each operation as a subsection.
|
|
3
|
+
import { joinFrontmatter } from '@openmoca/moca-core';
|
|
4
|
+
import { slugify } from '../../slug.js';
|
|
5
|
+
import { uniqueSlug } from '../../text.js';
|
|
6
|
+
import { resolveSchema } from './parse.js';
|
|
7
|
+
|
|
8
|
+
const OPERATION_ID_PATTERN = /^[A-Za-z0-9_.:-]+$/;
|
|
9
|
+
|
|
10
|
+
/**
|
|
11
|
+
* @param {string} path
|
|
12
|
+
* @param {string} method
|
|
13
|
+
* @param {object} operation
|
|
14
|
+
* @param {object} doc
|
|
15
|
+
* @param {{ parameters?: object[], taken?: Set<string> }} [more] `parameters`: the
|
|
16
|
+
* operation's and its path's (collectOperations); `taken`: file names already used,
|
|
17
|
+
* so two operations whose paths slug alike get distinct files
|
|
18
|
+
* @returns {import('../index.js').ContentNode}
|
|
19
|
+
*/
|
|
20
|
+
export function renderOperationNode(path, method, operation, doc, { parameters = operation.parameters ?? [], taken = new Set() } = {}) {
|
|
21
|
+
const title = firstNonEmpty(operation.summary, `${method.toUpperCase()} ${path}`);
|
|
22
|
+
const operationId = safeOperationId(operation.operationId);
|
|
23
|
+
const frontmatter = {
|
|
24
|
+
type: 'API Operation',
|
|
25
|
+
title,
|
|
26
|
+
resource: `${method.toUpperCase()} ${path}`,
|
|
27
|
+
...(operationId ? { tags: [operationId] } : {}),
|
|
28
|
+
};
|
|
29
|
+
const body = `# ${title}\n\n${renderSections(operation, doc, 2, parameters)}`;
|
|
30
|
+
return {
|
|
31
|
+
path: `content/${uniqueSlug(`${method}-${slugifyOperationPath(path)}`, taken)}.md`,
|
|
32
|
+
body: joinFrontmatter(frontmatter, body),
|
|
33
|
+
};
|
|
34
|
+
}
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* @param {string} tag
|
|
38
|
+
* @param {Array<{ path: string, method: string, operation: object }>} operations
|
|
39
|
+
* @param {object} doc
|
|
40
|
+
* @returns {import('../index.js').ContentNode}
|
|
41
|
+
*/
|
|
42
|
+
export function renderTagNode(tag, operations, doc, taken = new Set()) {
|
|
43
|
+
const sections = operations
|
|
44
|
+
.map(({ path, method, operation, parameters }) => {
|
|
45
|
+
const opTitle = firstNonEmpty(operation.summary, `${method.toUpperCase()} ${path}`);
|
|
46
|
+
return `## ${method.toUpperCase()} ${path} — ${opTitle}\n\n${renderSections(operation, doc, 3, parameters ?? operation.parameters ?? [])}`;
|
|
47
|
+
})
|
|
48
|
+
.join('\n');
|
|
49
|
+
const body = `# ${tag}\n\n${sections}`;
|
|
50
|
+
return {
|
|
51
|
+
path: `content/${uniqueSlug(slugify(tag), taken)}.md`,
|
|
52
|
+
body: joinFrontmatter({ type: 'API Tag', title: tag }, body),
|
|
53
|
+
};
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/**
|
|
57
|
+
* Renders the Description/Request/Responses subsections for one operation,
|
|
58
|
+
* starting at the given heading level (2 for a standalone operation node's
|
|
59
|
+
* "##" sections, 3 when nested one level deeper under a tag node's "## METHOD
|
|
60
|
+
* path" heading).
|
|
61
|
+
*/
|
|
62
|
+
function renderSections(operation, doc, level, parameters) {
|
|
63
|
+
const h = '#'.repeat(level);
|
|
64
|
+
const hSub = '#'.repeat(level + 1);
|
|
65
|
+
const lines = [];
|
|
66
|
+
|
|
67
|
+
lines.push(`${h} Description`, '', describe(operation), '');
|
|
68
|
+
|
|
69
|
+
const requestBody = operation.requestBody;
|
|
70
|
+
if (parameters.length > 0 || requestBody) {
|
|
71
|
+
lines.push(`${h} Request`, '');
|
|
72
|
+
if (parameters.length > 0) {
|
|
73
|
+
lines.push(...parameterTable(parameters), '');
|
|
74
|
+
}
|
|
75
|
+
const requestSchema = requestBody && firstJsonSchema(requestBody.content);
|
|
76
|
+
if (requestSchema) {
|
|
77
|
+
lines.push('```json', JSON.stringify(resolveSchema(requestSchema, doc), null, 2), '```', '');
|
|
78
|
+
}
|
|
79
|
+
}
|
|
80
|
+
|
|
81
|
+
const responses = operation.responses ?? {};
|
|
82
|
+
const statusCodes = Object.keys(responses).sort();
|
|
83
|
+
if (statusCodes.length > 0) {
|
|
84
|
+
lines.push(`${h} Responses`, '');
|
|
85
|
+
for (const status of statusCodes) {
|
|
86
|
+
const response = responses[status] ?? {};
|
|
87
|
+
lines.push(`${hSub} ${status}`, '');
|
|
88
|
+
if (typeof response.description === 'string' && response.description.trim()) {
|
|
89
|
+
lines.push(response.description.trim(), '');
|
|
90
|
+
}
|
|
91
|
+
const responseSchema = firstJsonSchema(response.content);
|
|
92
|
+
if (responseSchema) {
|
|
93
|
+
lines.push('```json', JSON.stringify(resolveSchema(responseSchema, doc), null, 2), '```', '');
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
}
|
|
97
|
+
|
|
98
|
+
return lines
|
|
99
|
+
.join('\n')
|
|
100
|
+
.replace(/\n{3,}/g, '\n\n')
|
|
101
|
+
.trimEnd() + '\n';
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
function describe(operation) {
|
|
105
|
+
return firstNonEmpty(operation.description, operation.summary, '_No description provided._').trim();
|
|
106
|
+
}
|
|
107
|
+
|
|
108
|
+
function parameterTable(parameters) {
|
|
109
|
+
const rows = ['| Parameter | In | Required | Type |', '|---|---|---|---|'];
|
|
110
|
+
for (const param of parameters) {
|
|
111
|
+
rows.push(`| ${cell(param.name)} | ${cell(param.in)} | ${param.required ? 'yes' : 'no'} | ${cell(schemaType(param.schema))} |`);
|
|
112
|
+
}
|
|
113
|
+
return rows;
|
|
114
|
+
}
|
|
115
|
+
|
|
116
|
+
/** A table cell from the document: one line, with `|` escaped so it cannot add a column. */
|
|
117
|
+
function cell(value) {
|
|
118
|
+
return typeof value === 'string' ? value.replace(/[\r\n]+/g, ' ').replace(/\\/g, '\\\\').replace(/\|/g, '\\|') : '';
|
|
119
|
+
}
|
|
120
|
+
|
|
121
|
+
function schemaType(schema) {
|
|
122
|
+
if (!schema || typeof schema !== 'object') return '';
|
|
123
|
+
if (typeof schema.type === 'string') return schema.type;
|
|
124
|
+
if (typeof schema.$ref === 'string') return schema.$ref.split('/').pop();
|
|
125
|
+
return '';
|
|
126
|
+
}
|
|
127
|
+
|
|
128
|
+
function firstJsonSchema(content) {
|
|
129
|
+
if (!content || typeof content !== 'object') return null;
|
|
130
|
+
const mediaType = content['application/json'] ?? Object.values(content)[0];
|
|
131
|
+
return mediaType?.schema ?? null;
|
|
132
|
+
}
|
|
133
|
+
|
|
134
|
+
function safeOperationId(operationId) {
|
|
135
|
+
return typeof operationId === 'string' && OPERATION_ID_PATTERN.test(operationId) ? operationId : undefined;
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
function slugifyOperationPath(path) {
|
|
139
|
+
const segments = path
|
|
140
|
+
.replace(/[{}]/g, '')
|
|
141
|
+
.split('/')
|
|
142
|
+
.filter(Boolean)
|
|
143
|
+
.map((segment) => slugify(segment));
|
|
144
|
+
return segments.length > 0 ? segments.join('-') : 'root';
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
function firstNonEmpty(...values) {
|
|
148
|
+
return values.find((v) => typeof v === 'string' && v.trim().length > 0) ?? values[values.length - 1];
|
|
149
|
+
}
|
|
@@ -0,0 +1,41 @@
|
|
|
1
|
+
// "Suitable" per the moca-convert design means an OpenAPI document whose
|
|
2
|
+
// operations carry real human-readable summary/description fields, not a
|
|
3
|
+
// bare machine-generated schema dump -- converting the latter would emit a
|
|
4
|
+
// low-value package that merely echoes the raw schema back as prose.
|
|
5
|
+
import { collectOperations } from './parse.js';
|
|
6
|
+
|
|
7
|
+
export const DEFAULT_MIN_DESCRIPTION_RATIO = 0.5;
|
|
8
|
+
|
|
9
|
+
/**
|
|
10
|
+
* @param {object} doc
|
|
11
|
+
* @param {number} [minRatio]
|
|
12
|
+
* @returns {{ suitable: true } | { suitable: false, reason: string }}
|
|
13
|
+
*/
|
|
14
|
+
export function checkSuitability(doc, minRatio = DEFAULT_MIN_DESCRIPTION_RATIO) {
|
|
15
|
+
const operations = collectOperations(doc);
|
|
16
|
+
const total = operations.length;
|
|
17
|
+
|
|
18
|
+
if (total === 0) {
|
|
19
|
+
return { suitable: false, reason: 'No operations found under "paths".' };
|
|
20
|
+
}
|
|
21
|
+
|
|
22
|
+
const described = operations.filter(({ operation }) => hasDescription(operation)).length;
|
|
23
|
+
const ratio = described / total;
|
|
24
|
+
|
|
25
|
+
if (ratio < minRatio) {
|
|
26
|
+
return {
|
|
27
|
+
suitable: false,
|
|
28
|
+
reason: `Only ${described}/${total} operation(s) (${Math.round(ratio * 100)}%) have a summary or description; need at least ${Math.round(minRatio * 100)}%.`,
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
return { suitable: true };
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
function hasDescription(operation) {
|
|
36
|
+
return isNonEmptyString(operation.summary) || isNonEmptyString(operation.description);
|
|
37
|
+
}
|
|
38
|
+
|
|
39
|
+
function isNonEmptyString(value) {
|
|
40
|
+
return typeof value === 'string' && value.trim().length > 0;
|
|
41
|
+
}
|
|
@@ -0,0 +1,79 @@
|
|
|
1
|
+
// `openapi` adapter: a "suitable" OpenAPI 3.x document (JSON or YAML) --
|
|
2
|
+
// one whose operations carry real summary/description text -- becomes one
|
|
3
|
+
// content node per operation (default) or per tag (--chunker tag).
|
|
4
|
+
import { existsSync, statSync } from 'node:fs';
|
|
5
|
+
import { UsageError } from '../target.js';
|
|
6
|
+
import { parseOpenApiDocument, collectOperations } from './openapi/parse.js';
|
|
7
|
+
import { checkSuitability, DEFAULT_MIN_DESCRIPTION_RATIO } from './openapi/suitability.js';
|
|
8
|
+
import { renderOperationNode, renderTagNode } from './openapi/render.js';
|
|
9
|
+
import { buildManifest } from '../manifest.js';
|
|
10
|
+
|
|
11
|
+
export const name = 'openapi';
|
|
12
|
+
|
|
13
|
+
const OPENAPI_FILE_EXT = /\.(json|ya?ml)$/i;
|
|
14
|
+
const CHUNKER_MODES = ['operation', 'tag'];
|
|
15
|
+
|
|
16
|
+
/**
|
|
17
|
+
* @param {string} inputPath
|
|
18
|
+
* @returns {boolean} true for a single JSON/YAML file that parses as an
|
|
19
|
+
* OpenAPI 3.x document.
|
|
20
|
+
*/
|
|
21
|
+
export function detect(inputPath) {
|
|
22
|
+
if (!existsSync(inputPath) || !statSync(inputPath).isFile()) return false;
|
|
23
|
+
if (!OPENAPI_FILE_EXT.test(inputPath)) return false;
|
|
24
|
+
try {
|
|
25
|
+
parseOpenApiDocument(inputPath);
|
|
26
|
+
return true;
|
|
27
|
+
} catch {
|
|
28
|
+
return false;
|
|
29
|
+
}
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/**
|
|
33
|
+
* @param {object} ctx
|
|
34
|
+
* @param {string} ctx.inputPath
|
|
35
|
+
* @param {{ id?: string, title?: string, version?: string, minDescriptionRatio?: number, chunker?: string }} ctx.options
|
|
36
|
+
* @returns {import('./index.js').PackageDraft}
|
|
37
|
+
*/
|
|
38
|
+
export function convert({ inputPath, options }) {
|
|
39
|
+
const chunker = options.chunker ?? 'operation';
|
|
40
|
+
if (!CHUNKER_MODES.includes(chunker)) {
|
|
41
|
+
throw new UsageError(`Unknown --chunker "${chunker}"; expected one of: ${CHUNKER_MODES.join(', ')}.`);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
const doc = parseOpenApiDocument(inputPath);
|
|
45
|
+
|
|
46
|
+
const minRatio = options.minDescriptionRatio ?? DEFAULT_MIN_DESCRIPTION_RATIO;
|
|
47
|
+
const suitability = checkSuitability(doc, minRatio);
|
|
48
|
+
if (!suitability.suitable) {
|
|
49
|
+
throw new UsageError(`"${inputPath}" is not suitable for conversion: ${suitability.reason}`);
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
const title = options.title ?? (typeof doc.info?.title === 'string' ? doc.info.title : undefined);
|
|
53
|
+
if (!title) {
|
|
54
|
+
throw new UsageError(`"${inputPath}" has no "info.title" and no --title was given.`);
|
|
55
|
+
}
|
|
56
|
+
|
|
57
|
+
const description = typeof doc.info?.description === 'string' ? doc.info.description.trim() : '';
|
|
58
|
+
const manifest = buildManifest({ ...options, title, description });
|
|
59
|
+
const operations = collectOperations(doc);
|
|
60
|
+
const contentNodes = chunker === 'tag' ? buildTagNodes(operations, doc) : buildOperationNodes(operations, doc);
|
|
61
|
+
|
|
62
|
+
return { manifest, contentNodes, warnings: [] };
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
function buildOperationNodes(operations, doc) {
|
|
66
|
+
const taken = new Set();
|
|
67
|
+
return operations.map(({ path, method, operation, parameters }) => renderOperationNode(path, method, operation, doc, { parameters, taken }));
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
function buildTagNodes(operations, doc) {
|
|
71
|
+
const groups = new Map();
|
|
72
|
+
for (const entry of operations) {
|
|
73
|
+
const tag = entry.operation.tags?.[0] ?? 'Untagged';
|
|
74
|
+
if (!groups.has(tag)) groups.set(tag, []);
|
|
75
|
+
groups.get(tag).push(entry);
|
|
76
|
+
}
|
|
77
|
+
const taken = new Set();
|
|
78
|
+
return [...groups.keys()].sort().map((tag) => renderTagNode(tag, groups.get(tag), doc, taken));
|
|
79
|
+
}
|