@hia-doc/dotnetdoc-runner 0.1.12 → 1.0.0-rc.1

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/src/index.mjs CHANGED
@@ -3,7 +3,7 @@
3
3
  * @lang zh-CN 编排显式.NET输入的抽取与HIA/关系输出,仅唯一精确声明补全XML签名,不修改业务输入。
4
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
5
  */
6
- import { readFile, mkdir, readdir, writeFile } from "node:fs/promises";
6
+ import { readFile, mkdir, readdir, writeFile, realpath } from "node:fs/promises";
7
7
  import path from "node:path";
8
8
 
9
9
  import { extractAspNetEndpoints, extractDotnetMarkupComments, extractDotnetProjectDiscovery, extractDotnetSourceFiles } from "@hia-doc/dotnet-source-extractor";
@@ -27,20 +27,46 @@ export {
27
27
  DOTNETDOC_CONFIG_SCHEMA_VERSION
28
28
  } from "./schema.mjs";
29
29
  import { DOTNETDOC_CONFIG_SCHEMA_ID, DOTNETDOC_CONFIG_SCHEMA_VERSION } from "./schema.mjs";
30
+ import { cloneDotnetDocJson } from '@hia-doc/dotnetdoc-spec';
31
+ import { inspectDotnetDocConfig } from './config-compatibility.mjs';
32
+ /** 两代配置schema的精确选择,不执行配置或读取schema URL。 @lang en Exact dual-generation config-schema selection without config execution or schema URL reads. */
33
+ export { getDotnetDocConfigSchema } from './config-compatibility.mjs';
34
+ import * as legacyConfig from './schema-legacy.mjs';
35
+ /**
36
+ * @lang zh-CN 原档案配置schema的同一对象,不克隆或改写旧规则。
37
+ * @lang en The original archived config-schema object without cloning or rewriting historical rules.
38
+ */
39
+ export const DOTNETDOC_LEGACY_CONFIG_JSON_SCHEMA = legacyConfig.DOTNETDOC_CONFIG_JSON_SCHEMA;
40
+ /**
41
+ * @lang zh-CN 原档案配置schema身份,不访问URL或替换为新版本。
42
+ * @lang en Original archived config-schema identity, without URL access or substitution by a new version.
43
+ */
44
+ export const DOTNETDOC_LEGACY_CONFIG_SCHEMA_ID = legacyConfig.DOTNETDOC_CONFIG_SCHEMA_ID;
45
+ /**
46
+ * @lang zh-CN 原档案配置版本,不重标历史工件。
47
+ * @lang en Original archived config version, without relabeling historical artifacts.
48
+ */
49
+ export const DOTNETDOC_LEGACY_CONFIG_SCHEMA_VERSION = legacyConfig.DOTNETDOC_CONFIG_SCHEMA_VERSION;
30
50
  import { enrichXmlSourceLocations } from "./source-locations.mjs";
31
-
51
+ import { createDotnetDocSourceMap, hasUnpairedSurrogate } from "./doc-source-map.mjs";
52
+ export { createDotnetDocSourceMap, DOTNETDOC_DOC_SOURCE_MAP_CONTRACT_VERSION } from "./doc-source-map.mjs";
53
+ /** @lang zh-CN 复用包内纯数据定义的同一冻结对象。 @lang en Reuses the same frozen objects from owner-local plain-data definitions. */
54
+ import {DOTNETDOC_RUNNER_VERSION, DOTNETDOC_INPUT_KINDS, DOTNETDOC_OUTPUT_KINDS} from './metadata.mjs';
55
+ export {DOTNETDOC_RUNNER_VERSION, DOTNETDOC_INPUT_KINDS, DOTNETDOC_OUTPUT_KINDS} from './metadata.mjs';
32
56
  /**
33
- * @lang zh-CN DotNetDoc runner/producer 的公开包版本;它与各个 `0.1.0-draft` artifact contract version 分离。
34
- * @lang en Public package version of the DotNetDoc runner/producer, kept separate from every `0.1.0-draft` artifact contract version.
57
+ * @lang zh-CN 构建告警分类契约名称,与下方版本共同标识数据语义,不是发布或验收状态。
58
+ * @lang en Build-warning classification contract name; together with its version it identifies data semantics, not release or acceptance status.
35
59
  */
36
- export const DOTNETDOC_RUNNER_VERSION = "0.1.12";
37
- export const DOTNETDOC_INPUT_KINDS = Object.freeze(["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface", "dotnet-markup-comments", "dotnet-project"]);
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"]);
39
60
  export const DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT = "dotnetdoc-build-warning-classification";
40
- export const DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT_VERSION = "0.1.0-draft";
61
+ /**
62
+ * @lang zh-CN 构建告警分类的新稳定wire,旧产物由spec精确读取。
63
+ * @lang en Stable current build-warning wire with exact legacy reading in the spec package.
64
+ */
65
+ export const DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT_VERSION = "1.0.0";
41
66
 
42
67
  const RESULT_CONTRACT = "documentation-producer-result";
43
- const RESULT_CONTRACT_VERSION = "0.1.0-draft";
68
+ /** 主SDK已确认的新结果身份,独立于.NET领域wire。 @lang en Confirmed current main SDK result identity, independent from .NET domain wires. */
69
+ const RESULT_CONTRACT_VERSION = "1.0.0";
44
70
  const PRODUCER_ID = "dotnetdoc";
45
71
  const SAFE_ID_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
46
72
  const DESIGNER_CODE_PATTERN = /(?:^|[\\/])[^\\/]+\.designer\.(?:cs|vb)$/iu;
@@ -48,13 +74,13 @@ const GENERATED_CODE_PATTERN = /(?:^|[\\/])(?:obj|bin|generated|generatedcode)(?
48
74
  const COMPILER_DIAGNOSTIC_PATTERN = /^(?<path>.+?)\((?<line>\d+),(?<column>\d+)\):\s*(?<severity>warning|error)\s+(?<code>[A-Z]+\d+):\s*(?<message>.+)$/iu;
49
75
 
50
76
  /**
51
- * 执行一次 .NET XML documentation 文档构建,并返回 documentation producer result。
52
- * Runs one .NET XML documentation build and returns a documentation producer result.
53
- *
77
+ * @lang zh-CN 执行一次.NET XML文档构建,并返回文档生产器结果。
78
+ * @lang en Runs one .NET XML documentation build and returns a documentation producer result.
54
79
  * @param {object} request <lang><en>DotNetDoc runner request with absolute workspace/output directories.</en><zh-CN>包含绝对工作区与输出目录的 DotNetDoc runner 请求。</zh-CN></lang>
55
- * @param {{ signal?: AbortSignal, reportProgress?: Function }} [context] <lang><en>Optional producer runtime context.</en><zh-CN>可选 producer 运行时上下文。</zh-CN></lang>
80
+ * @param {Object} [context] <lang><en>Optional producer runtime context.</en><zh-CN>可选 producer 运行时上下文。</zh-CN></lang>
81
+ * @param {AbortSignal} [context.signal] <lang><zh-CN>可选取消信号。</zh-CN><en>Optional cancellation signal.</en></lang>
82
+ * @param {Function} [context.reportProgress] <lang><zh-CN>可选进度回调。</zh-CN><en>Optional progress callback.</en></lang>
56
83
  * @returns {Promise<object>} <lang><en>Documentation producer result.</en><zh-CN>Documentation producer result。</zh-CN></lang>
57
- * @lang zh-CN 执行 .NET XML documentation 构建。
58
84
  */
59
85
  export async function runDotnetDoc(request, context = {}) {
60
86
  const normalizedRequest = normalizeRequest(request);
@@ -62,6 +88,23 @@ export async function runDotnetDoc(request, context = {}) {
62
88
  ...normalizedRequest,
63
89
  inputs: await expandInputs(normalizedRequest)
64
90
  };
91
+ // <lang><zh-CN>任何输出写入前预检所有地图路径与显式文档身份;拒绝重复、ADS 和不可逆编码的 UTF-16。</zh-CN><en>Preflight every map path and explicit document identity before output writes, rejecting collisions, ADS, and malformed UTF-16.</en></lang>
92
+ if (normalized.options.writeDocSourceMapArtifact) {
93
+ const outputBases = new Set();
94
+ for (const input of normalized.inputs) {
95
+ const artifactBasePath = normalizeSafeRelativePath(input.artifactBasePath, 'artifactBasePath');
96
+ if (input.hiaDocumentId !== undefined && (typeof input.hiaDocumentId !== 'string' || hasUnpairedSurrogate(input.hiaDocumentId))) {
97
+ throw new TypeError('Unsafe DotNetDoc map member identity.');
98
+ }
99
+ for (const suffix of ['.dotnetdoc.json', '.hia.json', '.doc-source-map.json']) {
100
+ const artifactPath = normalizeSafeRelativePath(`${artifactBasePath}${suffix}`, 'map artifact path');
101
+ encodeURIComponent(artifactPath);
102
+ }
103
+ const base = path.normalize(input.artifactBasePath).toLowerCase();
104
+ if (outputBases.has(base)) throw new TypeError('Duplicate DotNetDoc output artifact base collision.');
105
+ outputBases.add(base);
106
+ }
107
+ }
65
108
  await mkdir(normalized.outputDirectory, { recursive: true });
66
109
 
67
110
  const artifacts = [];
@@ -88,13 +131,14 @@ export async function runDotnetDoc(request, context = {}) {
88
131
  diagnostics.push(...generated.diagnostics);
89
132
  extractionRecords.push(generated.extractionRecord);
90
133
  completed += 1;
91
- } catch (error) {
134
+ } catch {
135
+ // <lang><zh-CN>底层异常可能含私有绝对路径/正文,公开结果只保留固定原因。</zh-CN><en>Lower-layer errors may contain private absolute paths/bodies; public results retain only a fixed cause.</en></lang>
92
136
  diagnostics.push(createDiagnostic(
93
137
  "DOTNETDOC_RUNNER_INPUT_FAILED",
94
138
  `Unable to process DotNetDoc input ${input.path}.`,
95
139
  "error",
96
140
  input.path,
97
- { cause: error instanceof Error ? error.message : String(error) }
141
+ { cause: 'input-processing-failed' }
98
142
  ));
99
143
  }
100
144
  }
@@ -102,6 +146,26 @@ export async function runDotnetDoc(request, context = {}) {
102
146
  // <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
147
  const sourceRelation = buildSourceRelationArtifact(extractionRecords, normalized);
104
148
  diagnostics.push(...await enrichXmlSourceLocations(extractionRecords, normalized));
149
+ if (normalized.options.writeDocSourceMapArtifact) {
150
+ // <lang><zh-CN>源码映射只对成员抽取生成;路径真实包含检查先于纯数据 writer,XML 出处不进入代码引用。</zh-CN><en>Emit maps only for member extractions; real-path containment precedes the pure writer, and XML origins never become code references.</en></lang>
151
+ for (const record of extractionRecords) {
152
+ if (![DOTNETDOC_XML_DOC_EXTRACTION_CONTRACT, DOTNETDOC_CSHARP_SOURCE_EXTRACTION_CONTRACT].includes(record.artifact.contract)) continue;
153
+ try {
154
+ const verifiedSourcePaths = await verifyCodePaths(record.hiaDocument, normalized.workspaceRoot);
155
+ const map = createDotnetDocSourceMap({ record, verifiedSourcePaths, producerVersion: DOTNETDOC_RUNNER_VERSION });
156
+ const mapPath = `${record.input.artifactBasePath}.doc-source-map.json`;
157
+ // <lang><zh-CN>先写地图,再写带引用的 HIA 文档;前者失败时旧文档不含悬空引用。</zh-CN><en>Write the map before the referencing HIA document so map failures cannot leave a dangling HIA reference.</en></lang>
158
+ await writeJson(path.join(normalized.outputDirectory, mapPath), map);
159
+ const updatedDocument = { ...record.hiaDocument, metadata: { ...record.hiaDocument.metadata, docSourceMaps: [{ contract: map.contract, contractVersion: map.contractVersion, path: mapPath }] } };
160
+ await writeJson(path.join(normalized.outputDirectory, record.hiaPath), updatedDocument);
161
+ record.hiaDocument = updatedDocument;
162
+ artifacts.push({ ...artifact(reversibleArtifactId('doc-source-map', mapPath), 'doc-source-map', mapPath, normalized.profileIds), contract: map.contract, contractVersion: map.contractVersion });
163
+ } catch {
164
+ // <lang><zh-CN>单个地图失败只降为受控 partial,不拷贝可能含私有路径或正文的底层异常。</zh-CN><en>A single map failure becomes a controlled partial result without copying a potentially private underlying exception.</en></lang>
165
+ diagnostics.push(createDiagnostic('DOTNETDOC_RUNNER_SOURCE_MAP_FAILED', 'Unable to emit a DotNetDoc source map for this input.', 'error', record.input.path));
166
+ }
167
+ }
168
+ }
105
169
  if (sourceRelation && normalized.options.writeSourceRelationArtifact) {
106
170
  const relationPath = "dotnetdoc.source-relation.json";
107
171
  await writeJson(path.join(normalized.outputDirectory, relationPath), sourceRelation);
@@ -142,12 +206,10 @@ export async function runDotnetDoc(request, context = {}) {
142
206
 
143
207
 
144
208
  /**
145
- * 将 .NET build / MSBuild 文本诊断分类为 manual、designer 或 generated 边界。
146
- * Classifies .NET build / MSBuild textual diagnostics into manual, designer or generated boundaries.
147
- *
209
+ * @lang zh-CN 将.NET构建与MSBuild文本诊断分类为手工编写、设计器或生成代码边界。
210
+ * @lang en Classifies .NET build and MSBuild textual diagnostics into manual, designer or generated-code boundaries.
148
211
  * @param {Array<string|object>} diagnostics <lang><en>Compiler diagnostic lines or normalized diagnostic objects.</en><zh-CN>编译器诊断文本行或规范化诊断对象。</zh-CN></lang>
149
212
  * @returns {object} <lang><en>Warning classification artifact that contains no source body.</en><zh-CN>不含源码正文的 warning 分类产物。</zh-CN></lang>
150
- * @lang zh-CN 对 .NET build warning 进行 generated/designer 边界分类。
151
213
  */
152
214
  export function classifyDotnetBuildDiagnostics(diagnostics) {
153
215
  if (!Array.isArray(diagnostics)) {
@@ -166,7 +228,7 @@ export function classifyDotnetBuildDiagnostics(diagnostics) {
166
228
  },
167
229
  policy: {
168
230
  name: "dotnetdoc-generated-designer-warning-policy",
169
- version: "0.1.0-draft",
231
+ version: DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT_VERSION,
170
232
  defaultDocumentationGate: "do-not-block-on-generated-or-designer-cs1591",
171
233
  sourcesContentPolicy: "none"
172
234
  },
@@ -176,25 +238,17 @@ export function classifyDotnetBuildDiagnostics(diagnostics) {
176
238
  }
177
239
 
178
240
  /**
179
- * 读取 versioned DotNetDoc JSON config 并转成 runner request。
180
- * Loads a versioned DotNetDoc JSON config and converts it into a runner request.
181
- *
241
+ * @lang zh-CN 读取带版本的.NET文档JSON配置,并转换为运行器请求。
242
+ * @lang en Loads a versioned .NET documentation JSON config and converts it into a runner request.
182
243
  * @param {string} configPath <lang><en>Config path relative to cwd or absolute.</en><zh-CN>相对当前目录或绝对的配置文件路径。</zh-CN></lang>
183
- * @param {{ cwd?: string }} [options] <lang><en>Config loading options.</en><zh-CN>配置加载选项。</zh-CN></lang>
244
+ * @param {Object} [options] <lang><en>Config loading options.</en><zh-CN>配置加载选项。</zh-CN></lang>
245
+ * @param {string} [options.cwd] <lang><zh-CN>相对路径基准;省略时使用当前工作目录。</zh-CN><en>Base for relative paths; defaults to the current working directory.</en></lang>
184
246
  * @returns {Promise<object>} <lang><en>Normalized runner request.</en><zh-CN>规范化后的 runner 请求。</zh-CN></lang>
185
- * @lang zh-CN 加载 DotNetDoc 配置。
186
247
  */
187
248
  export async function loadDotnetDocConfig(configPath, options = {}) {
188
249
  const absoluteConfigPath = path.resolve(options.cwd ?? process.cwd(), configPath);
189
- const config = JSON.parse(await readFile(absoluteConfigPath, "utf8"));
190
- assertRecord(config, "DotNetDoc config must be a JSON object.");
191
- assertKnownKeys(config, ["$schema", "schemaVersion", "workspaceRoot", "outputDirectory", "inputs", "options", "profileIds"], "config");
192
- if (config.schemaVersion !== DOTNETDOC_CONFIG_SCHEMA_VERSION) {
193
- throw new TypeError(`schemaVersion must be ${DOTNETDOC_CONFIG_SCHEMA_VERSION}.`);
194
- }
195
- if (config.$schema !== undefined && config.$schema !== DOTNETDOC_CONFIG_SCHEMA_ID) {
196
- throw new TypeError(`$schema must be ${DOTNETDOC_CONFIG_SCHEMA_ID}.`);
197
- }
250
+ // <lang><zh-CN>读取两代精确身份,规范化和执行继续分开;不自动升级旧配置。</zh-CN><en>Read both exact identities while keeping normalization/execution separate, without automatically upgrading legacy config.</en></lang>
251
+ const config = readDotnetDocConfig(JSON.parse(await readFile(absoluteConfigPath, "utf8")));
198
252
 
199
253
  const configDirectory = path.dirname(absoluteConfigPath);
200
254
  const workspaceDirectory = normalizeConfigDirectory(config.workspaceRoot ?? ".", "workspaceRoot");
@@ -210,6 +264,47 @@ export async function loadDotnetDocConfig(configPath, options = {}) {
210
264
  });
211
265
  }
212
266
 
267
+ /**
268
+ * @lang zh-CN 精确读取两代配置并保留原对象;旧版保留原运行时省略/null默认,新版另受严格schema约束。
269
+ * @lang en Reads two exact config generations and retains the original object; legacy reading keeps omission/null defaults while current reading also enforces the strict schema.
270
+ * @param {unknown} value <lang><zh-CN>普通JSON配置;不执行getter、抽取或I/O。</zh-CN><en>Ordinary-JSON config without getter, extraction or I/O execution.</en></lang>
271
+ * @returns {object} <lang><zh-CN>原对象;相对目录未物化为绝对路径。</zh-CN><en>Original object without materializing relative directories into absolute paths.</en></lang>
272
+ * @throws {TypeError} <lang><zh-CN>未知/错配身份或无效原运行语义固定拒绝。</zh-CN><en>Fixed refusal for unknown/mismatched identities or invalid original runtime semantics.</en></lang>
273
+ */
274
+ export function readDotnetDocConfig(value) {
275
+ try {
276
+ // <lang><zh-CN>副本只用于校验,原调用方对象在通过后原样返回;不把旧schema错误required变成历史正确。</zh-CN><en>Use a copy only for validation and return the caller object unchanged; do not recast the legacy schema's incorrect required fields as historically correct.</en></lang>
277
+ const config = inspectDotnetDocConfig(value);
278
+ assertRecord(config, 'DotNetDoc config must be a JSON object.');
279
+ assertKnownKeys(config, ['$schema', 'schemaVersion', 'workspaceRoot', 'outputDirectory', 'inputs', 'options', 'profileIds'], 'config');
280
+ // <lang><zh-CN>纯规范化只验证既有目录/输入/option语义;结果丢弃,不创建目录或启动helper。</zh-CN><en>Pure normalization validates existing directory/input/option semantics; discard the result without creating directories or starting the helper.</en></lang>
281
+ const workspaceDirectory = normalizeConfigDirectory(config.workspaceRoot ?? '.', 'workspaceRoot');
282
+ const outputDirectory = normalizeConfigDirectory(config.outputDirectory ?? 'dist/dotnetdoc', 'outputDirectory');
283
+ normalizeRequest({ workspaceRoot: workspaceDirectory, outputDirectory, inputs: config.inputs, options: config.options, profileIds: config.profileIds });
284
+ return value;
285
+ } catch { throw new TypeError('DotNetDoc config must match an exact supported identity and structure.'); }
286
+ }
287
+
288
+ /**
289
+ * @lang zh-CN 显式无损迁移旧配置,仅更新身份,不能把null/扩展/特殊JSON值静默改写成新默认。
290
+ * @lang en Explicitly migrates legacy config losslessly by updating identity only, never silently rewriting nulls, extensions or non-JSON values into current defaults.
291
+ * @param {unknown} value <lang><zh-CN>精确旧配置,先按原运行语义验证。</zh-CN><en>Exact legacy config, first validated against original runtime semantics.</en></lang>
292
+ * @returns {object} <lang><zh-CN>新对象,保持内容、字段省略和相对路径;不写盘或执行。</zh-CN><en>Fresh object retaining content, omitted fields and relative paths without file writes or execution.</en></lang>
293
+ * @throws {TypeError} <lang><zh-CN>不满足任一代读取或JSON无损条件则固定拒绝。</zh-CN><en>Fixed refusal when either generation's reading or lossless-JSON conditions fail.</en></lang>
294
+ */
295
+ export function migrateDotnetDocConfig(value) {
296
+ try {
297
+ // <lang><zh-CN>副本校验后只变版本及已有$schema,不强制填目录或推断输入kind。</zh-CN><en>After copy validation change only version and an existing $schema, never filling directories or inferring input kinds.</en></lang>
298
+ const config = cloneDotnetDocJson(value);
299
+ if (config?.schemaVersion !== '0.1.0-draft') throw new TypeError('Unsupported legacy config.');
300
+ readDotnetDocConfig(config);
301
+ config.schemaVersion = DOTNETDOC_CONFIG_SCHEMA_VERSION;
302
+ if (config.$schema !== undefined) config.$schema = DOTNETDOC_CONFIG_SCHEMA_ID;
303
+ readDotnetDocConfig(config);
304
+ return config;
305
+ } catch { throw new TypeError('DotNetDoc config cannot be migrated losslessly.'); }
306
+ }
307
+
213
308
  function normalizeRequest(request) {
214
309
  assertRecord(request, "DotNetDoc request must be an object.");
215
310
  const workspaceRoot = path.resolve(String(request.workspaceRoot ?? process.cwd()));
@@ -220,7 +315,8 @@ function normalizeRequest(request) {
220
315
 
221
316
  const options = {
222
317
  writeResultManifest: request.options?.writeResultManifest !== false,
223
- writeSourceRelationArtifact: request.options?.writeSourceRelationArtifact !== false
318
+ writeSourceRelationArtifact: request.options?.writeSourceRelationArtifact !== false,
319
+ writeDocSourceMapArtifact: request.options?.writeDocSourceMapArtifact === true
224
320
  };
225
321
  const profileIds = normalizeProfileIds(request.profileIds ?? ["dotnetdoc"]);
226
322
 
@@ -313,11 +409,11 @@ async function processInput(input, request) {
313
409
  return {
314
410
  artifacts: [
315
411
  {
316
- ...artifact(`${safeArtifactId(input.artifactBasePath)}-dotnetdoc`, "dotnetdoc-extraction", dotnetdocPath, request.profileIds),
412
+ ...artifact(request.options.writeDocSourceMapArtifact ? reversibleArtifactId('dotnetdoc-extraction', dotnetdocPath) : `${safeArtifactId(input.artifactBasePath)}-dotnetdoc`, "dotnetdoc-extraction", dotnetdocPath, request.profileIds),
317
413
  contract: dotnetdoc.contract,
318
414
  contractVersion: dotnetdoc.contractVersion
319
415
  },
320
- artifact(`${safeArtifactId(input.artifactBasePath)}-hia-document`, "hia-document", hiaPath, request.profileIds)
416
+ artifact(request.options.writeDocSourceMapArtifact ? reversibleArtifactId('hia-document', hiaPath) : `${safeArtifactId(input.artifactBasePath)}-hia-document`, "hia-document", hiaPath, request.profileIds)
321
417
  ],
322
418
  diagnostics: [...(dotnetdoc.diagnostics ?? []), ...(hiaDocument.diagnostics ?? [])]
323
419
  .map(normalizeRunnerDiagnostic),
@@ -867,6 +963,30 @@ function artifact(id, kind, artifactPath, profileIds) {
867
963
  };
868
964
  }
869
965
 
966
+ /**
967
+ * @lang zh-CN 仅确认已有 C# 文件的真实路径仍在工作区内,且不读取或嵌入源码正文。
968
+ * @lang en Verifies existing C# files remain within the real workspace without reading or embedding their bodies.
969
+ * @param {object} document <lang><zh-CN>本次生成的 HIA 文档。</zh-CN><en>The HIA document generated in this run.</en></lang>
970
+ * @param {string} workspaceRoot <lang><zh-CN>工作区根目录。</zh-CN><en>Workspace root.</en></lang>
971
+ * @returns {Promise<Set<string>>} <lang><zh-CN>经词法与真实路径双重检查的相对文件路径。</zh-CN><en>Relative file paths passing lexical and real-path containment checks.</en></lang>
972
+ */
973
+ async function verifyCodePaths(document, workspaceRoot) {
974
+ const verified = new Set();
975
+ const root = await realpath(workspaceRoot);
976
+ for (const symbol of document.symbols ?? []) {
977
+ const relative = symbol?.source?.definedIn?.relativePath?.replaceAll('\\', '/');
978
+ if (typeof relative !== 'string' || !/\.cs$/iu.test(relative) || hasUnpairedSurrogate(relative) || relative.includes(':') || /^(?:[/\\]|[a-z][a-z0-9+.-]*:)/iu.test(relative) || relative.split('/').includes('..') || verified.has(relative)) continue;
979
+ try {
980
+ const file = await realpath(path.resolve(root, relative));
981
+ const inside = path.relative(root, file);
982
+ if (inside && !path.isAbsolute(inside) && inside !== '..' && !inside.startsWith(`..${path.sep}`)) verified.add(relative);
983
+ } catch {
984
+ // <lang><zh-CN>失效/越根文件保留 HIA 成员但不发布精确代码位置。</zh-CN><en>A missing or escaping file leaves the HIA member intact without a precise code location.</en></lang>
985
+ }
986
+ }
987
+ return verified;
988
+ }
989
+
870
990
  async function writeJson(filePath, value) {
871
991
  await mkdir(path.dirname(filePath), { recursive: true });
872
992
  await writeFile(filePath, `${JSON.stringify(value, null, 2)}\n`, "utf8");
@@ -1003,7 +1123,7 @@ function normalizeSafeRelativePath(value, label) {
1003
1123
  throw new TypeError(`${label} must be a non-empty relative path.`);
1004
1124
  }
1005
1125
  const normalized = value.replaceAll("\\", "/").replace(/^\.\//, "");
1006
- if (!normalized || normalized.startsWith("/") || /^[a-zA-Z]:\//.test(normalized) || normalized.split("/").includes("..")) {
1126
+ if (!normalized || normalized.startsWith("/") || hasUnpairedSurrogate(normalized) || normalized.includes(":") || normalized.split("/").includes("..")) {
1007
1127
  throw new TypeError(`${label} must be a safe relative path.`);
1008
1128
  }
1009
1129
  return normalized;
@@ -1014,7 +1134,7 @@ function normalizeSafeGlobPattern(value, label) {
1014
1134
  throw new TypeError(`${label} must be a non-empty relative glob pattern.`);
1015
1135
  }
1016
1136
  const normalized = value.replaceAll("\\", "/").replace(/^\.\//, "");
1017
- if (!normalized || normalized.startsWith("/") || /^[a-zA-Z]:\//.test(normalized) || normalized.split("/").includes("..")) {
1137
+ if (!normalized || normalized.startsWith("/") || hasUnpairedSurrogate(normalized) || normalized.includes(":") || normalized.split("/").includes("..")) {
1018
1138
  throw new TypeError(`${label} must be a safe relative glob pattern.`);
1019
1139
  }
1020
1140
  return normalized;
@@ -1099,6 +1219,17 @@ function safeArtifactId(value) {
1099
1219
  return value.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-|-$/g, "") || "input";
1100
1220
  }
1101
1221
 
1222
+ /**
1223
+ * @lang zh-CN 仅为显式启用地图的结果工件生成可逆路径身份,避免不同路径在旧 slug 下相撞。
1224
+ * @lang en Makes path-reversible result artifact identities only for map-enabled builds, avoiding legacy slug collisions.
1225
+ * @param {string} kind <lang><zh-CN>结果工件类别。</zh-CN><en>Result artifact kind.</en></lang>
1226
+ * @param {string} artifactPath <lang><zh-CN>已经预检的相对输出路径。</zh-CN><en>Preflighted relative output path.</en></lang>
1227
+ * @returns {string} <lang><zh-CN>由 UTF-8 十六进制路径组成的无冲突身份。</zh-CN><en>Collision-free identity containing the UTF-8 hexadecimal path.</en></lang>
1228
+ */
1229
+ function reversibleArtifactId(kind, artifactPath) {
1230
+ return `${kind}-${Buffer.from(artifactPath, 'utf8').toString('hex')}`;
1231
+ }
1232
+
1102
1233
  function assertRecord(value, message) {
1103
1234
  if (!value || typeof value !== "object" || Array.isArray(value)) {
1104
1235
  throw new TypeError(message);
@@ -0,0 +1,20 @@
1
+ /**
2
+ * @file
3
+ * @lang zh-CN 运行器纯元数据子入口的精确类型,与旧根声明相同。
4
+ * @lang en Exact types of the pure runner metadata subpath, matching existing root declarations.
5
+ */
6
+ /**
7
+ * @lang zh-CN 独立的精确版本身份,不用于推断其它契约版本(DOTNETDOC_RUNNER_VERSION)。
8
+ * @lang en Exact DOTNETDOC_RUNNER_VERSION registry value, independent from other version, authority and precision decisions.
9
+ */
10
+ export const DOTNETDOC_RUNNER_VERSION: "1.0.0";
11
+ /**
12
+ * @lang zh-CN 当前支持的固定登记集合,不推断额外语法(DOTNETDOC_INPUT_KINDS)。
13
+ * @lang en Exact DOTNETDOC_INPUT_KINDS registry value, independent from other version, authority and precision decisions.
14
+ */
15
+ export const DOTNETDOC_INPUT_KINDS: readonly ["dotnet-xml-doc","dotnet-csharp-source","dotnet-aspnet-surface","dotnet-markup-comments","dotnet-project"];
16
+ /**
17
+ * @lang zh-CN 当前支持的固定登记集合,不推断额外语法(DOTNETDOC_OUTPUT_KINDS)。
18
+ * @lang en Exact DOTNETDOC_OUTPUT_KINDS registry value, independent from other version, authority and precision decisions.
19
+ */
20
+ export const DOTNETDOC_OUTPUT_KINDS: readonly ["dotnetdoc-extraction","hia-document","doc-source-map","dotnetdoc-source-relation","dotnetdoc-aspnet-endpoint-extraction","dotnetdoc-markup-comment-extraction","dotnetdoc-project-discovery"];
@@ -0,0 +1,19 @@
1
+ /** @file @lang zh-CN 运行器纯元数据,含版本及冻结输入/输出种类。 @lang en Pure runner metadata containing its version and frozen input/output kinds. */
2
+
3
+ /**
4
+ * @lang zh-CN 显式.NET/XML/C#/ASP.NET/标记/项目输入种类;列出能力不授予执行目标项目的权限。
5
+ * @lang en Explicit .NET/XML/C#/ASP.NET/markup/project input kinds; listing capabilities grants no permission to execute targets.
6
+ */
7
+ export const DOTNETDOC_INPUT_KINDS = Object.freeze(["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface", "dotnet-markup-comments", "dotnet-project"]);
8
+
9
+ /**
10
+ * @lang zh-CN 运行器可能产出的工件种类;具体清单仅以每次成功构建的实际结果为准。
11
+ * @lang en Artifact kinds the runner may produce; each successful build's actual result is authoritative for its concrete manifest.
12
+ */
13
+ export const DOTNETDOC_OUTPUT_KINDS = Object.freeze(["dotnetdoc-extraction", "hia-document", "doc-source-map", "dotnetdoc-source-relation", "dotnetdoc-aspnet-endpoint-extraction", "dotnetdoc-markup-comment-extraction", "dotnetdoc-project-discovery"]);
14
+
15
+ /**
16
+ * @lang zh-CN DotNetDoc runner/producer公开包版本,与领域工件、配置及主SDK各自身份分开。
17
+ * @lang en Public DotNetDoc runner/producer package version, independent from domain-artifact, config and main SDK identities.
18
+ */
19
+ export const DOTNETDOC_RUNNER_VERSION = "1.0.0";
@@ -0,0 +1,79 @@
1
+ export const DOTNETDOC_CONFIG_SCHEMA_VERSION = "0.1.0-draft";
2
+ export const DOTNETDOC_CONFIG_SCHEMA_ID = "https://mandolin.github.io/HIA-Documentation/schemas/dotnetdoc-config-0.1.0-draft.schema.json";
3
+
4
+ const relativePath = {
5
+ type: "string",
6
+ minLength: 1,
7
+ not: {
8
+ anyOf: [
9
+ { pattern: "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)" },
10
+ { pattern: ":" },
11
+ { pattern: "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)" }
12
+ ]
13
+ }
14
+ };
15
+
16
+ const relativePathArray = {
17
+ type: "array",
18
+ minItems: 1,
19
+ items: relativePath
20
+ };
21
+
22
+ export const DOTNETDOC_CONFIG_JSON_SCHEMA = Object.freeze({
23
+ $schema: "https://json-schema.org/draft/2020-12/schema",
24
+ $id: DOTNETDOC_CONFIG_SCHEMA_ID,
25
+ title: "DotNetDoc Config",
26
+ type: "object",
27
+ additionalProperties: false,
28
+ required: ["schemaVersion", "workspaceRoot", "outputDirectory", "inputs"],
29
+ properties: {
30
+ $schema: { const: DOTNETDOC_CONFIG_SCHEMA_ID },
31
+ schemaVersion: { const: DOTNETDOC_CONFIG_SCHEMA_VERSION },
32
+ workspaceRoot: relativePath,
33
+ outputDirectory: relativePath,
34
+ inputs: {
35
+ type: "array",
36
+ minItems: 1,
37
+ items: {
38
+ type: "object",
39
+ additionalProperties: false,
40
+ required: ["kind"],
41
+ anyOf: [
42
+ { required: ["path"] },
43
+ { required: ["paths"] },
44
+ { required: ["projectPath"] },
45
+ { required: ["glob"] },
46
+ { required: ["globs"] }
47
+ ],
48
+ properties: {
49
+ kind: { enum: ["dotnet-xml-doc", "dotnet-csharp-source", "dotnet-aspnet-surface", "dotnet-markup-comments", "dotnet-project"] },
50
+ path: relativePath,
51
+ paths: relativePathArray,
52
+ projectPath: relativePath,
53
+ glob: relativePath,
54
+ globs: relativePathArray,
55
+ excludeGlobs: relativePathArray,
56
+ applicationRoot: relativePath,
57
+ artifactBasePath: relativePath,
58
+ hiaDocumentId: { type: "string", minLength: 1 },
59
+ title: { type: "string", minLength: 1 }
60
+ }
61
+ }
62
+ },
63
+ options: {
64
+ type: "object",
65
+ additionalProperties: false,
66
+ properties: {
67
+ writeResultManifest: { type: "boolean" },
68
+ writeSourceRelationArtifact: { type: "boolean" },
69
+ writeDocSourceMapArtifact: { type: "boolean" }
70
+ }
71
+ },
72
+ profileIds: {
73
+ type: "array",
74
+ minItems: 1,
75
+ uniqueItems: true,
76
+ items: { type: "string", pattern: "^[a-z0-9][a-z0-9._-]*$" }
77
+ }
78
+ }
79
+ });
package/src/schema.mjs CHANGED
@@ -1,5 +1,14 @@
1
- export const DOTNETDOC_CONFIG_SCHEMA_VERSION = "0.1.0-draft";
2
- export const DOTNETDOC_CONFIG_SCHEMA_ID = "https://mandolin.github.io/HIA-Documentation/schemas/dotnetdoc-config-0.1.0-draft.schema.json";
1
+ /** @file 已确认B的新配置schema;原schema完整保留在schema-legacy.mjs,读取/迁移不原位放宽历史。 @lang en Confirmed B current config schema; the original remains intact in schema-legacy.mjs and reading/migration never loosens history in place. */
2
+ /**
3
+ * @lang zh-CN 新配置精确版本,独立于npm与领域工件身份。
4
+ * @lang en Exact current config version, independent from npm and domain-artifact identities.
5
+ */
6
+ export const DOTNETDOC_CONFIG_SCHEMA_VERSION = "1.0.0";
7
+ /**
8
+ * @lang zh-CN 稳定资源ID,不代表已发布到网络,也不会被loader下载。
9
+ * @lang en Stable resource ID, neither a claim of online publication nor a loader download target.
10
+ */
11
+ export const DOTNETDOC_CONFIG_SCHEMA_ID = "https://mandolin.github.io/HIA-Documentation/schemas/dotnetdoc-config-1.0.0.schema.json";
3
12
 
4
13
  const relativePath = {
5
14
  type: "string",
@@ -7,6 +16,7 @@ const relativePath = {
7
16
  not: {
8
17
  anyOf: [
9
18
  { pattern: "^(?:[A-Za-z]:|/|\\\\|[A-Za-z][A-Za-z0-9+.-]*:)" },
19
+ { pattern: ":" },
10
20
  { pattern: "(?:^|[\\\\/])\\.\\.(?:[\\\\/]|$)" }
11
21
  ]
12
22
  }
@@ -18,13 +28,18 @@ const relativePathArray = {
18
28
  items: relativePath
19
29
  };
20
30
 
31
+ /**
32
+ * @lang zh-CN 保留五种显式输入和原目录默认;省略目录允许,显式null仍拒绝。
33
+ * @lang en Retains five explicit input kinds and original directory defaults; omissions are allowed while explicit null is rejected.
34
+ */
21
35
  export const DOTNETDOC_CONFIG_JSON_SCHEMA = Object.freeze({
22
36
  $schema: "https://json-schema.org/draft/2020-12/schema",
23
37
  $id: DOTNETDOC_CONFIG_SCHEMA_ID,
38
+ $comment: "中文:当前配置保留目录省略默认、要求显式输入kind并拒绝null;验证不授权执行。 English: Current config retains omission defaults, requires explicit input kinds and rejects null; validation grants no execution permission.",
24
39
  title: "DotNetDoc Config",
25
40
  type: "object",
26
41
  additionalProperties: false,
27
- required: ["schemaVersion", "workspaceRoot", "outputDirectory", "inputs"],
42
+ required: ["schemaVersion", "inputs"],
28
43
  properties: {
29
44
  $schema: { const: DOTNETDOC_CONFIG_SCHEMA_ID },
30
45
  schemaVersion: { const: DOTNETDOC_CONFIG_SCHEMA_VERSION },
@@ -64,7 +79,8 @@ export const DOTNETDOC_CONFIG_JSON_SCHEMA = Object.freeze({
64
79
  additionalProperties: false,
65
80
  properties: {
66
81
  writeResultManifest: { type: "boolean" },
67
- writeSourceRelationArtifact: { type: "boolean" }
82
+ writeSourceRelationArtifact: { type: "boolean" },
83
+ writeDocSourceMapArtifact: { type: "boolean" }
68
84
  }
69
85
  },
70
86
  profileIds: {