@mandolin/jsdoc-plugin-hia-sys 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,36 @@
+# Changelog
+
+## Unreleased
+
+### Added
+
+- Field-level text i18n metadata at `doclet.hia.i18n.fields`.
+- `@lang` doclet description blocks and XML-like `<lang>` inline segments.
+- Source metadata at `doclet.hia.source.definedIn` and `doclet.hia.source.primaryBlock`.
+- Source metadata contract fields for `kind`, `referenceKind`, `model` and `modelVersion`.
+- JavaScript declaration range parser for `doclet.hia.source.primaryBlock`, with heuristic fallback.
+
+### Changed
+
+- `@hiaText` and `@hiaBlock` now act as compatibility inputs for the newer text i18n pipeline.
+- `@coderef` output is modeled as extra source references rather than the only source metadata entry point.
+- The default source preview range strategy is now `parser-js`.
+- Release metadata now declares public scoped publishing and records the publish strategy/checklist.
+- HIA Integration output now omits empty synthetic doclets, normalizes source link open modes and emits relative localization resource records.
+
+## 0.1.0 - 2026-07-05
+
+### Added
+
+- JSDoc plugin entry with internal micro-plugin runner.
+- `@codeblock`, `@codeblockend` and `@coderef` source fragment flow.
+- Source link and source preview metadata.
+- `doc-i18n` metadata with inline text, external resources, fallback and generation modes.
+- Standalone output contract for `jsdoc-theme-hia`.
+- HIA Integration output contract and optional JSON file output.
+- Diagnostics collection and fixture coverage.
+
+### Notes
+
+- This is an early public package for standalone JSDoc usage and HIA metadata experiments.
+- Public API stability is not guaranteed yet.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 HIA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,222 @@
+# @mandolin/jsdoc-plugin-hia-sys
+
+HIA metadata plugin for JSDoc.
+
+`@mandolin/jsdoc-plugin-hia-sys` extends JSDoc with structured metadata for source references, source previews, multilingual documentation and optional HIA integration output. It can be used as a standalone JSDoc plugin in ordinary JavaScript projects, or as a JSDoc adapter in a larger HIA documentation pipeline.
+
+GitHub: <https://github.com/mandolin/jsdoc-plugin-hia-sys>
+
+## Features
+
+- Adds `doclet.hia` metadata to JSDoc doclets.
+- Supports source fragment markers with `@codeblock`, `@codeblockend` and `@coderef`.
+- Generates `definedIn`, `primaryBlock`, source link and source preview metadata for themes.
+- Supports `@lang`, XML-like `<lang>` inline segments and resource-backed multilingual documentation metadata.
+- Provides a small internal micro-plugin pipeline for feature composition.
+- Can write an HIA Integration JSON file for downstream tooling.
+- Includes diagnostics for missing fragments, missing translations and related metadata issues.
+
+## Install
+
+```bash
+npm install --save-dev jsdoc @mandolin/jsdoc-plugin-hia-sys
+```
+
+For projects that also need the companion HTML theme:
+
+```bash
+npm install --save-dev jsdoc @mandolin/jsdoc-plugin-hia-sys @mandolin/jsdoc-theme-hia
+```
+
+## Basic Usage
+
+Add the plugin to your JSDoc configuration:
+
+```json
+{
+  "plugins": ["node_modules/@mandolin/jsdoc-plugin-hia-sys/src/index.cjs"],
+  "source": {
+    "include": ["src"]
+  },
+  "opts": {
+    "destination": "docs/api",
+    "recurse": true,
+    "hia": {
+      "mode": "standalone"
+    }
+  }
+}
+```
+
+Configuration can be placed under `opts.hia`, `hia`, `opts["jsdoc-plugin-hia-sys"]`, `opts["@mandolin/jsdoc-plugin-hia-sys"]`, `jsdoc-plugin-hia-sys` or `@mandolin/jsdoc-plugin-hia-sys`.
+
+## Source Metadata
+
+Each doclet receives source metadata when JSDoc provides file and line information:
+
+- `doclet.hia.source.definedIn`: relative path, line, language and source link metadata.
+- `doclet.hia.source.primaryBlock`: a source preview block for the doclet itself. The default range strategy uses a JavaScript declaration parser with heuristic fallback.
+- `doclet.hia.source.references`: extra source fragments referenced with `@coderef`.
+
+Enable source links and previews in JSDoc configuration:
+
+```json
+{
+  "opts": {
+    "hia": {
+      "source": {
+        "basePath": ".",
+        "mode": "all",
+        "link": {
+          "enabled": true,
+          "rootUrl": "https://github.com/example/project/blob/main",
+          "openMode": "new-tab"
+        },
+        "preview": {
+          "enabled": true,
+          "defaultExpanded": false,
+          "rangeStrategy": "parser-js"
+        }
+      }
+    }
+  }
+}
+```
+
+## Source References
+
+Mark reusable source fragments in code:
+
+```js
+function greet(name) {
+  /* @codeblock GREET_BODY */
+  const message = `Hello, ${name}`;
+  return message;
+  /* @codeblockend GREET_BODY */
+}
+```
+
+Reference the fragment from a JSDoc comment:
+
+```js
+/**
+ * Greets a user.
+ *
+ * @example <caption>Basic greeting</caption>
+ * @coderef GREET_BODY
+ */
+function greet(name) {}
+```
+
+The plugin writes reference data to `doclet.hia.source.references`, including source link and preview metadata when enabled.
+
+## Multilingual Metadata
+
+Use `@lang` for localized doclet descriptions:
+
+```js
+/**
+ * @hiaKey user.greet
+ * @hiaPath api.user.greet
+ * @lang zh-CN 问候一个用户。
+ * @lang en Greets a user.
+ */
+function greet(name) {}
+```
+
+Use `<lang>` inside any description text field:
+
+```js
+/**
+ * Greets a <lang key="greet.target"><zh-CN>用户</zh-CN><en>user</en></lang>.
+ *
+ * @param {string} name User <lang key="greet.param.name"><zh-CN>名称</zh-CN><en>name</en></lang>.
+ */
+function greet(name) {}
+```
+
+The plugin writes field-level data to `doclet.hia.i18n.fields`. For compatibility, it also keeps the older `doclet.hia.i18n.localized` and generation fields. `@hiaText` and `@hiaBlock` are still accepted as compatibility inputs.
+
+External resource files are also supported:
+
+```json
+{
+  "opts": {
+    "hia": {
+      "i18n": {
+        "enabled": true,
+        "defaultLocale": "zh-CN",
+        "fallbackLocale": "en",
+        "locales": ["zh-CN", "en"],
+        "mode": "runtimeSwitch",
+        "resources": ["docs/i18n/docs.hia-i18n.json"]
+      }
+    }
+  }
+}
+```
+
+Resource files can be grouped by locale:
+
+```json
+{
+  "zh-CN": {
+    "user.greet": {
+      "text": "问候一个用户。"
+    }
+  },
+  "en": {
+    "user.greet": {
+      "text": "Greets a user."
+    }
+  }
+}
+```
+
+## HIA Integration Output
+
+Standalone mode enriches JSDoc doclets for themes and local tooling. HIA Integration mode additionally writes a JSON artifact for downstream processing:
+
+```json
+{
+  "opts": {
+    "hia": {
+      "mode": "hiaIntegration",
+      "integration": {
+        "enabled": true,
+        "outputFile": "docs/api/hia-integration.json"
+      }
+    }
+  }
+}
+```
+
+The integration artifact currently contains IR nodes, source fragments, localization resources, diagnostics and a doclet-to-node map.
+
+Current integration output keeps user-facing doclets only, omitting empty JSDoc synthetic nodes created by module/export inference. Source links use `same-tab` or `new-tab`; legacy `currentPage` input is normalized when metadata is produced. Resource records use relative `external-resource` entries, and generated integration JSON does not expose local `filePath` values.
+
+## Scripts
+
+```bash
+npm run check:syntax
+npm test
+npm run test:jsdoc
+npm run release:check
+npm run test:all
+```
+
+`npm test` runs fixture coverage for the plugin pipeline and metadata output. `npm run test:jsdoc` loads the plugin through real JSDoc. `npm run release:check` validates package metadata and required release files.
+
+## Compatibility
+
+- Node.js 18 or newer.
+- JSDoc 4.x.
+- CommonJS runtime.
+
+## Stability
+
+Version `0.1.0` is an early public package. The Standalone metadata shape is intended for experimentation and companion-theme use. The HIA Integration IR is still a draft contract and may change before a stable release.
+
+## License
+
+MIT

package/RELEASE_CHECKLIST.md

@@ -0,0 +1,41 @@
+# Release Checklist
+
+## Scope
+
+Package: `@mandolin/jsdoc-plugin-hia-sys`
+
+Version: `0.1.0`
+
+## Required Checks
+
+- [ ] `npm run check:syntax`
+- [ ] `npm test`
+- [ ] `npm run test:jsdoc`
+- [ ] `npm run clean:examples`
+- [ ] `npm run release:check`
+- [ ] `npm run test:all`
+- [ ] `npm pack --dry-run --json`
+
+## Manual Review
+
+- [ ] README describes Standalone and HIA Integration use.
+- [ ] `examples/basic/README.md` explains the example.
+- [ ] `src/runtime/output-contract.cjs` matches current output shape.
+- [ ] `THIRD_PARTY_NOTICES.md` is current.
+- [ ] `CHANGELOG.md` has the target version.
+- [ ] `package.json` keeps `publishConfig.access` as `public`.
+- [ ] Dry-run artifact contents are limited to package sources, examples and release docs.
+- [ ] `examples/basic/out` is not present.
+- [ ] No `.tgz` dry-run tarball remains.
+
+## Publish Strategy
+
+- Keep version `0.1.0` for the first public package unless registry preflight shows it is already published.
+- Use `npm publish --access public` for the scoped package.
+- If publishing before W-P3.5 HIA Integration hardening, publish with `--tag next` and avoid promoting to `latest` until the integration producer contract is confirmed.
+
+## Current Boundaries
+
+- API stability is not final.
+- The HIA Integration IR is a draft contract, not final core schema.
+- This package supports JSDoc 4.x in the current cycle.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,23 @@
+# Third Party Notices
+
+## Runtime Dependencies
+
+This package has no bundled runtime dependency besides Node.js built-ins.
+
+## Peer Dependencies
+
+- `jsdoc` `^4.0.0` (`Apache-2.0`)
+
+`jsdoc` is expected to be installed by the consuming project or used through this package's development environment.
+
+## Development Dependencies
+
+- `jsdoc` `^4.0.5` (`Apache-2.0`)
+
+## Assets
+
+No third-party visual assets, fonts, images, or copied theme code are bundled.
+
+## Legacy Material
+
+Older `jsdoc-plugin-hia` ideas were used as design reference only. This package is a new implementation and does not copy source files from the old repository.

package/examples/basic/README.md

@@ -0,0 +1,22 @@
+# Basic Example
+
+This example shows the core plugin features:
+
+- JSDoc plugin loading.
+- `@codeblock`, `@codeblockend` and `@coderef`.
+- Source `definedIn`, `primaryBlock`, link and preview metadata.
+- `@lang`, `<lang>` inline segments and resource-backed `doc-i18n`.
+- HIA Integration JSON output.
+
+Run:
+
+```bash
+npm run test:jsdoc
+```
+
+Expected generated files under `examples/basic/out`:
+
+- Standard JSDoc output files.
+- `hia-integration.json` from `opts.hia.integration.outputFile`.
+
+Generated files are test artifacts and should not be committed.

package/examples/basic/i18n/docs.hia-i18n.json

@@ -0,0 +1,12 @@
+{
+  "zh-CN": {
+    "shared.helper": {
+      "text": "标准化用户名称。"
+    }
+  },
+  "en": {
+    "shared.helper": {
+      "text": "Normalizes a user name."
+    }
+  }
+}

package/examples/basic/jsdoc.conf.json

@@ -0,0 +1,42 @@
+{
+  "plugins": ["./src/index.cjs"],
+  "source": {
+    "include": ["examples/basic/src"]
+  },
+  "opts": {
+    "destination": "examples/basic/out",
+    "recurse": true,
+    "hia": {
+      "mode": "standalone",
+      "source": {
+        "mode": "all",
+        "link": {
+          "enabled": true,
+          "rootUrl": "https://example.test/repo",
+          "openMode": "same-tab"
+        },
+        "preview": {
+          "enabled": true,
+          "defaultExpanded": false
+        },
+        "references": {
+          "enabled": true,
+          "defaultExpanded": false
+        }
+      },
+      "i18n": {
+        "enabled": true,
+        "defaultLocale": "zh-CN",
+        "fallbackLocale": "en",
+        "locales": ["zh-CN", "en"],
+        "mode": "runtimeSwitch",
+        "resourceBasePath": ".",
+        "resources": ["examples/basic/i18n/docs.hia-i18n.json"]
+      },
+      "integration": {
+        "enabled": true,
+        "outputFile": "examples/basic/out/hia-integration.json"
+      }
+    }
+  }
+}

package/examples/basic/src/greet.js

@@ -0,0 +1,26 @@
+"use strict";
+
+/**
+ * Greets a <lang key="greet.target"><zh-CN>用户</zh-CN><en>user</en></lang>.
+ *
+ * @function greet
+ * @example
+ * // @coderef GREET_BODY
+ * @param {string} name User <lang key="greet.param.name"><zh-CN>名称</zh-CN><en>name</en></lang>.
+ * @returns {string} Greeting <lang key="greet.return.text"><zh-CN>文本</zh-CN><en>text</en></lang>.
+ * @coderef GREET_BODY
+ * @hiaKey greet.description
+ * @hiaPath api.greet
+ * @lang zh-CN 问候一个用户。
+ * @lang en Greets a user.
+ */
+function greet(name) {
+  /* @codeblock GREET_BODY */
+  const message = `Hello, ${name}`;
+  return message;
+  /* @codeblockend GREET_BODY */
+}
+
+module.exports = {
+  greet
+};

package/examples/basic/src/shared.js

@@ -0,0 +1,20 @@
+"use strict";
+
+/**
+ * Shared helper.
+ *
+ * @function normalizeName
+ * @param {string} name User name.
+ * @returns {string} Normalized name.
+ * @hiaKey shared.helper
+ * @hiaPath api.shared
+ */
+/* @codeblock SHARED_HELPER */
+function normalizeName(name) {
+  return String(name).trim();
+}
+/* @codeblockend SHARED_HELPER */
+
+module.exports = {
+  normalizeName
+};

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@mandolin/jsdoc-plugin-hia-sys",
+  "version": "0.1.0",
+  "private": false,
+  "description": "HIA JSDoc integration system with internal micro-plugin support.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mandolin/jsdoc-plugin-hia-sys.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mandolin/jsdoc-plugin-hia-sys/issues"
+  },
+  "homepage": "https://github.com/mandolin/jsdoc-plugin-hia-sys#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "main": "src/index.cjs",
+  "exports": {
+    ".": "./src/index.cjs"
+  },
+  "files": [
+    "src",
+    "examples/basic/jsdoc.conf.json",
+    "examples/basic/README.md",
+    "examples/basic/i18n",
+    "examples/basic/src",
+    "README.md",
+    "CHANGELOG.md",
+    "RELEASE_CHECKLIST.md",
+    "THIRD_PARTY_NOTICES.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "check:syntax": "node --check src/index.cjs && node --check src/config/defaults.cjs && node --check src/runtime/create-plugin-system.cjs && node --check src/runtime/diagnostics.cjs && node --check src/runtime/i18n.cjs && node --check src/runtime/metadata.cjs && node --check src/runtime/output-contract.cjs && node --check src/runtime/source.cjs && node --check src/micro-plugins/code-fragment.cjs && node --check src/micro-plugins/diagnostics.cjs && node --check src/micro-plugins/doc-i18n.cjs && node --check src/micro-plugins/doclet-normalizer.cjs && node --check src/micro-plugins/hia-ir-exporter.cjs && node --check src/micro-plugins/index.cjs && node --check src/micro-plugins/source-link.cjs && node --check src/micro-plugins/source-preview.cjs && node --check test/run-fixtures.cjs && node --check scripts/clean-generated.cjs && node --check scripts/release-check.cjs",
+    "clean:examples": "node scripts/clean-generated.cjs",
+    "release:check": "node scripts/release-check.cjs && npm pack --dry-run",
+    "test": "node test/run-fixtures.cjs",
+    "test:fixtures": "node test/run-fixtures.cjs",
+    "test:jsdoc": "jsdoc -c examples/basic/jsdoc.conf.json",
+    "test:all": "npm run check:syntax && npm test && npm run test:jsdoc && npm run clean:examples && npm run release:check"
+  },
+  "keywords": [
+    "jsdoc",
+    "jsdoc-plugin",
+    "hia",
+    "documentation",
+    "source-preview",
+    "i18n",
+    "plugin"
+  ],
+  "peerDependencies": {
+    "jsdoc": "^4.0.0"
+  },
+  "devDependencies": {
+    "jsdoc": "^4.0.5"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}

package/src/config/defaults.cjs

@@ -0,0 +1,114 @@
+"use strict";
+
+const DEFAULT_CONFIG = Object.freeze({
+  mode: "standalone",
+  metadataKey: "hia",
+  microPlugins: [
+    "code-fragment",
+    "source-link",
+    "source-preview",
+    "doc-i18n",
+    "doclet-normalizer",
+    "hia-ir-exporter",
+    "diagnostics"
+  ],
+  source: {
+    basePath: "",
+    mode: "all",
+    link: {
+      enabled: false,
+      rootUrl: "",
+      openMode: "same-tab"
+    },
+    preview: {
+      enabled: false,
+      defaultExpanded: false,
+      rangeStrategy: "parser-js",
+      contextLines: 0,
+      maxLines: 80,
+      maxScanLines: 40
+    },
+    references: {
+      enabled: true,
+      defaultExpanded: false
+    }
+  },
+  i18n: {
+    enabled: true,
+    defaultLocale: "zh-CN",
+    fallbackLocale: "zh-CN",
+    locales: ["zh-CN"],
+    mode: "runtimeSwitch",
+    resourceBasePath: "",
+    resources: []
+  },
+  diagnostics: {
+    throwOnError: false
+  },
+  integration: {
+    enabled: true,
+    outputFile: ""
+  }
+});
+
+function isPlainObject(value) {
+  return (
+    value !== null &&
+    typeof value === "object" &&
+    !Array.isArray(value) &&
+    Object.getPrototypeOf(value) === Object.prototype
+  );
+}
+
+function mergeConfig(...sources) {
+  const result = {};
+
+  for (const source of sources) {
+    if (!isPlainObject(source)) {
+      continue;
+    }
+
+    for (const [key, value] of Object.entries(source)) {
+      if (isPlainObject(value) && isPlainObject(result[key])) {
+        result[key] = mergeConfig(result[key], value);
+      } else if (isPlainObject(value)) {
+        result[key] = mergeConfig(value);
+      } else if (Array.isArray(value)) {
+        result[key] = value.slice();
+      } else {
+        result[key] = value;
+      }
+    }
+  }
+
+  return result;
+}
+
+function readJsdocEnvConfig() {
+  try {
+    const env = require("jsdoc/env");
+    const conf = env && env.conf ? env.conf : {};
+    const opts = conf.opts || {};
+
+    return mergeConfig(
+      conf.hia,
+      conf["jsdoc-plugin-hia-sys"],
+      conf["@mandolin/jsdoc-plugin-hia-sys"],
+      opts.hia,
+      opts["jsdoc-plugin-hia-sys"],
+      opts["@mandolin/jsdoc-plugin-hia-sys"]
+    );
+  } catch (_error) {
+    return {};
+  }
+}
+
+function loadConfig(overrides) {
+  return mergeConfig(DEFAULT_CONFIG, readJsdocEnvConfig(), overrides);
+}
+
+module.exports = {
+  DEFAULT_CONFIG,
+  loadConfig,
+  mergeConfig
+};

package/src/index.cjs

@@ -0,0 +1,37 @@
+"use strict";
+
+const { createPluginSystem } = require("./runtime/create-plugin-system.cjs");
+const outputContract = require("./runtime/output-contract.cjs");
+const { builtInMicroPlugins } = require("./micro-plugins/index.cjs");
+
+const system = createPluginSystem({
+  microPlugins: builtInMicroPlugins
+});
+
+exports.defineTags = function defineTags(dictionary) {
+  system.defineTags(dictionary);
+};
+
+exports.handlers = {
+  beforeParse(event) {
+    system.handle("beforeParse", event);
+  },
+  newDoclet(event) {
+    system.handle("newDoclet", event);
+  },
+  parseComplete(event) {
+    system.handle("parseComplete", event);
+  },
+  processingComplete(event) {
+    system.handle("processingComplete", event);
+  }
+};
+
+exports._hia = {
+  createPluginSystem,
+  builtInMicroPlugins,
+  outputContract,
+  getState() {
+    return system.getState();
+  }
+};