@hia-doc/jsdoc-extra-plugin-registry 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 +21 -0
- package/MIGRATION.md +50 -0
- package/README.md +44 -2
- package/package.json +33 -4
- package/src/index.mjs +94 -0
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,45 @@
|
|
|
1
|
-
#
|
|
1
|
+
# JSDoc Extra Plugin Registry
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
Tracks user JSDoc plugin configuration, ordering and diagnostics.
|
|
13
|
+
|
|
14
|
+
The registry currently supports `before` and `after` phases around the HIA plugin and emits diagnostics for invalid or unsafe plugin entries.
|
|
15
|
+
|
|
16
|
+
## Public API
|
|
17
|
+
|
|
18
|
+
`normalizeExtraPluginRegistry` has signature `(input = {})` and returns `{before, after, diagnostics, order}`.
|
|
19
|
+
Each phase accepts strings or `{module?, package?, optional?, config?}` objects;
|
|
20
|
+
`module` precedes its `package` alias. `before`/`after` take precedence over
|
|
21
|
+
`pre`/`post` using nullish fallback. Entries retain order and duplicates;
|
|
22
|
+
`optional` is boolean-coerced, and an object-shaped `config` is retained by reference.
|
|
23
|
+
The final order inserts the `hia-jsdoc-plugin` marker between the two phases.
|
|
24
|
+
The preset subsequently deduplicates plugin paths when merging its final config.
|
|
25
|
+
|
|
26
|
+
**Errors:** malformed phase lists/entries become warning diagnostics with
|
|
27
|
+
`HIA_JSDOC_PLUGIN_LIST_INVALID`, `HIA_JSDOC_PLUGIN_ENTRY_INVALID` or
|
|
28
|
+
`HIA_JSDOC_PLUGIN_PATH_UNSAFE`. Rejected paths are omitted from diagnostic data;
|
|
29
|
+
only phase and index are retained. The input contract expects an object;
|
|
30
|
+
explicit null is not an alternate empty registry. Existing lexical checks reject
|
|
31
|
+
`..` and drive-root paths; they are not a universal path validator or a sandbox.
|
|
32
|
+
|
|
33
|
+
**Side effects:** no filesystem reads, writes or module execution. Successful
|
|
34
|
+
entries are trusted local configuration, potentially containing private paths or
|
|
35
|
+
settings, and must not be published as raw diagnostics. Third-party plugins run
|
|
36
|
+
with the JSDoc process's permissions; optional is metadata, not an install or
|
|
37
|
+
missing-plugin suppression guarantee.
|
|
38
|
+
|
|
39
|
+
中文:规范化不执行插件,保留顺序/重复与配置引用;拒绝诊断不含原路径。词法筛选不是沙箱,optional也不保证忽略CLI加载失败。
|
|
40
|
+
|
|
41
|
+
## Package candidate and migration
|
|
42
|
+
|
|
43
|
+
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.
|
|
44
|
+
|
|
45
|
+
中文:当前包为1.0.0源码候选,永久依赖与版本元数据协调;实际发布另验,旧wire不改号。
|
package/package.json
CHANGED
|
@@ -1,6 +1,35 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hia-doc/jsdoc-extra-plugin-registry",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"description": "
|
|
6
|
-
|
|
3
|
+
"version": "1.0.0-rc.2",
|
|
4
|
+
"private": false,
|
|
5
|
+
"description": "User JSDoc plugin registry and diagnostics.",
|
|
6
|
+
"license": "MIT",
|
|
7
|
+
"type": "module",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": "./src/index.mjs"
|
|
10
|
+
},
|
|
11
|
+
"dependencies": {
|
|
12
|
+
"@hia-doc/jsdoc-spec": "1.0.0-rc.2"
|
|
13
|
+
},
|
|
14
|
+
"engines": {
|
|
15
|
+
"node": "^22.23.4 || ^24.22.1"
|
|
16
|
+
},
|
|
17
|
+
"publishConfig": {
|
|
18
|
+
"access": "public"
|
|
19
|
+
},
|
|
20
|
+
"repository": {
|
|
21
|
+
"directory": "packages/jsdoc-extra-plugin-registry",
|
|
22
|
+
"type": "git",
|
|
23
|
+
"url": "git+https://github.com/mandolin/hia-jsdoc.git"
|
|
24
|
+
},
|
|
25
|
+
"homepage": "https://github.com/mandolin/hia-jsdoc/tree/main/packages/jsdoc-extra-plugin-registry",
|
|
26
|
+
"bugs": {
|
|
27
|
+
"url": "https://github.com/mandolin/hia-jsdoc/issues"
|
|
28
|
+
},
|
|
29
|
+
"files": [
|
|
30
|
+
"src",
|
|
31
|
+
"README.md",
|
|
32
|
+
"MIGRATION.md",
|
|
33
|
+
"LICENSE"
|
|
34
|
+
]
|
|
35
|
+
}
|
package/src/index.mjs
ADDED
|
@@ -0,0 +1,94 @@
|
|
|
1
|
+
import { HIA_JSDOC_EXTRA_PLUGIN_PHASES } from "@hia-doc/jsdoc-spec";
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* Normalizes user-supplied extra JSDoc plugin configuration into ordered bridge phases.
|
|
5
|
+
*
|
|
6
|
+
* @param {object} [input] <lang><zh-CN>用户提供的 before/after 或 pre/post 插件配置。</zh-CN><en>User supplied before/after or pre/post plugin configuration.</en></lang>
|
|
7
|
+
* @returns {object} <lang><zh-CN>规范化插件阶段、诊断列表和最终插件加载顺序。</zh-CN><en>Normalized plugin phases, diagnostics, and final plugin load order.</en></lang>
|
|
8
|
+
* @lang zh-CN 将使用者传入的额外 JSDoc 插件配置规范化为 umbrella bridge 可消费的有序阶段。
|
|
9
|
+
* @lang en Normalizes user-supplied extra JSDoc plugin configuration into ordered umbrella bridge phases.
|
|
10
|
+
*/
|
|
11
|
+
export function normalizeExtraPluginRegistry(input = {}) {
|
|
12
|
+
// <lang><zh-CN>诊断只承载固定阶段/索引,原路径与配置不得进入可发布摘要。</zh-CN><en>Diagnostics carry only fixed phases/indices; original paths and configuration must not enter publishable summaries.</en></lang>
|
|
13
|
+
const diagnostics = [];
|
|
14
|
+
// <lang><zh-CN>规范名称优先于兼容别名;保持输入顺序及重复项,不在注册阶段执行模块。</zh-CN><en>Canonical names take precedence over compatibility aliases; preserve order and duplicates without executing modules during registration.</en></lang>
|
|
15
|
+
const before = normalizePluginList(input.before ?? input.pre ?? [], "before", diagnostics);
|
|
16
|
+
const after = normalizePluginList(input.after ?? input.post ?? [], "after", diagnostics);
|
|
17
|
+
|
|
18
|
+
return {
|
|
19
|
+
before,
|
|
20
|
+
after,
|
|
21
|
+
diagnostics,
|
|
22
|
+
order: [
|
|
23
|
+
...before.map((plugin) => plugin.module),
|
|
24
|
+
"hia-jsdoc-plugin",
|
|
25
|
+
...after.map((plugin) => plugin.module)
|
|
26
|
+
]
|
|
27
|
+
};
|
|
28
|
+
}
|
|
29
|
+
|
|
30
|
+
/**
|
|
31
|
+
* @lang zh-CN 将单阶段声明转为顺序列表,无效项写固定诊断;不查模块存在性。
|
|
32
|
+
* @lang en Converts one phase declaration into an ordered list with fixed diagnostics for invalid entries; does not check module existence.
|
|
33
|
+
* @param {unknown} value 阶段声明。 / Phase declaration.
|
|
34
|
+
* @param {string} phase 实现给定的阶段。 / Implementation-supplied phase.
|
|
35
|
+
* @param {object[]} diagnostics 本轮可变诊断。 / Mutable diagnostics for this invocation.
|
|
36
|
+
* @returns {object[]} 合法条目列表。 / Admitted entry list.
|
|
37
|
+
*/
|
|
38
|
+
function normalizePluginList(value, phase, diagnostics) {
|
|
39
|
+
if (!HIA_JSDOC_EXTRA_PLUGIN_PHASES.includes(phase)) {
|
|
40
|
+
diagnostics.push(createDiagnostic("HIA_JSDOC_PLUGIN_PHASE_UNSUPPORTED", `Unsupported plugin phase: ${phase}`, { phase }));
|
|
41
|
+
return [];
|
|
42
|
+
}
|
|
43
|
+
if (!Array.isArray(value)) {
|
|
44
|
+
diagnostics.push(createDiagnostic("HIA_JSDOC_PLUGIN_LIST_INVALID", `Plugin phase ${phase} must be an array.`, { phase }));
|
|
45
|
+
return [];
|
|
46
|
+
}
|
|
47
|
+
|
|
48
|
+
return value.map((entry, index) => normalizePluginEntry(entry, phase, index, diagnostics)).filter(Boolean);
|
|
49
|
+
}
|
|
50
|
+
|
|
51
|
+
/**
|
|
52
|
+
* @lang zh-CN 读取一个受信本地插件声明;只作既有词法筛选,不承诺文件系统隔离。
|
|
53
|
+
* @lang en Reads a trusted local plugin declaration; existing lexical filtering is not filesystem isolation.
|
|
54
|
+
* @param {unknown} entry 条目,配置对象保留引用。 / Entry whose config object retains its reference.
|
|
55
|
+
* @param {string} phase 已知阶段。 / Known phase.
|
|
56
|
+
* @param {number} index 从零起索引。 / Zero-based index.
|
|
57
|
+
* @param {object[]} diagnostics 本轮可变诊断。 / Mutable diagnostics for this invocation.
|
|
58
|
+
* @returns {object|null} 合法声明或拒绝。 / Admitted declaration or refusal.
|
|
59
|
+
*/
|
|
60
|
+
function normalizePluginEntry(entry, phase, index, diagnostics) {
|
|
61
|
+
// <lang><zh-CN>module优先package别名;值仅在本地成功声明中保留,拒绝诊断不复制它。</zh-CN><en>Module precedes the package alias; retain it only in admitted local declarations, never in refusal diagnostics.</en></lang>
|
|
62
|
+
const rawModule = typeof entry === "string" ? entry : entry?.module ?? entry?.package;
|
|
63
|
+
if (!rawModule || typeof rawModule !== "string") {
|
|
64
|
+
diagnostics.push(createDiagnostic("HIA_JSDOC_PLUGIN_ENTRY_INVALID", `Plugin entry ${phase}[${index}] must provide a module string.`, { phase, index }));
|
|
65
|
+
return null;
|
|
66
|
+
}
|
|
67
|
+
if (rawModule.includes("..") || /^[a-zA-Z]:[\\/]/.test(rawModule)) {
|
|
68
|
+
diagnostics.push(createDiagnostic("HIA_JSDOC_PLUGIN_PATH_UNSAFE", `Plugin entry ${phase}[${index}] uses an unsafe module path.`, { phase, index }));
|
|
69
|
+
return null;
|
|
70
|
+
}
|
|
71
|
+
return {
|
|
72
|
+
module: rawModule,
|
|
73
|
+
phase,
|
|
74
|
+
optional: Boolean(typeof entry === "object" && entry.optional),
|
|
75
|
+
config: typeof entry === "object" && entry.config && typeof entry.config === "object" ? entry.config : {}
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/**
|
|
80
|
+
* @lang zh-CN 构造固定warning;参数由实现提供,不接原始路径或异常。
|
|
81
|
+
* @lang en Creates a fixed warning from implementation-supplied fields, never raw paths or exceptions.
|
|
82
|
+
* @param {string} code 稳定码。 / Stable code.
|
|
83
|
+
* @param {string} message 固定摘要。 / Fixed summary.
|
|
84
|
+
* @param {object} [data={}] 阶段与索引。 / Phase and index.
|
|
85
|
+
* @returns {object} 新诊断对象。 / New diagnostic object.
|
|
86
|
+
*/
|
|
87
|
+
function createDiagnostic(code, message, data = {}) {
|
|
88
|
+
return {
|
|
89
|
+
code,
|
|
90
|
+
message,
|
|
91
|
+
severity: "warning",
|
|
92
|
+
data
|
|
93
|
+
};
|
|
94
|
+
}
|