@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 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.8",
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.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"
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
- export const DOTNETDOC_RUNNER_VERSION = "0.1.8";
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
- const sourceRelation = normalized.options.writeSourceRelationArtifact
91
- ? buildSourceRelationArtifact(extractionRecords, normalized)
92
- : null;
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: "none",
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"),