@hia-doc/dotnetdoc-runner 0.1.9 → 0.1.11
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 +19 -0
- package/package.json +5 -5
- package/src/index.mjs +13 -5
- package/src/source-locations.mjs +131 -0
package/README.md
CHANGED
|
@@ -68,3 +68,22 @@ resolution、confidence、provenance 分开输出。relation 仍是 metadata-onl
|
|
|
68
68
|
"title": "Web Markup Comments"
|
|
69
69
|
}
|
|
70
70
|
```
|
|
71
|
+
|
|
72
|
+
## Code source locations
|
|
73
|
+
|
|
74
|
+
Compiler XML paths are documentation origins. They stay in extraction `member.source`
|
|
75
|
+
and HIA `metadata.dotnetdoc.documentationSource`; they are not exposed as code definitions.
|
|
76
|
+
For real C# locations, use a configured `dotnet-project` solution/project input or set
|
|
77
|
+
`projectPath` on an XML input. The runner reuses its Roslyn extractor and requires a
|
|
78
|
+
unique assembly and complete documentation-comment ID match. It does not add duplicate
|
|
79
|
+
C# documentation pages and works with `writeSourceRelationArtifact: false`.
|
|
80
|
+
|
|
81
|
+
Unresolved or ambiguous members have no code locator. Partial declarations, missing
|
|
82
|
+
references, unavailable .NET tooling and sources outside the workspace are never repaired
|
|
83
|
+
by choosing an arbitrary filename. Extraction reads configured source only; it does not
|
|
84
|
+
execute the target build, download source, parse Windows/Portable PDBs or grant publication
|
|
85
|
+
permission. Existing source preview settings still require explicit publication consent.
|
|
86
|
+
|
|
87
|
+
中文:XML是文档出处;代码定位来自已配置项目中的唯一真实Roslyn声明。缺失/歧义保持未定位,
|
|
88
|
+
不会回退XML或按名称猜文件。需要现有.NET 8 SDK/helper;本轮不实现PDB读取,尤其不能把传统
|
|
89
|
+
Windows PDB当作Portable PDB。范围与语言随真实声明输出,所有XML注释/本地化字段保持。
|
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.11",
|
|
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.11",
|
|
40
|
+
"@hia-doc/dotnet-xml-doc-extractor": "0.1.11",
|
|
41
|
+
"@hia-doc/dotnetdoc-adapter": "0.1.11",
|
|
42
|
+
"@hia-doc/dotnetdoc-spec": "0.1.11"
|
|
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
|
|
|
@@ -22,12 +27,13 @@ export {
|
|
|
22
27
|
DOTNETDOC_CONFIG_SCHEMA_VERSION
|
|
23
28
|
} from "./schema.mjs";
|
|
24
29
|
import { DOTNETDOC_CONFIG_SCHEMA_ID, DOTNETDOC_CONFIG_SCHEMA_VERSION } from "./schema.mjs";
|
|
30
|
+
import { enrichXmlSourceLocations } from "./source-locations.mjs";
|
|
25
31
|
|
|
26
32
|
/**
|
|
27
33
|
* @lang zh-CN DotNetDoc runner/producer 的公开包版本;它与各个 `0.1.0-draft` artifact contract version 分离。
|
|
28
34
|
* @lang en Public package version of the DotNetDoc runner/producer, kept separate from every `0.1.0-draft` artifact contract version.
|
|
29
35
|
*/
|
|
30
|
-
export const DOTNETDOC_RUNNER_VERSION = "0.1.
|
|
36
|
+
export const DOTNETDOC_RUNNER_VERSION = "0.1.11";
|
|
31
37
|
export const DOTNETDOC_INPUT_KINDS = Object.freeze(["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface", "dotnet-markup-comments", "dotnet-project"]);
|
|
32
38
|
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
39
|
export const DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT = "dotnetdoc-build-warning-classification";
|
|
@@ -93,10 +99,10 @@ export async function runDotnetDoc(request, context = {}) {
|
|
|
93
99
|
}
|
|
94
100
|
}
|
|
95
101
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
|
|
99
|
-
if (sourceRelation) {
|
|
102
|
+
// <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>
|
|
103
|
+
const sourceRelation = buildSourceRelationArtifact(extractionRecords, normalized);
|
|
104
|
+
diagnostics.push(...await enrichXmlSourceLocations(extractionRecords, normalized));
|
|
105
|
+
if (sourceRelation && normalized.options.writeSourceRelationArtifact) {
|
|
100
106
|
const relationPath = "dotnetdoc.source-relation.json";
|
|
101
107
|
await writeJson(path.join(normalized.outputDirectory, relationPath), sourceRelation);
|
|
102
108
|
artifacts.push({
|
|
@@ -133,6 +139,8 @@ export async function runDotnetDoc(request, context = {}) {
|
|
|
133
139
|
return result;
|
|
134
140
|
}
|
|
135
141
|
|
|
142
|
+
|
|
143
|
+
|
|
136
144
|
/**
|
|
137
145
|
* 将 .NET build / MSBuild 文本诊断分类为 manual、designer 或 generated 边界。
|
|
138
146
|
* Classifies .NET build / MSBuild textual diagnostics into manual, designer or generated boundaries.
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file
|
|
3
|
+
* @lang zh-CN 将配置项目中的唯一Roslyn声明投影为XML文档成员的代码定位;不猜路径、不执行业务构建。
|
|
4
|
+
* @lang en Projects unique Roslyn declarations from configured projects into XML member code locators without path guessing or target builds.
|
|
5
|
+
*/
|
|
6
|
+
import { realpath, writeFile } from 'node:fs/promises';
|
|
7
|
+
import path from 'node:path';
|
|
8
|
+
import { extractDotnetProjectDiscovery, extractDotnetSourceFiles } from '@hia-doc/dotnet-source-extractor';
|
|
9
|
+
import { dotnetXmlDocsToHiaDocument } from '@hia-doc/dotnetdoc-adapter';
|
|
10
|
+
import { DOTNETDOC_XML_DOC_EXTRACTION_CONTRACT, DOTNETDOC_CSHARP_SOURCE_EXTRACTION_CONTRACT, DOTNETDOC_PROJECT_DISCOVERY_CONTRACT } from '@hia-doc/dotnetdoc-spec';
|
|
11
|
+
|
|
12
|
+
/**
|
|
13
|
+
* @lang zh-CN 按完整成员ID选择唯一声明;已知程序集不能跨界,重复注册和partial多位置保持歧义。
|
|
14
|
+
* @lang en Selects a declaration by its complete member ID, respecting known assemblies and retaining ambiguity for duplicate registrations or partial locations.
|
|
15
|
+
* @param {object} member <lang><zh-CN>XML成员身份。</zh-CN><en>XML member identity.</en></lang>
|
|
16
|
+
* @param {object[]} candidates <lang><zh-CN>声明及其程序集身份。</zh-CN><en>Declarations with assembly identities.</en></lang>
|
|
17
|
+
* @param {string|null} assembly <lang><zh-CN>XML声明的程序集。</zh-CN><en>Assembly declared by the XML input.</en></lang>
|
|
18
|
+
* @returns {{declaration?:object,status:string}} <lang><zh-CN>唯一声明或missing/ambiguous;不按简称或参数数量回退。</zh-CN><en>Unique declaration or missing/ambiguous, without short-name or arity fallback.</en></lang>
|
|
19
|
+
*/
|
|
20
|
+
export function selectExactDeclaration(member, candidates, assembly) {
|
|
21
|
+
// <lang><zh-CN>沿用既有唯一声明门禁;相同位置重复注册也不自动推断为同一输入事实。</zh-CN><en>Retain the existing unique-declaration gate; duplicate registrations at the same location are not automatically treated as one input fact.</en></lang>
|
|
22
|
+
const unique = [];
|
|
23
|
+
for (const candidate of candidates) {
|
|
24
|
+
if (candidate.member.semantic?.documentationCommentId !== member.memberName) continue;
|
|
25
|
+
if (assembly && candidate.assembly && candidate.assembly !== 'DotNetDoc.SourceExtraction' && candidate.assembly !== assembly) continue;
|
|
26
|
+
unique.push(candidate.member);
|
|
27
|
+
}
|
|
28
|
+
return unique.length === 1 ? { status: 'resolved', declaration: unique[0] } : { status: unique.length === 0 ? 'missing' : 'ambiguous' };
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
/**
|
|
32
|
+
* @lang zh-CN 在既有HIA输出路径补全源码/签名;原XML extraction wire及文档字段不修改。
|
|
33
|
+
* @lang en Enriches source/signature at existing HIA output paths without changing raw XML extraction wire data or documentation fields.
|
|
34
|
+
* @param {object[]} records <lang><zh-CN>当前请求抽取记录。</zh-CN><en>Extraction records from this request.</en></lang>
|
|
35
|
+
* @param {object} request <lang><zh-CN>规范化工作区/输出根。</zh-CN><en>Normalized workspace/output roots.</en></lang>
|
|
36
|
+
* @returns {Promise<object[]>} <lang><zh-CN>每个XML输入至多一条未定位警告,无正文或绝对路径。</zh-CN><en>At most one unresolved warning per XML input, without bodies or absolute paths.</en></lang>
|
|
37
|
+
*/
|
|
38
|
+
export async function enrichXmlSourceLocations(records, request) {
|
|
39
|
+
// <lang><zh-CN>只使用已配置发现结果或XML输入显式绑定的projectPath;不扫描整个业务工作区。</zh-CN><en>Use configured discovery results or an XML input's explicit projectPath only, without scanning the target workspace.</en></lang>
|
|
40
|
+
const projects = new Map(records.filter(record => record.artifact.contract === DOTNETDOC_PROJECT_DISCOVERY_CONTRACT).flatMap(record => record.artifact.projects ?? []).map(project => [project.path, project]));
|
|
41
|
+
const explicit = records.filter(record => record.artifact.contract === DOTNETDOC_CSHARP_SOURCE_EXTRACTION_CONTRACT).flatMap(record => candidatesFrom(record.artifact));
|
|
42
|
+
const cache = new Map();
|
|
43
|
+
const diagnostics = [];
|
|
44
|
+
for (const record of records) {
|
|
45
|
+
if (record.artifact.contract !== DOTNETDOC_XML_DOC_EXTRACTION_CONTRACT) continue;
|
|
46
|
+
// <lang><zh-CN>程序集匹配先于源码抽取;同名不同工程不能按文件顺序决定归属。</zh-CN><en>Assembly matching precedes source extraction; input order cannot resolve ownership between projects.</en></lang>
|
|
47
|
+
const assembly = record.artifact.assembly?.name;
|
|
48
|
+
let available = [...projects.values()];
|
|
49
|
+
if (record.input.projectPath) {
|
|
50
|
+
try {
|
|
51
|
+
await assertContainedFile(request.workspaceRoot, record.input.projectPath);
|
|
52
|
+
const discovery = await extractDotnetProjectDiscovery({ workspaceRoot: request.workspaceRoot, paths: [record.input.projectPath] });
|
|
53
|
+
available = discovery.projects;
|
|
54
|
+
} catch { available = []; }
|
|
55
|
+
}
|
|
56
|
+
const matches = assembly ? available.filter(project => (project.assemblyName ?? project.name) === assembly) : [];
|
|
57
|
+
// <lang><zh-CN>每项目串行抽取并缓存一次;失败也是本请求缓存结果,不反复启动helper。</zh-CN><en>Extract each project serially once and cache failures too, preventing repeated helper launches.</en></lang>
|
|
58
|
+
let discovered = [];
|
|
59
|
+
if (matches.length === 1) {
|
|
60
|
+
const project = matches[0];
|
|
61
|
+
if (!cache.has(project.path)) cache.set(project.path, await readProjectCandidates(project, request.workspaceRoot));
|
|
62
|
+
discovered = cache.get(project.path);
|
|
63
|
+
}
|
|
64
|
+
// <lang><zh-CN>显式输入对其成员ID优先;自动项目发现不重复注册同一显式身份,显式输入之间的重复仍拒绝。</zh-CN><en>Explicit inputs take precedence for their member IDs; automatic discovery never duplicates an explicit identity, while duplicates between explicit inputs remain refused.</en></lang>
|
|
65
|
+
const explicitIds = new Set(explicit.filter(candidate => !assembly || !candidate.assembly || candidate.assembly === assembly || candidate.assembly === 'DotNetDoc.SourceExtraction').map(candidate => candidate.member.semantic?.documentationCommentId));
|
|
66
|
+
const candidates = [...explicit, ...discovered.filter(candidate => !explicitIds.has(candidate.member.semantic?.documentationCommentId))];
|
|
67
|
+
const byId = new Map();
|
|
68
|
+
for (const candidate of candidates) {
|
|
69
|
+
const id = candidate.member.semantic?.documentationCommentId;
|
|
70
|
+
if (!id) continue;
|
|
71
|
+
const bucket = byId.get(id) ?? [];
|
|
72
|
+
bucket.push(candidate);
|
|
73
|
+
byId.set(id, bucket);
|
|
74
|
+
}
|
|
75
|
+
// <lang><zh-CN>统计是有界元数据;每个符号保留XML原文/i18n,只合并验证后的代码声明。
|
|
76
|
+
// </zh-CN><en>Counts are bounded metadata; each symbol retains XML text/i18n and merges only verified code declarations.</en></lang>
|
|
77
|
+
const summary = { strategy: 'assembly-and-documentation-id', resolved: 0, ambiguous: 0, missing: 0 };
|
|
78
|
+
const members = [];
|
|
79
|
+
for (const member of record.artifact.members) {
|
|
80
|
+
const selected = selectExactDeclaration(member, byId.get(member.memberName) ?? [], assembly);
|
|
81
|
+
if (selected.status !== 'resolved') { summary[selected.status] += 1; members.push(member); continue; }
|
|
82
|
+
const declaration = selected.declaration;
|
|
83
|
+
try {
|
|
84
|
+
await assertContainedFile(request.workspaceRoot, declaration.source.path);
|
|
85
|
+
if (!/\.cs$/iu.test(declaration.source.path) || !validRange(declaration.source.range)) throw new Error('Not a bounded C# declaration');
|
|
86
|
+
summary.resolved += 1;
|
|
87
|
+
members.push({ ...member, source: declaration.source, semantic: { ...member.semantic, ...declaration.semantic } });
|
|
88
|
+
} catch { summary.missing += 1; members.push(member); }
|
|
89
|
+
}
|
|
90
|
+
const document = dotnetXmlDocsToHiaDocument({ ...record.artifact, members }, { id: record.input.hiaDocumentId, title: record.input.title });
|
|
91
|
+
document.metadata.sourceLocationResolution = summary;
|
|
92
|
+
record.hiaDocument = document;
|
|
93
|
+
await writeFile(path.join(request.outputDirectory, record.hiaPath), `${JSON.stringify(document, null, 2)}\n`, 'utf8');
|
|
94
|
+
if (summary.missing || summary.ambiguous) diagnostics.push({ code: 'DOTNETDOC_SOURCE_LOCATION_UNRESOLVED', message: 'Some XML members have no unique C# declaration. Configure the matching project/source inputs and resolve missing references; XML origins are not exposed as code.', severity: 'warning', source: { path: record.input.path }, metadata: summary });
|
|
95
|
+
}
|
|
96
|
+
return diagnostics;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/** @lang zh-CN 从已有抽取结果取身份和定位,不复制方法体。 @lang en Selects identities/locators from existing extraction results without copying method bodies. */
|
|
100
|
+
function candidatesFrom(artifact) {
|
|
101
|
+
return artifact.members.map(member => ({ member, assembly: artifact.assembly?.name ?? member.semantic?.containingAssembly }));
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
/** @lang zh-CN 受限项目只读抽取;任何路径/工具失败都变为未定位,不泄露底层错误。 @lang en Performs bounded read-only project extraction, mapping path/tool failures to unresolved locations without leaking underlying errors. */
|
|
105
|
+
async function readProjectCandidates(project, root) {
|
|
106
|
+
try {
|
|
107
|
+
await assertContainedFile(root, project.path);
|
|
108
|
+
// <lang><zh-CN>显式Compile条目先验证真实路径;SDK默认遍历不跟随symlink,项目根仍须在工作区内。</zh-CN><en>Validate real paths of explicit Compile items first; SDK enumeration does not follow symlinks and its project root must remain inside the workspace.</en></lang>
|
|
109
|
+
for (const item of project.compileItems ?? []) {
|
|
110
|
+
if (typeof item.include !== 'string' || !/\.cs$/iu.test(item.include)) continue;
|
|
111
|
+
const sourcePath = path.posix.normalize(path.posix.join(path.posix.dirname(project.path), item.include.replaceAll('\\', '/')));
|
|
112
|
+
await assertContainedFile(root, sourcePath);
|
|
113
|
+
}
|
|
114
|
+
return candidatesFrom(await extractDotnetSourceFiles({ workspaceRoot: root, projectPath: project.path }));
|
|
115
|
+
} catch { return []; }
|
|
116
|
+
}
|
|
117
|
+
|
|
118
|
+
/** @lang zh-CN 双重路径包含检查,不读取越界symlink目标正文。 @lang en Checks lexical and real-path containment without reading bodies behind escaping symlinks. */
|
|
119
|
+
async function assertContainedFile(root, relative) {
|
|
120
|
+
if (typeof relative !== 'string' || /^(?:[/\\]|[a-z][a-z0-9+.-]*:)/iu.test(relative) || relative.replaceAll('\\', '/').split('/').includes('..')) throw new Error('Unsafe source locator');
|
|
121
|
+
const [realRoot, realFile] = await Promise.all([realpath(root), realpath(path.resolve(root, relative))]);
|
|
122
|
+
const inside = path.relative(realRoot, realFile);
|
|
123
|
+
if (path.isAbsolute(inside) || inside === '..' || inside.startsWith(`..${path.sep}`)) throw new Error('Source leaves workspace');
|
|
124
|
+
}
|
|
125
|
+
|
|
126
|
+
/** @lang zh-CN 只接受一基有序物理范围;不从XML默认第一行。 @lang en Accepts one-based ordered physical ranges without defaulting XML to line one. */
|
|
127
|
+
function validRange(range) {
|
|
128
|
+
const start = range?.start;
|
|
129
|
+
const end = range?.end;
|
|
130
|
+
return Number.isSafeInteger(start?.line) && start.line > 0 && Number.isSafeInteger(end?.line) && end.line >= start.line && (start.column === undefined || Number.isSafeInteger(start.column) && start.column > 0) && (end.column === undefined || Number.isSafeInteger(end.column) && end.column > 0) && (end.line !== start.line || end.column === undefined || start.column === undefined || end.column >= start.column);
|
|
131
|
+
}
|