create-graphql-markdown-docs 0.1.1 → 1.0.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/README.md +100 -26
- package/lib/create.mjs +495 -670
- package/lib/frameworks/docusaurus.mjs +66 -0
- package/lib/frameworks/index.mjs +53 -0
- package/lib/frameworks/links.mjs +102 -0
- package/lib/frameworks/nuxt.mjs +266 -0
- package/lib/frameworks/presets.mjs +133 -0
- package/lib/helpers.mjs +83 -0
- package/lib/project.mjs +136 -0
- package/lib/rewrites/graphqlrc.mjs +61 -0
- package/lib/rewrites/lines.mjs +18 -0
- package/lib/schema.mjs +102 -0
- package/lib/target.mjs +95 -0
- package/lib/tasks.mjs +154 -0
- package/lib/wire/deps.mjs +38 -0
- package/lib/wire/plan.mjs +241 -0
- package/lib/wire/steps.mjs +333 -0
- package/lib/wire/yaml.mjs +93 -0
- package/package.json +2 -2
- package/templates/docusaurus/gitignore +20 -0
- package/templates/docusaurus/package.json +1 -1
- package/templates/nuxt/gitignore +30 -0
- package/templates/nuxt/package.json +1 -1
|
@@ -0,0 +1,241 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
|
|
4
|
+
import {
|
|
5
|
+
normalizeOutput,
|
|
6
|
+
splitOutput,
|
|
7
|
+
suggestLinkRoot,
|
|
8
|
+
} from "../frameworks/links.mjs";
|
|
9
|
+
import { toYaml } from "./yaml.mjs";
|
|
10
|
+
|
|
11
|
+
/** GraphQL config file names that may already hold a project's configuration. */
|
|
12
|
+
const GRAPHQL_CONFIG_FILES = [
|
|
13
|
+
".graphqlrc",
|
|
14
|
+
".graphqlrc.yml",
|
|
15
|
+
".graphqlrc.yaml",
|
|
16
|
+
".graphqlrc.json",
|
|
17
|
+
".graphqlrc.js",
|
|
18
|
+
".graphqlrc.ts",
|
|
19
|
+
".graphqlrc.cjs",
|
|
20
|
+
".graphqlrc.mjs",
|
|
21
|
+
".graphqlrc.cts",
|
|
22
|
+
".graphqlrc.mts",
|
|
23
|
+
".graphqlrc.toml",
|
|
24
|
+
"graphql.config.yml",
|
|
25
|
+
"graphql.config.yaml",
|
|
26
|
+
"graphql.config.json",
|
|
27
|
+
"graphql.config.js",
|
|
28
|
+
"graphql.config.cjs",
|
|
29
|
+
"graphql.config.mjs",
|
|
30
|
+
"graphql.config.ts",
|
|
31
|
+
"graphql.config.cts",
|
|
32
|
+
"graphql.config.mts",
|
|
33
|
+
"graphql.config.toml",
|
|
34
|
+
];
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* Inspect a project directory for package.json and an existing GraphQL config.
|
|
38
|
+
* @param {string} projectDir
|
|
39
|
+
* @returns {{ packageJson: object | null, packageJsonIndent: string | number, existingConfig: string | null }}
|
|
40
|
+
*/
|
|
41
|
+
export function inspectProject(projectDir) {
|
|
42
|
+
let packageJson = null;
|
|
43
|
+
let packageJsonIndent = 2;
|
|
44
|
+
const pkgPath = path.join(projectDir, "package.json");
|
|
45
|
+
if (fs.existsSync(pkgPath)) {
|
|
46
|
+
const raw = fs.readFileSync(pkgPath, "utf8");
|
|
47
|
+
packageJson = JSON.parse(raw);
|
|
48
|
+
const match = /^([ \t]+)\S/m.exec(raw);
|
|
49
|
+
if (match) {
|
|
50
|
+
packageJsonIndent = match[1];
|
|
51
|
+
}
|
|
52
|
+
}
|
|
53
|
+
let existingConfig = GRAPHQL_CONFIG_FILES.find((name) =>
|
|
54
|
+
fs.existsSync(path.join(projectDir, name)),
|
|
55
|
+
);
|
|
56
|
+
if (!existingConfig && packageJson && "graphql" in packageJson) {
|
|
57
|
+
existingConfig = "package.json#graphql";
|
|
58
|
+
}
|
|
59
|
+
return {
|
|
60
|
+
packageJson,
|
|
61
|
+
packageJsonIndent,
|
|
62
|
+
existingConfig: existingConfig ?? null,
|
|
63
|
+
};
|
|
64
|
+
}
|
|
65
|
+
|
|
66
|
+
/**
|
|
67
|
+
* Validate the output folder against the project directory.
|
|
68
|
+
* @param {string} projectDir
|
|
69
|
+
* @param {string} output
|
|
70
|
+
* @returns {{ error?: string, warning?: string }}
|
|
71
|
+
*/
|
|
72
|
+
export function validateOutput(projectDir, output) {
|
|
73
|
+
if (!output?.trim()) {
|
|
74
|
+
return { error: "Output folder is required." };
|
|
75
|
+
}
|
|
76
|
+
if (path.isAbsolute(output)) {
|
|
77
|
+
return { error: "Output folder must be relative to the project root." };
|
|
78
|
+
}
|
|
79
|
+
const normalized = path.posix.normalize(
|
|
80
|
+
normalizeOutput(output.trim()) || ".",
|
|
81
|
+
);
|
|
82
|
+
if (normalized === ".") {
|
|
83
|
+
return { error: "Output folder must be a subfolder of the project." };
|
|
84
|
+
}
|
|
85
|
+
if (normalized === ".." || normalized.startsWith("../")) {
|
|
86
|
+
return { error: "Output folder must be inside the project." };
|
|
87
|
+
}
|
|
88
|
+
const target = path.join(projectDir, normalized);
|
|
89
|
+
if (fs.existsSync(target)) {
|
|
90
|
+
if (!fs.statSync(target).isDirectory()) {
|
|
91
|
+
return { error: `${output} already exists and is not a directory.` };
|
|
92
|
+
}
|
|
93
|
+
if (fs.readdirSync(target).length > 0) {
|
|
94
|
+
return {
|
|
95
|
+
warning: `${output} already exists and is not empty — generated files may overwrite pages in it.`,
|
|
96
|
+
};
|
|
97
|
+
}
|
|
98
|
+
}
|
|
99
|
+
return {};
|
|
100
|
+
}
|
|
101
|
+
|
|
102
|
+
/**
|
|
103
|
+
* Build the .graphqlrc content as a plain object.
|
|
104
|
+
* @param {object} inputs
|
|
105
|
+
* @param {object} inputs.descriptor
|
|
106
|
+
* @param {string} inputs.schema
|
|
107
|
+
* @param {object} inputs.loader
|
|
108
|
+
* @param {string} inputs.output
|
|
109
|
+
* @param {string | null} [inputs.linkRoot] `null` omits linkRoot from the config.
|
|
110
|
+
* @param {string} [inputs.siteBase]
|
|
111
|
+
* @param {string} [inputs.formatter]
|
|
112
|
+
* @returns {object}
|
|
113
|
+
*/
|
|
114
|
+
export function buildGraphqlrc({
|
|
115
|
+
descriptor,
|
|
116
|
+
schema,
|
|
117
|
+
loader,
|
|
118
|
+
output,
|
|
119
|
+
linkRoot,
|
|
120
|
+
siteBase,
|
|
121
|
+
formatter,
|
|
122
|
+
}) {
|
|
123
|
+
const { rootPath, baseURL } = splitOutput(descriptor, output);
|
|
124
|
+
const resolvedLinkRoot =
|
|
125
|
+
descriptor.links === "relative" || linkRoot === null
|
|
126
|
+
? undefined
|
|
127
|
+
: (linkRoot ?? suggestLinkRoot(descriptor, output, { siteBase }));
|
|
128
|
+
const resolvedFormatter = formatter ?? descriptor.formatter;
|
|
129
|
+
|
|
130
|
+
const { options, tokenEnvVar } = loader;
|
|
131
|
+
const loaders =
|
|
132
|
+
!options && !tokenEnvVar
|
|
133
|
+
? { [loader.className]: loader.package }
|
|
134
|
+
: {
|
|
135
|
+
[loader.className]: {
|
|
136
|
+
module: loader.package,
|
|
137
|
+
options: {
|
|
138
|
+
...options,
|
|
139
|
+
...(tokenEnvVar && { token: "${" + tokenEnvVar + "}" }),
|
|
140
|
+
},
|
|
141
|
+
},
|
|
142
|
+
};
|
|
143
|
+
|
|
144
|
+
return {
|
|
145
|
+
schema,
|
|
146
|
+
extensions: {
|
|
147
|
+
"graphql-markdown": {
|
|
148
|
+
rootPath: rootPath === "." ? "." : `./${rootPath}`,
|
|
149
|
+
baseURL,
|
|
150
|
+
...(resolvedLinkRoot !== undefined && { linkRoot: resolvedLinkRoot }),
|
|
151
|
+
...(resolvedFormatter && { formatter: resolvedFormatter }),
|
|
152
|
+
loaders,
|
|
153
|
+
},
|
|
154
|
+
},
|
|
155
|
+
};
|
|
156
|
+
}
|
|
157
|
+
|
|
158
|
+
/**
|
|
159
|
+
* Plan the files and package.json changes needed to wire a project.
|
|
160
|
+
* @param {object} inputs Arguments for buildGraphqlrc.
|
|
161
|
+
* @param {ReturnType<typeof inspectProject>} project
|
|
162
|
+
* @param {{ scriptName?: string }} [options]
|
|
163
|
+
* @returns {{ files: { path: string, content: string }[], mergeBlock?: string, script: object, warnings: string[] }}
|
|
164
|
+
*/
|
|
165
|
+
export function planWire(inputs, project, { scriptName = "docs:api" } = {}) {
|
|
166
|
+
const config = buildGraphqlrc(inputs);
|
|
167
|
+
const warnings = [];
|
|
168
|
+
let files = [];
|
|
169
|
+
let mergeBlock;
|
|
170
|
+
if (project.existingConfig) {
|
|
171
|
+
mergeBlock = toYaml({ extensions: config.extensions });
|
|
172
|
+
warnings.push(
|
|
173
|
+
`Found ${project.existingConfig} — not writing .graphqlrc. Merge the block below into it (schema: ${inputs.schema}).`,
|
|
174
|
+
);
|
|
175
|
+
} else {
|
|
176
|
+
files = [{ path: ".graphqlrc", content: toYaml(config) }];
|
|
177
|
+
}
|
|
178
|
+
|
|
179
|
+
let script;
|
|
180
|
+
if (!project.packageJson) {
|
|
181
|
+
script = { skipped: "no package.json" };
|
|
182
|
+
} else if (project.packageJson.scripts?.[scriptName]) {
|
|
183
|
+
script = { skipped: `script "${scriptName}" already exists` };
|
|
184
|
+
} else {
|
|
185
|
+
script = { name: scriptName, command: "gqlmd graphql-to-doc" };
|
|
186
|
+
}
|
|
187
|
+
return { files, mergeBlock, script, warnings };
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
/**
|
|
191
|
+
* Apply a wire plan to disk. Never overwrites existing files.
|
|
192
|
+
* @param {string} projectDir
|
|
193
|
+
* @param {ReturnType<typeof planWire>} plan
|
|
194
|
+
* @param {ReturnType<typeof inspectProject>} project
|
|
195
|
+
* @returns {string[]} Written paths (relative to projectDir).
|
|
196
|
+
*/
|
|
197
|
+
export function applyWirePlan(projectDir, plan, project) {
|
|
198
|
+
const written = [];
|
|
199
|
+
for (const file of plan.files) {
|
|
200
|
+
fs.writeFileSync(path.join(projectDir, file.path), file.content, {
|
|
201
|
+
flag: "wx",
|
|
202
|
+
});
|
|
203
|
+
written.push(file.path);
|
|
204
|
+
}
|
|
205
|
+
if (plan.script.name) {
|
|
206
|
+
const pkg = project.packageJson;
|
|
207
|
+
pkg.scripts = { ...pkg.scripts, [plan.script.name]: plan.script.command };
|
|
208
|
+
fs.writeFileSync(
|
|
209
|
+
path.join(projectDir, "package.json"),
|
|
210
|
+
JSON.stringify(pkg, null, project.packageJsonIndent) + "\n",
|
|
211
|
+
);
|
|
212
|
+
written.push("package.json");
|
|
213
|
+
}
|
|
214
|
+
return written;
|
|
215
|
+
}
|
|
216
|
+
|
|
217
|
+
/**
|
|
218
|
+
* Render a wire plan as human-readable text (for --dry-run).
|
|
219
|
+
* @param {ReturnType<typeof planWire>} plan
|
|
220
|
+
* @returns {string}
|
|
221
|
+
*/
|
|
222
|
+
export function formatWirePlan(plan) {
|
|
223
|
+
const lines = [];
|
|
224
|
+
for (const file of plan.files) {
|
|
225
|
+
lines.push(`Write ${file.path}:`, file.content);
|
|
226
|
+
}
|
|
227
|
+
if (plan.script.name) {
|
|
228
|
+
lines.push(
|
|
229
|
+
`Add script to package.json: "${plan.script.name}": "${plan.script.command}"`,
|
|
230
|
+
);
|
|
231
|
+
} else {
|
|
232
|
+
lines.push(`Skip package.json script: ${plan.script.skipped}`);
|
|
233
|
+
}
|
|
234
|
+
if (plan.mergeBlock) {
|
|
235
|
+
lines.push("", "Merge block:", plan.mergeBlock);
|
|
236
|
+
}
|
|
237
|
+
for (const warning of plan.warnings) {
|
|
238
|
+
lines.push(`Warning: ${warning}`);
|
|
239
|
+
}
|
|
240
|
+
return lines.join("\n");
|
|
241
|
+
}
|
|
@@ -0,0 +1,333 @@
|
|
|
1
|
+
import fs from "node:fs";
|
|
2
|
+
import { createRequire } from "node:module";
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
|
|
5
|
+
import * as prompts from "@clack/prompts";
|
|
6
|
+
|
|
7
|
+
import { WIRE_FRAMEWORKS } from "../frameworks/index.mjs";
|
|
8
|
+
import { normalizeOutput, suggestLinkRoot } from "../frameworks/links.mjs";
|
|
9
|
+
import {
|
|
10
|
+
DOCS_URL,
|
|
11
|
+
fail,
|
|
12
|
+
failureNote,
|
|
13
|
+
resolvePackageManager,
|
|
14
|
+
unlessCancelled,
|
|
15
|
+
validateSchemaSource,
|
|
16
|
+
} from "../helpers.mjs";
|
|
17
|
+
import { detectLoader } from "../schema.mjs";
|
|
18
|
+
import { addDevCommand, addDevDependencies } from "../tasks.mjs";
|
|
19
|
+
import { detectFrameworks, toSchemaRef } from "../target.mjs";
|
|
20
|
+
import { requiredPackages } from "./deps.mjs";
|
|
21
|
+
import {
|
|
22
|
+
applyWirePlan,
|
|
23
|
+
formatWirePlan,
|
|
24
|
+
inspectProject,
|
|
25
|
+
planWire,
|
|
26
|
+
validateOutput,
|
|
27
|
+
} from "./plan.mjs";
|
|
28
|
+
|
|
29
|
+
const labelOf = (id) => WIRE_FRAMEWORKS[id].label;
|
|
30
|
+
|
|
31
|
+
/** Whether wire mode has dependencies to add: a package.json and packages not yet listed. */
|
|
32
|
+
const needsInstall = (ctx) => {
|
|
33
|
+
return Boolean(ctx.project.packageJson) && ctx.packages.length > 0;
|
|
34
|
+
};
|
|
35
|
+
|
|
36
|
+
/** Frameworks found in package.json plus the --framework value (empty counts as absent). */
|
|
37
|
+
function requestedFramework(args) {
|
|
38
|
+
return args.framework || undefined;
|
|
39
|
+
}
|
|
40
|
+
|
|
41
|
+
/** With --yes, everything that cannot be guessed must be passed as a flag. */
|
|
42
|
+
function preflight(ctx) {
|
|
43
|
+
const { args } = ctx;
|
|
44
|
+
if (!args.yes) return;
|
|
45
|
+
const missing = [];
|
|
46
|
+
if (!args.schema) missing.push("--schema");
|
|
47
|
+
if (!args.output) missing.push("--output");
|
|
48
|
+
if (!requestedFramework(args) && ctx.detected.length !== 1) {
|
|
49
|
+
missing.push("--framework");
|
|
50
|
+
}
|
|
51
|
+
if (missing.length === 0) return;
|
|
52
|
+
let message = `Missing required options to add GraphQL-Markdown without prompts: ${missing.join(", ")}.`;
|
|
53
|
+
if (ctx.detected.length > 1) {
|
|
54
|
+
message += ` Detected: ${ctx.detected.map(labelOf).join(", ")}.`;
|
|
55
|
+
} else if (ctx.detected.length === 0) {
|
|
56
|
+
message += " Use --framework generic for an unlisted framework.";
|
|
57
|
+
}
|
|
58
|
+
fail(message);
|
|
59
|
+
}
|
|
60
|
+
|
|
61
|
+
function frameworkOptions(ids) {
|
|
62
|
+
return ids.map((id) => ({
|
|
63
|
+
value: id,
|
|
64
|
+
label: WIRE_FRAMEWORKS[id].label,
|
|
65
|
+
hint: WIRE_FRAMEWORKS[id].hint,
|
|
66
|
+
}));
|
|
67
|
+
}
|
|
68
|
+
|
|
69
|
+
async function resolveWireFramework(ctx) {
|
|
70
|
+
const { args, detected } = ctx;
|
|
71
|
+
const requested = requestedFramework(args);
|
|
72
|
+
if (requested) {
|
|
73
|
+
if (!Object.hasOwn(WIRE_FRAMEWORKS, requested)) {
|
|
74
|
+
fail(
|
|
75
|
+
`Invalid --framework "${requested}" — expected one of: ${Object.keys(WIRE_FRAMEWORKS).join(", ")}.`,
|
|
76
|
+
);
|
|
77
|
+
}
|
|
78
|
+
return requested;
|
|
79
|
+
}
|
|
80
|
+
if (detected.length === 1 && args.yes) {
|
|
81
|
+
prompts.log.info(`Detected ${labelOf(detected[0])}`);
|
|
82
|
+
return detected[0];
|
|
83
|
+
}
|
|
84
|
+
const all = Object.keys(WIRE_FRAMEWORKS);
|
|
85
|
+
const select = (options, initialValue) =>
|
|
86
|
+
prompts.select({
|
|
87
|
+
message: "Which framework does this project use?",
|
|
88
|
+
options,
|
|
89
|
+
initialValue,
|
|
90
|
+
});
|
|
91
|
+
if (detected.length === 1) {
|
|
92
|
+
return unlessCancelled(await select(frameworkOptions(all), detected[0]));
|
|
93
|
+
}
|
|
94
|
+
if (detected.length > 1) {
|
|
95
|
+
return unlessCancelled(await select(frameworkOptions(detected)));
|
|
96
|
+
}
|
|
97
|
+
return unlessCancelled(await select(frameworkOptions(all), "generic"));
|
|
98
|
+
}
|
|
99
|
+
|
|
100
|
+
async function resolveWireSchema(ctx) {
|
|
101
|
+
const { args, projectDir } = ctx;
|
|
102
|
+
let source = args.schema?.trim();
|
|
103
|
+
if (source) {
|
|
104
|
+
const problem = validateSchemaSource(source);
|
|
105
|
+
if (problem) fail(problem);
|
|
106
|
+
} else {
|
|
107
|
+
source = unlessCancelled(
|
|
108
|
+
await prompts.text({
|
|
109
|
+
message: "Schema source (path, glob or URL)",
|
|
110
|
+
validate: validateSchemaSource,
|
|
111
|
+
}),
|
|
112
|
+
).trim();
|
|
113
|
+
}
|
|
114
|
+
ctx.schemaRef = toSchemaRef(source, projectDir);
|
|
115
|
+
ctx.loader = detectLoader(source);
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
async function resolveWireOutput(ctx) {
|
|
119
|
+
const { args, projectDir, descriptor } = ctx;
|
|
120
|
+
let output = args.output;
|
|
121
|
+
if (output === undefined) {
|
|
122
|
+
const hint = descriptor.outputHint ? ` (${descriptor.outputHint})` : "";
|
|
123
|
+
output = unlessCancelled(
|
|
124
|
+
await prompts.text({
|
|
125
|
+
message: `Output folder for the generated docs${hint}`,
|
|
126
|
+
validate: (value) => validateOutput(projectDir, value).error,
|
|
127
|
+
}),
|
|
128
|
+
);
|
|
129
|
+
}
|
|
130
|
+
const { error, warning } = validateOutput(projectDir, output);
|
|
131
|
+
if (error) fail(error);
|
|
132
|
+
if (warning) prompts.log.warn(warning);
|
|
133
|
+
ctx.output = output.trim();
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
async function resolveSiteBase(ctx) {
|
|
137
|
+
const { args } = ctx;
|
|
138
|
+
if (args["site-base"] !== undefined) return args["site-base"];
|
|
139
|
+
if (args.yes) return "/";
|
|
140
|
+
const answer = unlessCancelled(
|
|
141
|
+
await prompts.text({
|
|
142
|
+
message: "Base path the site is served from",
|
|
143
|
+
placeholder: "/",
|
|
144
|
+
defaultValue: "/",
|
|
145
|
+
}),
|
|
146
|
+
);
|
|
147
|
+
return answer.trim() || "/";
|
|
148
|
+
}
|
|
149
|
+
|
|
150
|
+
async function resolveLinkRoot(ctx) {
|
|
151
|
+
const { args } = ctx;
|
|
152
|
+
if (args["link-root"] !== undefined) {
|
|
153
|
+
return args["link-root"].trim() || null;
|
|
154
|
+
}
|
|
155
|
+
const suggestion = suggestLinkRoot(ctx.descriptor, ctx.output, {
|
|
156
|
+
siteBase: ctx.siteBase,
|
|
157
|
+
});
|
|
158
|
+
if (args.yes) return suggestion;
|
|
159
|
+
const answer = unlessCancelled(
|
|
160
|
+
await prompts.text({
|
|
161
|
+
message: "Link root (route of the generated docs, blank for none)",
|
|
162
|
+
initialValue: suggestion,
|
|
163
|
+
}),
|
|
164
|
+
);
|
|
165
|
+
return answer.trim() || null;
|
|
166
|
+
}
|
|
167
|
+
|
|
168
|
+
async function resolveWireLinks(ctx) {
|
|
169
|
+
const { links } = ctx.descriptor;
|
|
170
|
+
if (links === "relative") return;
|
|
171
|
+
if (links === "absolute") ctx.siteBase = await resolveSiteBase(ctx);
|
|
172
|
+
ctx.linkRoot = await resolveLinkRoot(ctx);
|
|
173
|
+
}
|
|
174
|
+
|
|
175
|
+
/** Warns when the requested formatter cannot be found yet. */
|
|
176
|
+
function checkFormatter(ctx) {
|
|
177
|
+
const name = ctx.args.formatter;
|
|
178
|
+
if (!name) return;
|
|
179
|
+
if (name.startsWith(".") || name.startsWith("/")) {
|
|
180
|
+
if (!fs.existsSync(path.resolve(ctx.projectDir, name))) {
|
|
181
|
+
prompts.log.warn(`${name} does not exist.`);
|
|
182
|
+
}
|
|
183
|
+
return;
|
|
184
|
+
}
|
|
185
|
+
try {
|
|
186
|
+
createRequire(path.join(ctx.projectDir, "package.json")).resolve(name);
|
|
187
|
+
} catch {
|
|
188
|
+
prompts.log.warn(`${name} is not installed in the project yet.`);
|
|
189
|
+
}
|
|
190
|
+
}
|
|
191
|
+
|
|
192
|
+
/** Works out the packages wire mode needs and warns when --install has no package.json to use. */
|
|
193
|
+
function planDependencies(ctx) {
|
|
194
|
+
const { args, project, descriptor, loader } = ctx;
|
|
195
|
+
ctx.packages = requiredPackages({
|
|
196
|
+
descriptor,
|
|
197
|
+
loader,
|
|
198
|
+
formatter: args.formatter,
|
|
199
|
+
packageJson: project.packageJson,
|
|
200
|
+
});
|
|
201
|
+
if (args.install && !project.packageJson) {
|
|
202
|
+
prompts.log.warn(
|
|
203
|
+
"--install ignored: there is no package.json — run the generator with npx instead.",
|
|
204
|
+
);
|
|
205
|
+
}
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
function writePlan(ctx) {
|
|
209
|
+
const { args, projectDir, project, descriptor } = ctx;
|
|
210
|
+
const plan = planWire(
|
|
211
|
+
{
|
|
212
|
+
descriptor,
|
|
213
|
+
schema: ctx.schemaRef,
|
|
214
|
+
loader: ctx.loader,
|
|
215
|
+
output: ctx.output,
|
|
216
|
+
linkRoot: ctx.linkRoot,
|
|
217
|
+
siteBase: ctx.siteBase,
|
|
218
|
+
formatter: args.formatter,
|
|
219
|
+
},
|
|
220
|
+
project,
|
|
221
|
+
{ scriptName: ctx.scriptName },
|
|
222
|
+
);
|
|
223
|
+
ctx.plan = plan;
|
|
224
|
+
checkFormatter(ctx);
|
|
225
|
+
planDependencies(ctx);
|
|
226
|
+
if (args["dry-run"]) {
|
|
227
|
+
prompts.note(formatWirePlan(plan), "Dry run — nothing written");
|
|
228
|
+
return;
|
|
229
|
+
}
|
|
230
|
+
for (const file of applyWirePlan(projectDir, plan, project)) {
|
|
231
|
+
prompts.log.success(`Wrote ${file}`);
|
|
232
|
+
}
|
|
233
|
+
for (const warning of plan.warnings) prompts.log.warn(warning);
|
|
234
|
+
if (plan.mergeBlock) {
|
|
235
|
+
prompts.note(plan.mergeBlock, "Merge into your existing GraphQL config");
|
|
236
|
+
}
|
|
237
|
+
}
|
|
238
|
+
|
|
239
|
+
/** Ordered steps that add GraphQL-Markdown to an existing project. */
|
|
240
|
+
export const WIRE_STEPS = [
|
|
241
|
+
{
|
|
242
|
+
id: "inspect",
|
|
243
|
+
title: "Inspect project",
|
|
244
|
+
run(ctx) {
|
|
245
|
+
ctx.project = inspectProject(ctx.projectDir);
|
|
246
|
+
ctx.detected = detectFrameworks(ctx.project.packageJson);
|
|
247
|
+
ctx.scriptName = ctx.args.script || "docs:api";
|
|
248
|
+
preflight(ctx);
|
|
249
|
+
},
|
|
250
|
+
},
|
|
251
|
+
{
|
|
252
|
+
id: "framework",
|
|
253
|
+
title: "Choose framework",
|
|
254
|
+
async run(ctx) {
|
|
255
|
+
ctx.framework = await resolveWireFramework(ctx);
|
|
256
|
+
ctx.descriptor = WIRE_FRAMEWORKS[ctx.framework];
|
|
257
|
+
},
|
|
258
|
+
},
|
|
259
|
+
{ id: "schema", title: "Choose schema", run: resolveWireSchema },
|
|
260
|
+
{ id: "output", title: "Choose output folder", run: resolveWireOutput },
|
|
261
|
+
{ id: "links", title: "Configure links", run: resolveWireLinks },
|
|
262
|
+
{ id: "write", title: "Write configuration", run: writePlan },
|
|
263
|
+
{
|
|
264
|
+
id: "packageManager",
|
|
265
|
+
title: "Choose package manager",
|
|
266
|
+
when: (ctx) =>
|
|
267
|
+
Boolean(ctx.project.packageJson) &&
|
|
268
|
+
(!ctx.args["dry-run"] || ctx.packages.length > 0),
|
|
269
|
+
async run(ctx) {
|
|
270
|
+
ctx.packageManager = await resolvePackageManager(
|
|
271
|
+
ctx.args,
|
|
272
|
+
ctx.projectDir,
|
|
273
|
+
);
|
|
274
|
+
},
|
|
275
|
+
},
|
|
276
|
+
{
|
|
277
|
+
id: "install",
|
|
278
|
+
title: "Install dev dependencies",
|
|
279
|
+
optional: true,
|
|
280
|
+
when: (ctx) =>
|
|
281
|
+
Boolean(ctx.args.install) && !ctx.args["dry-run"] && needsInstall(ctx),
|
|
282
|
+
run: (ctx) =>
|
|
283
|
+
addDevDependencies(ctx.packageManager, ctx.projectDir, ctx.packages),
|
|
284
|
+
catchUp: (ctx) =>
|
|
285
|
+
needsInstall(ctx)
|
|
286
|
+
? [addDevCommand(ctx.packageManager, ctx.packages)]
|
|
287
|
+
: [],
|
|
288
|
+
},
|
|
289
|
+
];
|
|
290
|
+
|
|
291
|
+
/** Prints the closing summary for wire mode; `outcomes` are the step results. */
|
|
292
|
+
export function printWireOutro(ctx, outcomes = []) {
|
|
293
|
+
if (ctx.args["dry-run"]) {
|
|
294
|
+
if (needsInstall(ctx)) {
|
|
295
|
+
const command = addDevCommand(ctx.packageManager, ctx.packages);
|
|
296
|
+
prompts.log.info(
|
|
297
|
+
ctx.args.install
|
|
298
|
+
? `Would install: ${command}`
|
|
299
|
+
: `Install with: ${command}`,
|
|
300
|
+
);
|
|
301
|
+
}
|
|
302
|
+
prompts.outro("Dry run complete — nothing was written.");
|
|
303
|
+
return;
|
|
304
|
+
}
|
|
305
|
+
const { plan, scriptName, descriptor } = ctx;
|
|
306
|
+
const hasScript = plan.script.name || plan.script.skipped?.includes("exists");
|
|
307
|
+
const generate = hasScript
|
|
308
|
+
? `${ctx.packageManager} run ${scriptName}`
|
|
309
|
+
: "npx -p @graphql-markdown/cli gqlmd graphql-to-doc";
|
|
310
|
+
// Commands for steps that did not finish (e.g. the install), then the generate step.
|
|
311
|
+
const catchUp = outcomes
|
|
312
|
+
.filter((outcome) => outcome.status !== "done" && outcome.catchUp)
|
|
313
|
+
.flatMap(({ step }) => step.catchUp?.(ctx) ?? []);
|
|
314
|
+
const steps = [
|
|
315
|
+
...catchUp,
|
|
316
|
+
generate,
|
|
317
|
+
descriptor.nextSteps({
|
|
318
|
+
outputDir: normalizeOutput(ctx.output),
|
|
319
|
+
route: ctx.linkRoot,
|
|
320
|
+
}),
|
|
321
|
+
];
|
|
322
|
+
const { tokenEnvVar } = ctx.loader;
|
|
323
|
+
const tokenHint = tokenEnvVar
|
|
324
|
+
? `\nNote: set the ${tokenEnvVar} environment variable so the GitHub schema can be loaded.\n`
|
|
325
|
+
: "";
|
|
326
|
+
const list = steps.map((step, i) => ` ${i + 1}. ${step}`).join("\n");
|
|
327
|
+
prompts.outro(`
|
|
328
|
+
${failureNote(outcomes)}Next steps:
|
|
329
|
+
${list}
|
|
330
|
+
${tokenHint}
|
|
331
|
+
Documentation: ${DOCS_URL}
|
|
332
|
+
`);
|
|
333
|
+
}
|
|
@@ -0,0 +1,93 @@
|
|
|
1
|
+
const BARE_KEY = /^[A-Za-z_][\w-]*$/;
|
|
2
|
+
|
|
3
|
+
const INDENT = " ";
|
|
4
|
+
|
|
5
|
+
const quoteSingle = (text) => `'${text.replaceAll("'", "''")}'`;
|
|
6
|
+
|
|
7
|
+
const isPlainObject = (value) => {
|
|
8
|
+
if (value === null || typeof value !== "object" || Array.isArray(value)) {
|
|
9
|
+
return false;
|
|
10
|
+
}
|
|
11
|
+
const proto = Object.getPrototypeOf(value);
|
|
12
|
+
return proto === Object.prototype || proto === null;
|
|
13
|
+
};
|
|
14
|
+
|
|
15
|
+
const describeType = (value) => {
|
|
16
|
+
if (Array.isArray(value)) {
|
|
17
|
+
return "array";
|
|
18
|
+
}
|
|
19
|
+
return typeof value;
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
const formatKey = (key) => (BARE_KEY.test(key) ? key : quoteSingle(key));
|
|
23
|
+
|
|
24
|
+
const formatScalar = (value, path) => {
|
|
25
|
+
if (value === null) {
|
|
26
|
+
return "null";
|
|
27
|
+
}
|
|
28
|
+
switch (typeof value) {
|
|
29
|
+
case "string":
|
|
30
|
+
return quoteSingle(value);
|
|
31
|
+
case "boolean":
|
|
32
|
+
return String(value);
|
|
33
|
+
case "number":
|
|
34
|
+
if (!Number.isFinite(value)) {
|
|
35
|
+
throw new TypeError(
|
|
36
|
+
`Unsupported value at ${path}: non-finite number ${value}`,
|
|
37
|
+
);
|
|
38
|
+
}
|
|
39
|
+
return String(value);
|
|
40
|
+
default:
|
|
41
|
+
throw new TypeError(
|
|
42
|
+
`Unsupported value at ${path}: ${describeType(value)}`,
|
|
43
|
+
);
|
|
44
|
+
}
|
|
45
|
+
};
|
|
46
|
+
|
|
47
|
+
const serializeObject = (object, depth, parentPath, lines) => {
|
|
48
|
+
const pad = INDENT.repeat(depth);
|
|
49
|
+
for (const key of Object.keys(object)) {
|
|
50
|
+
const value = object[key];
|
|
51
|
+
if (value === undefined) {
|
|
52
|
+
continue;
|
|
53
|
+
}
|
|
54
|
+
const path = parentPath ? `${parentPath}.${key}` : key;
|
|
55
|
+
const head = `${pad}${formatKey(key)}`;
|
|
56
|
+
if (isPlainObject(value)) {
|
|
57
|
+
if (Object.keys(value).length === 0) {
|
|
58
|
+
lines.push(`${head}: {}`);
|
|
59
|
+
} else {
|
|
60
|
+
lines.push(`${head}:`);
|
|
61
|
+
serializeObject(value, depth + 1, path, lines);
|
|
62
|
+
}
|
|
63
|
+
} else {
|
|
64
|
+
lines.push(`${head}: ${formatScalar(value, path)}`);
|
|
65
|
+
}
|
|
66
|
+
}
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Minimal YAML serializer for `.graphqlrc` files.
|
|
71
|
+
*
|
|
72
|
+
* Exists so that `npm create` does not need a YAML dependency: the generated
|
|
73
|
+
* config only uses plain objects, strings, booleans, finite numbers and null.
|
|
74
|
+
* Strings are always single-quoted, `undefined` values are omitted, and arrays
|
|
75
|
+
* or other unsupported types throw a TypeError naming the offending key path.
|
|
76
|
+
*
|
|
77
|
+
* @param {Record<string, unknown>} value Plain object to serialize.
|
|
78
|
+
* @returns {string} YAML text with 2-space indentation and a single trailing newline.
|
|
79
|
+
* @throws {TypeError} When the top level is not an object or a nested value is unsupported.
|
|
80
|
+
*/
|
|
81
|
+
export const toYaml = (value) => {
|
|
82
|
+
if (!isPlainObject(value)) {
|
|
83
|
+
throw new TypeError(
|
|
84
|
+
`toYaml expects a plain object at the top level, received ${describeType(value)}`,
|
|
85
|
+
);
|
|
86
|
+
}
|
|
87
|
+
const lines = [];
|
|
88
|
+
serializeObject(value, 0, "", lines);
|
|
89
|
+
if (lines.length === 0) {
|
|
90
|
+
return "{}\n";
|
|
91
|
+
}
|
|
92
|
+
return `${lines.join("\n")}\n`;
|
|
93
|
+
};
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "create-graphql-markdown-docs",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "1.0.0",
|
|
4
4
|
"description": "Create a new GraphQL API documentation site with GraphQL Markdown and Nuxt or Docusaurus",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"homepage": "https://graphql-markdown.dev",
|
|
@@ -51,7 +51,7 @@
|
|
|
51
51
|
"package-manager-detector": "^1.0.0"
|
|
52
52
|
},
|
|
53
53
|
"devDependencies": {
|
|
54
|
-
"@graphql-markdown/tooling-config": ""
|
|
54
|
+
"@graphql-markdown/tooling-config": "^1.0.0"
|
|
55
55
|
},
|
|
56
56
|
"engines": {
|
|
57
57
|
"node": ">=22.12.0"
|
|
@@ -0,0 +1,20 @@
|
|
|
1
|
+
# Dependencies
|
|
2
|
+
/node_modules
|
|
3
|
+
|
|
4
|
+
# Production
|
|
5
|
+
/build
|
|
6
|
+
|
|
7
|
+
# Generated files
|
|
8
|
+
.docusaurus
|
|
9
|
+
.cache-loader
|
|
10
|
+
|
|
11
|
+
# Misc
|
|
12
|
+
.DS_Store
|
|
13
|
+
.env.local
|
|
14
|
+
.env.development.local
|
|
15
|
+
.env.test.local
|
|
16
|
+
.env.production.local
|
|
17
|
+
|
|
18
|
+
npm-debug.log*
|
|
19
|
+
yarn-debug.log*
|
|
20
|
+
yarn-error.log*
|