@hia-doc/dotnetdoc-runner 0.1.6 → 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.
- package/package.json +5 -5
- 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.
|
|
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.
|
|
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.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.
|
|
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
|
-
|
|
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
|
-
|
|
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:
|
|
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:
|
|
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)
|
|
754
|
-
throw new TypeError(`inputs[${index}].paths must be
|
|
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
|
-
|
|
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
|
+
}
|