@hia-doc/jsdoc-plugin-hia-bridge 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,40 @@
1
- # Temporary Holding Version
1
+ # JSDoc Plugin HIA Bridge
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
+ Bridges the published HIA JSDoc plugin package into the JSDoc umbrella.
13
+
14
+ The bridge keeps `@mandolin/jsdoc-plugin-hia-sys` as a dependency reference and exposes the standard JSDoc plugin path. It does not migrate or copy JPHS source code.
15
+
16
+ ## Public API
17
+
18
+ | Export | Behavior |
19
+ | --- | --- |
20
+ | `createHiaJsdocPluginBridge` | `options = {}` → new `{package, version, pluginPath, order}`. Overrides are packageName/version/pluginPath/order; defaults come from jsdoc-spec, with order hia-core. Nullish overrides use defaults. |
21
+ | `getHiaJsdocPluginPath` | `options = {}` → the descriptor's pluginPath. |
22
+
23
+ **Errors:** these helpers do not validate custom package versions or prove path
24
+ existence; invalid local objects/types may fail at consumption. They do not
25
+ resolve a selected version from the registry. The default path is
26
+ node_modules/@mandolin/jsdoc-plugin-hia-sys/src/index.cjs, interpreted in the
27
+ consumer's JSDoc environment. The version summary describes the declared candidate edge,
28
+ not a newly released source owner's version.
29
+
30
+ **Side effects:** no I/O, installation or module execution; no plugin source is
31
+ copied. Custom paths are trusted local execution configuration, not sandboxed
32
+ requests or source disclosure permission.
33
+
34
+ 中文:两个helper只投影既有默认与覆盖,不证明registry、文件存在性或执行权限,不复制插件实现。
35
+
36
+ ## Package candidate and migration
37
+
38
+ 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.
39
+
40
+ 中文:当前包为1.0.0源码候选,永久依赖与版本元数据协调;实际发布另验,旧wire不改号。
package/package.json CHANGED
@@ -1,6 +1,35 @@
1
1
  {
2
2
  "name": "@hia-doc/jsdoc-plugin-hia-bridge",
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": "Bridge for @mandolin/jsdoc-plugin-hia-sys.",
6
+ "license": "MIT",
7
+ "type": "module",
8
+ "exports": {
9
+ ".": "./src/index.mjs"
10
+ },
11
+ "dependencies": {
12
+ "@mandolin/jsdoc-plugin-hia-sys": "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-plugin-hia-bridge",
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-plugin-hia-bridge",
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,34 @@
1
+ import {
2
+ HIA_JSDOC_PLUGIN_PACKAGE,
3
+ HIA_JSDOC_PLUGIN_PATH,
4
+ HIA_JSDOC_PLUGIN_VERSION
5
+ } from "@hia-doc/jsdoc-spec";
6
+
7
+ /**
8
+ * Creates the bridge descriptor for the HIA JSDoc plugin package.
9
+ *
10
+ * @param {object} [options] <lang><zh-CN>插件包名、版本、路径或顺序覆盖项。</zh-CN><en>Plugin package, version, path, or ordering overrides.</en></lang>
11
+ * @returns {object} <lang><zh-CN>用于 preset/runner 组装 JSDoc 插件链的 bridge descriptor。</zh-CN><en>A bridge descriptor used by the preset and runner to assemble the JSDoc plugin chain.</en></lang>
12
+ * @lang zh-CN 创建 HIA JSDoc 插件包的 bridge descriptor。
13
+ * @lang en Creates the bridge descriptor for the HIA JSDoc plugin package.
14
+ */
15
+ export function createHiaJsdocPluginBridge(options = {}) {
16
+ return {
17
+ package: options.packageName ?? HIA_JSDOC_PLUGIN_PACKAGE,
18
+ version: options.version ?? HIA_JSDOC_PLUGIN_VERSION,
19
+ pluginPath: options.pluginPath ?? HIA_JSDOC_PLUGIN_PATH,
20
+ order: options.order ?? "hia-core"
21
+ };
22
+ }
23
+
24
+ /**
25
+ * Resolves the JSDoc plugin path from the HIA plugin bridge descriptor.
26
+ *
27
+ * @param {object} [options] <lang><zh-CN>传递给插件 bridge descriptor 的覆盖项。</zh-CN><en>Overrides passed to the plugin bridge descriptor.</en></lang>
28
+ * @returns {string} <lang><zh-CN>JSDoc 可加载的插件路径。</zh-CN><en>The plugin path loadable by JSDoc.</en></lang>
29
+ * @lang zh-CN 从 HIA 插件 bridge descriptor 中解析 JSDoc 插件路径。
30
+ * @lang en Resolves the JSDoc plugin path from the HIA plugin bridge descriptor.
31
+ */
32
+ export function getHiaJsdocPluginPath(options = {}) {
33
+ return createHiaJsdocPluginBridge(options).pluginPath;
34
+ }