@hia-doc/dotnetdoc-runner 0.1.0 → 0.1.1
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 +4 -3
- package/package.json +5 -5
- package/src/cli.mjs +0 -0
- package/src/index.mjs +220 -13
- package/src/schema.mjs +4 -2
package/README.md
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
# @hia-doc/dotnetdoc-runner
|
|
2
2
|
|
|
3
|
-
Standalone runner and CLI for compiler-generated .NET XML documentation files
|
|
3
|
+
Standalone runner and CLI for compiler-generated .NET XML documentation files,
|
|
4
|
+
C# source inputs and ASP.NET endpoint surface inputs.
|
|
4
5
|
|
|
5
6
|
```sh
|
|
6
7
|
hia-dotnetdoc --config dotnetdoc.config.json
|
|
7
8
|
```
|
|
8
9
|
|
|
9
|
-
This package emits DotNetDoc extraction artifacts, HIA document artifacts
|
|
10
|
+
This package emits DotNetDoc extraction artifacts, HIA document artifacts,
|
|
11
|
+
optional source relation artifacts, ASP.NET endpoint extraction artifacts and a
|
|
10
12
|
documentation producer result manifest without embedding private source text.
|
|
11
|
-
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hia-doc/dotnetdoc-runner",
|
|
3
|
-
"version": "0.1.
|
|
3
|
+
"version": "0.1.1",
|
|
4
4
|
"description": "Standalone .NET XML documentation runner and CLI.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"license": "MIT",
|
|
@@ -36,9 +36,9 @@
|
|
|
36
36
|
"LICENSE"
|
|
37
37
|
],
|
|
38
38
|
"dependencies": {
|
|
39
|
-
"@hia-doc/dotnet-source-extractor": "0.1.
|
|
40
|
-
"@hia-doc/dotnet-xml-doc-extractor": "0.1.
|
|
41
|
-
"@hia-doc/dotnetdoc-adapter": "0.1.
|
|
42
|
-
"@hia-doc/dotnetdoc-spec": "0.1.
|
|
39
|
+
"@hia-doc/dotnet-source-extractor": "0.1.1",
|
|
40
|
+
"@hia-doc/dotnet-xml-doc-extractor": "0.1.1",
|
|
41
|
+
"@hia-doc/dotnetdoc-adapter": "0.1.1",
|
|
42
|
+
"@hia-doc/dotnetdoc-spec": "0.1.1"
|
|
43
43
|
}
|
|
44
44
|
}
|
package/src/cli.mjs
CHANGED
|
File without changes
|
package/src/index.mjs
CHANGED
|
@@ -1,9 +1,16 @@
|
|
|
1
1
|
import { readFile, mkdir, writeFile } from "node:fs/promises";
|
|
2
2
|
import path from "node:path";
|
|
3
3
|
|
|
4
|
-
import { extractDotnetSourceFiles } from "@hia-doc/dotnet-source-extractor";
|
|
4
|
+
import { extractAspNetEndpoints, extractDotnetSourceFiles } from "@hia-doc/dotnet-source-extractor";
|
|
5
5
|
import { extractDotnetXmlDocs } from "@hia-doc/dotnet-xml-doc-extractor";
|
|
6
|
-
import { dotnetXmlDocsToHiaDocument } from "@hia-doc/dotnetdoc-adapter";
|
|
6
|
+
import { dotnetAspNetEndpointsToHiaDocument, dotnetXmlDocsToHiaDocument } from "@hia-doc/dotnetdoc-adapter";
|
|
7
|
+
import {
|
|
8
|
+
DOTNETDOC_ASPNET_ENDPOINT_EXTRACTION_CONTRACT,
|
|
9
|
+
DOTNETDOC_CSHARP_SOURCE_EXTRACTION_CONTRACT,
|
|
10
|
+
DOTNETDOC_SOURCE_RELATION_CONTRACT,
|
|
11
|
+
DOTNETDOC_SOURCE_RELATION_CONTRACT_VERSION,
|
|
12
|
+
DOTNETDOC_XML_DOC_EXTRACTION_CONTRACT
|
|
13
|
+
} from "@hia-doc/dotnetdoc-spec";
|
|
7
14
|
|
|
8
15
|
export {
|
|
9
16
|
DOTNETDOC_CONFIG_JSON_SCHEMA,
|
|
@@ -12,9 +19,9 @@ export {
|
|
|
12
19
|
} from "./schema.mjs";
|
|
13
20
|
import { DOTNETDOC_CONFIG_SCHEMA_ID, DOTNETDOC_CONFIG_SCHEMA_VERSION } from "./schema.mjs";
|
|
14
21
|
|
|
15
|
-
export const DOTNETDOC_RUNNER_VERSION = "0.1.
|
|
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"]);
|
|
22
|
+
export const DOTNETDOC_RUNNER_VERSION = "0.1.1";
|
|
23
|
+
export const DOTNETDOC_INPUT_KINDS = Object.freeze(["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface"]);
|
|
24
|
+
export const DOTNETDOC_OUTPUT_KINDS = Object.freeze(["dotnetdoc-extraction", "hia-document", "dotnetdoc-source-relation", "dotnetdoc-aspnet-endpoint-extraction"]);
|
|
18
25
|
|
|
19
26
|
const RESULT_CONTRACT = "documentation-producer-result";
|
|
20
27
|
const RESULT_CONTRACT_VERSION = "0.1.0-draft";
|
|
@@ -36,6 +43,7 @@ export async function runDotnetDoc(request, context = {}) {
|
|
|
36
43
|
|
|
37
44
|
const artifacts = [];
|
|
38
45
|
const diagnostics = [];
|
|
46
|
+
const extractionRecords = [];
|
|
39
47
|
let completed = 0;
|
|
40
48
|
|
|
41
49
|
for (const [index, input] of normalized.inputs.entries()) {
|
|
@@ -55,6 +63,7 @@ export async function runDotnetDoc(request, context = {}) {
|
|
|
55
63
|
const generated = await processInput(input, normalized);
|
|
56
64
|
artifacts.push(...generated.artifacts);
|
|
57
65
|
diagnostics.push(...generated.diagnostics);
|
|
66
|
+
extractionRecords.push(generated.extractionRecord);
|
|
58
67
|
completed += 1;
|
|
59
68
|
} catch (error) {
|
|
60
69
|
diagnostics.push(createDiagnostic(
|
|
@@ -67,6 +76,20 @@ export async function runDotnetDoc(request, context = {}) {
|
|
|
67
76
|
}
|
|
68
77
|
}
|
|
69
78
|
|
|
79
|
+
const sourceRelation = normalized.options.writeSourceRelationArtifact
|
|
80
|
+
? buildSourceRelationArtifact(extractionRecords, normalized)
|
|
81
|
+
: null;
|
|
82
|
+
if (sourceRelation) {
|
|
83
|
+
const relationPath = "dotnetdoc.source-relation.json";
|
|
84
|
+
await writeJson(path.join(normalized.outputDirectory, relationPath), sourceRelation);
|
|
85
|
+
artifacts.push({
|
|
86
|
+
...artifact("dotnetdoc-source-relation", "dotnetdoc-source-relation", relationPath, normalized.profileIds),
|
|
87
|
+
contract: sourceRelation.contract,
|
|
88
|
+
contractVersion: sourceRelation.contractVersion
|
|
89
|
+
});
|
|
90
|
+
diagnostics.push(...sourceRelation.diagnostics);
|
|
91
|
+
}
|
|
92
|
+
|
|
70
93
|
const hasErrors = diagnostics.some((diagnostic) => diagnostic.severity === "error");
|
|
71
94
|
const result = {
|
|
72
95
|
contract: RESULT_CONTRACT,
|
|
@@ -137,7 +160,8 @@ function normalizeRequest(request) {
|
|
|
137
160
|
}
|
|
138
161
|
|
|
139
162
|
const options = {
|
|
140
|
-
writeResultManifest: request.options?.writeResultManifest !== false
|
|
163
|
+
writeResultManifest: request.options?.writeResultManifest !== false,
|
|
164
|
+
writeSourceRelationArtifact: request.options?.writeSourceRelationArtifact !== false
|
|
141
165
|
};
|
|
142
166
|
const profileIds = normalizeProfileIds(request.profileIds ?? ["dotnetdoc"]);
|
|
143
167
|
|
|
@@ -152,7 +176,7 @@ function normalizeRequest(request) {
|
|
|
152
176
|
|
|
153
177
|
function normalizeInput(input, index) {
|
|
154
178
|
assertRecord(input, `inputs[${index}] must be an object.`);
|
|
155
|
-
assertKnownKeys(input, ["kind", "path", "artifactBasePath", "hiaDocumentId", "title"], `inputs[${index}]`);
|
|
179
|
+
assertKnownKeys(input, ["kind", "path", "applicationRoot", "artifactBasePath", "hiaDocumentId", "title"], `inputs[${index}]`);
|
|
156
180
|
if (!DOTNETDOC_INPUT_KINDS.includes(input.kind)) {
|
|
157
181
|
throw new TypeError(`inputs[${index}].kind must be one of: ${DOTNETDOC_INPUT_KINDS.join(", ")}.`);
|
|
158
182
|
}
|
|
@@ -165,6 +189,7 @@ function normalizeInput(input, index) {
|
|
|
165
189
|
return {
|
|
166
190
|
kind: input.kind,
|
|
167
191
|
path: inputPath,
|
|
192
|
+
applicationRoot: input.applicationRoot ? normalizeSafeRelativePath(input.applicationRoot, `inputs[${index}].applicationRoot`) : ".",
|
|
168
193
|
artifactBasePath,
|
|
169
194
|
hiaDocumentId: input.hiaDocumentId,
|
|
170
195
|
title: input.title
|
|
@@ -174,11 +199,18 @@ function normalizeInput(input, index) {
|
|
|
174
199
|
async function processInput(input, request) {
|
|
175
200
|
const dotnetdoc = input.kind === "dotnet-xml-doc"
|
|
176
201
|
? await processXmlDocInput(input, request)
|
|
177
|
-
:
|
|
178
|
-
|
|
179
|
-
|
|
180
|
-
|
|
181
|
-
|
|
202
|
+
: input.kind === "dotnet-csharp-source"
|
|
203
|
+
? await processCSharpSourceInput(input, request)
|
|
204
|
+
: await processAspNetEndpointInput(input, request);
|
|
205
|
+
const hiaDocument = dotnetdoc.contract === DOTNETDOC_ASPNET_ENDPOINT_EXTRACTION_CONTRACT
|
|
206
|
+
? dotnetAspNetEndpointsToHiaDocument(dotnetdoc, {
|
|
207
|
+
id: input.hiaDocumentId,
|
|
208
|
+
title: input.title
|
|
209
|
+
})
|
|
210
|
+
: dotnetXmlDocsToHiaDocument(dotnetdoc, {
|
|
211
|
+
id: input.hiaDocumentId,
|
|
212
|
+
title: input.title
|
|
213
|
+
});
|
|
182
214
|
|
|
183
215
|
const dotnetdocPath = `${input.artifactBasePath}.dotnetdoc.json`;
|
|
184
216
|
const hiaPath = `${input.artifactBasePath}.hia.json`;
|
|
@@ -194,7 +226,174 @@ async function processInput(input, request) {
|
|
|
194
226
|
},
|
|
195
227
|
artifact(`${safeArtifactId(input.artifactBasePath)}-hia-document`, "hia-document", hiaPath, request.profileIds)
|
|
196
228
|
],
|
|
197
|
-
diagnostics: [...(dotnetdoc.diagnostics ?? []), ...(hiaDocument.diagnostics ?? [])]
|
|
229
|
+
diagnostics: [...(dotnetdoc.diagnostics ?? []), ...(hiaDocument.diagnostics ?? [])],
|
|
230
|
+
extractionRecord: {
|
|
231
|
+
input,
|
|
232
|
+
artifactPath: dotnetdocPath,
|
|
233
|
+
hiaPath,
|
|
234
|
+
artifact: dotnetdoc,
|
|
235
|
+
hiaDocument
|
|
236
|
+
}
|
|
237
|
+
};
|
|
238
|
+
}
|
|
239
|
+
|
|
240
|
+
/**
|
|
241
|
+
* Build a relation artifact from compiler XML documentation members to C# declarations.
|
|
242
|
+
*
|
|
243
|
+
* @param {object[]} extractionRecords <lang><en>Extraction records produced by the current runner request.</en><zh-CN>当前 runner 请求生成的抽取记录。</zh-CN></lang>
|
|
244
|
+
* @param {object} request <lang><en>Normalized runner request.</en><zh-CN>规范化后的 runner 请求。</zh-CN></lang>
|
|
245
|
+
* @returns {object|null} <lang><en>Relation artifact when XML and source inputs both exist.</en><zh-CN>当 XML 与源码输入同时存在时返回关系产物。</zh-CN></lang>
|
|
246
|
+
* @lang zh-CN 从编译器 XML documentation member 到 C# declaration 构建关系产物。
|
|
247
|
+
*/
|
|
248
|
+
function buildSourceRelationArtifact(extractionRecords, request) {
|
|
249
|
+
const xmlRecords = extractionRecords.filter((record) => record.artifact.contract === DOTNETDOC_XML_DOC_EXTRACTION_CONTRACT);
|
|
250
|
+
const sourceRecords = extractionRecords.filter((record) => record.artifact.contract === DOTNETDOC_CSHARP_SOURCE_EXTRACTION_CONTRACT);
|
|
251
|
+
if (xmlRecords.length === 0 || sourceRecords.length === 0) {
|
|
252
|
+
return null;
|
|
253
|
+
}
|
|
254
|
+
|
|
255
|
+
const sourceMembers = groupMembersByName(sourceRecords);
|
|
256
|
+
const xmlMembers = groupMembersByName(xmlRecords);
|
|
257
|
+
const relations = [];
|
|
258
|
+
const unresolved = [];
|
|
259
|
+
|
|
260
|
+
for (const xmlRecord of xmlRecords) {
|
|
261
|
+
for (const xmlMember of xmlRecord.artifact.members) {
|
|
262
|
+
const matches = sourceMembers.get(xmlMember.memberName) ?? [];
|
|
263
|
+
if (matches.length === 0) {
|
|
264
|
+
unresolved.push(unresolvedMember("missing-csharp-source", "xml-doc", xmlRecord, xmlMember));
|
|
265
|
+
continue;
|
|
266
|
+
}
|
|
267
|
+
for (const [index, match] of matches.entries()) {
|
|
268
|
+
relations.push(createSourceRelation(xmlRecord, xmlMember, match.record, match.member, index));
|
|
269
|
+
}
|
|
270
|
+
}
|
|
271
|
+
}
|
|
272
|
+
|
|
273
|
+
for (const sourceRecord of sourceRecords) {
|
|
274
|
+
for (const sourceMember of sourceRecord.artifact.members) {
|
|
275
|
+
if (!xmlMembers.has(sourceMember.memberName)) {
|
|
276
|
+
unresolved.push(unresolvedMember("missing-xml-documentation", "csharp-source", sourceRecord, sourceMember));
|
|
277
|
+
}
|
|
278
|
+
}
|
|
279
|
+
}
|
|
280
|
+
|
|
281
|
+
return {
|
|
282
|
+
contract: DOTNETDOC_SOURCE_RELATION_CONTRACT,
|
|
283
|
+
contractVersion: DOTNETDOC_SOURCE_RELATION_CONTRACT_VERSION,
|
|
284
|
+
producer: {
|
|
285
|
+
name: "@hia-doc/dotnetdoc-runner",
|
|
286
|
+
version: DOTNETDOC_RUNNER_VERSION
|
|
287
|
+
},
|
|
288
|
+
source: {
|
|
289
|
+
kind: "dotnetdoc-source-relation",
|
|
290
|
+
relation: "xml-doc-to-csharp-source",
|
|
291
|
+
xmlDocArtifacts: xmlRecords.map((record) => sourceArtifactRef(record)),
|
|
292
|
+
csharpSourceArtifacts: sourceRecords.map((record) => sourceArtifactRef(record))
|
|
293
|
+
},
|
|
294
|
+
summary: {
|
|
295
|
+
relationCount: relations.length,
|
|
296
|
+
unresolvedCount: unresolved.length,
|
|
297
|
+
xmlMemberCount: countMembers(xmlRecords),
|
|
298
|
+
csharpSourceMemberCount: countMembers(sourceRecords)
|
|
299
|
+
},
|
|
300
|
+
privacy: {
|
|
301
|
+
sourcesContentPolicy: "none",
|
|
302
|
+
sourcePreviewPolicy: "none",
|
|
303
|
+
embedsSourcesContent: false
|
|
304
|
+
},
|
|
305
|
+
relations,
|
|
306
|
+
unresolved,
|
|
307
|
+
diagnostics: unresolved.length === 0 ? [] : [
|
|
308
|
+
createDiagnostic(
|
|
309
|
+
"DOTNETDOC_SOURCE_RELATION_UNRESOLVED_MEMBERS",
|
|
310
|
+
`DotNetDoc source relation left ${unresolved.length} member(s) unresolved.`,
|
|
311
|
+
"warning",
|
|
312
|
+
null,
|
|
313
|
+
{
|
|
314
|
+
unresolvedCount: unresolved.length
|
|
315
|
+
}
|
|
316
|
+
)
|
|
317
|
+
]
|
|
318
|
+
};
|
|
319
|
+
}
|
|
320
|
+
|
|
321
|
+
function createSourceRelation(xmlRecord, xmlMember, sourceRecord, sourceMember, duplicateIndex) {
|
|
322
|
+
const duplicateSuffix = duplicateIndex === 0 ? "" : `-${duplicateIndex + 1}`;
|
|
323
|
+
return {
|
|
324
|
+
id: `dotnetdoc:source-relation:${safeArtifactId(xmlMember.memberName)}${duplicateSuffix}`,
|
|
325
|
+
relation: "documents-declaration",
|
|
326
|
+
memberName: xmlMember.memberName,
|
|
327
|
+
memberId: xmlMember.id,
|
|
328
|
+
kind: xmlMember.kind,
|
|
329
|
+
name: xmlMember.name,
|
|
330
|
+
confidence: sourceMember.source?.confidence ?? "medium",
|
|
331
|
+
hiaSymbol: {
|
|
332
|
+
id: xmlMember.id,
|
|
333
|
+
artifactPath: xmlRecord.hiaPath,
|
|
334
|
+
documentId: xmlRecord.input.hiaDocumentId ?? null
|
|
335
|
+
},
|
|
336
|
+
documentation: {
|
|
337
|
+
memberId: xmlMember.id,
|
|
338
|
+
artifactPath: xmlRecord.artifactPath,
|
|
339
|
+
path: xmlMember.source?.path ?? xmlRecord.input.path,
|
|
340
|
+
language: "xml",
|
|
341
|
+
range: xmlMember.source?.range ?? null,
|
|
342
|
+
rangeSource: xmlMember.source?.rangeSource ?? "compiler-xml-doc",
|
|
343
|
+
confidence: xmlMember.source?.confidence ?? "high"
|
|
344
|
+
},
|
|
345
|
+
declaration: {
|
|
346
|
+
memberId: sourceMember.id,
|
|
347
|
+
artifactPath: sourceRecord.artifactPath,
|
|
348
|
+
path: sourceMember.source?.path ?? sourceRecord.input.path,
|
|
349
|
+
language: sourceMember.source?.language ?? "csharp",
|
|
350
|
+
range: sourceMember.source?.range ?? null,
|
|
351
|
+
rangeSource: sourceMember.source?.rangeSource ?? "roslyn-syntax",
|
|
352
|
+
confidence: sourceMember.source?.confidence ?? "medium"
|
|
353
|
+
}
|
|
354
|
+
};
|
|
355
|
+
}
|
|
356
|
+
|
|
357
|
+
function groupMembersByName(records) {
|
|
358
|
+
const grouped = new Map();
|
|
359
|
+
for (const record of records) {
|
|
360
|
+
for (const member of record.artifact.members ?? []) {
|
|
361
|
+
const group = grouped.get(member.memberName) ?? [];
|
|
362
|
+
group.push({ record, member });
|
|
363
|
+
grouped.set(member.memberName, group);
|
|
364
|
+
}
|
|
365
|
+
}
|
|
366
|
+
return grouped;
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
function countMembers(records) {
|
|
370
|
+
return records.reduce((count, record) => count + (record.artifact.members?.length ?? 0), 0);
|
|
371
|
+
}
|
|
372
|
+
|
|
373
|
+
function sourceArtifactRef(record) {
|
|
374
|
+
return {
|
|
375
|
+
contract: record.artifact.contract,
|
|
376
|
+
contractVersion: record.artifact.contractVersion,
|
|
377
|
+
artifactPath: record.artifactPath,
|
|
378
|
+
inputPath: record.input.path
|
|
379
|
+
};
|
|
380
|
+
}
|
|
381
|
+
|
|
382
|
+
function unresolvedMember(reason, side, record, member) {
|
|
383
|
+
return {
|
|
384
|
+
memberName: member.memberName,
|
|
385
|
+
memberId: member.id,
|
|
386
|
+
kind: member.kind,
|
|
387
|
+
name: member.name,
|
|
388
|
+
side,
|
|
389
|
+
reason,
|
|
390
|
+
source: {
|
|
391
|
+
path: member.source?.path ?? record.input.path,
|
|
392
|
+
language: member.source?.language ?? (side === "xml-doc" ? "xml" : "csharp"),
|
|
393
|
+
range: member.source?.range ?? null,
|
|
394
|
+
rangeSource: member.source?.rangeSource ?? null,
|
|
395
|
+
confidence: member.source?.confidence ?? null
|
|
396
|
+
}
|
|
198
397
|
};
|
|
199
398
|
}
|
|
200
399
|
|
|
@@ -211,6 +410,14 @@ async function processCSharpSourceInput(input, request) {
|
|
|
211
410
|
});
|
|
212
411
|
}
|
|
213
412
|
|
|
413
|
+
async function processAspNetEndpointInput(input, request) {
|
|
414
|
+
return extractAspNetEndpoints({
|
|
415
|
+
workspaceRoot: request.workspaceRoot,
|
|
416
|
+
applicationRoot: input.applicationRoot,
|
|
417
|
+
paths: [input.path]
|
|
418
|
+
});
|
|
419
|
+
}
|
|
420
|
+
|
|
214
421
|
function artifact(id, kind, artifactPath, profileIds) {
|
|
215
422
|
return {
|
|
216
423
|
id,
|
package/src/schema.mjs
CHANGED
|
@@ -32,8 +32,9 @@ export const DOTNETDOC_CONFIG_JSON_SCHEMA = Object.freeze({
|
|
|
32
32
|
additionalProperties: false,
|
|
33
33
|
required: ["kind", "path"],
|
|
34
34
|
properties: {
|
|
35
|
-
kind: { enum: ["dotnet-xml-doc", "dotnet-csharp-source"] },
|
|
35
|
+
kind: { enum: ["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface"] },
|
|
36
36
|
path: relativePath,
|
|
37
|
+
applicationRoot: relativePath,
|
|
37
38
|
artifactBasePath: relativePath,
|
|
38
39
|
hiaDocumentId: { type: "string", minLength: 1 },
|
|
39
40
|
title: { type: "string", minLength: 1 }
|
|
@@ -44,7 +45,8 @@ export const DOTNETDOC_CONFIG_JSON_SCHEMA = Object.freeze({
|
|
|
44
45
|
type: "object",
|
|
45
46
|
additionalProperties: false,
|
|
46
47
|
properties: {
|
|
47
|
-
writeResultManifest: { type: "boolean" }
|
|
48
|
+
writeResultManifest: { type: "boolean" },
|
|
49
|
+
writeSourceRelationArtifact: { type: "boolean" }
|
|
48
50
|
}
|
|
49
51
|
},
|
|
50
52
|
profileIds: {
|