@hia-doc/dotnetdoc-runner 0.1.0 → 0.1.2

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