@hia-doc/dotnetdoc-runner 0.1.11 → 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.
@@ -0,0 +1,364 @@
1
+ /**
2
+ * @file
3
+ * @lang zh-CN 运行器内存请求/配置/结果类型;独立于领域与包版本。
4
+ * @lang en Runner in-memory request/config/result types, independent from domain and package versions.
5
+ */
6
+ import type { DotnetDocRecord, DotnetDocSource } from '@hia-doc/dotnetdoc-spec';
7
+ /**
8
+ * @lang zh-CN 五种显式输入,未知kind由运行时拒绝。
9
+ * @lang en Five explicit inputs, with unknown kinds rejected at runtime.
10
+ */
11
+ export type DotnetDocInputKind = 'dotnet-xml-doc' | 'dotnet-csharp-source' | 'dotnet-aspnet-surface' | 'dotnet-markup-comments' | 'dotnet-project';
12
+ /**
13
+ * @lang zh-CN 至少一种定位器;路径仅为相对表达式,实际安全仍需运行时验证。
14
+ * @lang en At least one locator; paths are relative expressions whose actual safety still requires runtime checks.
15
+ * @remarks <lang><zh-CN>类型要求至少满足一个定位器分支,可同时满足多个分支。实际输入类别与路径权限由运行时检查。</zh-CN><en>The type requires at least one locator branch and permits overlapping branches. Runtime checks the actual input kind and path authority.</en></lang>
16
+ */
17
+ export type DotnetDocInput = {
18
+ /**
19
+ * @lang zh-CN 五种已登记输入类别之一,决定后续领域处理器。
20
+ * @lang en One of five registered input kinds selecting the subsequent domain handler.
21
+ */
22
+ kind: DotnetDocInputKind;
23
+ /**
24
+ * @lang zh-CN ASP.NET输入的应用根定位器,适用范围由运行器核验。
25
+ * @lang en Application-root locator for ASP.NET input, with applicability checked by the runner.
26
+ */
27
+ applicationRoot?: string;
28
+ /**
29
+ * @lang zh-CN 可选输出工件前缀,路径边界由运行器校验。
30
+ * @lang en Optional output-artifact prefix whose path boundary is validated by the runner.
31
+ */
32
+ artifactBasePath?: string;
33
+ /**
34
+ * @lang zh-CN 该输入投影的HIA文档身份覆盖值。
35
+ * @lang en HIA-document identity override for this input's projection.
36
+ */
37
+ hiaDocumentId?: string;
38
+ /**
39
+ * @lang zh-CN 该输入输出文档的可选标题。
40
+ * @lang en Optional title for this input's output document.
41
+ */
42
+ title?: string;
43
+ /**
44
+ * @lang zh-CN 可选排除模式,其适用输入及匹配规则由领域处理器解释。
45
+ * @lang en Optional exclusion patterns whose applicable inputs and matching rules are interpreted by the domain handler.
46
+ */
47
+ excludeGlobs?: string[];
48
+ } & ({
49
+ /**
50
+ * @lang zh-CN 单一路径定位器,满足一个输入定位分支。
51
+ * @lang en Single-path locator satisfying one input-location branch.
52
+ */
53
+ path: string;
54
+ } | {
55
+ /**
56
+ * @lang zh-CN 多路径定位器,由对应领域处理器解释。
57
+ * @lang en Multiple-path locator interpreted by the corresponding domain handler.
58
+ */
59
+ paths: string[];
60
+ } | {
61
+ /**
62
+ * @lang zh-CN 静态项目定位器,具体适用类别由运行时检查。
63
+ * @lang en Static project locator whose applicable kind is checked at runtime.
64
+ */
65
+ projectPath: string;
66
+ } | {
67
+ /**
68
+ * @lang zh-CN 单个路径匹配模式,匹配与授权范围分别核验。
69
+ * @lang en Single path-matching pattern with matching and authorization checked separately.
70
+ */
71
+ glob: string;
72
+ } | {
73
+ /**
74
+ * @lang zh-CN 多个路径匹配模式,展开后的文件仍须通过路径检查。
75
+ * @lang en Multiple path-matching patterns whose expanded files still require path checks.
76
+ */
77
+ globs: string[];
78
+ });
79
+ /**
80
+ * @lang zh-CN 输出控制默认前两项true、地图false;不隐式发布源码正文。
81
+ * @lang en Output controls default the first two to true and maps to false, without implicit source-body publication.
82
+ */
83
+ export interface DotnetDocOptions {
84
+ /**
85
+ * @lang zh-CN 是否写结果清单,省略时默认true。
86
+ * @lang en Whether to write the result manifest, defaulting to true when omitted.
87
+ */
88
+ writeResultManifest?: boolean;
89
+ /**
90
+ * @lang zh-CN 是否写来源关系工件,省略时默认true。
91
+ * @lang en Whether to write the source-relation artifact, defaulting to true when omitted.
92
+ */
93
+ writeSourceRelationArtifact?: boolean;
94
+ /**
95
+ * @lang zh-CN 是否写独立文档源码地图,省略时默认false。
96
+ * @lang en Whether to write the independent documentation source map, defaulting to false when omitted.
97
+ */
98
+ writeDocSourceMapArtifact?: boolean;
99
+ }
100
+ /**
101
+ * @lang zh-CN 内存请求可省略目录并沿cwd/dist默认;宿主上下文路径不可直接序列化为公开wire。
102
+ * @lang en In-memory requests may omit directories for cwd/dist defaults; host context paths must not be directly serialized as public wire data.
103
+ */
104
+ export interface DotnetDocRequest {
105
+ /**
106
+ * @lang zh-CN 输入工作区根,省略时沿既有cwd默认。
107
+ * @lang en Input workspace root using the existing cwd default when omitted.
108
+ */
109
+ workspaceRoot?: string;
110
+ /**
111
+ * @lang zh-CN 输出目录定位器,省略时沿既有dist默认。
112
+ * @lang en Output-directory locator using the existing dist default when omitted.
113
+ */
114
+ outputDirectory?: string;
115
+ /**
116
+ * @lang zh-CN 显式领域输入列表,逐项处理并记录结果。
117
+ * @lang en Explicit domain inputs processed and recorded individually.
118
+ */
119
+ inputs: DotnetDocInput[];
120
+ /**
121
+ * @lang zh-CN 可选输出控制,省略项使用运行器默认。
122
+ * @lang en Optional output controls whose omitted members use runner defaults.
123
+ */
124
+ options?: DotnetDocOptions;
125
+ /**
126
+ * @lang zh-CN 可选文档化profile选择,不授予额外执行权限。
127
+ * @lang en Optional documentation-profile selection granting no additional execution authority.
128
+ */
129
+ profileIds?: string[];
130
+ }
131
+ /**
132
+ * @lang zh-CN 当前配置身份,目录安全性由schema及loader保证。
133
+ * @lang en Current config identity, with directory safety enforced by schema and loader.
134
+ */
135
+ export interface DotnetDocCurrentConfig extends DotnetDocRequest {
136
+ /**
137
+ * @lang zh-CN 当前配置的精确1.0.0身份。
138
+ * @lang en Exact 1.0.0 identity of the current configuration.
139
+ */
140
+ schemaVersion: '1.0.0';
141
+ /**
142
+ * @lang zh-CN 可选配置schema标识,实际匹配由本地读者检查。
143
+ * @lang en Optional configuration schema identity checked by the local reader.
144
+ */
145
+ $schema?: string;
146
+ }
147
+ /**
148
+ * @lang zh-CN 旧配置保留原有null默认兼容;其它行为性输入仍拒绝。
149
+ * @lang en Legacy config retains null-default compatibility while still refusing behavioral inputs.
150
+ */
151
+ export interface DotnetDocLegacyConfig {
152
+ /**
153
+ * @lang zh-CN 旧配置的精确0.1.0-draft身份,保持兼容读取。
154
+ * @lang en Exact legacy 0.1.0-draft configuration identity retained for compatibility reading.
155
+ */
156
+ schemaVersion: '0.1.0-draft';
157
+ /**
158
+ * @lang zh-CN 可选旧配置schema标识。
159
+ * @lang en Optional legacy configuration schema identity.
160
+ */
161
+ $schema?: string;
162
+ /**
163
+ * @lang zh-CN 旧工作区定位器,省略或null沿既有默认处理。
164
+ * @lang en Legacy workspace locator whose omission or null uses existing defaults.
165
+ */
166
+ workspaceRoot?: string | null;
167
+ /**
168
+ * @lang zh-CN 旧输出定位器,省略或null保留原默认行为。
169
+ * @lang en Legacy output locator retaining original defaults for omission or null.
170
+ */
171
+ outputDirectory?: string | null;
172
+ /**
173
+ * @lang zh-CN 显式输入列表,按各输入类别分别验证。
174
+ * @lang en Explicit input list validated separately by input kind.
175
+ */
176
+ inputs: DotnetDocInput[];
177
+ /**
178
+ * @lang zh-CN 旧输出选项,null保持既有默认兼容。
179
+ * @lang en Legacy output options retaining existing null-default compatibility.
180
+ */
181
+ options?: DotnetDocOptions | null;
182
+ /**
183
+ * @lang zh-CN 旧profile选择,null或省略保留原处理规则。
184
+ * @lang en Legacy profile selection retaining original rules for null or omission.
185
+ */
186
+ profileIds?: string[] | null;
187
+ }
188
+ /**
189
+ * @lang zh-CN 两代读取联合;显式迁移另返回当前版本。
190
+ * @lang en Dual-generation reading union; explicit migration separately returns the current version.
191
+ */
192
+ export type DotnetDocConfig = DotnetDocCurrentConfig | DotnetDocLegacyConfig;
193
+ /**
194
+ * @lang zh-CN 进度数为输入项计数而非百分比;回调可能抛错。
195
+ * @lang en Progress numbers count input items rather than percentages; callbacks may throw.
196
+ */
197
+ export interface DotnetDocProgress {
198
+ /**
199
+ * @lang zh-CN 当前处理阶段的提供者标签。
200
+ * @lang en Producer-supplied label for the current processing phase.
201
+ */
202
+ phase: string;
203
+ /**
204
+ * @lang zh-CN 可选当前输入项计数,使用输入项单位。
205
+ * @lang en Optional current count measured in input items.
206
+ */
207
+ current?: number;
208
+ /**
209
+ * @lang zh-CN 可选输入项总数,使用输入项单位。
210
+ * @lang en Optional total count measured in input items.
211
+ */
212
+ total?: number;
213
+ /**
214
+ * @lang zh-CN 可选本地进度说明,公开范围由宿主决定。
215
+ * @lang en Optional local progress prose whose publication scope is determined by the host.
216
+ */
217
+ message?: string;
218
+ }
219
+ /**
220
+ * @lang zh-CN 可选中止只检查已aborted状态,不强杀helper或回滚已写文件。
221
+ * @lang en Optional cancellation checks the aborted state without killing helpers or rolling back written files.
222
+ */
223
+ export interface DotnetDocContext {
224
+ /**
225
+ * @lang zh-CN 可选中止状态引用,运行器按既有检查点读取。
226
+ * @lang en Optional cancellation-state reference read at existing runner checkpoints.
227
+ */
228
+ signal?: {
229
+ /**
230
+ * @lang zh-CN 已中止标志,只读查询不表示强制终止helper。
231
+ * @lang en Aborted flag whose readonly observation does not force helper termination.
232
+ */
233
+ readonly aborted: boolean;
234
+ };
235
+ /**
236
+ * @lang zh-CN 可选宿主进度回调,回调异常可能传播。
237
+ * @lang en Optional host progress callback whose exceptions may propagate.
238
+ */
239
+ reportProgress?: (progress: DotnetDocProgress) => void;
240
+ }
241
+ /**
242
+ * @lang zh-CN 结果文件声明不嵌入内容,path相对输出目录。
243
+ * @lang en Output-file declaration without content; path is relative to the output directory.
244
+ */
245
+ export interface DotnetDocOutputArtifact {
246
+ /**
247
+ * @lang zh-CN 本结果清单中的工件身份。
248
+ * @lang en Artifact identity within this result manifest.
249
+ */
250
+ id: string;
251
+ /**
252
+ * @lang zh-CN 工件类别,消费时仍需选择对应契约。
253
+ * @lang en Artifact kind whose corresponding contract still needs selection during consumption.
254
+ */
255
+ kind: string;
256
+ /**
257
+ * @lang zh-CN 相对于输出目录的文件定位器。
258
+ * @lang en File locator relative to the output directory.
259
+ */
260
+ path: string;
261
+ /**
262
+ * @lang zh-CN 可选序列化格式标签。
263
+ * @lang en Optional serialization-format label.
264
+ */
265
+ format?: string;
266
+ /**
267
+ * @lang zh-CN 可选媒体类型。
268
+ * @lang en Optional media type.
269
+ */
270
+ mediaType?: string;
271
+ /**
272
+ * @lang zh-CN 与工件关联的可选profile身份。
273
+ * @lang en Optional profile identities associated with the artifact.
274
+ */
275
+ profileIds?: string[];
276
+ /**
277
+ * @lang zh-CN 可选工件契约名,须与版本一起解释。
278
+ * @lang en Optional artifact contract name interpreted together with its version.
279
+ */
280
+ contract?: string;
281
+ /**
282
+ * @lang zh-CN 可选工件精确版本,独立于包版本。
283
+ * @lang en Optional exact artifact version, independent of the package version.
284
+ */
285
+ contractVersion?: string;
286
+ }
287
+ /**
288
+ * @lang zh-CN 受控运行诊断;任意metadata仍需宿主逐项公开审查。
289
+ * @lang en Controlled runner diagnostics; arbitrary metadata still requires host publication review.
290
+ */
291
+ export interface DotnetDocDiagnostic {
292
+ /**
293
+ * @lang zh-CN 诊断提供者给出的机器标识。
294
+ * @lang en Machine-readable identity supplied by the diagnostic producer.
295
+ */
296
+ code: string;
297
+ /**
298
+ * @lang zh-CN 诊断说明文本,发布范围仍由宿主控制。
299
+ * @lang en Diagnostic prose whose publication scope remains host-controlled.
300
+ */
301
+ message: string;
302
+ /**
303
+ * @lang zh-CN info、warning或error级别。
304
+ * @lang en Severity of info, warning or error.
305
+ */
306
+ severity: 'info' | 'warning' | 'error';
307
+ /**
308
+ * @lang zh-CN 可选领域来源元数据,精确代码定位需另行核验。
309
+ * @lang en Optional domain provenance requiring separate verification for precise code locations.
310
+ */
311
+ source?: DotnetDocSource;
312
+ /**
313
+ * @lang zh-CN 可扩展诊断记录,消费和发布前需检查具体值。
314
+ * @lang en Extensible diagnostic record whose values need review before consumption or publication.
315
+ */
316
+ metadata?: DotnetDocRecord;
317
+ }
318
+ /**
319
+ * @lang zh-CN SDK1.0.0结果;部分失败保留已成功输出,不自动回滚。
320
+ * @lang en SDK 1.0.0 result; partial failures retain successful outputs without automatic rollback.
321
+ */
322
+ export interface DotnetDocResult {
323
+ /**
324
+ * @lang zh-CN SDK结果契约的固定名称。
325
+ * @lang en Fixed name of the SDK result contract.
326
+ */
327
+ contract: 'documentation-producer-result';
328
+ /**
329
+ * @lang zh-CN SDK结果的精确1.0.0身份。
330
+ * @lang en Exact 1.0.0 identity of the SDK result.
331
+ */
332
+ contractVersion: '1.0.0';
333
+ /**
334
+ * @lang zh-CN 报告本轮输出的生产者身份。
335
+ * @lang en Producer identity reporting this run's output.
336
+ */
337
+ producer: {
338
+ /**
339
+ * @lang zh-CN 生产者的机器身份。
340
+ * @lang en Machine-readable producer identity.
341
+ */
342
+ id: string;
343
+ /**
344
+ * @lang zh-CN 生产者报告的版本,独立于各工件版本。
345
+ * @lang en Producer-reported version, independent of individual artifact versions.
346
+ */
347
+ version: string;
348
+ };
349
+ /**
350
+ * @lang zh-CN 整轮success、partial或failed状态。
351
+ * @lang en Run-level status of success, partial or failed.
352
+ */
353
+ status: 'success' | 'partial' | 'failed';
354
+ /**
355
+ * @lang zh-CN 本轮登记的成功工件,不包含文件正文。
356
+ * @lang en Successful artifacts registered for this run, without file bodies.
357
+ */
358
+ artifacts: DotnetDocOutputArtifact[];
359
+ /**
360
+ * @lang zh-CN 本轮受控诊断列表,具体公开内容由宿主复核。
361
+ * @lang en Controlled run diagnostics whose publication content is reviewed by the host.
362
+ */
363
+ diagnostics: DotnetDocDiagnostic[];
364
+ }
package/src/cli.mjs CHANGED
@@ -1,5 +1,10 @@
1
1
  #!/usr/bin/env node
2
2
 
3
+ /**
4
+ * @file
5
+ * @lang zh-CN .NET文档CLI统一处理参数、配置和执行失败,公开消息不回显私有原值。
6
+ * @lang en The .NET documentation CLI controls argument, configuration and execution failures, keeping private values out of public messages.
7
+ */
3
8
  import path from "node:path";
4
9
  import { parseArgs } from "node:util";
5
10
 
@@ -9,30 +14,35 @@ import {
9
14
  runDotnetDoc
10
15
  } from "./index.mjs";
11
16
 
12
- const { values, positionals } = parseArgs({
13
- options: {
14
- config: { type: "string", short: "c" },
15
- help: { type: "boolean", short: "h" },
16
- "out-dir": { type: "string", short: "o" },
17
- title: { type: "string" },
18
- version: { type: "boolean", short: "v" },
19
- "workspace-root": { type: "string" }
20
- },
21
- allowPositionals: true,
22
- strict: true
23
- });
17
+ try {
18
+ // <lang><zh-CN>参数解析也在受控边界内,未知选项不能逃出成Node堆栈。</zh-CN><en>Argument parsing is inside the controlled boundary so unknown options cannot escape as Node stacks.</en></lang>
19
+ const { values, positionals } = parseArgs({
20
+ options: {
21
+ config: { type: "string", short: "c" },
22
+ help: { type: "boolean", short: "h" },
23
+ "out-dir": { type: "string", short: "o" },
24
+ title: { type: "string" },
25
+ version: { type: "boolean", short: "v" },
26
+ "workspace-root": { type: "string" }
27
+ },
28
+ allowPositionals: true,
29
+ strict: true
30
+ });
24
31
 
25
- if (values.help) {
26
- process.stdout.write(`HIA DotNetDoc ${DOTNETDOC_RUNNER_VERSION}\n\nUsage:\n hia-dotnetdoc --config dotnetdoc.config.json\n hia-dotnetdoc [options] <documentation.xml...>\n\nOptions:\n -c, --config <path>\n -o, --out-dir <path>\n --workspace-root <path>\n --title <title>\n -v, --version\n`);
27
- process.exit(0);
28
- }
32
+ if (values.help) {
33
+ // <lang><zh-CN>两调用名共用规范帮助,真实宽TTY用120列,其余及重定向用80列。</zh-CN><en>Both invocation names share canonical help, using 120 columns on actual wide TTYs and 80 elsewhere and for redirection.</en></lang>
34
+ const help = await import("./command-documentation/help.mjs");
35
+ process.stdout.write(process.stdout.isTTY && process.stdout.columns >= 120
36
+ ? help.DOTNETDOC_HELP_120 : help.DOTNETDOC_HELP_80);
37
+ process.exit(0);
38
+ }
29
39
 
30
- if (values.version) {
31
- process.stdout.write(`${DOTNETDOC_RUNNER_VERSION}\n`);
32
- process.exit(0);
33
- }
40
+ if (values.version) {
41
+ process.stdout.write(`${DOTNETDOC_RUNNER_VERSION}\n`);
42
+ process.exit(0);
43
+ }
34
44
 
35
- try {
45
+ // <lang><zh-CN>仅解析成功后加载配置或建立显式XML请求;路径安全仍由runner裁决。</zh-CN><en>Load config or create explicit XML requests only after successful parsing; the runner still decides path safety.</en></lang>
36
46
  const request = values.config
37
47
  ? await loadDotnetDocConfig(values.config)
38
48
  : createCliRequest(values, positionals);
@@ -41,18 +51,29 @@ try {
41
51
  request.outputDirectory = path.resolve(request.workspaceRoot, values["out-dir"]);
42
52
  }
43
53
 
54
+ // <lang><zh-CN>公开完成摘要只包含受控status与产物数,不序列化底层异常。</zh-CN><en>The public completion summary contains only controlled status and artifact count, never serialized lower-layer errors.</en></lang>
44
55
  const result = await runDotnetDoc(request);
45
56
  process.stdout.write(`DotNetDoc ${result.status}: ${result.artifacts.length} artifact(s).\n`);
46
57
  process.exitCode = result.status === "success" ? 0 : 1;
47
- } catch (error) {
48
- process.stderr.write(`DotNetDoc failed: ${error instanceof Error ? error.message : String(error)}\n`);
58
+ } catch {
59
+ // <lang><zh-CN>异常详情留给显式私有调试,不写公开stderr;请求/文件名/源码均不回显。</zh-CN><en>Exception details require explicit private debugging and never enter public stderr; do not echo request values, filenames or source.</en></lang>
60
+ process.stderr.write('DotNetDoc failed: request or input could not be processed.\n');
49
61
  process.exitCode = 1;
50
62
  }
51
63
 
64
+ /**
65
+ * @lang zh-CN 为位置参数建立既有XML请求;不在解析阶段读取文件或启动helper。
66
+ * @lang en Builds an existing XML request from positionals without file reads or helper execution during parsing.
67
+ * @param {object} cliValues <lang><zh-CN>已由Node parseArgs解析的选项。</zh-CN><en>Options already parsed by Node parseArgs.</en></lang>
68
+ * @param {string[]} inputs <lang><zh-CN>显式XML相对路径列表。</zh-CN><en>Explicit relative XML paths.</en></lang>
69
+ * @returns {object} <lang><zh-CN>工作区内文档请求,实际安全检查仍由runner负责。</zh-CN><en>Documentation request with actual safety checks delegated to the runner.</en></lang>
70
+ * @throws {TypeError} <lang><zh-CN>无输入时拒绝。</zh-CN><en>Rejects missing input.</en></lang>
71
+ */
52
72
  function createCliRequest(cliValues, inputs) {
53
73
  if (inputs.length === 0) {
54
74
  throw new TypeError("At least one XML documentation input or --config is required.");
55
75
  }
76
+ // <lang><zh-CN>命令行cwd只用作显式工作区基址;它不决定包内Roslyn helper的SDK选择。</zh-CN><en>The CLI cwd is only the explicit workspace base and does not select the bundled Roslyn helper's SDK.</en></lang>
56
77
  const workspaceRoot = path.resolve(process.cwd(), cliValues["workspace-root"] ?? ".");
57
78
  return {
58
79
  workspaceRoot,