@rapidoc/cli 0.0.0-stage → 0.1.2
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.txt +22 -0
- package/README.md +57 -2
- package/package.json +59 -4
- package/src/bundle/components.js +187 -0
- package/src/bundle/dereference.js +67 -0
- package/src/bundle/write.js +20 -0
- package/src/commands/build.js +59 -0
- package/src/commands/bundle.js +187 -0
- package/src/commands/completion.js +37 -0
- package/src/commands/dev.js +51 -0
- package/src/commands/doctor.js +214 -0
- package/src/commands/init.js +163 -0
- package/src/commands/lint.js +160 -0
- package/src/commands/mcp.js +190 -0
- package/src/commands/migrate.js +112 -0
- package/src/commands/mock.js +200 -0
- package/src/commands/preview.js +218 -0
- package/src/commands/serve.js +95 -0
- package/src/commands/validate.js +139 -0
- package/src/index.js +126 -0
- package/src/lib/args.js +156 -0
- package/src/lib/completion.js +222 -0
- package/src/lib/engines.js +74 -0
- package/src/lib/errors.js +32 -0
- package/src/lib/help.js +75 -0
- package/src/lib/open.js +23 -0
- package/src/lib/openapi-shape.js +110 -0
- package/src/lib/output.js +38 -0
- package/src/lib/ports.js +65 -0
- package/src/lib/prompt.js +73 -0
- package/src/lib/suggest.js +36 -0
- package/src/lint/config.js +112 -0
- package/src/lint/rules/index.js +40 -0
- package/src/lint/rules/info-contact.js +12 -0
- package/src/lint/rules/info-license.js +11 -0
- package/src/lint/rules/media-example.js +35 -0
- package/src/lint/rules/no-server-example-com.js +30 -0
- package/src/lint/rules/no-unused-components.js +41 -0
- package/src/lint/rules/operation-2xx-response.js +17 -0
- package/src/lint/rules/operation-4xx-response.js +17 -0
- package/src/lint/rules/operation-description.js +12 -0
- package/src/lint/rules/operation-operationId-unique.js +24 -0
- package/src/lint/rules/operation-operationId-url-safe.js +18 -0
- package/src/lint/rules/operation-operationId.js +12 -0
- package/src/lint/rules/operation-summary.js +12 -0
- package/src/lint/rules/operation-tag-defined.js +22 -0
- package/src/lint/rules/path-kebab-case.js +16 -0
- package/src/lint/rules/security-defined.js +23 -0
- package/src/lint/rules/security-scheme-defined.js +28 -0
- package/src/lint/rules/tag-description.js +11 -0
- package/src/lint/run.js +50 -0
- package/src/lint/traverse.js +114 -0
- package/src/lint/types.js +46 -0
- package/src/validate/bundle.js +238 -0
- package/src/validate/check.js +122 -0
- package/src/validate/report.js +140 -0
|
@@ -0,0 +1,122 @@
|
|
|
1
|
+
import {
|
|
2
|
+
bundleSpec,
|
|
3
|
+
decodePointer,
|
|
4
|
+
isUrl,
|
|
5
|
+
locate,
|
|
6
|
+
position,
|
|
7
|
+
SpecSyntaxError,
|
|
8
|
+
valueAt,
|
|
9
|
+
} from "./bundle.js";
|
|
10
|
+
|
|
11
|
+
/**
|
|
12
|
+
* Checks one spec (a file path or URL) against the OpenAPI Specification with @scalar/openapi-validator,
|
|
13
|
+
* which is strict: every required field (info.version, a response's description, ...) must be there.
|
|
14
|
+
* (@scalar/openapi-parser's own validate fills in defaults first, so it lets those through.)
|
|
15
|
+
*
|
|
16
|
+
* `bundle` is an already loaded bundleSpec result (then nothing is read).
|
|
17
|
+
* Returns { location, version, problems, skipped }: problems are
|
|
18
|
+
* { severity: "error", rule, message, location, pointer, line, column }; skipped lists remote files its
|
|
19
|
+
* $refs point to that were not fetched (see `remote`).
|
|
20
|
+
*/
|
|
21
|
+
export async function checkSpec(location, { remote = false, bundle: loaded } = {}) {
|
|
22
|
+
// Imported here: the CLI loads every command module for its help; only validate needs these.
|
|
23
|
+
const { validate } = await import("@scalar/openapi-validator");
|
|
24
|
+
|
|
25
|
+
let bundle = loaded; // lint passes the bundle it loaded, so the spec is read once
|
|
26
|
+
try {
|
|
27
|
+
bundle ??= await bundleSpec(location, { remote });
|
|
28
|
+
} catch (err) {
|
|
29
|
+
if (err instanceof SpecSyntaxError) {
|
|
30
|
+
const where = { location: err.location, pointer: [], line: err.line, column: err.column };
|
|
31
|
+
return {
|
|
32
|
+
location,
|
|
33
|
+
problems: [{ severity: "error", rule: "syntax", message: err.message, ...where }],
|
|
34
|
+
skipped: [],
|
|
35
|
+
};
|
|
36
|
+
}
|
|
37
|
+
throw err;
|
|
38
|
+
}
|
|
39
|
+
|
|
40
|
+
const problems = [];
|
|
41
|
+
const seen = new Set();
|
|
42
|
+
const add = (rule, message, segments, fromBundle = true) => {
|
|
43
|
+
const at = fromBundle ? locate(bundle, segments) : segments;
|
|
44
|
+
const { line, column } = position(bundle.files.get(at.location), at.pointer);
|
|
45
|
+
const key = `${at.location}:${line}:${column}:${message}`;
|
|
46
|
+
if (seen.has(key)) return;
|
|
47
|
+
seen.add(key);
|
|
48
|
+
problems.push({
|
|
49
|
+
severity: "error",
|
|
50
|
+
rule,
|
|
51
|
+
message,
|
|
52
|
+
location: at.location,
|
|
53
|
+
pointer: at.pointer,
|
|
54
|
+
line,
|
|
55
|
+
column,
|
|
56
|
+
});
|
|
57
|
+
};
|
|
58
|
+
|
|
59
|
+
for (const problem of bundle.problems) add("ref", problem.message, problem, false);
|
|
60
|
+
|
|
61
|
+
// 1. The document against the OpenAPI schema for its version (plus the cookie-parameter rules).
|
|
62
|
+
const result = await validate(bundle.value, { checkPathParameters: false });
|
|
63
|
+
for (const error of result.errors ?? []) add("openapi", error.message, segmentsOf(error.path));
|
|
64
|
+
|
|
65
|
+
// 2. Declared path parameters ({id} in the path) must be defined. The validator needs parameter
|
|
66
|
+
// $refs resolved for that, so it gets a copy where only those are; its schema errors are already
|
|
67
|
+
// reported above, so only the path-parameter findings (array paths) are kept.
|
|
68
|
+
if (result.version && result.version !== "2.0") {
|
|
69
|
+
const withParameters = await validate(resolveParameters(bundle.value), {
|
|
70
|
+
checkPathParameters: true,
|
|
71
|
+
checkCookieParameters: false,
|
|
72
|
+
});
|
|
73
|
+
for (const error of withParameters.errors ?? [])
|
|
74
|
+
if (Array.isArray(error.path)) add("openapi", error.message, segmentsOf(error.path));
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
return { location, version: result.version, problems, skipped: bundle.skipped };
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
/** A validator error path ("/paths/~1a/get", ["paths", "/a", "get"] or nothing) as segments. */
|
|
81
|
+
function segmentsOf(errorPath) {
|
|
82
|
+
if (Array.isArray(errorPath)) return errorPath.map(String);
|
|
83
|
+
if (typeof errorPath === "string" && errorPath) return decodePointer(`#${errorPath}`);
|
|
84
|
+
return [];
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
/** A copy of the document with `#/...` $refs in parameter lists (and path items) followed. */
|
|
88
|
+
function resolveParameters(document) {
|
|
89
|
+
const follow = (node) => {
|
|
90
|
+
for (
|
|
91
|
+
let hops = 0;
|
|
92
|
+
node && typeof node.$ref === "string" && node.$ref.startsWith("#") && hops < 10;
|
|
93
|
+
hops++
|
|
94
|
+
)
|
|
95
|
+
node = valueAt(document, decodePointer(node.$ref)) ?? node;
|
|
96
|
+
return node;
|
|
97
|
+
};
|
|
98
|
+
const withParams = (node) =>
|
|
99
|
+
Array.isArray(node?.parameters) ? { ...node, parameters: node.parameters.map(follow) } : node;
|
|
100
|
+
|
|
101
|
+
const paths = {};
|
|
102
|
+
for (const [route, rawItem] of Object.entries(document.paths ?? {})) {
|
|
103
|
+
const item = withParams(follow(rawItem));
|
|
104
|
+
if (!item || typeof item !== "object") {
|
|
105
|
+
paths[route] = item;
|
|
106
|
+
continue;
|
|
107
|
+
}
|
|
108
|
+
const copy = { ...item };
|
|
109
|
+
for (const [key, operation] of Object.entries(item))
|
|
110
|
+
if (
|
|
111
|
+
operation &&
|
|
112
|
+
typeof operation === "object" &&
|
|
113
|
+
!Array.isArray(operation) &&
|
|
114
|
+
key !== "parameters"
|
|
115
|
+
)
|
|
116
|
+
copy[key] = withParams(operation);
|
|
117
|
+
paths[route] = copy;
|
|
118
|
+
}
|
|
119
|
+
return { ...document, paths };
|
|
120
|
+
}
|
|
121
|
+
|
|
122
|
+
export { isUrl };
|
|
@@ -0,0 +1,140 @@
|
|
|
1
|
+
import path from "node:path";
|
|
2
|
+
import { isUrl } from "./bundle.js";
|
|
3
|
+
import { encodePointer } from "./bundle.js";
|
|
4
|
+
import { error, icon, info, success, warn } from "../lib/output.js";
|
|
5
|
+
|
|
6
|
+
/*
|
|
7
|
+
* The results of `rapidoc validate`, as one list of checked items:
|
|
8
|
+
* { kind: "spec" | "workflows", id, location, skipped?: true, problems: [ { severity, rule, message,
|
|
9
|
+
* location?, pointer?, line?, column? } ] }
|
|
10
|
+
* and three ways to print them: pretty (the terminal), json (scripts) and sarif (GitHub code scanning).
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
/** A location as printed: a path relative to the current folder (forward slashes) or a URL. */
|
|
14
|
+
export const displayPath = (location) =>
|
|
15
|
+
isUrl(location)
|
|
16
|
+
? location
|
|
17
|
+
: path.relative(process.cwd(), location).split(path.sep).join("/") || ".";
|
|
18
|
+
|
|
19
|
+
const where = (problem) =>
|
|
20
|
+
problem.location
|
|
21
|
+
? `${displayPath(problem.location)}${problem.line ? `:${problem.line}:${problem.column}` : ""}`
|
|
22
|
+
: "";
|
|
23
|
+
|
|
24
|
+
export function counts(items) {
|
|
25
|
+
const all = items.flatMap((item) => item.problems);
|
|
26
|
+
return {
|
|
27
|
+
errors: all.filter((p) => p.severity === "error").length,
|
|
28
|
+
warnings: all.filter((p) => p.severity === "warning").length,
|
|
29
|
+
};
|
|
30
|
+
}
|
|
31
|
+
|
|
32
|
+
/** Prints one checked item as soon as it's done (pretty format). `ok` is the line for a clean spec. */
|
|
33
|
+
export function printItem(item, { ok } = {}) {
|
|
34
|
+
info(`\n${icon("🔍")}${item.id}: ${displayPath(item.location)}`);
|
|
35
|
+
if (item.skipped) {
|
|
36
|
+
info(` ${icon("⏭️ ")}remote, skipped (use --remote to check it)`);
|
|
37
|
+
return;
|
|
38
|
+
}
|
|
39
|
+
const errors = item.problems.filter((p) => p.severity === "error");
|
|
40
|
+
if (errors.length) {
|
|
41
|
+
error(`${errors.length} error(s):`, " ");
|
|
42
|
+
for (const problem of errors) process.stderr.write(` ${describe(problem)}\n`);
|
|
43
|
+
} else if (ok) {
|
|
44
|
+
success(ok, " ");
|
|
45
|
+
} else if (item.kind === "spec") {
|
|
46
|
+
success("Valid OpenAPI", " ");
|
|
47
|
+
} else {
|
|
48
|
+
success("Workflows resolve against the portal's APIs", " ");
|
|
49
|
+
}
|
|
50
|
+
for (const problem of item.problems.filter((p) => p.severity === "warning"))
|
|
51
|
+
warn(describe(problem), " ");
|
|
52
|
+
}
|
|
53
|
+
|
|
54
|
+
/** "file:line:col message [rule] (#/pointer)"; the parts a problem has. */
|
|
55
|
+
function describe(problem) {
|
|
56
|
+
const at = problem.location && problem.line ? `${where(problem)} ` : "";
|
|
57
|
+
const rule = LINT_RULE.test(problem.rule) ? ` [${problem.rule}]` : "";
|
|
58
|
+
const pointer = problem.pointer?.length ? ` (${encodePointer(problem.pointer)})` : "";
|
|
59
|
+
return `${at}${problem.message}${rule}${pointer}`;
|
|
60
|
+
}
|
|
61
|
+
|
|
62
|
+
// validate's own rule ids (syntax, openapi, ref, portal, workflow) are not shown; lint's are.
|
|
63
|
+
const LINT_RULE = /-/;
|
|
64
|
+
|
|
65
|
+
export function toJson(items, { strict }) {
|
|
66
|
+
const { errors, warnings } = counts(items);
|
|
67
|
+
return {
|
|
68
|
+
valid: errors === 0 && (!strict || warnings === 0),
|
|
69
|
+
errors,
|
|
70
|
+
warnings,
|
|
71
|
+
items: items.map((item) => ({
|
|
72
|
+
kind: item.kind,
|
|
73
|
+
id: item.id,
|
|
74
|
+
location: displayPath(item.location),
|
|
75
|
+
...(item.skipped && { skipped: true }),
|
|
76
|
+
problems: item.problems.map((problem) => ({
|
|
77
|
+
severity: problem.severity,
|
|
78
|
+
rule: problem.rule,
|
|
79
|
+
message: problem.message,
|
|
80
|
+
...(problem.location && { location: displayPath(problem.location) }),
|
|
81
|
+
...(problem.line && { line: problem.line, column: problem.column }),
|
|
82
|
+
...(problem.pointer && { pointer: encodePointer(problem.pointer) }),
|
|
83
|
+
})),
|
|
84
|
+
})),
|
|
85
|
+
};
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
const RULES = {
|
|
89
|
+
syntax: "The file is not valid YAML or JSON.",
|
|
90
|
+
openapi:
|
|
91
|
+
"The document must follow the OpenAPI Specification (required fields, types, path parameters).",
|
|
92
|
+
ref: "Every $ref must point to something that exists.",
|
|
93
|
+
portal: "Links and references the portal checks (operation ids, anchors).",
|
|
94
|
+
workflow: "Arazzo workflow steps must resolve against the portal's APIs.",
|
|
95
|
+
};
|
|
96
|
+
|
|
97
|
+
/** SARIF 2.1.0, for GitHub code scanning (github/codeql-action/upload-sarif). `rules` adds to validate's. */
|
|
98
|
+
export function toSarif(items, { version, tool = "rapidoc validate", rules = {} }) {
|
|
99
|
+
const results = items.flatMap((item) =>
|
|
100
|
+
item.problems.map((problem) => {
|
|
101
|
+
const location = problem.location ?? item.location;
|
|
102
|
+
const region = problem.line
|
|
103
|
+
? { region: { startLine: problem.line, startColumn: problem.column } }
|
|
104
|
+
: {};
|
|
105
|
+
return {
|
|
106
|
+
ruleId: problem.rule,
|
|
107
|
+
level: problem.severity,
|
|
108
|
+
message: { text: problem.message },
|
|
109
|
+
locations: [
|
|
110
|
+
{
|
|
111
|
+
physicalLocation: { artifactLocation: { uri: displayPath(location) }, ...region },
|
|
112
|
+
...(problem.pointer?.length && {
|
|
113
|
+
logicalLocations: [{ fullyQualifiedName: encodePointer(problem.pointer) }],
|
|
114
|
+
}),
|
|
115
|
+
},
|
|
116
|
+
],
|
|
117
|
+
};
|
|
118
|
+
}),
|
|
119
|
+
);
|
|
120
|
+
return {
|
|
121
|
+
$schema: "https://json.schemastore.org/sarif-2.1.0.json",
|
|
122
|
+
version: "2.1.0",
|
|
123
|
+
runs: [
|
|
124
|
+
{
|
|
125
|
+
tool: {
|
|
126
|
+
driver: {
|
|
127
|
+
name: tool,
|
|
128
|
+
version,
|
|
129
|
+
informationUri: "https://rapidocui.com",
|
|
130
|
+
rules: Object.entries({ ...RULES, ...rules }).map(([id, text]) => ({
|
|
131
|
+
id,
|
|
132
|
+
shortDescription: { text },
|
|
133
|
+
})),
|
|
134
|
+
},
|
|
135
|
+
},
|
|
136
|
+
results,
|
|
137
|
+
},
|
|
138
|
+
],
|
|
139
|
+
};
|
|
140
|
+
}
|