@hia-doc/cssdoc-runner 0.0.0-stage → 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 +108 -0
- package/LICENSE +21 -0
- package/MIGRATION.md +81 -0
- package/README.md +165 -2
- package/package.json +50 -4
- package/src/cli.mjs +91 -0
- package/src/command-content.mjs +218 -0
- package/src/command-documentation/command.schema.json +1466 -0
- package/src/command-documentation/description.json +1860 -0
- package/src/command-documentation/document.hia.json +2699 -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 +62 -0
- package/src/config-compatibility.mjs +99 -0
- package/src/index.mjs +405 -0
- package/src/metadata.mjs +27 -0
- package/src/schema-legacy.mjs +57 -0
- package/src/schema.mjs +86 -0
- package/src/schemas/cssdoc-config-0.1.0-draft.schema.json +116 -0
- package/src/schemas/cssdoc-config-1.0.0.schema.json +115 -0
|
@@ -0,0 +1,218 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file
|
|
3
|
+
* @lang zh-CN CSSDoc命令的纯双语内容,供静态帮助及开发期core投影共同使用。
|
|
4
|
+
* @lang en Pure bilingual CSSDoc command content shared by static help and development-time core projection.
|
|
5
|
+
*/
|
|
6
|
+
import { CSSDOC_RUNNER_VERSION, CSSDOC_INPUT_KINDS } 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 返回cssdoc真实行为的独立内容图,版本来自运行器元数据,无文件或命令副作用。
|
|
66
|
+
* @lang en Return an independent content graph for actual cssdoc behavior, taking the version from runner metadata without file or command effects.
|
|
67
|
+
* @returns {object} <lang><zh-CN>待开发工具绑定真实来源的命令声明。</zh-CN><en>Command declaration awaiting actual-source binding by development tooling.</en></lang>
|
|
68
|
+
*/
|
|
69
|
+
export function createCssDocCommandContent() {
|
|
70
|
+
return {
|
|
71
|
+
id: "cssdoc",
|
|
72
|
+
executable: "cssdoc",
|
|
73
|
+
path: [],
|
|
74
|
+
kind: "command",
|
|
75
|
+
signature: "cssdoc [options] <input...>",
|
|
76
|
+
i18n: localized({
|
|
77
|
+
summary: [
|
|
78
|
+
"提取CSS与设计令牌文档",
|
|
79
|
+
"Extract CSS and design-token documentation",
|
|
80
|
+
],
|
|
81
|
+
description: [
|
|
82
|
+
"显式配置或直接输入构造运行请求,提取CSS、PostCSS与设计令牌文档。",
|
|
83
|
+
"Build a request from explicit configuration or direct inputs to extract CSS, PostCSS and design-token documentation.",
|
|
84
|
+
],
|
|
85
|
+
configUsage: [
|
|
86
|
+
"cssdoc --config cssdoc.config.json",
|
|
87
|
+
"cssdoc --config cssdoc.config.json",
|
|
88
|
+
],
|
|
89
|
+
configOverrides: [
|
|
90
|
+
"配置模式中,CLI可覆盖out-dir、sources-content-policy及no-doc-source-map。",
|
|
91
|
+
"In config mode CLI can override out-dir, sources-content-policy and no-doc-source-map.",
|
|
92
|
+
],
|
|
93
|
+
directOnly: [
|
|
94
|
+
"kind及workspace-root用于直接模式;配置模式忽略它们和位置输入。",
|
|
95
|
+
"kind and workspace-root apply to direct mode; config mode ignores them and positional inputs.",
|
|
96
|
+
],
|
|
97
|
+
paths: [
|
|
98
|
+
"配置文件相对调用目录,配置工作区相对配置目录;输出相对所选工作区。",
|
|
99
|
+
"Config paths use cwd, configured workspaces use the config directory, and output uses the selected workspace.",
|
|
100
|
+
],
|
|
101
|
+
writes: [
|
|
102
|
+
"运行会创建目录并写工件,失败时可能已写部分文件。embed策略会写入获准公开的源码正文。",
|
|
103
|
+
"Runs create directories and artifacts; failures may leave partial output. The embed policy includes source bodies authorized for publication.",
|
|
104
|
+
],
|
|
105
|
+
parsing: [
|
|
106
|
+
"Node严格解析先于帮助;未知、缺值或类型错误返回1。重复带值选项取最后值,--之后作为位置输入。",
|
|
107
|
+
"Node strict parsing precedes help; unknown, missing or invalid option values exit 1. Repeated value options use the last value, and tokens after -- are positional inputs.",
|
|
108
|
+
],
|
|
109
|
+
offline: [
|
|
110
|
+
"@hia-doc/cssdoc-runner/README.md",
|
|
111
|
+
"@hia-doc/cssdoc-runner/README.md",
|
|
112
|
+
],
|
|
113
|
+
}),
|
|
114
|
+
displayVersion: { kind: "runner", value: CSSDOC_RUNNER_VERSION },
|
|
115
|
+
parsing: {
|
|
116
|
+
helpOrder: "after-argument-validation",
|
|
117
|
+
unknownOptions: "reject",
|
|
118
|
+
},
|
|
119
|
+
options: [
|
|
120
|
+
parameter(
|
|
121
|
+
"config",
|
|
122
|
+
"从JSON配置构造请求。",
|
|
123
|
+
"Build a request from JSON configuration.",
|
|
124
|
+
{
|
|
125
|
+
short: "c",
|
|
126
|
+
metavar: "path",
|
|
127
|
+
defaultRule: { kind: "not-applicable" },
|
|
128
|
+
},
|
|
129
|
+
),
|
|
130
|
+
parameter(
|
|
131
|
+
"kind",
|
|
132
|
+
"直接输入的类型,省略时从输入推断。",
|
|
133
|
+
"Direct-input kind, inferred from input when omitted.",
|
|
134
|
+
{ short: "k", metavar: "kind", choices: [...CSSDOC_INPUT_KINDS] },
|
|
135
|
+
),
|
|
136
|
+
parameter(
|
|
137
|
+
"out-dir",
|
|
138
|
+
"配置模式非空值覆盖输出;直接模式缺省dist/cssdoc,空字符串为工作区根。",
|
|
139
|
+
"Nonempty values override configured output; direct mode defaults to dist/cssdoc, with an empty string selecting the workspace root.",
|
|
140
|
+
{ short: "o", metavar: "path" },
|
|
141
|
+
),
|
|
142
|
+
parameter(
|
|
143
|
+
"workspace-root",
|
|
144
|
+
"直接模式的工作区根,省略时使用调用目录。",
|
|
145
|
+
"Workspace root for direct mode, defaulting to cwd.",
|
|
146
|
+
{ metavar: "path" },
|
|
147
|
+
),
|
|
148
|
+
parameter(
|
|
149
|
+
"sources-content-policy",
|
|
150
|
+
"直接模式缺省none;配置模式省略或空值时保留原值,非空值覆盖。",
|
|
151
|
+
"Direct mode defaults to none; config mode retains its policy for omission or empty strings and uses nonempty overrides.",
|
|
152
|
+
{
|
|
153
|
+
metavar: "none|reference|embed",
|
|
154
|
+
choices: ["none", "reference", "embed"],
|
|
155
|
+
},
|
|
156
|
+
),
|
|
157
|
+
parameter(
|
|
158
|
+
"no-doc-source-map",
|
|
159
|
+
"提供时关闭地图;省略时直接模式生成地图,配置模式保留原值。",
|
|
160
|
+
"Supplying the flag disables maps; omission enables direct-mode maps and retains the configured value.",
|
|
161
|
+
{ valueType: "boolean" },
|
|
162
|
+
),
|
|
163
|
+
parameter("help", "输出帮助并退出0。", "Print help and exit 0.", {
|
|
164
|
+
short: "h",
|
|
165
|
+
valueType: "boolean",
|
|
166
|
+
defaultRule: { kind: "not-applicable" },
|
|
167
|
+
}),
|
|
168
|
+
parameter(
|
|
169
|
+
"version",
|
|
170
|
+
"输出运行器版本并退出0。",
|
|
171
|
+
"Print runner version and exit 0.",
|
|
172
|
+
{
|
|
173
|
+
short: "v",
|
|
174
|
+
valueType: "boolean",
|
|
175
|
+
defaultRule: { kind: "not-applicable" },
|
|
176
|
+
},
|
|
177
|
+
),
|
|
178
|
+
],
|
|
179
|
+
positionals: [
|
|
180
|
+
parameter(
|
|
181
|
+
"positionals",
|
|
182
|
+
"直接模式至少一个相对工作区的输入;配置模式忽略。",
|
|
183
|
+
"Direct mode requires at least one workspace-relative input; config mode ignores positional inputs.",
|
|
184
|
+
{
|
|
185
|
+
kind: "positional",
|
|
186
|
+
metavar: "input...",
|
|
187
|
+
multiple: true,
|
|
188
|
+
defaultRule: { kind: "not-applicable" },
|
|
189
|
+
},
|
|
190
|
+
),
|
|
191
|
+
],
|
|
192
|
+
examples: ["cssdoc --config cssdoc.config.json"],
|
|
193
|
+
effects: { filesystem: "read-write", network: "none" },
|
|
194
|
+
exitCodes: [
|
|
195
|
+
{
|
|
196
|
+
code: 0,
|
|
197
|
+
i18n: localized({
|
|
198
|
+
summary: ["成功、帮助或版本", "Success, help or version"],
|
|
199
|
+
description: ["成功、帮助或版本", "Success, help or version"],
|
|
200
|
+
}),
|
|
201
|
+
},
|
|
202
|
+
{
|
|
203
|
+
code: 1,
|
|
204
|
+
i18n: localized({
|
|
205
|
+
summary: [
|
|
206
|
+
"参数、配置或构建失败",
|
|
207
|
+
"Argument, configuration or build failure",
|
|
208
|
+
],
|
|
209
|
+
description: [
|
|
210
|
+
"参数、配置、partial或failed构建",
|
|
211
|
+
"Argument/configuration errors or partial/failed builds",
|
|
212
|
+
],
|
|
213
|
+
}),
|
|
214
|
+
},
|
|
215
|
+
],
|
|
216
|
+
evidence: [],
|
|
217
|
+
};
|
|
218
|
+
}
|