@hia-doc/htmdoc-producer 0.1.0 → 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 ADDED
@@ -0,0 +1,56 @@
1
+ # HTML documentation producer API
2
+
3
+ ## Public exports
4
+
5
+ `htmdocProducerDescriptor` is the immutable SDK descriptor.
6
+ `htmdocProducer` is `{descriptor,produce}`; `default` is that same producer.
7
+ The descriptor reference is shared by the named and default objects.
8
+
9
+ ## Inputs
10
+
11
+ `produce(request, context)` delegates the original request/context to runHtmDoc:
12
+ absolute runtime roots, explicit relative HTML/fragment/template/CEM inputs,
13
+ options/profileIds, abort signal and progress callback. No plugin scanning occurs.
14
+
15
+ ## Returns
16
+
17
+ The runner Promise resolves a documentation-producer-result containing actual
18
+ artifacts, safe diagnostics, implementation identity and success/partial/failed.
19
+ The descriptor contains contract/version, id, version, displayName, inputKinds,
20
+ outputKinds and capabilities. It carries no runtime absolute paths.
21
+
22
+ ## Defaults
23
+
24
+ Context defaults to an empty object; runner defaults apply unchanged. Descriptor
25
+ id htmdoc, sourceLinkage true, incremental/watch false. Implementation version
26
+ follows the runner package, independently of wire contract versions.
27
+
28
+ ## Errors
29
+
30
+ Invalid request rejection, output I/O and progress-callback errors follow
31
+ runHtmDoc. Per-input failures become result diagnostics. The wrapper does not
32
+ catch, retry, repair, migrate or reinterpret these outcomes.
33
+
34
+ ## Effects
35
+
36
+ Importing creates only metadata/objects. Calling produce performs the runner's
37
+ explicit reads/writes; no additional I/O or host/network action is added.
38
+ Cancellation does not roll back files already written.
39
+
40
+ ## Compatibility
41
+
42
+ Package 1.0.0 uses confirmed descriptor/result 1.0.0. Exact old results remain
43
+ readable in the shared SDK/conformance reader. Old published tarballs are not
44
+ rewritten and artifact versions remain independent.
45
+
46
+ ## Source linkage
47
+
48
+ The descriptor declares sourceLinkage, while actual maps retain their own
49
+ 1.1.0 identity and known/unknown precision. Capability metadata alone is not a
50
+ source authorization or cross-transform same-point proof.
51
+
52
+ ## Privacy
53
+
54
+ Runtime roots are never descriptor data. Output privacy follows runner options
55
+ and owner-reviewed domain text. This wrapper is not a sandbox for callbacks,
56
+ symlinks or arbitrary caller-provided documentation.
package/MIGRATION.md ADDED
@@ -0,0 +1,43 @@
1
+ # HTML contract migration
2
+
3
+ Current source introduces config, extraction and profile `1.0.0` while keeping
4
+ exact `0.1.0-draft` reads. Package publication is a separate event: published
5
+ `0.1.0` tarballs retain their previous behavior.
6
+
7
+ ## Config
8
+
9
+ ```js
10
+ import { migrateHtmDocConfig } from "@hia-doc/htmdoc-runner";
11
+ const current = migrateHtmDocConfig(savedLegacyConfig);
12
+ ```
13
+
14
+ Only the exact old identity is migratable. The pure function validates the
15
+ supported JSON structure, preserves every field and omission, coordinates
16
+ `schemaVersion` and an existing `$schema`, validates the target, and returns a
17
+ fresh object. Omitted directories and kind keep existing loader defaults.
18
+ Legacy schema modules and JSON resources are preserved separately; new defaults
19
+ do not retroactively change their assertions.
20
+
21
+ ## Extraction and profile
22
+
23
+ ```js
24
+ import { migrateHtmDocExtraction } from "@hia-doc/htmdoc-spec";
25
+ const current = migrateHtmDocExtraction(savedLegacyExtraction);
26
+ ```
27
+
28
+ This validates both versions and preserves all source, symbols, annotations,
29
+ diagnostics, metadata and extensions. Only extraction/profile identities change.
30
+ New optional parent/summary fields can be null; legacy producers usually omit
31
+ absent values. Invalid old structures, unknown/current versions, cycles,
32
+ accessors and non-JSON values fail with fixed errors instead of silent loss.
33
+
34
+ New HTML and CEM writers emit the ordinary-JSON wire shape, omitting optional
35
+ `undefined` properties. Adapters, output conformance and projection requests
36
+ read exact old/new extractions. Source maps retain `1.1.0`, proven parse5 ranges
37
+ stay exclusive UTF-16, and CEM or unproven locations stay unknown. Handoff and
38
+ projection output versions remain unchanged. New descriptor/result writers
39
+ use the separately confirmed SDK `1.0.0`.
40
+
41
+ All schema resources are bundled; lookup and migration perform no file/network
42
+ I/O and do not modify input. The schema URLs identify contracts and are never
43
+ fetched during validation. No new UI, host action or CEM syntax is introduced.
package/README.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # @hia-doc/htmdoc-producer
2
2
 
3
- Thin `documentation-producer@0.1.0-draft` adapter for HTMDoc.
3
+ Thin `documentation-producer@1.0.0` adapter for HTMDoc in the current source.
4
4
 
5
5
  ```sh
6
6
  npm install @hia-doc/htmdoc-producer
@@ -13,3 +13,19 @@ import htmdocProducer from "@hia-doc/htmdoc-producer";
13
13
  The producer delegates to `@hia-doc/htmdoc-runner`, so standalone and HIA
14
14
  project builds use the same extraction and artifact pipeline. The producer is
15
15
  loaded explicitly by an HIA project; it does not scan installed modules.
16
+
17
+ `descriptor`, named `htmdocProducerDescriptor`, and the default producer refer
18
+ to the same immutable descriptor. `produce(request, context)` returns the
19
+ runner's promise and writes `documentation-producer-result@1.0.0`. Request
20
+ roots remain runtime-only absolute paths; artifacts use relative paths.
21
+ Input validation, output effects and exceptions follow `runHtmDoc()`; progress
22
+ callbacks and abort signals are delegated without wrapping. Incremental/watch
23
+ are unsupported. Importing this module does not read sources or write files.
24
+
25
+ Package versions and wire contract versions are independent. Published
26
+ `0.1.0` archives retain their original contracts. The output conformance reader
27
+ keeps exact legacy result reads and does not infer unknown-version compatibility.
28
+
29
+ ## Public API and migration
30
+
31
+ See [API reference](API.md) for every exported function, constant, resource and binary, including defaults, errors, effects, source precision and publication privacy. [Migration](MIGRATION.md) describes exact legacy/current contracts. Version 1.0.0 is a source candidate; registry publication is a separate event.
package/package.json CHANGED
@@ -1,15 +1,22 @@
1
1
  {
2
2
  "name": "@hia-doc/htmdoc-producer",
3
- "version": "0.1.0",
3
+ "version": "1.0.0-rc.2",
4
4
  "description": "Documentation producer adapter for HTMDoc.",
5
5
  "license": "MIT",
6
- "keywords": ["documentation", "html", "producer", "htmdoc"],
6
+ "keywords": [
7
+ "documentation",
8
+ "html",
9
+ "producer",
10
+ "htmdoc"
11
+ ],
7
12
  "repository": {
8
13
  "type": "git",
9
14
  "url": "git+https://github.com/mandolin/hia-htmdoc.git",
10
15
  "directory": "packages/htmdoc-producer"
11
16
  },
12
- "bugs": { "url": "https://github.com/mandolin/hia-htmdoc/issues" },
17
+ "bugs": {
18
+ "url": "https://github.com/mandolin/hia-htmdoc/issues"
19
+ },
13
20
  "homepage": "https://github.com/mandolin/hia-htmdoc/tree/main/packages/htmdoc-producer#readme",
14
21
  "type": "module",
15
22
  "exports": {
@@ -18,13 +25,17 @@
18
25
  "files": [
19
26
  "src",
20
27
  "README.md",
28
+ "API.md",
29
+ "MIGRATION.md",
21
30
  "LICENSE"
22
31
  ],
23
32
  "engines": {
24
- "node": ">=20.19.0"
33
+ "node": "^22.23.4 || ^24.22.1"
34
+ },
35
+ "publishConfig": {
36
+ "access": "public"
25
37
  },
26
- "publishConfig": { "access": "public" },
27
38
  "dependencies": {
28
- "@hia-doc/htmdoc-runner": "0.1.0"
39
+ "@hia-doc/htmdoc-runner": "1.0.0-rc.2"
29
40
  }
30
41
  }
@@ -0,0 +1,65 @@
1
+ /** @file @lang zh-CN 生产器描述符的纯数据定义,执行函数由原入口提供。 @lang en Pure producer descriptor definitions with execution functions supplied by the original entry. */
2
+ import {HTMDOC_RUNNER_VERSION, HTMDOC_INPUT_KINDS, HTMDOC_OUTPUT_KINDS} from '@hia-doc/htmdoc-runner/metadata';
3
+
4
+ /**
5
+ * @lang zh-CN 已确认 documentation-producer 1.0.0 描述符;实现版本独立于契约身份,无运行时绝对路径。
6
+ * @lang en Confirmed documentation-producer 1.0.0 descriptor; implementation version is independent from contract identity and excludes runtime absolute paths.
7
+ */
8
+ export const htmdocProducerDescriptor = Object.freeze({
9
+ /**
10
+ * @lang zh-CN 生产器协议身份,用于宿主发现和校验。
11
+ * @lang en Producer contract identity used for host discovery and validation.
12
+ */
13
+ contract: "documentation-producer",
14
+ /**
15
+ * @lang zh-CN 生产器协议版本,用于主SDK精确匹配。
16
+ * @lang en Producer contract version used for exact matching by the main SDK.
17
+ */
18
+ contractVersion: "1.0.0",
19
+ /**
20
+ * @lang zh-CN 当前文档生产器的稳定领域标识。
21
+ * @lang en Stable domain identifier of this documentation producer.
22
+ */
23
+ id: "htmdoc",
24
+ /**
25
+ * @lang zh-CN 生产器实现版本,取自当前运行器。
26
+ * @lang en Producer implementation version supplied by the current runner.
27
+ */
28
+ version: HTMDOC_RUNNER_VERSION,
29
+ /**
30
+ * @lang zh-CN 供宿主显示的生产器名称。
31
+ * @lang en Producer name presented by the host.
32
+ */
33
+ displayName: "HTMDoc",
34
+ /**
35
+ * @lang zh-CN 当前运行器接受的显式输入种类。
36
+ * @lang en Explicit input kinds accepted by the current runner.
37
+ */
38
+ inputKinds: [...HTMDOC_INPUT_KINDS],
39
+ /**
40
+ * @lang zh-CN 当前运行器声明的输出工件种类。
41
+ * @lang en Output artifact kinds declared by the current runner.
42
+ */
43
+ outputKinds: [...HTMDOC_OUTPUT_KINDS],
44
+ /**
45
+ * @lang zh-CN 供主SDK校验的来源关联、增量和监视能力声明。
46
+ * @lang en Source-linkage, incremental and watch capability declarations validated by the main SDK.
47
+ */
48
+ capabilities: {
49
+ /**
50
+ * @lang zh-CN 声明支持来源关联,具体定位精度由实际产物描述。
51
+ * @lang en Declares source-linkage support with precision described by the actual artifacts.
52
+ */
53
+ sourceLinkage: true,
54
+ /**
55
+ * @lang zh-CN 取false,每次执行处理完整请求的输入集。
56
+ * @lang en False selects full processing of the requested input set on each invocation.
57
+ */
58
+ incremental: false,
59
+ /**
60
+ * @lang zh-CN 取false,每次构建由宿主的独立请求触发。
61
+ * @lang en False selects individual host-triggered build requests.
62
+ */
63
+ watch: false
64
+ }
65
+ });
package/src/index.mjs CHANGED
@@ -1,27 +1,21 @@
1
- import {
2
- HTMDOC_INPUT_KINDS,
3
- HTMDOC_OUTPUT_KINDS,
4
- HTMDOC_RUNNER_VERSION,
5
- runHtmDoc
6
- } from "@hia-doc/htmdoc-runner";
7
-
8
- export const htmdocProducerDescriptor = Object.freeze({
9
- contract: "documentation-producer",
10
- contractVersion: "0.1.0-draft",
11
- id: "htmdoc",
12
- version: HTMDOC_RUNNER_VERSION,
13
- displayName: "HTMDoc",
14
- inputKinds: [...HTMDOC_INPUT_KINDS],
15
- outputKinds: [...HTMDOC_OUTPUT_KINDS],
16
- capabilities: {
17
- sourceLinkage: true,
18
- incremental: false,
19
- watch: false
20
- }
21
- });
1
+ import {runHtmDoc} from '@hia-doc/htmdoc-runner';
2
+ /** @lang zh-CN 复用纯模块的同一描述符对象。 @lang en Reuses the same descriptor object from its pure module. */
3
+ import {htmdocProducerDescriptor} from './descriptor.mjs';
4
+ export {htmdocProducerDescriptor} from './descriptor.mjs';
22
5
 
6
+ /**
7
+ * @lang zh-CN 一次性无增量生产器;不在导入时读取/生成或连接宿主。
8
+ * @lang en One-shot nonincremental producer; importing it performs no reads, generation or host integration.
9
+ */
23
10
  export const htmdocProducer = Object.freeze({
24
11
  descriptor: htmdocProducerDescriptor,
12
+ /**
13
+ * @lang zh-CN 将显式请求与中止/进度上下文委派给HTML文档运行器,返回其异步生产结果。
14
+ * @lang en Delegates the explicit request and abort/progress context to the HTML documentation runner and returns its asynchronous production result.
15
+ * @param {object} request <lang><zh-CN>原样交给 runner 的绝对运行根与相对输入请求。</zh-CN><en>Absolute runtime roots and relative inputs passed unchanged to the runner.</en></lang>
16
+ * @param {object} [context] <lang><zh-CN>原样委派的中止/进度上下文。</zh-CN><en>Abort/progress context delegated unchanged.</en></lang>
17
+ * @returns {Promise<object>} <lang><zh-CN>SDK 1.0.0 结果;输出副作用与异常见 runHtmDoc。</zh-CN><en>SDK 1.0.0 result; see runHtmDoc for output effects and exceptions.</en></lang>
18
+ */
25
19
  produce(request, context = {}) {
26
20
  return runHtmDoc(request, context);
27
21
  }