@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 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 and a
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.0",
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.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"
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.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"]);
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
- : await processCSharpSourceInput(input, request);
178
- const hiaDocument = dotnetXmlDocsToHiaDocument(dotnetdoc, {
179
- id: input.hiaDocumentId,
180
- title: input.title
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: {