@hia-doc/jsdoc-spec 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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 HIA
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/MIGRATION.md ADDED
@@ -0,0 +1,50 @@
1
+ # Moving to the 1.0.0 source candidates
2
+
3
+ 中文摘要:八个umbrella包及独立插件/主题均协调为1.0.0源码候选,公开runtime依赖精确1.0.0。源码开发根保持private,使用固定Git提交的file tarball开发依赖与冻结锁;公开消费者无需这套准备。实际npm发布、站点/视觉验收及目标采用分别核验。
4
+
5
+ ## Versions and previous inputs
6
+
7
+ Package versions, runner/producer tool versions and plugin/theme dependency
8
+ metadata now identify 1.0.0. Published 0.x archives remain unchanged. Root imports,
9
+ staged producer, two schema JSON subpaths and hia-jsdoc CLI remain available.
10
+ Previously private child packages are now public-package source candidates with
11
+ explicit package files, MIT license and public access metadata; the workspace
12
+ root remains private and is not a distribution package.
13
+
14
+ Config/umbrella use 1.0.0, with exact old 0.1.0-draft reading and explicit
15
+ migrateHiaJsdocConfig. Migration creates a detached object or refuses data loss;
16
+ it does not rewrite files. Integration and page-map retain their exact 0.1.0
17
+ compatibility profiles, documentation source maps remain 1.1.0, and shared
18
+ producer/presentation/UI-locale identities remain 1.0.0. Never relabel old wire
19
+ objects solely to match the package version.
20
+
21
+ Project execution enforces effective output boundaries, declared input types,
22
+ unique profile IDs and public failure summaries. Rejected plugin-path diagnostics
23
+ omit the original path; hook summaries omit thrown messages while explicit local
24
+ throwOnError preserves the original value. Code parsing those old raw diagnostic
25
+ suffixes must use stable codes and admitted metadata instead. Empty output cannot
26
+ be SDK success; staged copying excludes new private runtime configs and remains
27
+ additive. Trusted plugin execution/raw local errors are not sandboxed or
28
+ automatically safe for publication.
29
+
30
+ See package README references for complete names/defaults/errors/effects and the
31
+ public [API inventory](https://github.com/mandolin/hia-jsdoc/blob/main/API.md).
32
+ Use Node.js ^22.23.4 or ^24.22.1 with tested JSDoc 4.0.5. Earlier runtime versions
33
+ and future upstream parser versions are not inferred compatible.
34
+
35
+ ## Frozen source development before registry publication
36
+
37
+ Place this source checkout beside jsdoc-plugin-hia-sys and jsdoc-theme-hia at the
38
+ exact commits in owner-sources.json. Run `npm run prepare:owners`, then `npm ci`.
39
+ Preparation uses existing Git/tar/local npm, disables lifecycle scripts, and
40
+ writes only ignored .owner-packages in this repository. It checks exact origin,
41
+ HEAD, package identity and prelocked SHA/SRI. It never fetches/checks out owners,
42
+ rewrites their manifests or fixes the lock silently. Wrong checkouts and corrupt
43
+ caches are rejected. The two exact HTTPS origin forms with/without .git work.
44
+
45
+ Only this private development root uses file-tarball devDependencies. All shipped
46
+ first-party runtime edges are exact ordinary 1.0.0 dependencies. Original candidate
47
+ tarballs can be consumed together without editing their manifests. Until actual
48
+ publication is verified, do not assume npm registry installation of 1.0.0 exists.
49
+ Publishing/provenance, dist-tags and a clean site deployment remain separate
50
+ release decisions; source qualification does not perform them.
package/README.md CHANGED
@@ -1,3 +1,81 @@
1
- # Temporary Holding Version
1
+ # JSDoc Spec
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ ## Supported runtime
4
+
5
+ Current source supports Node.js `^22.23.4 || ^24.22.1`. Release checks use
6
+ Node.js 22.23.4 and 24.22.1 on Windows and Ubuntu; actual package qualification
7
+ and npm availability remain separate. The repository default is Node.js 24.22.1.
8
+
9
+ 中文:当前源码运行范围为上述两条已确认版本线,CI/安装验收与实际npm发布分别核对。
10
+
11
+
12
+ Defines HIA JSDoc usage, configuration and compatibility rules.
13
+
14
+ The current umbrella configuration identity is `hia-jsdoc-umbrella-config@1.0.0`.
15
+ `createHiaJsdocVersionSummary()` and new preset metadata use this identity; their
16
+ plugin/theme numbers describe the exact 1.0.0 candidate dependencies, with registry publication verified separately.
17
+ `readHiaJsdocUmbrellaConfig(metadata)` admits only exact `1.0.0` and
18
+ `0.1.0-draft`, returning the original object and version. Invalid/missing identities
19
+ throw a fixed `TypeError`. This helper checks **identity only**, without validating
20
+ nested payloads, migrating them or authorizing execution. It does not select
21
+ versions through a SemVer range.
22
+
23
+ Integration `hia-jsdoc-integration@0.1.0` and page-map
24
+ `jsdoc-theme-hia/page-map@0.1.0` remain required compatibility profiles. Their wire
25
+ versions are independent of package and umbrella versions. Future incompatible
26
+ wire changes require a new wire identity; a tool package reaching 1.0.0 does not
27
+ relabel saved artifacts. Source-map 1.1.0 and presentation/UI-locale 1.0.0 keep
28
+ their existing readers and validation boundaries.
29
+
30
+ 中文:umbrella当前1.0.0,旧元数据精确身份读取保持原对象;仅身份检查不代表内容或权限验证。Integration与页映射保留0.1.0并纳入正式兼容责任,不能借0.x标签排除保证,亦不凭包版本改写工件。
31
+
32
+ `createHiaJsdocPortalUiLocaleBridge()` exposes the metadata-only Portal adoption descriptor for
33
+ `documentation-ui-locale-completeness@1.0.0`. The descriptor delegates message catalogs, runtime behavior, HTML/CSS and report generation to
34
+ `@hia-doc/renderer-html`; it contains no translations or target-project identity.
35
+
36
+ Historical `0.1.0-draft` report reading remains with the shared owner; this
37
+ bridge does not relabel or rebuild reports.
38
+ 中文:桥接声明当前1.0.0能力,旧报告由共享owner精确读取,不换号伪造迁移。
39
+
40
+ ## Complete public API
41
+
42
+ | Export | Meaning/default |
43
+ | --- | --- |
44
+ | `HIA_JSDOC_UMBRELLA_CONTRACT` | hia-jsdoc-umbrella-config identity. |
45
+ | `HIA_JSDOC_UMBRELLA_CONTRACT_VERSION` | Current 1.0.0. |
46
+ | `HIA_JSDOC_PLUGIN_PACKAGE` | @mandolin/jsdoc-plugin-hia-sys. |
47
+ | `HIA_JSDOC_PLUGIN_VERSION` | Exact candidate dependency 1.0.0; registry publication verified separately. |
48
+ | `HIA_JSDOC_PLUGIN_PATH` | node_modules/@mandolin/jsdoc-plugin-hia-sys/src/index.cjs. |
49
+ | `HIA_JSDOC_THEME_PACKAGE` | @mandolin/jsdoc-theme-hia. |
50
+ | `HIA_JSDOC_THEME_VERSION` | Exact candidate dependency 1.0.0. |
51
+ | `HIA_JSDOC_THEME_TEMPLATE` | node_modules/@mandolin/jsdoc-theme-hia. |
52
+ | `HIA_JSDOC_PRESENTATION_PROFILE_CONTRACT` | documentation-presentation-profile. |
53
+ | `HIA_JSDOC_PRESENTATION_PROFILE_CONTRACT_VERSION` | Current 1.0.0. |
54
+ | `HIA_JSDOC_PORTAL_UI_LOCALE_CAPABILITY` | documentation-ui-locale-completeness. |
55
+ | `HIA_JSDOC_PORTAL_UI_LOCALE_CAPABILITY_VERSION` | Current 1.0.0. |
56
+ | `HIA_JSDOC_PORTAL_UI_LOCALE_PROFILE_ID` | hia-jsdoc.portal-bridge. |
57
+ | `HIA_JSDOC_PORTAL_UI_LOCALE_REPORT_PATH` | documentation-ui-locale-completeness.json. |
58
+ | `JSDOC_PACKAGE` | jsdoc. |
59
+ | `JSDOC_VERSION` | Tested 4.0.5; no blanket guarantee for future 4.x. |
60
+ | `HIA_JSDOC_OUTPUT_MODES` | Frozen standalone/hiaIntegration/both array. |
61
+ | `HIA_JSDOC_EXTRA_PLUGIN_PHASES` | Frozen before/after array. |
62
+ | `normalizeHiaJsdocMode` | mode defaults both; returns admitted mode or throws Error for unknown values. Trusted local error text includes the supplied mode. |
63
+ | `createHiaJsdocVersionSummary` | No arguments; new umbrella/dependency metadata object. No registry lookup. |
64
+ | `createHiaJsdocPortalUiLocaleBridge` | No arguments; new metadata-only capability descriptor for renderer-html, two UI locales and interactive/no-script surfaces. Not a report or copied catalog. |
65
+ | `readHiaJsdocUmbrellaConfig` | Exact identity-only reader described above, no nested payload validation or implicit migration. |
66
+
67
+ **Errors:** mode normalization and the identity reader reject unsupported input;
68
+ other constants/builders do not validate existence, availability or source consent.
69
+ Use the project input boundary before publishing errors from trusted local helpers.
70
+
71
+ **Side effects:** no filesystem/network reads, installation, plugin execution or
72
+ rendering. Constants and version summaries do not prove npm publication, map
73
+ precision, site availability or UI acceptance.
74
+
75
+ 中文:二十二个导出按真实责任列明;默认依赖摘要仍为manifest已声明边,不能把源码/契约1.0.0当作npm已发布。
76
+
77
+ ## Package candidate and migration
78
+
79
+ Current source package identity is 1.0.0, with exact matching first-party runtime dependencies and public access metadata. See the shipped [migration guide](MIGRATION.md). Actual npm publication is verified separately; do not assume an unpublished registry version is available.
80
+
81
+ 中文:当前包为1.0.0源码候选,永久依赖与版本元数据协调;实际发布另验,旧wire不改号。
package/package.json CHANGED
@@ -1,6 +1,32 @@
1
1
  {
2
2
  "name": "@hia-doc/jsdoc-spec",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0-rc.2",
4
+ "private": false,
5
+ "description": "JSDoc usage, configuration and compatibility rules for HIA.",
6
+ "license": "MIT",
7
+ "type": "module",
8
+ "exports": {
9
+ ".": "./src/index.mjs"
10
+ },
11
+ "engines": {
12
+ "node": "^22.23.4 || ^24.22.1"
13
+ },
14
+ "publishConfig": {
15
+ "access": "public"
16
+ },
17
+ "repository": {
18
+ "directory": "packages/jsdoc-spec",
19
+ "type": "git",
20
+ "url": "git+https://github.com/mandolin/hia-jsdoc.git"
21
+ },
22
+ "homepage": "https://github.com/mandolin/hia-jsdoc/tree/main/packages/jsdoc-spec",
23
+ "bugs": {
24
+ "url": "https://github.com/mandolin/hia-jsdoc/issues"
25
+ },
26
+ "files": [
27
+ "src",
28
+ "README.md",
29
+ "MIGRATION.md",
30
+ "LICENSE"
31
+ ]
32
+ }
package/src/index.mjs ADDED
@@ -0,0 +1,241 @@
1
+ /**
2
+ * Identifies the umbrella configuration contract emitted by the HIA JSDoc preset.
3
+ *
4
+ * @constant {string}
5
+ * @lang zh-CN 标识 HIA JSDoc preset 输出的 umbrella 配置合同。
6
+ * @lang en Identifies the umbrella configuration contract emitted by the HIA JSDoc preset.
7
+ */
8
+ export const HIA_JSDOC_UMBRELLA_CONTRACT = "hia-jsdoc-umbrella-config";
9
+
10
+ /**
11
+ * Declares the current version of the HIA JSDoc umbrella configuration contract.
12
+ *
13
+ * @constant {string}
14
+ * @lang zh-CN 声明当前umbrella1.0.0;Integration/页映射保持精确0.1.0 profile。
15
+ * @lang en Declares current umbrella 1.0.0; Integration/page maps retain exact 0.1.0 profiles.
16
+ */
17
+ export const HIA_JSDOC_UMBRELLA_CONTRACT_VERSION = "1.0.0";
18
+
19
+ /**
20
+ * @lang zh-CN 精确读取新旧umbrella身份并返回原对象;仅验身份,不替代插件/主题/SDK内容校验或执行许可。
21
+ * @lang en Reads exact current/legacy umbrella identity and returns the original object; identity-only checking does not replace plugin/theme/SDK content validation or execution permission.
22
+ * @param {object} metadata <lang><zh-CN>已解析元数据,不自动迁移嵌套对象。</zh-CN><en>Parsed metadata; nested objects are not automatically migrated.</en></lang>
23
+ * @returns {object} <lang><zh-CN>原对象、原身份,无副作用。</zh-CN><en>Original object and identity, without side effects.</en></lang>
24
+ * @throws {TypeError} <lang><zh-CN>未知或缺失身份,不回显输入。</zh-CN><en>Unknown or missing identity, without echoing input.</en></lang>
25
+ */
26
+ export function readHiaJsdocUmbrellaConfig(metadata) {
27
+ if (!metadata || typeof metadata !== "object" || Array.isArray(metadata)
28
+ || metadata.contract !== HIA_JSDOC_UMBRELLA_CONTRACT
29
+ || !["0.1.0-draft", HIA_JSDOC_UMBRELLA_CONTRACT_VERSION].includes(metadata.contractVersion)) {
30
+ throw new TypeError("Unsupported HIA JSDoc umbrella configuration identity.");
31
+ }
32
+ return metadata;
33
+ }
34
+
35
+ /**
36
+ * Names the published HIA JSDoc plugin package consumed by the umbrella preset.
37
+ *
38
+ * @constant {string}
39
+ * @lang zh-CN 记录 umbrella preset 消费的已发布 HIA JSDoc 插件包名。
40
+ * @lang en Names the published HIA JSDoc plugin package consumed by the umbrella preset.
41
+ */
42
+ export const HIA_JSDOC_PLUGIN_PACKAGE = "@mandolin/jsdoc-plugin-hia-sys";
43
+
44
+ /**
45
+ * Pins the candidate HIA JSDoc plugin dependency version used by this compatibility layer.
46
+ *
47
+ * @constant {string}
48
+ * @lang zh-CN 固定当前兼容层的精确插件候选依赖;不证明该版本已在npm发布。
49
+ * @lang en Pins the exact plugin candidate dependency without proving npm publication.
50
+ */
51
+ export const HIA_JSDOC_PLUGIN_VERSION = "1.0.0";
52
+
53
+ /**
54
+ * Points JSDoc config generation at the local plugin entry resolved from dependencies.
55
+ *
56
+ * @constant {string}
57
+ * @lang zh-CN 指向从依赖中解析出的本地插件入口,用于生成 JSDoc 配置。
58
+ * @lang en Points JSDoc config generation at the local plugin entry resolved from dependencies.
59
+ */
60
+ export const HIA_JSDOC_PLUGIN_PATH = "node_modules/@mandolin/jsdoc-plugin-hia-sys/src/index.cjs";
61
+
62
+ /**
63
+ * Names the published HIA JSDoc theme package consumed by the umbrella preset.
64
+ *
65
+ * @constant {string}
66
+ * @lang zh-CN 记录 umbrella preset 消费的已发布 HIA JSDoc 主题包名。
67
+ * @lang en Names the published HIA JSDoc theme package consumed by the umbrella preset.
68
+ */
69
+ export const HIA_JSDOC_THEME_PACKAGE = "@mandolin/jsdoc-theme-hia";
70
+
71
+ /**
72
+ * Pins the candidate HIA JSDoc theme dependency version used by this compatibility layer.
73
+ *
74
+ * @constant {string}
75
+ * @lang zh-CN 固定当前兼容层的精确主题候选依赖;可用性由实际发行另验。
76
+ * @lang en Pins the exact theme candidate dependency; availability requires separate publication verification.
77
+ */
78
+ export const HIA_JSDOC_THEME_VERSION = "1.0.0";
79
+
80
+ /**
81
+ * Points JSDoc config generation at the theme template resolved from dependencies.
82
+ *
83
+ * @constant {string}
84
+ * @lang zh-CN 指向从依赖中解析出的主题模板路径,用于生成 JSDoc 配置。
85
+ * @lang en Points JSDoc config generation at the theme template resolved from dependencies.
86
+ */
87
+ export const HIA_JSDOC_THEME_TEMPLATE = "node_modules/@mandolin/jsdoc-theme-hia";
88
+
89
+ /**
90
+ * Identifies the renderer-neutral presentation profile adopted by the HIA JSDoc owner chain.
91
+ *
92
+ * @constant {string}
93
+ * @lang zh-CN 标识 HIA JSDoc owner chain 采用的 renderer-neutral presentation profile。
94
+ * @lang en Identifies the renderer-neutral presentation profile adopted by the HIA JSDoc owner chain.
95
+ */
96
+ export const HIA_JSDOC_PRESENTATION_PROFILE_CONTRACT = "documentation-presentation-profile";
97
+
98
+ /**
99
+ * Pins the exact current presentation profile version consumed by the HIA JSDoc bridge.
100
+ *
101
+ * @constant {string}
102
+ * @lang zh-CN 固定HIA JSDoc bridge当前写者1.0.0身份;旧工件另由精确历史reader读取。
103
+ * @lang en Pins the HIA JSDoc bridge's current writer identity 1.0.0; legacy artifacts use their exact historical reader separately.
104
+ */
105
+ export const HIA_JSDOC_PRESENTATION_PROFILE_CONTRACT_VERSION = "1.0.0";
106
+
107
+ /**
108
+ * Identifies the neutral UI-locale completeness capability consumed by the Portal bridge.
109
+ *
110
+ * @constant {string}
111
+ * @lang zh-CN 标识 hia-jsdoc Portal bridge 消费的中性 UI-locale 完整性能力;它不是新的 report contract。
112
+ * @lang en Identifies the neutral UI-locale completeness capability consumed by the hia-jsdoc Portal bridge; it is not a new report contract.
113
+ */
114
+ export const HIA_JSDOC_PORTAL_UI_LOCALE_CAPABILITY = "documentation-ui-locale-completeness";
115
+
116
+ /**
117
+ * Pins the current Portal writer capability to 1.0.0; the owner still reads exact historical 0.1.0-draft reports.
118
+ *
119
+ * @constant {string}
120
+ * @lang zh-CN 固定当前Portal写者的1.0.0能力;历史0.1.0-draft报告仍由owner精确读取。
121
+ * @lang en Pins the current Portal writer capability to 1.0.0; the owner still reads exact historical 0.1.0-draft reports.
122
+ */
123
+ export const HIA_JSDOC_PORTAL_UI_LOCALE_CAPABILITY_VERSION = "1.0.0";
124
+
125
+ /**
126
+ * Names the owner-neutral profile and surface used by hia-jsdoc Portal projection.
127
+ *
128
+ * @constant {string}
129
+ * @lang zh-CN 为 hia-jsdoc Portal 投影提供稳定且不含目标仓身份的 profile/surface ID。
130
+ * @lang en Provides the stable target-free profile/surface ID for hia-jsdoc Portal projection.
131
+ */
132
+ export const HIA_JSDOC_PORTAL_UI_LOCALE_PROFILE_ID = "hia-jsdoc.portal-bridge";
133
+
134
+ /**
135
+ * Declares the body-free report path emitted by the Portal owner.
136
+ *
137
+ * @constant {string}
138
+ * @lang zh-CN 声明由 Portal owner 生成的无正文完整性报告路径。
139
+ * @lang en Declares the body-free completeness-report path emitted by the Portal owner.
140
+ */
141
+ export const HIA_JSDOC_PORTAL_UI_LOCALE_REPORT_PATH = "documentation-ui-locale-completeness.json";
142
+
143
+ /**
144
+ * Creates the owner-neutral UI-locale capability descriptor embedded by the umbrella preset.
145
+ *
146
+ * @returns {object} <lang><zh-CN>仅含 capability、owner、surface、coverage 与 privacy metadata 的新 descriptor。</zh-CN><en>A fresh descriptor containing capability, owner, surface, coverage, and privacy metadata only.</en></lang>
147
+ * @lang zh-CN 创建 umbrella preset 嵌入的 owner-neutral UI-locale capability descriptor;不携带译文、DOM、CSS 或目标身份。
148
+ * @lang en Creates the owner-neutral UI-locale capability descriptor embedded by the umbrella preset; it carries no translations, DOM, CSS, or target identity.
149
+ */
150
+ export function createHiaJsdocPortalUiLocaleBridge() {
151
+ return {
152
+ capability: HIA_JSDOC_PORTAL_UI_LOCALE_CAPABILITY,
153
+ capabilityVersion: HIA_JSDOC_PORTAL_UI_LOCALE_CAPABILITY_VERSION,
154
+ ownerPackage: "@hia-doc/renderer-html",
155
+ profileId: HIA_JSDOC_PORTAL_UI_LOCALE_PROFILE_ID,
156
+ surfaceId: HIA_JSDOC_PORTAL_UI_LOCALE_PROFILE_ID,
157
+ reportPath: HIA_JSDOC_PORTAL_UI_LOCALE_REPORT_PATH,
158
+ uiLocales: ["zh-CN", "en"],
159
+ modes: ["interactive", "no-script"],
160
+ channels: ["visible", "accessibility", "status"],
161
+ privacy: "metadata-only"
162
+ };
163
+ }
164
+
165
+ /**
166
+ * Names the upstream JSDoc package used by the HIA JSDoc runner.
167
+ *
168
+ * @constant {string}
169
+ * @lang zh-CN 记录 HIA JSDoc runner 使用的上游 JSDoc 包名。
170
+ * @lang en Names the upstream JSDoc package used by the HIA JSDoc runner.
171
+ */
172
+ export const JSDOC_PACKAGE = "jsdoc";
173
+
174
+ /**
175
+ * Pins the upstream JSDoc version used by the HIA JSDoc runner.
176
+ *
177
+ * @constant {string}
178
+ * @lang zh-CN 固定 HIA JSDoc runner 使用的上游 JSDoc 版本。
179
+ * @lang en Pins the upstream JSDoc version used by the HIA JSDoc runner.
180
+ */
181
+ export const JSDOC_VERSION = "4.0.5";
182
+
183
+ /**
184
+ * Lists supported HIA JSDoc output modes for config normalization.
185
+ *
186
+ * @constant {ReadonlyArray<string>}
187
+ * @lang zh-CN 列出配置规范化可接受的 HIA JSDoc 输出模式。
188
+ * @lang en Lists supported HIA JSDoc output modes for config normalization.
189
+ */
190
+ export const HIA_JSDOC_OUTPUT_MODES = Object.freeze(["standalone", "hiaIntegration", "both"]);
191
+
192
+ /**
193
+ * Lists plugin insertion phases supported by the extra plugin registry.
194
+ *
195
+ * @constant {ReadonlyArray<string>}
196
+ * @lang zh-CN 列出额外插件注册表支持的插件插入阶段。
197
+ * @lang en Lists plugin insertion phases supported by the extra plugin registry.
198
+ */
199
+ export const HIA_JSDOC_EXTRA_PLUGIN_PHASES = Object.freeze(["before", "after"]);
200
+
201
+ /**
202
+ * Normalizes an HIA JSDoc output mode and rejects unknown modes.
203
+ *
204
+ * @param {string} [mode="both"] <lang><en>Candidate output mode.</en><zh-CN>候选输出模式。</zh-CN></lang>
205
+ * @returns {string} <lang><en>Supported output mode.</en><zh-CN>受支持的输出模式。</zh-CN></lang>
206
+ * @throws {Error} <lang><en>When the mode is not part of the HIA JSDoc mode registry.</en><zh-CN>当模式不在 HIA JSDoc 模式注册表内时抛出。</zh-CN></lang>
207
+ * @lang zh-CN 规范化 HIA JSDoc 输出模式,并拒绝未登记的模式。
208
+ * @lang en Normalizes an HIA JSDoc output mode and rejects unknown modes.
209
+ */
210
+ export function normalizeHiaJsdocMode(mode = "both") {
211
+ if (!HIA_JSDOC_OUTPUT_MODES.includes(mode)) {
212
+ throw new Error(`Unsupported HIA JSDoc output mode: ${mode}`);
213
+ }
214
+ return mode;
215
+ }
216
+
217
+ /**
218
+ * Creates the dependency version summary embedded into generated HIA JSDoc configs.
219
+ *
220
+ * @returns {object} <lang><en>Version summary for JSDoc, JPHS and JTH dependencies.</en><zh-CN>JSDoc、JPHS 与 JTH 依赖的版本摘要。</zh-CN></lang>
221
+ * @lang zh-CN 创建写入 HIA JSDoc 生成配置的依赖版本摘要。
222
+ * @lang en Creates the dependency version summary embedded into generated HIA JSDoc configs.
223
+ */
224
+ export function createHiaJsdocVersionSummary() {
225
+ return {
226
+ contract: HIA_JSDOC_UMBRELLA_CONTRACT,
227
+ contractVersion: HIA_JSDOC_UMBRELLA_CONTRACT_VERSION,
228
+ jsdoc: {
229
+ package: JSDOC_PACKAGE,
230
+ version: JSDOC_VERSION
231
+ },
232
+ plugin: {
233
+ package: HIA_JSDOC_PLUGIN_PACKAGE,
234
+ version: HIA_JSDOC_PLUGIN_VERSION
235
+ },
236
+ theme: {
237
+ package: HIA_JSDOC_THEME_PACKAGE,
238
+ version: HIA_JSDOC_THEME_VERSION
239
+ }
240
+ };
241
+ }