@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 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
+ });