@hia-doc/dotnetdoc-runner 0.1.8 → 0.1.10
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 +5 -0
- package/package.json +5 -5
- package/src/index.mjs +77 -7
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.
|
|
3
|
+
"version": "0.1.10",
|
|
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.10",
|
|
40
|
+
"@hia-doc/dotnet-xml-doc-extractor": "0.1.10",
|
|
41
|
+
"@hia-doc/dotnetdoc-adapter": "0.1.10",
|
|
42
|
+
"@hia-doc/dotnetdoc-spec": "0.1.10"
|
|
43
43
|
}
|
|
44
44
|
}
|
package/src/index.mjs
CHANGED
|
@@ -1,3 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file
|
|
3
|
+
* @lang zh-CN 编排显式.NET输入的抽取与HIA/关系输出,仅唯一精确声明补全XML签名,不修改业务输入。
|
|
4
|
+
* @lang en Orchestrates extraction and HIA/relation output for explicit .NET inputs, enriching XML signatures only from unique exact declarations without changing business inputs.
|
|
5
|
+
*/
|
|
1
6
|
import { readFile, mkdir, readdir, writeFile } from "node:fs/promises";
|
|
2
7
|
import path from "node:path";
|
|
3
8
|
|
|
@@ -9,6 +14,8 @@ import {
|
|
|
9
14
|
DOTNETDOC_CSHARP_SOURCE_EXTRACTION_CONTRACT,
|
|
10
15
|
DOTNETDOC_MARKUP_COMMENT_EXTRACTION_CONTRACT,
|
|
11
16
|
DOTNETDOC_PROJECT_DISCOVERY_CONTRACT,
|
|
17
|
+
DOTNETDOC_PROJECT_IDENTITY_POLICY,
|
|
18
|
+
DOTNETDOC_SOURCES_CONTENT_POLICY,
|
|
12
19
|
DOTNETDOC_SOURCE_RELATION_CONTRACT,
|
|
13
20
|
DOTNETDOC_SOURCE_RELATION_CONTRACT_VERSION,
|
|
14
21
|
DOTNETDOC_XML_DOC_EXTRACTION_CONTRACT
|
|
@@ -21,7 +28,11 @@ export {
|
|
|
21
28
|
} from "./schema.mjs";
|
|
22
29
|
import { DOTNETDOC_CONFIG_SCHEMA_ID, DOTNETDOC_CONFIG_SCHEMA_VERSION } from "./schema.mjs";
|
|
23
30
|
|
|
24
|
-
|
|
31
|
+
/**
|
|
32
|
+
* @lang zh-CN DotNetDoc runner/producer 的公开包版本;它与各个 `0.1.0-draft` artifact contract version 分离。
|
|
33
|
+
* @lang en Public package version of the DotNetDoc runner/producer, kept separate from every `0.1.0-draft` artifact contract version.
|
|
34
|
+
*/
|
|
35
|
+
export const DOTNETDOC_RUNNER_VERSION = "0.1.10";
|
|
25
36
|
export const DOTNETDOC_INPUT_KINDS = Object.freeze(["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface", "dotnet-markup-comments", "dotnet-project"]);
|
|
26
37
|
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
38
|
export const DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT = "dotnetdoc-build-warning-classification";
|
|
@@ -87,10 +98,10 @@ export async function runDotnetDoc(request, context = {}) {
|
|
|
87
98
|
}
|
|
88
99
|
}
|
|
89
100
|
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
93
|
-
if (sourceRelation) {
|
|
101
|
+
// <lang><zh-CN>精确声明投影独立于是否输出relation文件;单独消费XML的HIA产物也保留签名。</zh-CN><en>Exact declaration projection is independent of relation-file emission, retaining signatures in XML-derived HIA artifacts consumed alone.</en></lang>
|
|
102
|
+
const sourceRelation = buildSourceRelationArtifact(extractionRecords, normalized);
|
|
103
|
+
await enrichXmlHiaSignatures(extractionRecords, sourceRelation, normalized);
|
|
104
|
+
if (sourceRelation && normalized.options.writeSourceRelationArtifact) {
|
|
94
105
|
const relationPath = "dotnetdoc.source-relation.json";
|
|
95
106
|
await writeJson(path.join(normalized.outputDirectory, relationPath), sourceRelation);
|
|
96
107
|
artifacts.push({
|
|
@@ -127,6 +138,36 @@ export async function runDotnetDoc(request, context = {}) {
|
|
|
127
138
|
return result;
|
|
128
139
|
}
|
|
129
140
|
|
|
141
|
+
/**
|
|
142
|
+
* @lang zh-CN 仅将唯一、文档ID完全一致的Roslyn声明投影进XML派生HIA;不改变XML原始抽取或注释字段。
|
|
143
|
+
* @lang en Projects only unique Roslyn declarations with identical documentation IDs into XML-derived HIA, without altering raw XML extraction or comment fields.
|
|
144
|
+
* @param {object[]} records <lang><zh-CN>当前请求内已抽取记录,不重新发现源码。</zh-CN><en>Extraction records from this request; no source rediscovery.</en></lang>
|
|
145
|
+
* @param {object|null} relation <lang><zh-CN>当前请求的关系事实;缺失/模糊/回退匹配均不升级。</zh-CN><en>Relation facts for this request; absent, ambiguous and fallback matches never upgrade signatures.</en></lang>
|
|
146
|
+
* @param {object} request <lang><zh-CN>已规范化输出根,仍只写既定HIA路径。</zh-CN><en>Normalized output root; writes remain at existing HIA paths.</en></lang>
|
|
147
|
+
* @returns {Promise<void>} <lang><zh-CN>写回获精确签名的HIA文件,保持成员身份和注释内容。</zh-CN><en>Rewrites HIA files with exact signatures, retaining member identity and comment content.</en></lang>
|
|
148
|
+
*/
|
|
149
|
+
async function enrichXmlHiaSignatures(records, relation, request) {
|
|
150
|
+
if (!relation) return;
|
|
151
|
+
for (const record of records) {
|
|
152
|
+
if (record.artifact.contract !== DOTNETDOC_XML_DOC_EXTRACTION_CONTRACT) continue;
|
|
153
|
+
// <lang><zh-CN>同名多声明包括跨工程重复身份;不能按数组先后任意挑一个。</zh-CN><en>Multiple declarations include cross-project duplicate identities; array order must never choose an arbitrary winner.</en></lang>
|
|
154
|
+
let changed = false;
|
|
155
|
+
const members = record.artifact.members.map((member) => {
|
|
156
|
+
const matches = relation.relations.filter((item) => item.hiaSymbol.artifactPath === record.hiaPath && item.hiaSymbol.id === member.id);
|
|
157
|
+
if (matches.length !== 1) return member;
|
|
158
|
+
const exact = matches[0];
|
|
159
|
+
const semantic = exact.declaration?.semantic;
|
|
160
|
+
if (exact.match?.exactDocumentationId !== true || semantic?.documentationCommentId !== member.memberName || typeof semantic.signature !== "string" || !semantic.signature.trim()) return member;
|
|
161
|
+
changed = true;
|
|
162
|
+
return { ...member, semantic: { ...member.semantic, ...semantic } };
|
|
163
|
+
});
|
|
164
|
+
if (!changed) continue;
|
|
165
|
+
// <lang><zh-CN>适配器继续负责显式签名优先级和i18n投影,避免建立第二套转换逻辑。</zh-CN><en>The adapter retains responsibility for explicit-signature precedence and i18n projection, avoiding a second conversion implementation.</en></lang>
|
|
166
|
+
record.hiaDocument = dotnetXmlDocsToHiaDocument({ ...record.artifact, members }, { id: record.input.hiaDocumentId, title: record.input.title });
|
|
167
|
+
await writeJson(path.join(request.outputDirectory, record.hiaPath), record.hiaDocument);
|
|
168
|
+
}
|
|
169
|
+
}
|
|
170
|
+
|
|
130
171
|
/**
|
|
131
172
|
* 将 .NET build / MSBuild 文本诊断分类为 manual、designer 或 generated 边界。
|
|
132
173
|
* Classifies .NET build / MSBuild textual diagnostics into manual, designer or generated boundaries.
|
|
@@ -405,6 +446,14 @@ function buildSourceRelationArtifact(extractionRecords, request) {
|
|
|
405
446
|
xmlDocArtifacts: xmlRecords.map((record) => sourceArtifactRef(record)),
|
|
406
447
|
csharpSourceArtifacts: sourceRecords.map((record) => sourceArtifactRef(record))
|
|
407
448
|
},
|
|
449
|
+
identityPolicy: {
|
|
450
|
+
policy: DOTNETDOC_PROJECT_IDENTITY_POLICY,
|
|
451
|
+
scope: "workspace",
|
|
452
|
+
pathKind: "project-relative",
|
|
453
|
+
absolutePathInIdentity: false,
|
|
454
|
+
displayLabelInIdentity: false,
|
|
455
|
+
localeInIdentity: false
|
|
456
|
+
},
|
|
408
457
|
summary: {
|
|
409
458
|
relationCount: relations.length,
|
|
410
459
|
fallbackRelationCount,
|
|
@@ -414,7 +463,7 @@ function buildSourceRelationArtifact(extractionRecords, request) {
|
|
|
414
463
|
csharpSourceMemberCount: countMembers(sourceRecords)
|
|
415
464
|
},
|
|
416
465
|
privacy: {
|
|
417
|
-
sourcesContentPolicy:
|
|
466
|
+
sourcesContentPolicy: DOTNETDOC_SOURCES_CONTENT_POLICY,
|
|
418
467
|
sourcePreviewPolicy: "none",
|
|
419
468
|
embedsSourcesContent: false
|
|
420
469
|
},
|
|
@@ -446,7 +495,17 @@ function createSourceRelation(xmlRecord, xmlMember, sourceRecord, sourceMember,
|
|
|
446
495
|
memberId: xmlMember.id,
|
|
447
496
|
kind: xmlMember.kind,
|
|
448
497
|
name: xmlMember.name,
|
|
498
|
+
resolution: "resolved",
|
|
449
499
|
confidence: relationConfidence,
|
|
500
|
+
provenance: {
|
|
501
|
+
producer: "@hia-doc/dotnetdoc-runner",
|
|
502
|
+
activity: "xml-doc-to-csharp-source",
|
|
503
|
+
contract: DOTNETDOC_SOURCE_RELATION_CONTRACT,
|
|
504
|
+
contractVersion: DOTNETDOC_SOURCE_RELATION_CONTRACT_VERSION
|
|
505
|
+
},
|
|
506
|
+
...(sourceRecord.artifact.source?.projectContext?.projectIdentity
|
|
507
|
+
? { projectIdentity: sourceRecord.artifact.source.projectContext.projectIdentity }
|
|
508
|
+
: {}),
|
|
450
509
|
match: {
|
|
451
510
|
mode: matchMode,
|
|
452
511
|
exactDocumentationId: matchMode === "documentation-id"
|
|
@@ -628,7 +687,10 @@ function sourceArtifactRef(record) {
|
|
|
628
687
|
contract: record.artifact.contract,
|
|
629
688
|
contractVersion: record.artifact.contractVersion,
|
|
630
689
|
artifactPath: record.artifactPath,
|
|
631
|
-
inputPath: record.input.path
|
|
690
|
+
inputPath: record.input.path,
|
|
691
|
+
...(record.artifact.source?.projectContext?.projectIdentity
|
|
692
|
+
? { projectIdentity: record.artifact.source.projectContext.projectIdentity }
|
|
693
|
+
: {})
|
|
632
694
|
};
|
|
633
695
|
}
|
|
634
696
|
|
|
@@ -640,6 +702,14 @@ function unresolvedMember(reason, side, record, member) {
|
|
|
640
702
|
name: member.name,
|
|
641
703
|
side,
|
|
642
704
|
reason,
|
|
705
|
+
resolution: "unresolved",
|
|
706
|
+
confidence: member.source?.confidence ?? "low",
|
|
707
|
+
provenance: {
|
|
708
|
+
producer: "@hia-doc/dotnetdoc-runner",
|
|
709
|
+
activity: "xml-doc-to-csharp-source",
|
|
710
|
+
contract: DOTNETDOC_SOURCE_RELATION_CONTRACT,
|
|
711
|
+
contractVersion: DOTNETDOC_SOURCE_RELATION_CONTRACT_VERSION
|
|
712
|
+
},
|
|
643
713
|
source: {
|
|
644
714
|
path: member.source?.path ?? record.input.path,
|
|
645
715
|
language: member.source?.language ?? (side === "xml-doc" ? "xml" : "csharp"),
|