@hia-doc/dotnetdoc-runner 0.1.12 → 1.0.0-rc.2
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/API.md +96 -0
- package/MIGRATION.md +31 -0
- package/README.md +142 -2
- package/package.json +25 -9
- package/src/api-types.d.mts +364 -0
- package/src/cli.mjs +44 -23
- package/src/command-content.mjs +224 -0
- package/src/command-documentation/command.schema.json +1466 -0
- package/src/command-documentation/description.json +3067 -0
- package/src/command-documentation/document.hia.json +4461 -0
- package/src/command-documentation/document.schema.json +817 -0
- package/src/command-documentation/generation.json +12 -0
- package/src/command-documentation/help.mjs +16 -0
- package/src/command-documentation/observations.json +104 -0
- package/src/config-compatibility.mjs +40 -0
- package/src/doc-source-map.mjs +176 -0
- package/src/index.d.mts +125 -0
- package/src/index.mjs +171 -40
- package/src/metadata-types.d.mts +20 -0
- package/src/metadata.mjs +19 -0
- package/src/schema-legacy.mjs +79 -0
- package/src/schema.mjs +20 -4
- package/src/schemas/dotnetdoc-config-0.1.0-draft.schema.json +284 -0
- package/src/schemas/dotnetdoc-config-1.0.0.schema.json +283 -0
- package/src/source-locations.mjs +7 -5
|
@@ -0,0 +1,224 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file
|
|
3
|
+
* @lang zh-CN DotNetDoc命令的纯双语内容,供静态帮助及开发期core投影共同使用。
|
|
4
|
+
* @lang en Pure bilingual DotNetDoc command content shared by static help and development-time core projection.
|
|
5
|
+
*/
|
|
6
|
+
import { DOTNETDOC_RUNNER_VERSION } from "./metadata.mjs";
|
|
7
|
+
|
|
8
|
+
/** @lang zh-CN 创建独立的原生字段语言模型,键名及两语正文精确保留。
|
|
9
|
+
* @lang en Create an independent native field locale model retaining exact keys and both localized texts.
|
|
10
|
+
* @param {object} fields <lang><zh-CN>中文/英文文本对。</zh-CN><en>Chinese/English text pairs.</en></lang>
|
|
11
|
+
* @returns {object} <lang><zh-CN>1.0.0字段语言模型。</zh-CN><en>A 1.0.0 field locale model.</en></lang>
|
|
12
|
+
*/
|
|
13
|
+
function localized(fields) {
|
|
14
|
+
return {
|
|
15
|
+
enabled: true,
|
|
16
|
+
model: "hia-text-i18n",
|
|
17
|
+
modelVersion: "1.0.0",
|
|
18
|
+
defaultLocale: "zh-CN",
|
|
19
|
+
locales: ["zh-CN", "en"],
|
|
20
|
+
fields: Object.fromEntries(
|
|
21
|
+
Object.entries(fields).map(([key, value]) => [
|
|
22
|
+
key,
|
|
23
|
+
{
|
|
24
|
+
fieldPath: key,
|
|
25
|
+
kind: "text",
|
|
26
|
+
defaultLocale: "zh-CN",
|
|
27
|
+
localizedText: { "zh-CN": value[0], en: value[1] },
|
|
28
|
+
},
|
|
29
|
+
]),
|
|
30
|
+
),
|
|
31
|
+
};
|
|
32
|
+
}
|
|
33
|
+
|
|
34
|
+
/** @lang zh-CN 构造参数内容;其名称/类型/短名另由真实parseArgs调用观察。
|
|
35
|
+
* @lang en Construct parameter content, with names, types and short names independently observed from the actual parseArgs call.
|
|
36
|
+
* @param {string} name <lang><zh-CN>原生参数名。</zh-CN><en>Native parameter name.</en></lang>
|
|
37
|
+
* @param {string} zh <lang><zh-CN>中文说明。</zh-CN><en>Chinese description.</en></lang>
|
|
38
|
+
* @param {string} en <lang><zh-CN>英文说明。</zh-CN><en>English description.</en></lang>
|
|
39
|
+
* @param {object} settings <lang><zh-CN>原生类型、短名、显示槽及默认规则。</zh-CN><en>Native type, short name, display slot and default rule.</en></lang>
|
|
40
|
+
* @returns {object} <lang><zh-CN>带未绑定来源的参数内容。</zh-CN><en>Parameter content awaiting provenance binding.</en></lang>
|
|
41
|
+
*/
|
|
42
|
+
function parameter(name, zh, en, settings = {}) {
|
|
43
|
+
// <lang><zh-CN>显示槽属于文案,位置参数名保留Node原生positionals身份。</zh-CN><en>The displayed slot is prose, while positional names retain Node's native positionals identity.</en></lang>
|
|
44
|
+
const fields = { summary: [zh, en], description: [zh, en] };
|
|
45
|
+
if (settings.metavar) fields.metavar = [settings.metavar, settings.metavar];
|
|
46
|
+
return {
|
|
47
|
+
id: name,
|
|
48
|
+
kind: settings.kind ?? "option",
|
|
49
|
+
name,
|
|
50
|
+
...(settings.short ? { short: settings.short } : {}),
|
|
51
|
+
valueType: settings.valueType ?? "string",
|
|
52
|
+
required: false,
|
|
53
|
+
multiple: settings.multiple ?? false,
|
|
54
|
+
...(settings.choices ? { choices: settings.choices } : {}),
|
|
55
|
+
defaultRule: settings.defaultRule ?? {
|
|
56
|
+
kind: "conditional",
|
|
57
|
+
conditions: ["description"],
|
|
58
|
+
},
|
|
59
|
+
i18n: localized(fields),
|
|
60
|
+
evidence: [],
|
|
61
|
+
};
|
|
62
|
+
}
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* @lang zh-CN 返回两个包内调用名的独立内容图,规范入口和别名使用既有aliasOf关系。
|
|
66
|
+
* @lang en Return independent content graphs for both packaged invocation names, joining the canonical entry and alias with existing aliasOf semantics.
|
|
67
|
+
* @returns {object[]} <lang><zh-CN>规范入口及其别名,无IO或执行副作用。</zh-CN><en>The canonical entry and its alias without IO or execution effects.</en></lang>
|
|
68
|
+
*/
|
|
69
|
+
export function createDotnetDocCommands() {
|
|
70
|
+
// <lang><zh-CN>规范入口完整陈述现有六开关与条件XML输入,版本取真实纯元数据。</zh-CN><en>The canonical entry describes all six existing switches and conditional XML inputs, taking its version from actual pure metadata.</en></lang>
|
|
71
|
+
const command = {
|
|
72
|
+
id: "hia-dotnetdoc",
|
|
73
|
+
executable: "hia-dotnetdoc",
|
|
74
|
+
path: [],
|
|
75
|
+
kind: "command",
|
|
76
|
+
signature: "hia-dotnetdoc [options] <documentation.xml...>",
|
|
77
|
+
i18n: localized({
|
|
78
|
+
summary: [
|
|
79
|
+
"生成.NET XML及配置驱动文档",
|
|
80
|
+
"Generate .NET XML and configuration-driven documentation",
|
|
81
|
+
],
|
|
82
|
+
description: [
|
|
83
|
+
"从显式XML输入或JSON配置生成.NET文档工件及结果清单。",
|
|
84
|
+
"Generate .NET documentation artifacts and a result manifest from explicit XML inputs or JSON configuration.",
|
|
85
|
+
],
|
|
86
|
+
configUsage: [
|
|
87
|
+
"hia-dotnetdoc --config dotnetdoc.config.json",
|
|
88
|
+
"hia-dotnetdoc --config dotnetdoc.config.json",
|
|
89
|
+
],
|
|
90
|
+
aliases: [
|
|
91
|
+
"dotnetdoc与hia-dotnetdoc是同一实现的等价调用名,帮助展示规范入口。",
|
|
92
|
+
"dotnetdoc and hia-dotnetdoc are equivalent names for one implementation; help displays the canonical entry.",
|
|
93
|
+
],
|
|
94
|
+
configOverrides: [
|
|
95
|
+
"配置模式仅非空out-dir覆盖输出;空字符串保留配置。",
|
|
96
|
+
"In config mode only a nonempty out-dir overrides output; an empty string retains the configuration.",
|
|
97
|
+
],
|
|
98
|
+
directOnly: [
|
|
99
|
+
"workspace-root、title及XML位置输入仅用于直接模式,配置模式忽略。",
|
|
100
|
+
"workspace-root, title and positional XML inputs apply only to direct mode and are ignored in config mode.",
|
|
101
|
+
],
|
|
102
|
+
paths: [
|
|
103
|
+
"配置路径相对调用目录,配置工作区相对配置目录;直接工作区相对调用目录,输出相对工作区。",
|
|
104
|
+
"Config paths use cwd and configured workspaces use the config directory; direct workspaces use cwd and output uses the workspace.",
|
|
105
|
+
],
|
|
106
|
+
writes: [
|
|
107
|
+
"运行会创建目录、覆盖工件并写结果清单;partial或failed可能保留已成功写入。",
|
|
108
|
+
"Runs create directories, replace artifacts and write a result manifest; partial or failed results may retain successful writes.",
|
|
109
|
+
],
|
|
110
|
+
parsing: [
|
|
111
|
+
"Node严格解析先于帮助,未知开关或缺值返回1;重复带值选项取末值,--后作为XML位置输入。",
|
|
112
|
+
"Node strict parsing precedes help; unknown switches or missing values exit 1. Repeated value options use the last value, and tokens after -- are positional XML inputs.",
|
|
113
|
+
],
|
|
114
|
+
prerequisites: [
|
|
115
|
+
"纯XML抽取无需SDK。配置中的C#抽取或项目源码解析使用.NET10 SDK/helper,其构建可能按SDK设置进行还原及工作负载清单下载。",
|
|
116
|
+
"Plain XML extraction needs no SDK. Configured C# extraction or project source resolution uses the .NET 10 SDK/helper; its build may restore dependencies or download workload manifests according to SDK settings.",
|
|
117
|
+
],
|
|
118
|
+
offline: [
|
|
119
|
+
"@hia-doc/dotnetdoc-runner/README.md",
|
|
120
|
+
"@hia-doc/dotnetdoc-runner/README.md",
|
|
121
|
+
],
|
|
122
|
+
}),
|
|
123
|
+
displayVersion: { kind: "runner", value: DOTNETDOC_RUNNER_VERSION },
|
|
124
|
+
parsing: {
|
|
125
|
+
helpOrder: "after-argument-validation",
|
|
126
|
+
unknownOptions: "reject",
|
|
127
|
+
},
|
|
128
|
+
options: [
|
|
129
|
+
parameter(
|
|
130
|
+
"config",
|
|
131
|
+
"从JSON配置构造请求。",
|
|
132
|
+
"Build a request from JSON configuration.",
|
|
133
|
+
{
|
|
134
|
+
short: "c",
|
|
135
|
+
metavar: "path",
|
|
136
|
+
defaultRule: { kind: "not-applicable" },
|
|
137
|
+
},
|
|
138
|
+
),
|
|
139
|
+
parameter(
|
|
140
|
+
"out-dir",
|
|
141
|
+
"输出相对工作区,直接模式缺省dist/dotnetdoc;直接空字符串指向工作区根。",
|
|
142
|
+
"Output is workspace-relative and defaults to dist/dotnetdoc in direct mode; an empty direct-mode string selects the workspace root.",
|
|
143
|
+
{ short: "o", metavar: "path" },
|
|
144
|
+
),
|
|
145
|
+
parameter(
|
|
146
|
+
"workspace-root",
|
|
147
|
+
"直接模式相对调用目录,省略时为当前目录;配置模式忽略。",
|
|
148
|
+
"Direct mode resolves from cwd and defaults to cwd; ignored in config mode.",
|
|
149
|
+
{ metavar: "path" },
|
|
150
|
+
),
|
|
151
|
+
parameter(
|
|
152
|
+
"title",
|
|
153
|
+
"仅直接模式,为每个XML输入提供同一标题;省略时沿适配器默认,配置模式忽略。",
|
|
154
|
+
"Direct mode only, giving every XML input the same title; omission uses adapter defaults and config mode ignores it.",
|
|
155
|
+
{ metavar: "title" },
|
|
156
|
+
),
|
|
157
|
+
parameter("help", "输出帮助并退出0。", "Print help and exit 0.", {
|
|
158
|
+
short: "h",
|
|
159
|
+
valueType: "boolean",
|
|
160
|
+
defaultRule: { kind: "not-applicable" },
|
|
161
|
+
}),
|
|
162
|
+
parameter(
|
|
163
|
+
"version",
|
|
164
|
+
"输出运行器版本并退出0。",
|
|
165
|
+
"Print runner version and exit 0.",
|
|
166
|
+
{
|
|
167
|
+
short: "v",
|
|
168
|
+
valueType: "boolean",
|
|
169
|
+
defaultRule: { kind: "not-applicable" },
|
|
170
|
+
},
|
|
171
|
+
),
|
|
172
|
+
],
|
|
173
|
+
positionals: [
|
|
174
|
+
parameter(
|
|
175
|
+
"positionals",
|
|
176
|
+
"直接模式至少一个相对工作区的XML输入;配置模式忽略。",
|
|
177
|
+
"Direct mode requires at least one workspace-relative XML input; ignored in config mode.",
|
|
178
|
+
{
|
|
179
|
+
kind: "positional",
|
|
180
|
+
metavar: "documentation.xml...",
|
|
181
|
+
multiple: true,
|
|
182
|
+
defaultRule: { kind: "not-applicable" },
|
|
183
|
+
},
|
|
184
|
+
),
|
|
185
|
+
],
|
|
186
|
+
examples: [
|
|
187
|
+
"hia-dotnetdoc --config dotnetdoc.config.json",
|
|
188
|
+
"dotnetdoc --title SampleAPI sample.xml",
|
|
189
|
+
],
|
|
190
|
+
effects: { filesystem: "read-write", network: "explicit" },
|
|
191
|
+
exitCodes: [
|
|
192
|
+
{
|
|
193
|
+
code: 0,
|
|
194
|
+
i18n: localized({
|
|
195
|
+
summary: ["成功、帮助或版本", "Success, help or version"],
|
|
196
|
+
description: ["成功、帮助或版本", "Success, help or version"],
|
|
197
|
+
}),
|
|
198
|
+
},
|
|
199
|
+
{
|
|
200
|
+
code: 1,
|
|
201
|
+
i18n: localized({
|
|
202
|
+
summary: [
|
|
203
|
+
"参数、配置或构建失败",
|
|
204
|
+
"Argument, configuration or build failure",
|
|
205
|
+
],
|
|
206
|
+
description: [
|
|
207
|
+
"参数/配置错误或partial/failed构建",
|
|
208
|
+
"Argument/configuration errors or partial/failed builds",
|
|
209
|
+
],
|
|
210
|
+
}),
|
|
211
|
+
},
|
|
212
|
+
],
|
|
213
|
+
evidence: [],
|
|
214
|
+
};
|
|
215
|
+
// <lang><zh-CN>复制完整别名图,保留独立节点身份和规范入口的帮助正文。</zh-CN><en>Copy the complete alias graph, retaining independent node identities and the canonical entry's help prose.</en></lang>
|
|
216
|
+
const alias = structuredClone(command);
|
|
217
|
+
alias.id = "dotnetdoc";
|
|
218
|
+
alias.executable = "dotnetdoc";
|
|
219
|
+
alias.aliasOf = command.id;
|
|
220
|
+
alias.signature = "dotnetdoc [options] <documentation.xml...>";
|
|
221
|
+
for (const item of [...alias.options, ...alias.positionals])
|
|
222
|
+
item.id = alias.id + "." + item.name;
|
|
223
|
+
return [command, alias];
|
|
224
|
+
}
|