@hia-doc/htmdoc-spec 0.1.0 → 1.0.0-rc.1
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 +74 -0
- package/LICENSE +1 -1
- package/MIGRATION.md +43 -0
- package/README.md +41 -2
- package/package.json +29 -7
- package/src/compatibility.mjs +95 -0
- package/src/frozen-arrays.mjs +19 -0
- package/src/index.mjs +104 -21
- package/src/output-conformance-arrays.mjs +17 -0
- package/src/output-conformance.mjs +50 -40
- package/src/schema-legacy.mjs +182 -0
- package/src/schemas/hia-htmdoc-extraction-0.1.0-draft.schema.json +242 -0
- package/src/schemas/hia-htmdoc-extraction-1.0.0.schema.json +252 -0
package/API.md
ADDED
|
@@ -0,0 +1,74 @@
|
|
|
1
|
+
# HTML documentation specification API
|
|
2
|
+
|
|
3
|
+
## Public exports
|
|
4
|
+
|
|
5
|
+
| Export | Responsibility |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| `HTMDOC_EXTRACTION_CONTRACT`, `HTMDOC_EXTRACTION_CONTRACT_VERSION`, `HTMDOC_EXTRACTION_SCHEMA_ID`, `HTMDOC_EXTRACTION_JSON_SCHEMA` | Current exact extraction identity/schema. |
|
|
8
|
+
| `HTMDOC_PROFILE_VERSION`, `HTMDOC_SYMBOL_KINDS`, `HTMDOC_TAGS` | Current profile and supported kinds/tags; description/lang are text tags. |
|
|
9
|
+
| `HTMDOC_LEGACY_EXTRACTION_CONTRACT_VERSION`, `HTMDOC_LEGACY_EXTRACTION_SCHEMA_ID`, `HTMDOC_LEGACY_EXTRACTION_JSON_SCHEMA`, `HTMDOC_LEGACY_PROFILE_VERSION` | Exact preserved historical definitions. |
|
|
10
|
+
| `getHtmlDocSymbolKind(tag)`, `isHtmlDocTag(tag)` | Case-sensitive own registry lookup and registration test. |
|
|
11
|
+
| `getHtmDocExtractionSchema(identity)` | Exact version/schema-ID lookup; unknown returns undefined. |
|
|
12
|
+
| `validateHtmDocExtraction(value)` | Pure ordinary-JSON/schema/profile validation, fixed diagnostics. |
|
|
13
|
+
| `migrateHtmDocExtraction(value)` | Explicit validated lossless old-to-current JSON migration. |
|
|
14
|
+
| `evaluateHtmDocOutputConformance(bundle, options)` | Pure owner-local generated-output consistency check. |
|
|
15
|
+
| `HTMDOC_OUTPUT_CONFORMANCE_CONTRACT`, `HTMDOC_OUTPUT_CONFORMANCE_VERSION`, `HTMDOC_OUTPUT_CONFORMANCE_CODES` | Separate frozen owner-local report identity/codes. |
|
|
16
|
+
|
|
17
|
+
JSON resources are explicit subpaths:
|
|
18
|
+
|
|
19
|
+
- `./schemas/hia-htmdoc-extraction-1.0.0.schema.json`
|
|
20
|
+
- `./schemas/hia-htmdoc-extraction-0.1.0-draft.schema.json`
|
|
21
|
+
|
|
22
|
+
## Inputs
|
|
23
|
+
|
|
24
|
+
Canonical lowercase tag strings; exact version or schema ID for lookup;
|
|
25
|
+
ordinary JSON extraction for validation/migration. Conformance bundle fields
|
|
26
|
+
are extraction, document, docSourceMap and producerResult. Its only option is
|
|
27
|
+
explicit boolean `allowEmbeddedSource`; metadata alone cannot grant embed permission.
|
|
28
|
+
|
|
29
|
+
## Returns
|
|
30
|
+
|
|
31
|
+
Kind string/null, registration boolean, corresponding read-only schema data or
|
|
32
|
+
undefined. Validation returns an empty array or fixed error diagnostics.
|
|
33
|
+
Migration returns a fresh JSON object preserving all data/extensions except
|
|
34
|
+
coordinated contract/profile identities. Conformance returns a content-free
|
|
35
|
+
`{contract,contractVersion,conformant,violations}` report.
|
|
36
|
+
|
|
37
|
+
## Defaults
|
|
38
|
+
|
|
39
|
+
No unknown-version inference or automatic migration. Conformance refuses
|
|
40
|
+
embedded source unless explicitly allowed. Schema objects are shared definitions
|
|
41
|
+
and must be treated as read-only. Helpers do not lowercase caller tags.
|
|
42
|
+
|
|
43
|
+
## Errors
|
|
44
|
+
|
|
45
|
+
Migration throws fixed TypeError for invalid, current or unknown versions,
|
|
46
|
+
cycles, accessors, sparse arrays and non-JSON values. Validation converts
|
|
47
|
+
failures to fixed diagnostics. Registry lookup rejects inherited object keys.
|
|
48
|
+
Conformance records violations rather than fetching or repairing artifacts.
|
|
49
|
+
|
|
50
|
+
## Effects
|
|
51
|
+
|
|
52
|
+
No filesystem/network/host access, no input mutation or remote schema loading.
|
|
53
|
+
Ajv validates bundled definitions without coercion/default insertion/removal.
|
|
54
|
+
Writers use these identities, adapters check them, and runner delivery metadata
|
|
55
|
+
must agree with the actual map version.
|
|
56
|
+
|
|
57
|
+
## Compatibility
|
|
58
|
+
|
|
59
|
+
Package/current extraction/profile 1.0.0. Exact 0.1.0-draft schema modules and
|
|
60
|
+
resources remain preserved. Nullable parent/summary are new current rules, not
|
|
61
|
+
changes to historical definitions. Output-conformance report stays 0.1.0-draft;
|
|
62
|
+
it reads exact old/current producer results and old/current ordinary maps.
|
|
63
|
+
|
|
64
|
+
## Source linkage
|
|
65
|
+
|
|
66
|
+
Conformance checks metadata continuity and declared per-reference conventions.
|
|
67
|
+
It is not the general shared map validator and does not prove byte identity,
|
|
68
|
+
source authorization, file existence or cross-transform coordinate equality.
|
|
69
|
+
|
|
70
|
+
## Privacy
|
|
71
|
+
|
|
72
|
+
Validation/conformance failures contain fixed producer messages. Domain prose,
|
|
73
|
+
metadata and explicit embedded content remain owner-reviewed. Schemas are
|
|
74
|
+
identity data; their URLs are never fetched by these APIs.
|
package/LICENSE
CHANGED
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-spec
|
|
2
2
|
|
|
3
|
-
Defines
|
|
3
|
+
Defines annotation, tag registry, rule, diagnostic and compatibility semantics for the supported HTML documentation subset.
|
|
4
4
|
|
|
5
5
|
```sh
|
|
6
6
|
npm install @hia-doc/htmdoc-spec
|
|
@@ -15,7 +15,7 @@ import {
|
|
|
15
15
|
|
|
16
16
|
The current tag registry includes standard-level, unprefixed tags for components, elements, templates, attributes, slots, events, style hooks, accessibility notes, examples, descriptions and language metadata.
|
|
17
17
|
|
|
18
|
-
The
|
|
18
|
+
The current source exports the extraction `1.0.0` schema constants:
|
|
19
19
|
|
|
20
20
|
- `HTMDOC_EXTRACTION_SCHEMA_ID`
|
|
21
21
|
- `HTMDOC_EXTRACTION_JSON_SCHEMA`
|
|
@@ -25,3 +25,42 @@ It also exports the owner-local `evaluateHtmDocOutputConformance()` evaluator an
|
|
|
25
25
|
ordinary doc-source-map and producer-result JSON records. It performs no file, source, network or target-project
|
|
26
26
|
access, and is not a cross-package runtime capability schema. The default `none` source-content policy remains
|
|
27
27
|
content-free; an `embed` artifact requires explicit evaluator confirmation.
|
|
28
|
+
Its owner-local output gate accepts exact `doc-source-map@1.1.0` and historical
|
|
29
|
+
`0.1.0-draft` identities. Current ranged references must carry a valid
|
|
30
|
+
`rangeConvention`, and the producer-result map version must match the delivered
|
|
31
|
+
map. Full general map validation remains the responsibility of the shared
|
|
32
|
+
schema and reader.
|
|
33
|
+
|
|
34
|
+
## Exact versions and lossless migration
|
|
35
|
+
|
|
36
|
+
Current source `hia-htmdoc-extraction` and its profile use `1.0.0`; the exact
|
|
37
|
+
`0.1.0-draft` schema remains under `HTMDOC_LEGACY_EXTRACTION_*` and the original
|
|
38
|
+
module archive. New optional `parentId` and `summary` permit `null`; this is an
|
|
39
|
+
explicit new rule, while ordinary current producers usually omit absent values.
|
|
40
|
+
The legacy schema is not rewritten. Package versions remain independent of
|
|
41
|
+
these artifact identities.
|
|
42
|
+
|
|
43
|
+
`getHtmDocExtractionSchema(versionOrId)` returns the exact schema or
|
|
44
|
+
`undefined` for an unknown identity. `validateHtmDocExtraction(value)` accepts
|
|
45
|
+
ordinary JSON with exact contract/profile identities and the corresponding
|
|
46
|
+
schema. It returns an empty diagnostic array when valid; otherwise it returns
|
|
47
|
+
only a fixed public-safe error, without echoing Ajv details or caller values.
|
|
48
|
+
|
|
49
|
+
`migrateHtmDocExtraction(oldArtifact)` validates the exact old structure,
|
|
50
|
+
copies the entire JSON value, coordinates contract/profile versions, and
|
|
51
|
+
validates the target. Extensions and omitted fields are preserved. It returns
|
|
52
|
+
a new object and throws a fixed `TypeError` for current/unknown identities,
|
|
53
|
+
invalid structures, cycles, accessors, sparse arrays and non-JSON data rather
|
|
54
|
+
than silently deleting or relabeling them. No API reads a file, source, URL or
|
|
55
|
+
network; bundled Ajv validation uses no coercion, default insertion or removal.
|
|
56
|
+
|
|
57
|
+
The bundled JSON subpaths are
|
|
58
|
+
`@hia-doc/htmdoc-spec/schemas/hia-htmdoc-extraction-1.0.0.schema.json` and
|
|
59
|
+
`hia-htmdoc-extraction-0.1.0-draft.schema.json`. Conformance and the projection
|
|
60
|
+
adapter accept exact legacy/current extraction inputs; their own output
|
|
61
|
+
contract identities remain unchanged. This does not expand the supported HTML
|
|
62
|
+
syntax or CEM subset.
|
|
63
|
+
|
|
64
|
+
## Public API and migration
|
|
65
|
+
|
|
66
|
+
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,21 +1,43 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hia-doc/htmdoc-spec",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "1.0.0-rc.1",
|
|
4
4
|
"description": "HTML documentation annotation, tag registry and rule drafts.",
|
|
5
5
|
"license": "MIT",
|
|
6
|
-
"keywords": [
|
|
6
|
+
"keywords": [
|
|
7
|
+
"documentation",
|
|
8
|
+
"html",
|
|
9
|
+
"htmdoc",
|
|
10
|
+
"schema"
|
|
11
|
+
],
|
|
7
12
|
"repository": {
|
|
8
13
|
"type": "git",
|
|
9
14
|
"url": "git+https://github.com/mandolin/hia-htmdoc.git",
|
|
10
15
|
"directory": "packages/htmdoc-spec"
|
|
11
16
|
},
|
|
12
|
-
"bugs": {
|
|
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-spec#readme",
|
|
14
21
|
"type": "module",
|
|
15
22
|
"exports": {
|
|
16
|
-
".": "./src/index.mjs"
|
|
23
|
+
".": "./src/index.mjs",
|
|
24
|
+
"./schemas/hia-htmdoc-extraction-1.0.0.schema.json": "./src/schemas/hia-htmdoc-extraction-1.0.0.schema.json",
|
|
25
|
+
"./schemas/hia-htmdoc-extraction-0.1.0-draft.schema.json": "./src/schemas/hia-htmdoc-extraction-0.1.0-draft.schema.json"
|
|
26
|
+
},
|
|
27
|
+
"files": [
|
|
28
|
+
"src",
|
|
29
|
+
"README.md",
|
|
30
|
+
"API.md",
|
|
31
|
+
"MIGRATION.md",
|
|
32
|
+
"LICENSE"
|
|
33
|
+
],
|
|
34
|
+
"engines": {
|
|
35
|
+
"node": "^22.23.4 || ^24.22.1"
|
|
36
|
+
},
|
|
37
|
+
"publishConfig": {
|
|
38
|
+
"access": "public"
|
|
17
39
|
},
|
|
18
|
-
"
|
|
19
|
-
|
|
20
|
-
|
|
40
|
+
"dependencies": {
|
|
41
|
+
"ajv": "8.17.1"
|
|
42
|
+
}
|
|
21
43
|
}
|
|
@@ -0,0 +1,95 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file Exact HTML extraction reading and lossless JSON migration.
|
|
3
|
+
* @lang zh-CN 只编译随包 schema,拒绝未知版本/非 JSON;不读取 schema URL、源码或文件。
|
|
4
|
+
* @lang en Compiles bundled schemas only, rejecting unknown versions/non-JSON without reading schema URLs, sources or files.
|
|
5
|
+
*/
|
|
6
|
+
import Ajv2020 from "ajv/dist/2020.js";
|
|
7
|
+
import { HTMDOC_EXTRACTION_JSON_SCHEMA, HTMDOC_LEGACY_EXTRACTION_JSON_SCHEMA, HTMDOC_EXTRACTION_SCHEMA_ID, HTMDOC_LEGACY_EXTRACTION_SCHEMA_ID } from "./index.mjs";
|
|
8
|
+
|
|
9
|
+
/** @lang zh-CN 固定公开失败,不暴露 Ajv 原始诊断或输入。 @lang en Fixed public failure without raw Ajv diagnostics or input. */
|
|
10
|
+
const failure = "HTMDoc extraction must match an exact supported contract and JSON structure.";
|
|
11
|
+
/** @lang zh-CN 延迟缓存避免新旧 export 图的循环初始化读取;不启用远程 schema。 @lang en Lazy caching avoids cyclic export initialization reads and never enables remote schemas. */
|
|
12
|
+
const validators = new Map();
|
|
13
|
+
|
|
14
|
+
/**
|
|
15
|
+
* @lang zh-CN 按精确版本或Schema身份选择原HTML文档提取Schema对象,未知身份返回undefined。
|
|
16
|
+
* @lang en Selects the original HTML documentation extraction schema object by exact version or schema identity, returning undefined for unknown identities.
|
|
17
|
+
* @param {string} identity <lang><zh-CN>精确版本或 schema ID。</zh-CN><en>Exact version or schema ID.</en></lang>
|
|
18
|
+
* @returns {object|undefined} <lang><zh-CN>对应的原 schema;未知值返回 undefined,无默认猜测。</zh-CN><en>Corresponding original schema; unknown identities return undefined with no guessed default.</en></lang>
|
|
19
|
+
*/
|
|
20
|
+
export function getHtmDocExtractionSchema(identity) {
|
|
21
|
+
if (identity === "1.0.0" || identity === HTMDOC_EXTRACTION_SCHEMA_ID) return HTMDOC_EXTRACTION_JSON_SCHEMA;
|
|
22
|
+
if (identity === "0.1.0-draft" || identity === HTMDOC_LEGACY_EXTRACTION_SCHEMA_ID) return HTMDOC_LEGACY_EXTRACTION_JSON_SCHEMA;
|
|
23
|
+
return undefined;
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
/**
|
|
27
|
+
* @lang zh-CN 在普通JSON副本上校验HTML文档提取件的精确契约与profile配对,返回空数组或固定公开诊断。
|
|
28
|
+
* @lang en Validates an HTML documentation extraction's exact contract/profile pairing on an ordinary-JSON copy, returning an empty array or fixed public diagnostics.
|
|
29
|
+
* @param {unknown} value <lang><zh-CN>已物化的普通 JSON 提取件,不接受访问器或循环。</zh-CN><en>Materialized ordinary-JSON extraction excluding accessors/cycles.</en></lang>
|
|
30
|
+
* @returns {Array<object>} <lang><zh-CN>有效为空,否则只含固定公开诊断;不改变输入。</zh-CN><en>Empty when valid, otherwise fixed public diagnostics only; input is unchanged.</en></lang>
|
|
31
|
+
*/
|
|
32
|
+
export function validateHtmDocExtraction(value) {
|
|
33
|
+
try {
|
|
34
|
+
// <lang><zh-CN>先验证纯 JSON,避免 Ajv 读取 getter 或静默丢失非 JSON 值。</zh-CN><en>Check plain JSON first so Ajv cannot read getters or silently discard non-JSON values.</en></lang>
|
|
35
|
+
const json = cloneJson(value);
|
|
36
|
+
const schema = getHtmDocExtractionSchema(json?.contractVersion);
|
|
37
|
+
if (!schema || json?.profile?.version !== json.contractVersion) throw new TypeError(failure);
|
|
38
|
+
if (!validators.has(json.contractVersion)) {
|
|
39
|
+
// <lang><zh-CN>禁止 coercion/defaults/removeAdditional,迁移不能借验证修改输入。</zh-CN><en>No coercion/defaults/removeAdditional: validation must not modify migration inputs.</en></lang>
|
|
40
|
+
const ajv = new Ajv2020({ strict: false, allErrors: true });
|
|
41
|
+
validators.set(json.contractVersion, ajv.compile(schema));
|
|
42
|
+
}
|
|
43
|
+
if (!validators.get(json.contractVersion)(json)) throw new TypeError(failure);
|
|
44
|
+
return [];
|
|
45
|
+
} catch {
|
|
46
|
+
return [{ code: "HTMDOC_EXTRACTION_INVALID", message: failure, severity: "error" }];
|
|
47
|
+
}
|
|
48
|
+
}
|
|
49
|
+
|
|
50
|
+
/**
|
|
51
|
+
* @lang zh-CN 将合法旧版HTML文档提取件复制并协调契约及profile版本,返回通过当前Schema校验的副本。
|
|
52
|
+
* @lang en Copies a valid legacy HTML documentation extraction, coordinates its contract/profile versions and returns the copy after current-schema validation.
|
|
53
|
+
* @param {unknown} value <lang><zh-CN>精确 0.1.0-draft JSON 提取件,扩展字段也必须为普通 JSON。</zh-CN><en>Exact 0.1.0-draft JSON extraction, with ordinary JSON extensions.</en></lang>
|
|
54
|
+
* @returns {object} <lang><zh-CN>新对象,只协调契约/profile 身份,其余字段无损保留。</zh-CN><en>Fresh object coordinating only contract/profile identity while preserving all other fields losslessly.</en></lang>
|
|
55
|
+
* @throws {TypeError} <lang><zh-CN>旧结构或目标验证失败时固定拒绝,不修改输入。</zh-CN><en>Fixed refusal when legacy structure or target validation fails; input is unchanged.</en></lang>
|
|
56
|
+
*/
|
|
57
|
+
export function migrateHtmDocExtraction(value) {
|
|
58
|
+
try {
|
|
59
|
+
const json = cloneJson(value);
|
|
60
|
+
if (json.contractVersion !== "0.1.0-draft" || validateHtmDocExtraction(json).length) throw new TypeError(failure);
|
|
61
|
+
json.contractVersion = "1.0.0";
|
|
62
|
+
json.profile.version = "1.0.0";
|
|
63
|
+
if (validateHtmDocExtraction(json).length) throw new TypeError(failure);
|
|
64
|
+
return json;
|
|
65
|
+
} catch {
|
|
66
|
+
throw new TypeError(failure);
|
|
67
|
+
}
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* @param {unknown} value <lang><zh-CN>普通 JSON 值。</zh-CN><en>Ordinary JSON value.</en></lang>
|
|
72
|
+
* @param {Set<object>} [active] <lang><zh-CN>当前递归栈,不跨调用共享。</zh-CN><en>Current recursion stack, never shared across calls.</en></lang>
|
|
73
|
+
* @returns {unknown} <lang><zh-CN>不包含 getter、原型行为或共享可变容器的副本。</zh-CN><en>Copy without getters, prototype behavior or shared mutable containers.</en></lang>
|
|
74
|
+
* @throws {TypeError} <lang><zh-CN>拒绝所有非 JSON 值/稀疏数组/隐藏属性。</zh-CN><en>Rejects non-JSON values, sparse arrays and hidden properties.</en></lang>
|
|
75
|
+
*/
|
|
76
|
+
function cloneJson(value, active = new Set()) {
|
|
77
|
+
if (value === null || typeof value === "string" || typeof value === "boolean") return value;
|
|
78
|
+
if (typeof value === "number" && Number.isFinite(value)) return value;
|
|
79
|
+
if (!value || typeof value !== "object" || active.has(value)) throw new TypeError(failure);
|
|
80
|
+
const array = Array.isArray(value);
|
|
81
|
+
if (!array && ![Object.prototype, null].includes(Object.getPrototypeOf(value))) throw new TypeError(failure);
|
|
82
|
+
active.add(value);
|
|
83
|
+
try {
|
|
84
|
+
// <lang><zh-CN>描述符先检查,绝不通过普通属性读取触发用户访问器。</zh-CN><en>Inspect descriptors first, never triggering user accessors through ordinary property reads.</en></lang>
|
|
85
|
+
const result = array ? [] : {};
|
|
86
|
+
for (const key of Reflect.ownKeys(value)) {
|
|
87
|
+
if (array && key === "length") continue;
|
|
88
|
+
const descriptor = Object.getOwnPropertyDescriptor(value, key);
|
|
89
|
+
if (typeof key !== "string" || !descriptor.enumerable || !("value" in descriptor) || (array && !/^(0|[1-9][0-9]*)$/.test(key))) throw new TypeError(failure);
|
|
90
|
+
Object.defineProperty(result, key, { value: cloneJson(descriptor.value, active), enumerable: true, configurable: true, writable: true });
|
|
91
|
+
}
|
|
92
|
+
if (array && (result.length !== value.length || Object.keys(result).length !== value.length)) throw new TypeError(failure);
|
|
93
|
+
return result;
|
|
94
|
+
} finally { active.delete(value); }
|
|
95
|
+
}
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/** @file @lang zh-CN 包内冻结数组纯数据定义,无导入和运行器副作用。 @lang en Owner-local frozen-array plain-data definitions without imports or runner side effects. */
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* @lang zh-CN 规范化后支持的显式标签,description/lang 不独立创建 kind。
|
|
5
|
+
* @lang en Supported canonical tags; description/lang do not create standalone kinds.
|
|
6
|
+
*/
|
|
7
|
+
export const HTMDOC_TAGS = Object.freeze([
|
|
8
|
+
"component",
|
|
9
|
+
"element",
|
|
10
|
+
"template",
|
|
11
|
+
"attr",
|
|
12
|
+
"slot",
|
|
13
|
+
"event",
|
|
14
|
+
"stylehook",
|
|
15
|
+
"a11y",
|
|
16
|
+
"description",
|
|
17
|
+
"example",
|
|
18
|
+
"lang"
|
|
19
|
+
]);
|
package/src/index.mjs
CHANGED
|
@@ -1,7 +1,46 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @lang zh-CN 提取工件的固定中性身份,与包版本独立。
|
|
3
|
+
* @lang en Fixed extraction artifact identity, independent of package versions.
|
|
4
|
+
*/
|
|
1
5
|
export const HTMDOC_EXTRACTION_CONTRACT = "hia-htmdoc-extraction";
|
|
2
|
-
|
|
3
|
-
|
|
4
|
-
|
|
6
|
+
/**
|
|
7
|
+
* @lang zh-CN 已确认的新版提取 wire 身份,旧版仍精确可读。
|
|
8
|
+
* @lang en Confirmed current extraction wire identity with exact historical reading retained.
|
|
9
|
+
*/
|
|
10
|
+
export const HTMDOC_EXTRACTION_CONTRACT_VERSION = "1.0.0";
|
|
11
|
+
/**
|
|
12
|
+
* @lang zh-CN 公开 schema 身份,不执行网络请求。
|
|
13
|
+
* @lang en Public schema identity without network requests.
|
|
14
|
+
*/
|
|
15
|
+
export const HTMDOC_EXTRACTION_SCHEMA_ID = "https://mandolin.github.io/HIA-Documentation/schemas/hia-htmdoc-extraction-1.0.0.schema.json";
|
|
16
|
+
/**
|
|
17
|
+
* @lang zh-CN 已确认 annotation/CEM 子集的 profile 身份,不表示全生态支持。
|
|
18
|
+
* @lang en Profile identity for the confirmed annotation/CEM subset, not full ecosystem support.
|
|
19
|
+
*/
|
|
20
|
+
export const HTMDOC_PROFILE_VERSION = "1.0.0";
|
|
21
|
+
import * as legacyExtraction from "./schema-legacy.mjs";
|
|
22
|
+
/**
|
|
23
|
+
* @lang zh-CN 原档案提取schema的同一对象,不克隆或修改旧规则。
|
|
24
|
+
* @lang en The original archived extraction-schema object without cloning or changing historical rules.
|
|
25
|
+
*/
|
|
26
|
+
export const HTMDOC_LEGACY_EXTRACTION_JSON_SCHEMA = legacyExtraction.HTMDOC_EXTRACTION_JSON_SCHEMA;
|
|
27
|
+
/**
|
|
28
|
+
* @lang zh-CN 原档案提取schema身份,不读取URL。
|
|
29
|
+
* @lang en Original archived extraction-schema identity, without URL reads.
|
|
30
|
+
*/
|
|
31
|
+
export const HTMDOC_LEGACY_EXTRACTION_SCHEMA_ID = legacyExtraction.HTMDOC_EXTRACTION_SCHEMA_ID;
|
|
32
|
+
/**
|
|
33
|
+
* @lang zh-CN 原档案提取契约版本,不以当前版本替代旧语义。
|
|
34
|
+
* @lang en Original archived extraction-contract version, never substituting current semantics.
|
|
35
|
+
*/
|
|
36
|
+
export const HTMDOC_LEGACY_EXTRACTION_CONTRACT_VERSION = legacyExtraction.HTMDOC_EXTRACTION_CONTRACT_VERSION;
|
|
37
|
+
/**
|
|
38
|
+
* @lang zh-CN 原档案领域profile版本,独立于包与全局规范版本。
|
|
39
|
+
* @lang en Original archived domain-profile version, independent of package and global-specification versions.
|
|
40
|
+
*/
|
|
41
|
+
export const HTMDOC_LEGACY_PROFILE_VERSION = legacyExtraction.HTMDOC_PROFILE_VERSION;
|
|
42
|
+
/** @lang zh-CN 新旧精确读取和显式迁移均为无 I/O 纯 API。 @lang en Exact version reading and explicit migration are pure APIs without I/O. */
|
|
43
|
+
export { getHtmDocExtractionSchema, validateHtmDocExtraction, migrateHtmDocExtraction } from "./compatibility.mjs";
|
|
5
44
|
|
|
6
45
|
/**
|
|
7
46
|
* Owner-local output conformance evaluator for already-generated HTMDoc artifacts.
|
|
@@ -17,32 +56,65 @@ export {
|
|
|
17
56
|
HTMDOC_OUTPUT_CONFORMANCE_VERSION
|
|
18
57
|
} from "./output-conformance.mjs";
|
|
19
58
|
|
|
59
|
+
/**
|
|
60
|
+
* @lang zh-CN 已确认 HTML-facing 符号 kind 注册;与 CEM 的 JS metadata 区分。
|
|
61
|
+
* @lang en Confirmed HTML-facing kind registry, distinct from CEM JavaScript metadata.
|
|
62
|
+
*/
|
|
20
63
|
export const HTMDOC_SYMBOL_KINDS = Object.freeze({
|
|
64
|
+
/**
|
|
65
|
+
* @lang zh-CN HTML组件文档节点的领域种类。
|
|
66
|
+
* @lang en Domain kind for an HTML component documentation node.
|
|
67
|
+
*/
|
|
21
68
|
component: "html-component",
|
|
69
|
+
/**
|
|
70
|
+
* @lang zh-CN HTML元素文档节点的领域种类。
|
|
71
|
+
* @lang en Domain kind for an HTML element documentation node.
|
|
72
|
+
*/
|
|
22
73
|
element: "html-element",
|
|
74
|
+
/**
|
|
75
|
+
* @lang zh-CN HTML模板文档节点的领域种类。
|
|
76
|
+
* @lang en Domain kind for an HTML template documentation node.
|
|
77
|
+
*/
|
|
23
78
|
template: "html-template",
|
|
79
|
+
/**
|
|
80
|
+
* @lang zh-CN HTML属性文档节点的领域种类。
|
|
81
|
+
* @lang en Domain kind for an HTML attribute documentation node.
|
|
82
|
+
*/
|
|
24
83
|
attribute: "html-attribute",
|
|
84
|
+
/**
|
|
85
|
+
* @lang zh-CN HTML插槽文档节点的领域种类。
|
|
86
|
+
* @lang en Domain kind for an HTML slot documentation node.
|
|
87
|
+
*/
|
|
25
88
|
slot: "html-slot",
|
|
89
|
+
/**
|
|
90
|
+
* @lang zh-CN HTML事件文档节点的领域种类。
|
|
91
|
+
* @lang en Domain kind for an HTML event documentation node.
|
|
92
|
+
*/
|
|
26
93
|
event: "html-event",
|
|
94
|
+
/**
|
|
95
|
+
* @lang zh-CN HTML样式挂钩文档节点的领域种类。
|
|
96
|
+
* @lang en Domain kind for an HTML style-hook documentation node.
|
|
97
|
+
*/
|
|
27
98
|
styleHook: "html-style-hook",
|
|
99
|
+
/**
|
|
100
|
+
* @lang zh-CN HTML可访问性说明节点的领域种类。
|
|
101
|
+
* @lang en Domain kind for an HTML accessibility-note node.
|
|
102
|
+
*/
|
|
28
103
|
a11yNote: "html-a11y-note",
|
|
104
|
+
/**
|
|
105
|
+
* @lang zh-CN HTML示例文档节点的领域种类。
|
|
106
|
+
* @lang en Domain kind for an HTML example documentation node.
|
|
107
|
+
*/
|
|
29
108
|
example: "html-example"
|
|
30
109
|
});
|
|
110
|
+
/** @lang zh-CN 复用包内纯数据定义的同一冻结对象。 @lang en Reuses the same frozen objects from owner-local plain-data definitions. */
|
|
111
|
+
import {HTMDOC_TAGS} from './frozen-arrays.mjs';
|
|
112
|
+
export {HTMDOC_TAGS};
|
|
31
113
|
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
|
|
35
|
-
|
|
36
|
-
"attr",
|
|
37
|
-
"slot",
|
|
38
|
-
"event",
|
|
39
|
-
"stylehook",
|
|
40
|
-
"a11y",
|
|
41
|
-
"description",
|
|
42
|
-
"example",
|
|
43
|
-
"lang"
|
|
44
|
-
]);
|
|
45
|
-
|
|
114
|
+
/**
|
|
115
|
+
* @lang zh-CN 新版稳定子集 schema;nullable 为已确认新规则,旧 schema 不随之变化。
|
|
116
|
+
* @lang en Current stable-subset schema; nullable support is a confirmed new rule that does not change the legacy schema.
|
|
117
|
+
*/
|
|
46
118
|
export const HTMDOC_EXTRACTION_JSON_SCHEMA = Object.freeze({
|
|
47
119
|
$schema: "https://json-schema.org/draft/2020-12/schema",
|
|
48
120
|
$id: HTMDOC_EXTRACTION_SCHEMA_ID,
|
|
@@ -87,7 +159,7 @@ export const HTMDOC_EXTRACTION_JSON_SCHEMA = Object.freeze({
|
|
|
87
159
|
additionalProperties: true,
|
|
88
160
|
properties: {
|
|
89
161
|
name: { $ref: "#/$defs/nonEmptyString" },
|
|
90
|
-
version: {
|
|
162
|
+
version: { const: HTMDOC_PROFILE_VERSION }
|
|
91
163
|
}
|
|
92
164
|
},
|
|
93
165
|
source: {
|
|
@@ -131,8 +203,8 @@ export const HTMDOC_EXTRACTION_JSON_SCHEMA = Object.freeze({
|
|
|
131
203
|
id: { $ref: "#/$defs/nonEmptyString" },
|
|
132
204
|
kind: { enum: Object.values(HTMDOC_SYMBOL_KINDS) },
|
|
133
205
|
name: { $ref: "#/$defs/nonEmptyString" },
|
|
134
|
-
parentId: { $ref: "#/$defs/nonEmptyString" },
|
|
135
|
-
summary: { type: "string" },
|
|
206
|
+
parentId: { anyOf: [{ $ref: "#/$defs/nonEmptyString" }, { type: "null" }] },
|
|
207
|
+
summary: { type: ["string", "null"] },
|
|
136
208
|
source: {
|
|
137
209
|
type: "object",
|
|
138
210
|
required: ["path"],
|
|
@@ -161,6 +233,7 @@ export const HTMDOC_EXTRACTION_JSON_SCHEMA = Object.freeze({
|
|
|
161
233
|
}
|
|
162
234
|
});
|
|
163
235
|
|
|
236
|
+
/** @lang zh-CN 显式映射只可通过自有属性读取,不能把对象原型变成语言标签。 @lang en Read explicit mappings through own properties only, never promoting object prototypes into language tags. */
|
|
164
237
|
const TAG_TO_KIND = Object.freeze({
|
|
165
238
|
component: HTMDOC_SYMBOL_KINDS.component,
|
|
166
239
|
element: HTMDOC_SYMBOL_KINDS.element,
|
|
@@ -173,10 +246,20 @@ const TAG_TO_KIND = Object.freeze({
|
|
|
173
246
|
example: HTMDOC_SYMBOL_KINDS.example
|
|
174
247
|
});
|
|
175
248
|
|
|
249
|
+
/**
|
|
250
|
+
* @lang zh-CN 按原样字符串查询HTML文档标签到符号种类的自有注册表,未知标签返回null。
|
|
251
|
+
* @lang en Looks up an unchanged string in the HTML documentation tag-to-symbol-kind registry's own entries, returning null for unknown tags.
|
|
252
|
+
* @param {string} tag <lang><zh-CN>已规范化的小写标签,不执行类型转换。</zh-CN><en>Normalized lowercase tag without coercion.</en></lang> @returns {string|null} <lang><zh-CN>只返回自有 registry kind;未知/非字符串返回 null。</zh-CN><en>Own registry kind only; unknown/nonstring inputs return null.</en></lang>
|
|
253
|
+
*/
|
|
176
254
|
export function getHtmlDocSymbolKind(tag) {
|
|
177
|
-
return TAG_TO_KIND[tag]
|
|
255
|
+
return typeof tag === "string" && Object.hasOwn(TAG_TO_KIND, tag) ? TAG_TO_KIND[tag] : null;
|
|
178
256
|
}
|
|
179
257
|
|
|
258
|
+
/**
|
|
259
|
+
* @lang zh-CN 按大小写敏感的规范名称匹配HTML文档标签注册列表,返回识别结果。
|
|
260
|
+
* @lang en Matches case-sensitive canonical names against the HTML documentation tag registry and returns the recognition result.
|
|
261
|
+
* @param {string} tag <lang><zh-CN>区分大小写的规范标签。</zh-CN><en>Case-sensitive canonical tag.</en></lang> @returns {boolean} <lang><zh-CN>包含 description/lang 在内的显式标签注册;不修改输入。</zh-CN><en>Explicit registration including description/lang; input is unchanged.</en></lang>
|
|
262
|
+
*/
|
|
180
263
|
export function isHtmlDocTag(tag) {
|
|
181
264
|
return HTMDOC_TAGS.includes(tag);
|
|
182
265
|
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/** @file @lang zh-CN 包内冻结数组纯数据定义,无导入和运行器副作用。 @lang en Owner-local frozen-array plain-data definitions without imports or runner side effects. */
|
|
2
|
+
|
|
3
|
+
/**
|
|
4
|
+
* @lang zh-CN HTML文档输出一致性评估器发出的可公开违规码,仅描述工件边界,诊断内容排除源码正文、绝对路径、私有侧车定位器及调用方值。
|
|
5
|
+
* @lang en Public-safe violation codes emitted by the HTML documentation output conformance evaluator. Codes describe artifact boundaries and never echo source text, absolute paths, private sidecar locators or caller-supplied values.
|
|
6
|
+
*/
|
|
7
|
+
export const HTMDOC_OUTPUT_CONFORMANCE_CODES = Object.freeze([
|
|
8
|
+
"HTMDOC_OUTPUT_CONFORMANCE_INPUT_INVALID",
|
|
9
|
+
"HTMDOC_OUTPUT_CONFORMANCE_EXTRACTION_INVALID",
|
|
10
|
+
"HTMDOC_OUTPUT_CONFORMANCE_DOCUMENT_INVALID",
|
|
11
|
+
"HTMDOC_OUTPUT_CONFORMANCE_RELATION_INVALID",
|
|
12
|
+
"HTMDOC_OUTPUT_CONFORMANCE_PROVENANCE_INVALID",
|
|
13
|
+
"HTMDOC_OUTPUT_CONFORMANCE_SOURCE_POLICY_INVALID",
|
|
14
|
+
"HTMDOC_OUTPUT_CONFORMANCE_EMBED_UNAUTHORIZED",
|
|
15
|
+
"HTMDOC_OUTPUT_CONFORMANCE_SIDECAR_BOUNDARY_INVALID",
|
|
16
|
+
"HTMDOC_OUTPUT_CONFORMANCE_PRODUCER_RESULT_INVALID"
|
|
17
|
+
]);
|