@hia-doc/dotnetdoc-runner 0.1.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 +21 -0
- package/README.md +11 -0
- package/package.json +44 -0
- package/src/cli.mjs +69 -0
- package/src/index.mjs +283 -0
- package/src/schema.mjs +57 -0
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 mandolin
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
ADDED
|
@@ -0,0 +1,11 @@
|
|
|
1
|
+
# @hia-doc/dotnetdoc-runner
|
|
2
|
+
|
|
3
|
+
Standalone runner and CLI for compiler-generated .NET XML documentation files.
|
|
4
|
+
|
|
5
|
+
```sh
|
|
6
|
+
hia-dotnetdoc --config dotnetdoc.config.json
|
|
7
|
+
```
|
|
8
|
+
|
|
9
|
+
This package emits DotNetDoc extraction artifacts, HIA document artifacts and a
|
|
10
|
+
documentation producer result manifest without embedding private source text.
|
|
11
|
+
|
package/package.json
ADDED
|
@@ -0,0 +1,44 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@hia-doc/dotnetdoc-runner",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Standalone .NET XML documentation runner and CLI.",
|
|
5
|
+
"type": "module",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"keywords": [
|
|
8
|
+
"hia",
|
|
9
|
+
"dotnetdoc",
|
|
10
|
+
"dotnet",
|
|
11
|
+
"csharp",
|
|
12
|
+
"documentation"
|
|
13
|
+
],
|
|
14
|
+
"repository": {
|
|
15
|
+
"type": "git",
|
|
16
|
+
"url": "git+https://github.com/mandolin/hia-dotnetdoc.git",
|
|
17
|
+
"directory": "packages/dotnetdoc-runner"
|
|
18
|
+
},
|
|
19
|
+
"bugs": {
|
|
20
|
+
"url": "https://github.com/mandolin/hia-dotnetdoc/issues"
|
|
21
|
+
},
|
|
22
|
+
"homepage": "https://github.com/mandolin/hia-dotnetdoc/tree/main/packages/dotnetdoc-runner#readme",
|
|
23
|
+
"exports": {
|
|
24
|
+
".": "./src/index.mjs"
|
|
25
|
+
},
|
|
26
|
+
"bin": {
|
|
27
|
+
"hia-dotnetdoc": "src/cli.mjs",
|
|
28
|
+
"dotnetdoc": "src/cli.mjs"
|
|
29
|
+
},
|
|
30
|
+
"publishConfig": {
|
|
31
|
+
"access": "public"
|
|
32
|
+
},
|
|
33
|
+
"files": [
|
|
34
|
+
"src",
|
|
35
|
+
"README.md",
|
|
36
|
+
"LICENSE"
|
|
37
|
+
],
|
|
38
|
+
"dependencies": {
|
|
39
|
+
"@hia-doc/dotnet-source-extractor": "0.1.0",
|
|
40
|
+
"@hia-doc/dotnet-xml-doc-extractor": "0.1.0",
|
|
41
|
+
"@hia-doc/dotnetdoc-adapter": "0.1.0",
|
|
42
|
+
"@hia-doc/dotnetdoc-spec": "0.1.0"
|
|
43
|
+
}
|
|
44
|
+
}
|
package/src/cli.mjs
ADDED
|
@@ -0,0 +1,69 @@
|
|
|
1
|
+
#!/usr/bin/env node
|
|
2
|
+
|
|
3
|
+
import path from "node:path";
|
|
4
|
+
import { parseArgs } from "node:util";
|
|
5
|
+
|
|
6
|
+
import {
|
|
7
|
+
DOTNETDOC_RUNNER_VERSION,
|
|
8
|
+
loadDotnetDocConfig,
|
|
9
|
+
runDotnetDoc
|
|
10
|
+
} from "./index.mjs";
|
|
11
|
+
|
|
12
|
+
const { values, positionals } = parseArgs({
|
|
13
|
+
options: {
|
|
14
|
+
config: { type: "string", short: "c" },
|
|
15
|
+
help: { type: "boolean", short: "h" },
|
|
16
|
+
"out-dir": { type: "string", short: "o" },
|
|
17
|
+
title: { type: "string" },
|
|
18
|
+
version: { type: "boolean", short: "v" },
|
|
19
|
+
"workspace-root": { type: "string" }
|
|
20
|
+
},
|
|
21
|
+
allowPositionals: true,
|
|
22
|
+
strict: true
|
|
23
|
+
});
|
|
24
|
+
|
|
25
|
+
if (values.help) {
|
|
26
|
+
process.stdout.write(`HIA DotNetDoc ${DOTNETDOC_RUNNER_VERSION}\n\nUsage:\n hia-dotnetdoc --config dotnetdoc.config.json\n hia-dotnetdoc [options] <documentation.xml...>\n\nOptions:\n -c, --config <path>\n -o, --out-dir <path>\n --workspace-root <path>\n --title <title>\n -v, --version\n`);
|
|
27
|
+
process.exit(0);
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
if (values.version) {
|
|
31
|
+
process.stdout.write(`${DOTNETDOC_RUNNER_VERSION}\n`);
|
|
32
|
+
process.exit(0);
|
|
33
|
+
}
|
|
34
|
+
|
|
35
|
+
try {
|
|
36
|
+
const request = values.config
|
|
37
|
+
? await loadDotnetDocConfig(values.config)
|
|
38
|
+
: createCliRequest(values, positionals);
|
|
39
|
+
|
|
40
|
+
if (values["out-dir"]) {
|
|
41
|
+
request.outputDirectory = path.resolve(request.workspaceRoot, values["out-dir"]);
|
|
42
|
+
}
|
|
43
|
+
|
|
44
|
+
const result = await runDotnetDoc(request);
|
|
45
|
+
process.stdout.write(`DotNetDoc ${result.status}: ${result.artifacts.length} artifact(s).\n`);
|
|
46
|
+
process.exitCode = result.status === "success" ? 0 : 1;
|
|
47
|
+
} catch (error) {
|
|
48
|
+
process.stderr.write(`DotNetDoc failed: ${error instanceof Error ? error.message : String(error)}\n`);
|
|
49
|
+
process.exitCode = 1;
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
function createCliRequest(cliValues, inputs) {
|
|
53
|
+
if (inputs.length === 0) {
|
|
54
|
+
throw new TypeError("At least one XML documentation input or --config is required.");
|
|
55
|
+
}
|
|
56
|
+
const workspaceRoot = path.resolve(process.cwd(), cliValues["workspace-root"] ?? ".");
|
|
57
|
+
return {
|
|
58
|
+
workspaceRoot,
|
|
59
|
+
outputDirectory: path.resolve(workspaceRoot, cliValues["out-dir"] ?? "dist/dotnetdoc"),
|
|
60
|
+
inputs: inputs.map((inputPath) => ({
|
|
61
|
+
kind: "dotnet-xml-doc",
|
|
62
|
+
path: inputPath,
|
|
63
|
+
title: cliValues.title
|
|
64
|
+
})),
|
|
65
|
+
options: {
|
|
66
|
+
writeResultManifest: true
|
|
67
|
+
}
|
|
68
|
+
};
|
|
69
|
+
}
|
package/src/index.mjs
ADDED
|
@@ -0,0 +1,283 @@
|
|
|
1
|
+
import { readFile, mkdir, writeFile } from "node:fs/promises";
|
|
2
|
+
import path from "node:path";
|
|
3
|
+
|
|
4
|
+
import { extractDotnetSourceFiles } from "@hia-doc/dotnet-source-extractor";
|
|
5
|
+
import { extractDotnetXmlDocs } from "@hia-doc/dotnet-xml-doc-extractor";
|
|
6
|
+
import { dotnetXmlDocsToHiaDocument } from "@hia-doc/dotnetdoc-adapter";
|
|
7
|
+
|
|
8
|
+
export {
|
|
9
|
+
DOTNETDOC_CONFIG_JSON_SCHEMA,
|
|
10
|
+
DOTNETDOC_CONFIG_SCHEMA_ID,
|
|
11
|
+
DOTNETDOC_CONFIG_SCHEMA_VERSION
|
|
12
|
+
} from "./schema.mjs";
|
|
13
|
+
import { DOTNETDOC_CONFIG_SCHEMA_ID, DOTNETDOC_CONFIG_SCHEMA_VERSION } from "./schema.mjs";
|
|
14
|
+
|
|
15
|
+
export const DOTNETDOC_RUNNER_VERSION = "0.1.0";
|
|
16
|
+
export const DOTNETDOC_INPUT_KINDS = Object.freeze(["dotnet-xml-doc", "dotnet-csharp-source"]);
|
|
17
|
+
export const DOTNETDOC_OUTPUT_KINDS = Object.freeze(["dotnetdoc-extraction", "hia-document"]);
|
|
18
|
+
|
|
19
|
+
const RESULT_CONTRACT = "documentation-producer-result";
|
|
20
|
+
const RESULT_CONTRACT_VERSION = "0.1.0-draft";
|
|
21
|
+
const PRODUCER_ID = "dotnetdoc";
|
|
22
|
+
const SAFE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
|
|
23
|
+
|
|
24
|
+
/**
|
|
25
|
+
* 执行一次 .NET XML documentation 文档构建,并返回 documentation producer result。
|
|
26
|
+
* Runs one .NET XML documentation build and returns a documentation producer result.
|
|
27
|
+
*
|
|
28
|
+
* @param {object} request <lang><en>DotNetDoc runner request with absolute workspace/output directories.</en><zh-CN>包含绝对工作区与输出目录的 DotNetDoc runner 请求。</zh-CN></lang>
|
|
29
|
+
* @param {{ signal?: AbortSignal, reportProgress?: Function }} [context] <lang><en>Optional producer runtime context.</en><zh-CN>可选 producer 运行时上下文。</zh-CN></lang>
|
|
30
|
+
* @returns {Promise<object>} <lang><en>Documentation producer result.</en><zh-CN>Documentation producer result。</zh-CN></lang>
|
|
31
|
+
* @lang zh-CN 执行 .NET XML documentation 构建。
|
|
32
|
+
*/
|
|
33
|
+
export async function runDotnetDoc(request, context = {}) {
|
|
34
|
+
const normalized = normalizeRequest(request);
|
|
35
|
+
await mkdir(normalized.outputDirectory, { recursive: true });
|
|
36
|
+
|
|
37
|
+
const artifacts = [];
|
|
38
|
+
const diagnostics = [];
|
|
39
|
+
let completed = 0;
|
|
40
|
+
|
|
41
|
+
for (const [index, input] of normalized.inputs.entries()) {
|
|
42
|
+
if (context.signal?.aborted) {
|
|
43
|
+
diagnostics.push(createDiagnostic("DOTNETDOC_RUNNER_ABORTED", "DotNetDoc runner was aborted before all inputs completed.", "error"));
|
|
44
|
+
break;
|
|
45
|
+
}
|
|
46
|
+
|
|
47
|
+
context.reportProgress?.({
|
|
48
|
+
phase: "extract",
|
|
49
|
+
current: index,
|
|
50
|
+
total: normalized.inputs.length,
|
|
51
|
+
message: input.path
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
try {
|
|
55
|
+
const generated = await processInput(input, normalized);
|
|
56
|
+
artifacts.push(...generated.artifacts);
|
|
57
|
+
diagnostics.push(...generated.diagnostics);
|
|
58
|
+
completed += 1;
|
|
59
|
+
} catch (error) {
|
|
60
|
+
diagnostics.push(createDiagnostic(
|
|
61
|
+
"DOTNETDOC_RUNNER_INPUT_FAILED",
|
|
62
|
+
`Unable to process DotNetDoc input ${input.path}.`,
|
|
63
|
+
"error",
|
|
64
|
+
input.path,
|
|
65
|
+
{ cause: error instanceof Error ? error.message : String(error) }
|
|
66
|
+
));
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === "error");
|
|
71
|
+
const result = {
|
|
72
|
+
contract: RESULT_CONTRACT,
|
|
73
|
+
contractVersion: RESULT_CONTRACT_VERSION,
|
|
74
|
+
producer: {
|
|
75
|
+
id: PRODUCER_ID,
|
|
76
|
+
version: DOTNETDOC_RUNNER_VERSION
|
|
77
|
+
},
|
|
78
|
+
status: hasErrors ? (artifacts.length > 0 ? "partial" : "failed") : "success",
|
|
79
|
+
artifacts,
|
|
80
|
+
diagnostics
|
|
81
|
+
};
|
|
82
|
+
|
|
83
|
+
if (normalized.options.writeResultManifest) {
|
|
84
|
+
await writeJson(path.join(normalized.outputDirectory, "dotnetdoc.producer-result.json"), result);
|
|
85
|
+
}
|
|
86
|
+
|
|
87
|
+
context.reportProgress?.({
|
|
88
|
+
phase: "complete",
|
|
89
|
+
current: completed,
|
|
90
|
+
total: normalized.inputs.length
|
|
91
|
+
});
|
|
92
|
+
|
|
93
|
+
return result;
|
|
94
|
+
}
|
|
95
|
+
|
|
96
|
+
/**
|
|
97
|
+
* 读取 versioned DotNetDoc JSON config 并转成 runner request。
|
|
98
|
+
* Loads a versioned DotNetDoc JSON config and converts it into a runner request.
|
|
99
|
+
*
|
|
100
|
+
* @param {string} configPath <lang><en>Config path relative to cwd or absolute.</en><zh-CN>相对当前目录或绝对的配置文件路径。</zh-CN></lang>
|
|
101
|
+
* @param {{ cwd?: string }} [options] <lang><en>Config loading options.</en><zh-CN>配置加载选项。</zh-CN></lang>
|
|
102
|
+
* @returns {Promise<object>} <lang><en>Normalized runner request.</en><zh-CN>规范化后的 runner 请求。</zh-CN></lang>
|
|
103
|
+
* @lang zh-CN 加载 DotNetDoc 配置。
|
|
104
|
+
*/
|
|
105
|
+
export async function loadDotnetDocConfig(configPath, options = {}) {
|
|
106
|
+
const absoluteConfigPath = path.resolve(options.cwd ?? process.cwd(), configPath);
|
|
107
|
+
const config = JSON.parse(await readFile(absoluteConfigPath, "utf8"));
|
|
108
|
+
assertRecord(config, "DotNetDoc config must be a JSON object.");
|
|
109
|
+
assertKnownKeys(config, ["$schema", "schemaVersion", "workspaceRoot", "outputDirectory", "inputs", "options", "profileIds"], "config");
|
|
110
|
+
if (config.schemaVersion !== DOTNETDOC_CONFIG_SCHEMA_VERSION) {
|
|
111
|
+
throw new TypeError(`schemaVersion must be ${DOTNETDOC_CONFIG_SCHEMA_VERSION}.`);
|
|
112
|
+
}
|
|
113
|
+
if (config.$schema !== undefined && config.$schema !== DOTNETDOC_CONFIG_SCHEMA_ID) {
|
|
114
|
+
throw new TypeError(`$schema must be ${DOTNETDOC_CONFIG_SCHEMA_ID}.`);
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
const configDirectory = path.dirname(absoluteConfigPath);
|
|
118
|
+
const workspaceDirectory = normalizeConfigDirectory(config.workspaceRoot ?? ".", "workspaceRoot");
|
|
119
|
+
const outputDirectory = normalizeConfigDirectory(config.outputDirectory ?? "dist/dotnetdoc", "outputDirectory");
|
|
120
|
+
const workspaceRoot = path.resolve(configDirectory, workspaceDirectory);
|
|
121
|
+
|
|
122
|
+
return normalizeRequest({
|
|
123
|
+
workspaceRoot,
|
|
124
|
+
outputDirectory: path.resolve(workspaceRoot, outputDirectory),
|
|
125
|
+
inputs: config.inputs,
|
|
126
|
+
options: config.options,
|
|
127
|
+
profileIds: config.profileIds
|
|
128
|
+
});
|
|
129
|
+
}
|
|
130
|
+
|
|
131
|
+
function normalizeRequest(request) {
|
|
132
|
+
assertRecord(request, "DotNetDoc request must be an object.");
|
|
133
|
+
const workspaceRoot = path.resolve(String(request.workspaceRoot ?? process.cwd()));
|
|
134
|
+
const outputDirectory = path.resolve(String(request.outputDirectory ?? path.join(workspaceRoot, "dist", "dotnetdoc")));
|
|
135
|
+
if (!Array.isArray(request.inputs) || request.inputs.length === 0) {
|
|
136
|
+
throw new TypeError("DotNetDoc request must contain at least one input.");
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
const options = {
|
|
140
|
+
writeResultManifest: request.options?.writeResultManifest !== false
|
|
141
|
+
};
|
|
142
|
+
const profileIds = normalizeProfileIds(request.profileIds ?? ["dotnetdoc"]);
|
|
143
|
+
|
|
144
|
+
return {
|
|
145
|
+
workspaceRoot,
|
|
146
|
+
outputDirectory,
|
|
147
|
+
inputs: request.inputs.map(normalizeInput),
|
|
148
|
+
options,
|
|
149
|
+
profileIds
|
|
150
|
+
};
|
|
151
|
+
}
|
|
152
|
+
|
|
153
|
+
function normalizeInput(input, index) {
|
|
154
|
+
assertRecord(input, `inputs[${index}] must be an object.`);
|
|
155
|
+
assertKnownKeys(input, ["kind", "path", "artifactBasePath", "hiaDocumentId", "title"], `inputs[${index}]`);
|
|
156
|
+
if (!DOTNETDOC_INPUT_KINDS.includes(input.kind)) {
|
|
157
|
+
throw new TypeError(`inputs[${index}].kind must be one of: ${DOTNETDOC_INPUT_KINDS.join(", ")}.`);
|
|
158
|
+
}
|
|
159
|
+
|
|
160
|
+
const inputPath = normalizeSafeRelativePath(input.path, `inputs[${index}].path`);
|
|
161
|
+
const artifactBasePath = input.artifactBasePath
|
|
162
|
+
? normalizeSafeRelativePath(input.artifactBasePath, `inputs[${index}].artifactBasePath`)
|
|
163
|
+
: stripXmlExtension(inputPath);
|
|
164
|
+
|
|
165
|
+
return {
|
|
166
|
+
kind: input.kind,
|
|
167
|
+
path: inputPath,
|
|
168
|
+
artifactBasePath,
|
|
169
|
+
hiaDocumentId: input.hiaDocumentId,
|
|
170
|
+
title: input.title
|
|
171
|
+
};
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
async function processInput(input, request) {
|
|
175
|
+
const dotnetdoc = input.kind === "dotnet-xml-doc"
|
|
176
|
+
? await processXmlDocInput(input, request)
|
|
177
|
+
: await processCSharpSourceInput(input, request);
|
|
178
|
+
const hiaDocument = dotnetXmlDocsToHiaDocument(dotnetdoc, {
|
|
179
|
+
id: input.hiaDocumentId,
|
|
180
|
+
title: input.title
|
|
181
|
+
});
|
|
182
|
+
|
|
183
|
+
const dotnetdocPath = `${input.artifactBasePath}.dotnetdoc.json`;
|
|
184
|
+
const hiaPath = `${input.artifactBasePath}.hia.json`;
|
|
185
|
+
await writeJson(path.join(request.outputDirectory, dotnetdocPath), dotnetdoc);
|
|
186
|
+
await writeJson(path.join(request.outputDirectory, hiaPath), hiaDocument);
|
|
187
|
+
|
|
188
|
+
return {
|
|
189
|
+
artifacts: [
|
|
190
|
+
{
|
|
191
|
+
...artifact(`${safeArtifactId(input.artifactBasePath)}-dotnetdoc`, "dotnetdoc-extraction", dotnetdocPath, request.profileIds),
|
|
192
|
+
contract: dotnetdoc.contract,
|
|
193
|
+
contractVersion: dotnetdoc.contractVersion
|
|
194
|
+
},
|
|
195
|
+
artifact(`${safeArtifactId(input.artifactBasePath)}-hia-document`, "hia-document", hiaPath, request.profileIds)
|
|
196
|
+
],
|
|
197
|
+
diagnostics: [...(dotnetdoc.diagnostics ?? []), ...(hiaDocument.diagnostics ?? [])]
|
|
198
|
+
};
|
|
199
|
+
}
|
|
200
|
+
|
|
201
|
+
async function processXmlDocInput(input, request) {
|
|
202
|
+
const xmlPath = path.join(request.workspaceRoot, input.path);
|
|
203
|
+
const xmlText = await readFile(xmlPath, "utf8");
|
|
204
|
+
return extractDotnetXmlDocs(xmlText, { path: input.path });
|
|
205
|
+
}
|
|
206
|
+
|
|
207
|
+
async function processCSharpSourceInput(input, request) {
|
|
208
|
+
return extractDotnetSourceFiles({
|
|
209
|
+
workspaceRoot: request.workspaceRoot,
|
|
210
|
+
paths: [input.path]
|
|
211
|
+
});
|
|
212
|
+
}
|
|
213
|
+
|
|
214
|
+
function artifact(id, kind, artifactPath, profileIds) {
|
|
215
|
+
return {
|
|
216
|
+
id,
|
|
217
|
+
kind,
|
|
218
|
+
path: artifactPath,
|
|
219
|
+
format: "json",
|
|
220
|
+
mediaType: "application/json",
|
|
221
|
+
profileIds
|
|
222
|
+
};
|
|
223
|
+
}
|
|
224
|
+
|
|
225
|
+
async function writeJson(filePath, value) {
|
|
226
|
+
await mkdir(path.dirname(filePath), { recursive: true });
|
|
227
|
+
await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
|
|
228
|
+
}
|
|
229
|
+
|
|
230
|
+
function normalizeProfileIds(profileIds) {
|
|
231
|
+
if (!Array.isArray(profileIds) || profileIds.length === 0 || profileIds.some((id) => typeof id !== "string" || !SAFE_ID_PATTERN.test(id))) {
|
|
232
|
+
throw new TypeError("profileIds must be a non-empty array of safe profile ids.");
|
|
233
|
+
}
|
|
234
|
+
return profileIds;
|
|
235
|
+
}
|
|
236
|
+
|
|
237
|
+
function normalizeConfigDirectory(value, label) {
|
|
238
|
+
return normalizeSafeRelativePath(value, label);
|
|
239
|
+
}
|
|
240
|
+
|
|
241
|
+
function normalizeSafeRelativePath(value, label) {
|
|
242
|
+
if (typeof value !== "string" || value.trim().length === 0) {
|
|
243
|
+
throw new TypeError(`${label} must be a non-empty relative path.`);
|
|
244
|
+
}
|
|
245
|
+
const normalized = value.replaceAll("\\", "/").replace(/^\.\//, "");
|
|
246
|
+
if (!normalized || normalized.startsWith("/") || /^[a-zA-Z]:\//.test(normalized) || normalized.split("/").includes("..")) {
|
|
247
|
+
throw new TypeError(`${label} must be a safe relative path.`);
|
|
248
|
+
}
|
|
249
|
+
return normalized;
|
|
250
|
+
}
|
|
251
|
+
|
|
252
|
+
function stripXmlExtension(value) {
|
|
253
|
+
return value.replace(/\.xml$/i, "");
|
|
254
|
+
}
|
|
255
|
+
|
|
256
|
+
function safeArtifactId(value) {
|
|
257
|
+
return value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-|-$/g, "") || "input";
|
|
258
|
+
}
|
|
259
|
+
|
|
260
|
+
function assertRecord(value, message) {
|
|
261
|
+
if (!value || typeof value !== "object" || Array.isArray(value)) {
|
|
262
|
+
throw new TypeError(message);
|
|
263
|
+
}
|
|
264
|
+
}
|
|
265
|
+
|
|
266
|
+
function assertKnownKeys(value, allowedKeys, label) {
|
|
267
|
+
const allowed = new Set(allowedKeys);
|
|
268
|
+
for (const key of Object.keys(value)) {
|
|
269
|
+
if (!allowed.has(key)) {
|
|
270
|
+
throw new TypeError(`Unsupported ${label} key: ${key}.`);
|
|
271
|
+
}
|
|
272
|
+
}
|
|
273
|
+
}
|
|
274
|
+
|
|
275
|
+
function createDiagnostic(code, message, severity, pathValue, metadata = {}) {
|
|
276
|
+
return {
|
|
277
|
+
code,
|
|
278
|
+
message,
|
|
279
|
+
severity,
|
|
280
|
+
source: pathValue ? { path: pathValue } : null,
|
|
281
|
+
metadata
|
|
282
|
+
};
|
|
283
|
+
}
|
package/src/schema.mjs
ADDED
|
@@ -0,0 +1,57 @@
|
|
|
1
|
+
export const DOTNETDOC_CONFIG_SCHEMA_VERSION = "0.1.0-draft";
|
|
2
|
+
export const DOTNETDOC_CONFIG_SCHEMA_ID = "https://mandolin.github.io/HIA-Documentation/schemas/dotnetdoc-config-0.1.0-draft.schema.json";
|
|
3
|
+
|
|
4
|
+
const relativePath = {
|
|
5
|
+
type: "string",
|
|
6
|
+
minLength: 1,
|
|
7
|
+
not: {
|
|
8
|
+
anyOf: [
|
|
9
|
+
{ pattern: "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)" },
|
|
10
|
+
{ pattern: "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)" }
|
|
11
|
+
]
|
|
12
|
+
}
|
|
13
|
+
};
|
|
14
|
+
|
|
15
|
+
export const DOTNETDOC_CONFIG_JSON_SCHEMA = Object.freeze({
|
|
16
|
+
$schema: "https://json-schema.org/draft/2020-12/schema",
|
|
17
|
+
$id: DOTNETDOC_CONFIG_SCHEMA_ID,
|
|
18
|
+
title: "DotNetDoc Config",
|
|
19
|
+
type: "object",
|
|
20
|
+
additionalProperties: false,
|
|
21
|
+
required: ["schemaVersion", "workspaceRoot", "outputDirectory", "inputs"],
|
|
22
|
+
properties: {
|
|
23
|
+
$schema: { const: DOTNETDOC_CONFIG_SCHEMA_ID },
|
|
24
|
+
schemaVersion: { const: DOTNETDOC_CONFIG_SCHEMA_VERSION },
|
|
25
|
+
workspaceRoot: relativePath,
|
|
26
|
+
outputDirectory: relativePath,
|
|
27
|
+
inputs: {
|
|
28
|
+
type: "array",
|
|
29
|
+
minItems: 1,
|
|
30
|
+
items: {
|
|
31
|
+
type: "object",
|
|
32
|
+
additionalProperties: false,
|
|
33
|
+
required: ["kind", "path"],
|
|
34
|
+
properties: {
|
|
35
|
+
kind: { enum: ["dotnet-xml-doc", "dotnet-csharp-source"] },
|
|
36
|
+
path: relativePath,
|
|
37
|
+
artifactBasePath: relativePath,
|
|
38
|
+
hiaDocumentId: { type: "string", minLength: 1 },
|
|
39
|
+
title: { type: "string", minLength: 1 }
|
|
40
|
+
}
|
|
41
|
+
}
|
|
42
|
+
},
|
|
43
|
+
options: {
|
|
44
|
+
type: "object",
|
|
45
|
+
additionalProperties: false,
|
|
46
|
+
properties: {
|
|
47
|
+
writeResultManifest: { type: "boolean" }
|
|
48
|
+
}
|
|
49
|
+
},
|
|
50
|
+
profileIds: {
|
|
51
|
+
type: "array",
|
|
52
|
+
minItems: 1,
|
|
53
|
+
uniqueItems: true,
|
|
54
|
+
items: { type: "string", pattern: "^[a-z0-9][a-z0-9._-]*$" }
|
|
55
|
+
}
|
|
56
|
+
}
|
|
57
|
+
});
|