@hia-doc/dotnetdoc-runner 0.1.7 → 0.1.9

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.
Files changed (3) hide show
  1. package/README.md +5 -0
  2. package/package.json +5 -5
  3. package/src/index.mjs +251 -13
package/README.md CHANGED
@@ -45,6 +45,11 @@ Roslyn source extractor.
45
45
  对 `dotnet-csharp-source`,配置也可以提供 `projectPath`,由 runner 先从
46
46
  `.csproj` 推导源码文件集合,再调用轻量 Roslyn source extractor。
47
47
 
48
+ 当同一请求同时包含 XML documentation 与带 `projectPath` 的 C# source 时,
49
+ `dotnetdoc-source-relation` 会携带同一 project-relative identity,并把
50
+ resolution、confidence、provenance 分开输出。relation 仍是 metadata-only:
51
+ `sourcesContentPolicy: none`,不嵌入源码正文,也不授予 source reader 能力。
52
+
48
53
  ```json
49
54
  {
50
55
  "kind": "dotnet-csharp-source",
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hia-doc/dotnetdoc-runner",
3
- "version": "0.1.7",
3
+ "version": "0.1.9",
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.7",
40
- "@hia-doc/dotnet-xml-doc-extractor": "0.1.7",
41
- "@hia-doc/dotnetdoc-adapter": "0.1.7",
42
- "@hia-doc/dotnetdoc-spec": "0.1.7"
39
+ "@hia-doc/dotnet-source-extractor": "0.1.9",
40
+ "@hia-doc/dotnet-xml-doc-extractor": "0.1.9",
41
+ "@hia-doc/dotnetdoc-adapter": "0.1.9",
42
+ "@hia-doc/dotnetdoc-spec": "0.1.9"
43
43
  }
44
44
  }
package/src/index.mjs CHANGED
@@ -9,6 +9,8 @@ import {
9
9
  DOTNETDOC_CSHARP_SOURCE_EXTRACTION_CONTRACT,
10
10
  DOTNETDOC_MARKUP_COMMENT_EXTRACTION_CONTRACT,
11
11
  DOTNETDOC_PROJECT_DISCOVERY_CONTRACT,
12
+ DOTNETDOC_PROJECT_IDENTITY_POLICY,
13
+ DOTNETDOC_SOURCES_CONTENT_POLICY,
12
14
  DOTNETDOC_SOURCE_RELATION_CONTRACT,
13
15
  DOTNETDOC_SOURCE_RELATION_CONTRACT_VERSION,
14
16
  DOTNETDOC_XML_DOC_EXTRACTION_CONTRACT
@@ -21,7 +23,11 @@ export {
21
23
  } from "./schema.mjs";
22
24
  import { DOTNETDOC_CONFIG_SCHEMA_ID, DOTNETDOC_CONFIG_SCHEMA_VERSION } from "./schema.mjs";
23
25
 
24
- export const DOTNETDOC_RUNNER_VERSION = "0.1.7";
26
+ /**
27
+ * @lang zh-CN DotNetDoc runner/producer 的公开包版本;它与各个 `0.1.0-draft` artifact contract version 分离。
28
+ * @lang en Public package version of the DotNetDoc runner/producer, kept separate from every `0.1.0-draft` artifact contract version.
29
+ */
30
+ export const DOTNETDOC_RUNNER_VERSION = "0.1.9";
25
31
  export const DOTNETDOC_INPUT_KINDS = Object.freeze(["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface", "dotnet-markup-comments", "dotnet-project"]);
26
32
  export const DOTNETDOC_OUTPUT_KINDS = Object.freeze(["dotnetdoc-extraction", "hia-document", "dotnetdoc-source-relation", "dotnetdoc-aspnet-endpoint-extraction", "dotnetdoc-markup-comment-extraction", "dotnetdoc-project-discovery"]);
27
33
  export const DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT = "dotnetdoc-build-warning-classification";
@@ -305,7 +311,8 @@ async function processInput(input, request) {
305
311
  },
306
312
  artifact(`${safeArtifactId(input.artifactBasePath)}-hia-document`, "hia-document", hiaPath, request.profileIds)
307
313
  ],
308
- diagnostics: [...(dotnetdoc.diagnostics ?? []), ...(hiaDocument.diagnostics ?? [])],
314
+ diagnostics: [...(dotnetdoc.diagnostics ?? []), ...(hiaDocument.diagnostics ?? [])]
315
+ .map(normalizeRunnerDiagnostic),
309
316
  extractionRecord: {
310
317
  input,
311
318
  artifactPath: dotnetdocPath,
@@ -332,26 +339,60 @@ function buildSourceRelationArtifact(extractionRecords, request) {
332
339
  }
333
340
 
334
341
  const sourceMembers = groupMembersByName(sourceRecords);
342
+ const sourceMembersByFallbackIdentity = groupMembersByFallbackIdentity(sourceRecords);
343
+ const sourceMembersBySignatureIdentity = groupMembersBySignatureIdentity(sourceRecords);
335
344
  const xmlMembers = groupMembersByName(xmlRecords);
336
345
  const relations = [];
337
346
  const unresolved = [];
347
+ const matchedSourceMembers = new Set();
348
+ let fallbackRelationCount = 0;
349
+ let signatureFallbackRelationCount = 0;
338
350
 
339
351
  for (const xmlRecord of xmlRecords) {
340
352
  for (const xmlMember of xmlRecord.artifact.members) {
341
- const matches = sourceMembers.get(xmlMember.memberName) ?? [];
353
+ let matches = sourceMembers.get(xmlMember.memberName) ?? [];
354
+ let matchMode = "documentation-id";
355
+ if (matches.length === 0) {
356
+ const fallbackKey = createMemberFallbackIdentity(xmlMember);
357
+ const fallbackCandidates = fallbackKey
358
+ ? sourceMembersByFallbackIdentity.get(fallbackKey) ?? []
359
+ : [];
360
+ const fallbackMatches = fallbackCandidates
361
+ .filter((match) => !matchedSourceMembers.has(createMemberRecordIdentity(match)));
362
+ if (fallbackCandidates.length === 1 && fallbackMatches.length === 1) {
363
+ matches = fallbackMatches;
364
+ matchMode = "unique-member-fallback";
365
+ fallbackRelationCount += 1;
366
+ }
367
+ }
368
+ if (matches.length === 0) {
369
+ const signatureKey = createMemberSignatureIdentity(xmlMember);
370
+ const signatureMatches = signatureKey
371
+ ? (sourceMembersBySignatureIdentity.get(signatureKey) ?? [])
372
+ .filter((match) => !matchedSourceMembers.has(createMemberRecordIdentity(match)))
373
+ : [];
374
+ if (signatureMatches.length === 1) {
375
+ matches = signatureMatches;
376
+ matchMode = "normalized-signature-fallback";
377
+ fallbackRelationCount += 1;
378
+ signatureFallbackRelationCount += 1;
379
+ }
380
+ }
342
381
  if (matches.length === 0) {
343
382
  unresolved.push(unresolvedMember("missing-csharp-source", "xml-doc", xmlRecord, xmlMember));
344
383
  continue;
345
384
  }
346
385
  for (const [index, match] of matches.entries()) {
347
- relations.push(createSourceRelation(xmlRecord, xmlMember, match.record, match.member, index));
386
+ relations.push(createSourceRelation(xmlRecord, xmlMember, match.record, match.member, index, matchMode));
387
+ matchedSourceMembers.add(createMemberRecordIdentity(match));
348
388
  }
349
389
  }
350
390
  }
351
391
 
352
392
  for (const sourceRecord of sourceRecords) {
353
393
  for (const sourceMember of sourceRecord.artifact.members) {
354
- if (!xmlMembers.has(sourceMember.memberName)) {
394
+ const sourceMatch = { record: sourceRecord, member: sourceMember };
395
+ if (!xmlMembers.has(sourceMember.memberName) && !matchedSourceMembers.has(createMemberRecordIdentity(sourceMatch))) {
355
396
  unresolved.push(unresolvedMember("missing-xml-documentation", "csharp-source", sourceRecord, sourceMember));
356
397
  }
357
398
  }
@@ -370,14 +411,24 @@ function buildSourceRelationArtifact(extractionRecords, request) {
370
411
  xmlDocArtifacts: xmlRecords.map((record) => sourceArtifactRef(record)),
371
412
  csharpSourceArtifacts: sourceRecords.map((record) => sourceArtifactRef(record))
372
413
  },
414
+ identityPolicy: {
415
+ policy: DOTNETDOC_PROJECT_IDENTITY_POLICY,
416
+ scope: "workspace",
417
+ pathKind: "project-relative",
418
+ absolutePathInIdentity: false,
419
+ displayLabelInIdentity: false,
420
+ localeInIdentity: false
421
+ },
373
422
  summary: {
374
423
  relationCount: relations.length,
424
+ fallbackRelationCount,
425
+ signatureFallbackRelationCount,
375
426
  unresolvedCount: unresolved.length,
376
427
  xmlMemberCount: countMembers(xmlRecords),
377
428
  csharpSourceMemberCount: countMembers(sourceRecords)
378
429
  },
379
430
  privacy: {
380
- sourcesContentPolicy: "none",
431
+ sourcesContentPolicy: DOTNETDOC_SOURCES_CONTENT_POLICY,
381
432
  sourcePreviewPolicy: "none",
382
433
  embedsSourcesContent: false
383
434
  },
@@ -397,8 +448,11 @@ function buildSourceRelationArtifact(extractionRecords, request) {
397
448
  };
398
449
  }
399
450
 
400
- function createSourceRelation(xmlRecord, xmlMember, sourceRecord, sourceMember, duplicateIndex) {
451
+ function createSourceRelation(xmlRecord, xmlMember, sourceRecord, sourceMember, duplicateIndex, matchMode = "documentation-id") {
401
452
  const duplicateSuffix = duplicateIndex === 0 ? "" : `-${duplicateIndex + 1}`;
453
+ const relationConfidence = matchMode === "documentation-id"
454
+ ? sourceMember.source?.confidence ?? "medium"
455
+ : "low";
402
456
  return {
403
457
  id: `dotnetdoc:source-relation:${safeArtifactId(xmlMember.memberName)}${duplicateSuffix}`,
404
458
  relation: "documents-declaration",
@@ -406,7 +460,21 @@ function createSourceRelation(xmlRecord, xmlMember, sourceRecord, sourceMember,
406
460
  memberId: xmlMember.id,
407
461
  kind: xmlMember.kind,
408
462
  name: xmlMember.name,
409
- confidence: sourceMember.source?.confidence ?? "medium",
463
+ resolution: "resolved",
464
+ confidence: relationConfidence,
465
+ provenance: {
466
+ producer: "@hia-doc/dotnetdoc-runner",
467
+ activity: "xml-doc-to-csharp-source",
468
+ contract: DOTNETDOC_SOURCE_RELATION_CONTRACT,
469
+ contractVersion: DOTNETDOC_SOURCE_RELATION_CONTRACT_VERSION
470
+ },
471
+ ...(sourceRecord.artifact.source?.projectContext?.projectIdentity
472
+ ? { projectIdentity: sourceRecord.artifact.source.projectContext.projectIdentity }
473
+ : {}),
474
+ match: {
475
+ mode: matchMode,
476
+ exactDocumentationId: matchMode === "documentation-id"
477
+ },
410
478
  hiaSymbol: {
411
479
  id: xmlMember.id,
412
480
  artifactPath: xmlRecord.hiaPath,
@@ -428,7 +496,7 @@ function createSourceRelation(xmlRecord, xmlMember, sourceRecord, sourceMember,
428
496
  language: sourceMember.source?.language ?? "csharp",
429
497
  range: sourceMember.source?.range ?? null,
430
498
  rangeSource: sourceMember.source?.rangeSource ?? "roslyn-syntax",
431
- confidence: sourceMember.source?.confidence ?? "medium",
499
+ confidence: relationConfidence,
432
500
  semantic: sourceMember.semantic ?? null
433
501
  }
434
502
  };
@@ -446,6 +514,135 @@ function groupMembersByName(records) {
446
514
  return grouped;
447
515
  }
448
516
 
517
+ function groupMembersByFallbackIdentity(records) {
518
+ const grouped = new Map();
519
+ for (const record of records) {
520
+ for (const member of record.artifact.members ?? []) {
521
+ const identity = createMemberFallbackIdentity(member);
522
+ if (!identity) {
523
+ continue;
524
+ }
525
+ const group = grouped.get(identity) ?? [];
526
+ group.push({ record, member });
527
+ grouped.set(identity, group);
528
+ }
529
+ }
530
+ return grouped;
531
+ }
532
+
533
+ function groupMembersBySignatureIdentity(records) {
534
+ const grouped = new Map();
535
+ for (const record of records) {
536
+ for (const member of record.artifact.members ?? []) {
537
+ const identity = createMemberSignatureIdentity(member);
538
+ if (!identity) {
539
+ continue;
540
+ }
541
+ const group = grouped.get(identity) ?? [];
542
+ group.push({ record, member });
543
+ grouped.set(identity, group);
544
+ }
545
+ }
546
+ return grouped;
547
+ }
548
+
549
+ /**
550
+ * Build a conservative relation key that ignores parameter type spelling only.
551
+ *
552
+ * @param {object} member <lang><en>XML or C# extraction member.</en><zh-CN>XML 或 C# 抽取成员。</zh-CN></lang>
553
+ * @returns {string|null} <lang><en>Containing-type/member identity, or null when unavailable.</en><zh-CN>包含类型/成员标识;无法确定时返回 null。</zh-CN></lang>
554
+ * @lang zh-CN 仅在精确 documentation id 失败后用于唯一候选匹配;重载歧义不会自动关联。
555
+ */
556
+ function createMemberFallbackIdentity(member) {
557
+ const body = String(member.memberName ?? "").replace(/^[A-Z]:/u, "").replace(/\(.+$/u, "");
558
+ const separatorIndex = body.lastIndexOf(".");
559
+ if (!body || (member.kind !== "dotnet-type" && separatorIndex <= 0)) {
560
+ return null;
561
+ }
562
+ const containingType = member.kind === "dotnet-type" ? body : body.slice(0, separatorIndex);
563
+ const memberName = member.kind === "dotnet-type" ? body : body.slice(separatorIndex + 1);
564
+ return `${member.kind}|${containingType}|${memberName}`;
565
+ }
566
+
567
+ /**
568
+ * Build a signature key that tolerates unavailable legacy framework namespaces.
569
+ *
570
+ * @param {object} member <lang><en>XML or C# extraction member.</en><zh-CN>XML 或 C# 抽取成员。</zh-CN></lang>
571
+ * @returns {string|null} <lang><en>Normalized overload identity, or null for members without a parameter list.</en><zh-CN>规范化重载标识;没有参数列表时返回 null。</zh-CN></lang>
572
+ * @lang zh-CN 仅移除参数类型和转换返回类型的命名空间,仍保留容器、成员名、参数顺序、泛型结构与返回类型,避免把不同重载误关联。
573
+ */
574
+ function createMemberSignatureIdentity(member) {
575
+ const memberName = String(member.memberName ?? "");
576
+ const openIndex = memberName.indexOf("(");
577
+ if (member.kind !== "dotnet-method" || openIndex < 0) {
578
+ return null;
579
+ }
580
+ const closeIndex = findClosingDelimiter(memberName, openIndex, "(", ")");
581
+ if (closeIndex < 0) {
582
+ return null;
583
+ }
584
+ const callable = memberName.slice(0, openIndex);
585
+ const parameters = splitDocumentationTypes(memberName.slice(openIndex + 1, closeIndex))
586
+ .map(normalizeDocumentationTypeForSignature);
587
+ const returnType = memberName[closeIndex + 1] === "~"
588
+ ? normalizeDocumentationTypeForSignature(memberName.slice(closeIndex + 2))
589
+ : "";
590
+ return `${member.kind}|${callable}|${parameters.join(",")}|${returnType}`;
591
+ }
592
+
593
+ function findClosingDelimiter(value, openIndex, openToken, closeToken) {
594
+ let depth = 0;
595
+ for (let index = openIndex; index < value.length; index += 1) {
596
+ if (value[index] === openToken) {
597
+ depth += 1;
598
+ } else if (value[index] === closeToken) {
599
+ depth -= 1;
600
+ if (depth === 0) {
601
+ return index;
602
+ }
603
+ }
604
+ }
605
+ return -1;
606
+ }
607
+
608
+ function splitDocumentationTypes(value) {
609
+ if (value.length === 0) {
610
+ return [];
611
+ }
612
+ const items = [];
613
+ let start = 0;
614
+ let depth = 0;
615
+ for (let index = 0; index < value.length; index += 1) {
616
+ const token = value[index];
617
+ if (token === "{" || token === "[" || token === "(") {
618
+ depth += 1;
619
+ } else if (token === "}" || token === "]" || token === ")") {
620
+ depth -= 1;
621
+ } else if (token === "," && depth === 0) {
622
+ items.push(value.slice(start, index));
623
+ start = index + 1;
624
+ }
625
+ }
626
+ items.push(value.slice(start));
627
+ return items;
628
+ }
629
+
630
+ function normalizeDocumentationTypeForSignature(value) {
631
+ return value
632
+ .trim()
633
+ .replace(/[A-Za-z_][A-Za-z0-9_.`]*/gu, (token) => token.split(".").at(-1));
634
+ }
635
+
636
+ function createMemberRecordIdentity(match) {
637
+ return [
638
+ match.record.artifactPath,
639
+ match.member.id,
640
+ match.member.memberName,
641
+ match.member.source?.path,
642
+ match.member.source?.range?.start?.line
643
+ ].join("|");
644
+ }
645
+
449
646
  function countMembers(records) {
450
647
  return records.reduce((count, record) => count + (record.artifact.members?.length ?? 0), 0);
451
648
  }
@@ -455,7 +652,10 @@ function sourceArtifactRef(record) {
455
652
  contract: record.artifact.contract,
456
653
  contractVersion: record.artifact.contractVersion,
457
654
  artifactPath: record.artifactPath,
458
- inputPath: record.input.path
655
+ inputPath: record.input.path,
656
+ ...(record.artifact.source?.projectContext?.projectIdentity
657
+ ? { projectIdentity: record.artifact.source.projectContext.projectIdentity }
658
+ : {})
459
659
  };
460
660
  }
461
661
 
@@ -467,6 +667,14 @@ function unresolvedMember(reason, side, record, member) {
467
667
  name: member.name,
468
668
  side,
469
669
  reason,
670
+ resolution: "unresolved",
671
+ confidence: member.source?.confidence ?? "low",
672
+ provenance: {
673
+ producer: "@hia-doc/dotnetdoc-runner",
674
+ activity: "xml-doc-to-csharp-source",
675
+ contract: DOTNETDOC_SOURCE_RELATION_CONTRACT,
676
+ contractVersion: DOTNETDOC_SOURCE_RELATION_CONTRACT_VERSION
677
+ },
470
678
  source: {
471
679
  path: member.source?.path ?? record.input.path,
472
680
  language: member.source?.language ?? (side === "xml-doc" ? "xml" : "csharp"),
@@ -750,8 +958,8 @@ function normalizeInputPathList(input, index) {
750
958
  paths.push(normalizeSafeRelativePath(input.path, `inputs[${index}].path`));
751
959
  }
752
960
  if (input.paths !== undefined) {
753
- if (!Array.isArray(input.paths) || input.paths.length === 0) {
754
- throw new TypeError(`inputs[${index}].paths must be a non-empty array.`);
961
+ if (!Array.isArray(input.paths)) {
962
+ throw new TypeError(`inputs[${index}].paths must be an array.`);
755
963
  }
756
964
  paths.push(...input.paths.map((value, pathIndex) => normalizeSafeRelativePath(value, `inputs[${index}].paths[${pathIndex}]`)));
757
965
  }
@@ -903,7 +1111,37 @@ function createDiagnostic(code, message, severity, pathValue, metadata = {}) {
903
1111
  code,
904
1112
  message,
905
1113
  severity,
906
- source: pathValue ? { path: pathValue } : null,
1114
+ ...(pathValue ? { source: { path: pathValue } } : {}),
907
1115
  metadata
908
1116
  };
909
1117
  }
1118
+
1119
+ /**
1120
+ * 规范化领域 extractor 诊断,使 partial producer result 可直接进入统一文档聚合。
1121
+ * Normalizes domain extractor diagnostics so partial producer results can enter unified aggregation directly.
1122
+ *
1123
+ * @param {unknown} value <lang><en>Extractor or adapter diagnostic.</en><zh-CN>Extractor 或 adapter 诊断。</zh-CN></lang>
1124
+ * @returns {object} <lang><en>Producer-contract diagnostic without null source values.</en><zh-CN>不含空 source 的 producer contract 诊断。</zh-CN></lang>
1125
+ * @lang zh-CN 将 Roslyn hidden 诊断降为 info,并省略 null source。
1126
+ */
1127
+ function normalizeRunnerDiagnostic(value) {
1128
+ const diagnostic = value && typeof value === "object" && !Array.isArray(value)
1129
+ ? value
1130
+ : {
1131
+ code: "DOTNETDOC_DIAGNOSTIC",
1132
+ message: String(value ?? ""),
1133
+ severity: "warning"
1134
+ };
1135
+ const severity = diagnostic.severity === "error" || diagnostic.severity === "warning"
1136
+ ? diagnostic.severity
1137
+ : "info";
1138
+ const source = diagnostic.source && typeof diagnostic.source === "object" && !Array.isArray(diagnostic.source)
1139
+ ? diagnostic.source
1140
+ : undefined;
1141
+
1142
+ return {
1143
+ ...diagnostic,
1144
+ severity,
1145
+ ...(source ? { source } : {})
1146
+ };
1147
+ }