@hia-doc/dotnetdoc-runner 0.1.7 → 0.1.8

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 (2) hide show
  1. package/package.json +5 -5
  2. package/src/index.mjs +214 -11
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.8",
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.8",
40
+ "@hia-doc/dotnet-xml-doc-extractor": "0.1.8",
41
+ "@hia-doc/dotnetdoc-adapter": "0.1.8",
42
+ "@hia-doc/dotnetdoc-spec": "0.1.8"
43
43
  }
44
44
  }
package/src/index.mjs CHANGED
@@ -21,7 +21,7 @@ export {
21
21
  } from "./schema.mjs";
22
22
  import { DOTNETDOC_CONFIG_SCHEMA_ID, DOTNETDOC_CONFIG_SCHEMA_VERSION } from "./schema.mjs";
23
23
 
24
- export const DOTNETDOC_RUNNER_VERSION = "0.1.7";
24
+ export const DOTNETDOC_RUNNER_VERSION = "0.1.8";
25
25
  export const DOTNETDOC_INPUT_KINDS = Object.freeze(["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface", "dotnet-markup-comments", "dotnet-project"]);
26
26
  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
27
  export const DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT = "dotnetdoc-build-warning-classification";
@@ -305,7 +305,8 @@ async function processInput(input, request) {
305
305
  },
306
306
  artifact(`${safeArtifactId(input.artifactBasePath)}-hia-document`, "hia-document", hiaPath, request.profileIds)
307
307
  ],
308
- diagnostics: [...(dotnetdoc.diagnostics ?? []), ...(hiaDocument.diagnostics ?? [])],
308
+ diagnostics: [...(dotnetdoc.diagnostics ?? []), ...(hiaDocument.diagnostics ?? [])]
309
+ .map(normalizeRunnerDiagnostic),
309
310
  extractionRecord: {
310
311
  input,
311
312
  artifactPath: dotnetdocPath,
@@ -332,26 +333,60 @@ function buildSourceRelationArtifact(extractionRecords, request) {
332
333
  }
333
334
 
334
335
  const sourceMembers = groupMembersByName(sourceRecords);
336
+ const sourceMembersByFallbackIdentity = groupMembersByFallbackIdentity(sourceRecords);
337
+ const sourceMembersBySignatureIdentity = groupMembersBySignatureIdentity(sourceRecords);
335
338
  const xmlMembers = groupMembersByName(xmlRecords);
336
339
  const relations = [];
337
340
  const unresolved = [];
341
+ const matchedSourceMembers = new Set();
342
+ let fallbackRelationCount = 0;
343
+ let signatureFallbackRelationCount = 0;
338
344
 
339
345
  for (const xmlRecord of xmlRecords) {
340
346
  for (const xmlMember of xmlRecord.artifact.members) {
341
- const matches = sourceMembers.get(xmlMember.memberName) ?? [];
347
+ let matches = sourceMembers.get(xmlMember.memberName) ?? [];
348
+ let matchMode = "documentation-id";
349
+ if (matches.length === 0) {
350
+ const fallbackKey = createMemberFallbackIdentity(xmlMember);
351
+ const fallbackCandidates = fallbackKey
352
+ ? sourceMembersByFallbackIdentity.get(fallbackKey) ?? []
353
+ : [];
354
+ const fallbackMatches = fallbackCandidates
355
+ .filter((match) => !matchedSourceMembers.has(createMemberRecordIdentity(match)));
356
+ if (fallbackCandidates.length === 1 && fallbackMatches.length === 1) {
357
+ matches = fallbackMatches;
358
+ matchMode = "unique-member-fallback";
359
+ fallbackRelationCount += 1;
360
+ }
361
+ }
362
+ if (matches.length === 0) {
363
+ const signatureKey = createMemberSignatureIdentity(xmlMember);
364
+ const signatureMatches = signatureKey
365
+ ? (sourceMembersBySignatureIdentity.get(signatureKey) ?? [])
366
+ .filter((match) => !matchedSourceMembers.has(createMemberRecordIdentity(match)))
367
+ : [];
368
+ if (signatureMatches.length === 1) {
369
+ matches = signatureMatches;
370
+ matchMode = "normalized-signature-fallback";
371
+ fallbackRelationCount += 1;
372
+ signatureFallbackRelationCount += 1;
373
+ }
374
+ }
342
375
  if (matches.length === 0) {
343
376
  unresolved.push(unresolvedMember("missing-csharp-source", "xml-doc", xmlRecord, xmlMember));
344
377
  continue;
345
378
  }
346
379
  for (const [index, match] of matches.entries()) {
347
- relations.push(createSourceRelation(xmlRecord, xmlMember, match.record, match.member, index));
380
+ relations.push(createSourceRelation(xmlRecord, xmlMember, match.record, match.member, index, matchMode));
381
+ matchedSourceMembers.add(createMemberRecordIdentity(match));
348
382
  }
349
383
  }
350
384
  }
351
385
 
352
386
  for (const sourceRecord of sourceRecords) {
353
387
  for (const sourceMember of sourceRecord.artifact.members) {
354
- if (!xmlMembers.has(sourceMember.memberName)) {
388
+ const sourceMatch = { record: sourceRecord, member: sourceMember };
389
+ if (!xmlMembers.has(sourceMember.memberName) && !matchedSourceMembers.has(createMemberRecordIdentity(sourceMatch))) {
355
390
  unresolved.push(unresolvedMember("missing-xml-documentation", "csharp-source", sourceRecord, sourceMember));
356
391
  }
357
392
  }
@@ -372,6 +407,8 @@ function buildSourceRelationArtifact(extractionRecords, request) {
372
407
  },
373
408
  summary: {
374
409
  relationCount: relations.length,
410
+ fallbackRelationCount,
411
+ signatureFallbackRelationCount,
375
412
  unresolvedCount: unresolved.length,
376
413
  xmlMemberCount: countMembers(xmlRecords),
377
414
  csharpSourceMemberCount: countMembers(sourceRecords)
@@ -397,8 +434,11 @@ function buildSourceRelationArtifact(extractionRecords, request) {
397
434
  };
398
435
  }
399
436
 
400
- function createSourceRelation(xmlRecord, xmlMember, sourceRecord, sourceMember, duplicateIndex) {
437
+ function createSourceRelation(xmlRecord, xmlMember, sourceRecord, sourceMember, duplicateIndex, matchMode = "documentation-id") {
401
438
  const duplicateSuffix = duplicateIndex === 0 ? "" : `-${duplicateIndex + 1}`;
439
+ const relationConfidence = matchMode === "documentation-id"
440
+ ? sourceMember.source?.confidence ?? "medium"
441
+ : "low";
402
442
  return {
403
443
  id: `dotnetdoc:source-relation:${safeArtifactId(xmlMember.memberName)}${duplicateSuffix}`,
404
444
  relation: "documents-declaration",
@@ -406,7 +446,11 @@ function createSourceRelation(xmlRecord, xmlMember, sourceRecord, sourceMember,
406
446
  memberId: xmlMember.id,
407
447
  kind: xmlMember.kind,
408
448
  name: xmlMember.name,
409
- confidence: sourceMember.source?.confidence ?? "medium",
449
+ confidence: relationConfidence,
450
+ match: {
451
+ mode: matchMode,
452
+ exactDocumentationId: matchMode === "documentation-id"
453
+ },
410
454
  hiaSymbol: {
411
455
  id: xmlMember.id,
412
456
  artifactPath: xmlRecord.hiaPath,
@@ -428,7 +472,7 @@ function createSourceRelation(xmlRecord, xmlMember, sourceRecord, sourceMember,
428
472
  language: sourceMember.source?.language ?? "csharp",
429
473
  range: sourceMember.source?.range ?? null,
430
474
  rangeSource: sourceMember.source?.rangeSource ?? "roslyn-syntax",
431
- confidence: sourceMember.source?.confidence ?? "medium",
475
+ confidence: relationConfidence,
432
476
  semantic: sourceMember.semantic ?? null
433
477
  }
434
478
  };
@@ -446,6 +490,135 @@ function groupMembersByName(records) {
446
490
  return grouped;
447
491
  }
448
492
 
493
+ function groupMembersByFallbackIdentity(records) {
494
+ const grouped = new Map();
495
+ for (const record of records) {
496
+ for (const member of record.artifact.members ?? []) {
497
+ const identity = createMemberFallbackIdentity(member);
498
+ if (!identity) {
499
+ continue;
500
+ }
501
+ const group = grouped.get(identity) ?? [];
502
+ group.push({ record, member });
503
+ grouped.set(identity, group);
504
+ }
505
+ }
506
+ return grouped;
507
+ }
508
+
509
+ function groupMembersBySignatureIdentity(records) {
510
+ const grouped = new Map();
511
+ for (const record of records) {
512
+ for (const member of record.artifact.members ?? []) {
513
+ const identity = createMemberSignatureIdentity(member);
514
+ if (!identity) {
515
+ continue;
516
+ }
517
+ const group = grouped.get(identity) ?? [];
518
+ group.push({ record, member });
519
+ grouped.set(identity, group);
520
+ }
521
+ }
522
+ return grouped;
523
+ }
524
+
525
+ /**
526
+ * Build a conservative relation key that ignores parameter type spelling only.
527
+ *
528
+ * @param {object} member <lang><en>XML or C# extraction member.</en><zh-CN>XML 或 C# 抽取成员。</zh-CN></lang>
529
+ * @returns {string|null} <lang><en>Containing-type/member identity, or null when unavailable.</en><zh-CN>包含类型/成员标识;无法确定时返回 null。</zh-CN></lang>
530
+ * @lang zh-CN 仅在精确 documentation id 失败后用于唯一候选匹配;重载歧义不会自动关联。
531
+ */
532
+ function createMemberFallbackIdentity(member) {
533
+ const body = String(member.memberName ?? "").replace(/^[A-Z]:/u, "").replace(/\(.+$/u, "");
534
+ const separatorIndex = body.lastIndexOf(".");
535
+ if (!body || (member.kind !== "dotnet-type" && separatorIndex <= 0)) {
536
+ return null;
537
+ }
538
+ const containingType = member.kind === "dotnet-type" ? body : body.slice(0, separatorIndex);
539
+ const memberName = member.kind === "dotnet-type" ? body : body.slice(separatorIndex + 1);
540
+ return `${member.kind}|${containingType}|${memberName}`;
541
+ }
542
+
543
+ /**
544
+ * Build a signature key that tolerates unavailable legacy framework namespaces.
545
+ *
546
+ * @param {object} member <lang><en>XML or C# extraction member.</en><zh-CN>XML 或 C# 抽取成员。</zh-CN></lang>
547
+ * @returns {string|null} <lang><en>Normalized overload identity, or null for members without a parameter list.</en><zh-CN>规范化重载标识;没有参数列表时返回 null。</zh-CN></lang>
548
+ * @lang zh-CN 仅移除参数类型和转换返回类型的命名空间,仍保留容器、成员名、参数顺序、泛型结构与返回类型,避免把不同重载误关联。
549
+ */
550
+ function createMemberSignatureIdentity(member) {
551
+ const memberName = String(member.memberName ?? "");
552
+ const openIndex = memberName.indexOf("(");
553
+ if (member.kind !== "dotnet-method" || openIndex < 0) {
554
+ return null;
555
+ }
556
+ const closeIndex = findClosingDelimiter(memberName, openIndex, "(", ")");
557
+ if (closeIndex < 0) {
558
+ return null;
559
+ }
560
+ const callable = memberName.slice(0, openIndex);
561
+ const parameters = splitDocumentationTypes(memberName.slice(openIndex + 1, closeIndex))
562
+ .map(normalizeDocumentationTypeForSignature);
563
+ const returnType = memberName[closeIndex + 1] === "~"
564
+ ? normalizeDocumentationTypeForSignature(memberName.slice(closeIndex + 2))
565
+ : "";
566
+ return `${member.kind}|${callable}|${parameters.join(",")}|${returnType}`;
567
+ }
568
+
569
+ function findClosingDelimiter(value, openIndex, openToken, closeToken) {
570
+ let depth = 0;
571
+ for (let index = openIndex; index < value.length; index += 1) {
572
+ if (value[index] === openToken) {
573
+ depth += 1;
574
+ } else if (value[index] === closeToken) {
575
+ depth -= 1;
576
+ if (depth === 0) {
577
+ return index;
578
+ }
579
+ }
580
+ }
581
+ return -1;
582
+ }
583
+
584
+ function splitDocumentationTypes(value) {
585
+ if (value.length === 0) {
586
+ return [];
587
+ }
588
+ const items = [];
589
+ let start = 0;
590
+ let depth = 0;
591
+ for (let index = 0; index < value.length; index += 1) {
592
+ const token = value[index];
593
+ if (token === "{" || token === "[" || token === "(") {
594
+ depth += 1;
595
+ } else if (token === "}" || token === "]" || token === ")") {
596
+ depth -= 1;
597
+ } else if (token === "," && depth === 0) {
598
+ items.push(value.slice(start, index));
599
+ start = index + 1;
600
+ }
601
+ }
602
+ items.push(value.slice(start));
603
+ return items;
604
+ }
605
+
606
+ function normalizeDocumentationTypeForSignature(value) {
607
+ return value
608
+ .trim()
609
+ .replace(/[A-Za-z_][A-Za-z0-9_.`]*/gu, (token) => token.split(".").at(-1));
610
+ }
611
+
612
+ function createMemberRecordIdentity(match) {
613
+ return [
614
+ match.record.artifactPath,
615
+ match.member.id,
616
+ match.member.memberName,
617
+ match.member.source?.path,
618
+ match.member.source?.range?.start?.line
619
+ ].join("|");
620
+ }
621
+
449
622
  function countMembers(records) {
450
623
  return records.reduce((count, record) => count + (record.artifact.members?.length ?? 0), 0);
451
624
  }
@@ -750,8 +923,8 @@ function normalizeInputPathList(input, index) {
750
923
  paths.push(normalizeSafeRelativePath(input.path, `inputs[${index}].path`));
751
924
  }
752
925
  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.`);
926
+ if (!Array.isArray(input.paths)) {
927
+ throw new TypeError(`inputs[${index}].paths must be an array.`);
755
928
  }
756
929
  paths.push(...input.paths.map((value, pathIndex) => normalizeSafeRelativePath(value, `inputs[${index}].paths[${pathIndex}]`)));
757
930
  }
@@ -903,7 +1076,37 @@ function createDiagnostic(code, message, severity, pathValue, metadata = {}) {
903
1076
  code,
904
1077
  message,
905
1078
  severity,
906
- source: pathValue ? { path: pathValue } : null,
1079
+ ...(pathValue ? { source: { path: pathValue } } : {}),
907
1080
  metadata
908
1081
  };
909
1082
  }
1083
+
1084
+ /**
1085
+ * 规范化领域 extractor 诊断,使 partial producer result 可直接进入统一文档聚合。
1086
+ * Normalizes domain extractor diagnostics so partial producer results can enter unified aggregation directly.
1087
+ *
1088
+ * @param {unknown} value <lang><en>Extractor or adapter diagnostic.</en><zh-CN>Extractor 或 adapter 诊断。</zh-CN></lang>
1089
+ * @returns {object} <lang><en>Producer-contract diagnostic without null source values.</en><zh-CN>不含空 source 的 producer contract 诊断。</zh-CN></lang>
1090
+ * @lang zh-CN 将 Roslyn hidden 诊断降为 info,并省略 null source。
1091
+ */
1092
+ function normalizeRunnerDiagnostic(value) {
1093
+ const diagnostic = value && typeof value === "object" && !Array.isArray(value)
1094
+ ? value
1095
+ : {
1096
+ code: "DOTNETDOC_DIAGNOSTIC",
1097
+ message: String(value ?? ""),
1098
+ severity: "warning"
1099
+ };
1100
+ const severity = diagnostic.severity === "error" || diagnostic.severity === "warning"
1101
+ ? diagnostic.severity
1102
+ : "info";
1103
+ const source = diagnostic.source && typeof diagnostic.source === "object" && !Array.isArray(diagnostic.source)
1104
+ ? diagnostic.source
1105
+ : undefined;
1106
+
1107
+ return {
1108
+ ...diagnostic,
1109
+ severity,
1110
+ ...(source ? { source } : {})
1111
+ };
1112
+ }