@hia-doc/dotnetdoc-runner 0.1.9 → 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.
Files changed (2) hide show
  1. package/package.json +5 -5
  2. package/src/index.mjs +40 -5
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@hia-doc/dotnetdoc-runner",
3
- "version": "0.1.9",
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.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"
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
 
@@ -27,7 +32,7 @@ import { DOTNETDOC_CONFIG_SCHEMA_ID, DOTNETDOC_CONFIG_SCHEMA_VERSION } from "./s
27
32
  * @lang zh-CN DotNetDoc runner/producer 的公开包版本;它与各个 `0.1.0-draft` artifact contract version 分离。
28
33
  * @lang en Public package version of the DotNetDoc runner/producer, kept separate from every `0.1.0-draft` artifact contract version.
29
34
  */
30
- export const DOTNETDOC_RUNNER_VERSION = "0.1.9";
35
+ export const DOTNETDOC_RUNNER_VERSION = "0.1.10";
31
36
  export const DOTNETDOC_INPUT_KINDS = Object.freeze(["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface", "dotnet-markup-comments", "dotnet-project"]);
32
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"]);
33
38
  export const DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT = "dotnetdoc-build-warning-classification";
@@ -93,10 +98,10 @@ export async function runDotnetDoc(request, context = {}) {
93
98
  }
94
99
  }
95
100
 
96
- const sourceRelation = normalized.options.writeSourceRelationArtifact
97
- ? buildSourceRelationArtifact(extractionRecords, normalized)
98
- : null;
99
- 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) {
100
105
  const relationPath = "dotnetdoc.source-relation.json";
101
106
  await writeJson(path.join(normalized.outputDirectory, relationPath), sourceRelation);
102
107
  artifacts.push({
@@ -133,6 +138,36 @@ export async function runDotnetDoc(request, context = {}) {
133
138
  return result;
134
139
  }
135
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
+
136
171
  /**
137
172
  * 将 .NET build / MSBuild 文本诊断分类为 manual、designer 或 generated 边界。
138
173
  * Classifies .NET build / MSBuild textual diagnostics into manual, designer or generated boundaries.