@hia-doc/html-parser 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 +58 -0
- package/LICENSE +1 -1
- package/MIGRATION.md +43 -0
- package/README.md +4 -0
- package/package.json +23 -6
- package/src/index.mjs +50 -4
package/API.md
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# HTML parser API
|
|
2
|
+
|
|
3
|
+
## Public exports
|
|
4
|
+
|
|
5
|
+
| Export | Responsibility |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| `parseHtml(source, options)` | parse5 document or fragment, source locator and recovery diagnostics. |
|
|
8
|
+
| `visitHtmlNodes(node, visitor, parent)` | Synchronous preorder walk of `childNodes`; visitor receives `(node,parent)`. |
|
|
9
|
+
| `isHtmlElementNode(node)` | Tests string `tagName`. |
|
|
10
|
+
| `isHtmlCommentNode(node)` | Tests `nodeName === "#comment"`. |
|
|
11
|
+
| `getHtmlNodeAttributes(node)` | Fresh name/value record from `attrs`; empty when absent. |
|
|
12
|
+
| `getHtmlNodeLocation(node)` | Original location reference or null. |
|
|
13
|
+
|
|
14
|
+
## Inputs
|
|
15
|
+
|
|
16
|
+
`source` is explicit HTML text. Options: safe relative `path`, optional
|
|
17
|
+
`fragment`. Node helpers operate on parse5-shaped nodes; traversal requires a
|
|
18
|
+
callable visitor. Classification accepts absent nodes. This is a parser
|
|
19
|
+
boundary, not an HTML execution engine or full annotation extractor.
|
|
20
|
+
|
|
21
|
+
## Returns
|
|
22
|
+
|
|
23
|
+
Parsing returns `{kind,parser,source,document,diagnostics}`. The tree can have
|
|
24
|
+
parent links and is not a JSON wire artifact. Recovery diagnostics carry stable
|
|
25
|
+
codes and locations. Attribute extraction returns a new object; location lookup
|
|
26
|
+
retains the parser's object reference. Classification returns booleans.
|
|
27
|
+
|
|
28
|
+
## Defaults
|
|
29
|
+
|
|
30
|
+
`path` defaults to `input.html`, document mode is default, traversal root parent
|
|
31
|
+
is null. parse5 location reporting is enabled. `fragment` selects parseFragment.
|
|
32
|
+
|
|
33
|
+
## Errors
|
|
34
|
+
|
|
35
|
+
Unsafe absolute/URI/drive-relative/traversal source locators throw a fixed
|
|
36
|
+
TypeError without the raw value. parse5 input errors and visitor exceptions
|
|
37
|
+
propagate. Helpers do not provide general validation of arbitrary objects.
|
|
38
|
+
|
|
39
|
+
## Effects
|
|
40
|
+
|
|
41
|
+
No file/network/host access. Parsing builds a fresh tree; helpers do not mutate
|
|
42
|
+
it, but caller visitors can. Traversal neither detects cycles nor implicitly
|
|
43
|
+
walks `template.content`; callers must choose that traversal explicitly.
|
|
44
|
+
|
|
45
|
+
## Compatibility
|
|
46
|
+
|
|
47
|
+
Package 1.0.0 pins parse5 7.3.0 and its reviewed dependency. No AST interchange
|
|
48
|
+
format beyond that parser boundary is promised; published old archives stay unchanged.
|
|
49
|
+
|
|
50
|
+
## Source linkage
|
|
51
|
+
|
|
52
|
+
Original locations use one-based UTF-16 columns and exclusive ends. Recovered
|
|
53
|
+
implicit nodes can lack locations; null is preserved instead of invented ranges.
|
|
54
|
+
|
|
55
|
+
## Privacy
|
|
56
|
+
|
|
57
|
+
Callers own the supplied source, AST and attributes. No automatic content
|
|
58
|
+
redaction occurs; only source-locator rejection messages are value-free.
|
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
|
@@ -15,3 +15,7 @@ const result = parseHtml("<main>Documentation</main>");
|
|
|
15
15
|
The wrapper keeps parse5 private node shapes inside the parser boundary. Other
|
|
16
16
|
HTMDoc packages consume the stable helpers exported here rather than depending
|
|
17
17
|
on parse5 internals.
|
|
18
|
+
|
|
19
|
+
## Public API and migration
|
|
20
|
+
|
|
21
|
+
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,23 +1,40 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hia-doc/html-parser",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "1.0.0-rc.1",
|
|
4
4
|
"description": "HTML parser wrapper boundary for HTMDoc.",
|
|
5
5
|
"license": "MIT",
|
|
6
|
-
"keywords": [
|
|
6
|
+
"keywords": [
|
|
7
|
+
"documentation",
|
|
8
|
+
"html",
|
|
9
|
+
"parser",
|
|
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/html-parser"
|
|
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/html-parser#readme",
|
|
14
21
|
"type": "module",
|
|
15
22
|
"exports": {
|
|
16
23
|
".": "./src/index.mjs"
|
|
17
24
|
},
|
|
18
|
-
"files": [
|
|
19
|
-
|
|
20
|
-
|
|
25
|
+
"files": [
|
|
26
|
+
"src",
|
|
27
|
+
"README.md",
|
|
28
|
+
"API.md",
|
|
29
|
+
"MIGRATION.md",
|
|
30
|
+
"LICENSE"
|
|
31
|
+
],
|
|
32
|
+
"engines": {
|
|
33
|
+
"node": "^22.23.4 || ^24.22.1"
|
|
34
|
+
},
|
|
35
|
+
"publishConfig": {
|
|
36
|
+
"access": "public"
|
|
37
|
+
},
|
|
21
38
|
"dependencies": {
|
|
22
39
|
"parse5": "7.3.0"
|
|
23
40
|
}
|
package/src/index.mjs
CHANGED
|
@@ -1,7 +1,22 @@
|
|
|
1
|
+
/** @file @lang zh-CN parse5 解析边界和无 I/O 的节点辅助;不执行 HTML。 @lang en parse5 boundary and I/O-free node helpers; never executes HTML. */
|
|
1
2
|
import { parse, parseFragment } from "parse5";
|
|
2
3
|
|
|
4
|
+
/**
|
|
5
|
+
* @lang zh-CN 使用parse5解析显式HTML文档或片段,返回原生树、受限相对来源及带一基UTF-16位置的恢复诊断。
|
|
6
|
+
* @lang en Parses an explicit HTML document or fragment with parse5, returning its native tree, bounded relative provenance and recovery diagnostics with one-based UTF-16 positions.
|
|
7
|
+
* @param {string} source <lang><zh-CN>显式 HTML 文本。</zh-CN><en>Explicit HTML text.</en></lang>
|
|
8
|
+
* @param {Object} [options] <lang><zh-CN>解析来源与模式配置。</zh-CN><en>Parser source and mode options.</en></lang>
|
|
9
|
+
* @param {string} [options.path="input.html"] <lang><zh-CN>相对来源路径。</zh-CN><en>Relative source path.</en></lang>
|
|
10
|
+
* @param {boolean} [options.fragment=false] <lang><zh-CN>是否解析片段;默认解析完整文档。</zh-CN><en>Whether to parse a fragment; defaults to a complete document.</en></lang>
|
|
11
|
+
* @returns {object} <lang><zh-CN>parse5 树、相对来源及恢复诊断;隐式节点位置可能缺失。</zh-CN><en>parse5 tree, relative source and recovery diagnostics; implicit node positions may be absent.</en></lang>
|
|
12
|
+
* @throws {TypeError|Error} <lang><zh-CN>不安全来源或 parser 输入失败;路径错误不回显原值。</zh-CN><en>Unsafe source or parser input failure; path errors never echo raw values.</en></lang>
|
|
13
|
+
*/
|
|
3
14
|
export function parseHtml(source, options = {}) {
|
|
15
|
+
// <lang><zh-CN>先核来源再解析,非法定位器不进入 parser 或诊断对象。</zh-CN><en>Check the source before parsing so unsafe locators enter neither parser nor diagnostics.</en></lang>
|
|
16
|
+
const sourcePath = normalizeSourcePath(options.path ?? "input.html");
|
|
17
|
+
// <lang><zh-CN>每次调用独立收集 parse5 恢复位置,不包含源码正文。</zh-CN><en>Collect parse5 recovery positions per call without source bodies.</en></lang>
|
|
4
18
|
const parseErrors = [];
|
|
19
|
+
// <lang><zh-CN>显式启用一基 UTF-16 位置;onParseError 只保存稳定 code 与位置。</zh-CN><en>Explicitly enable one-based UTF-16 positions; onParseError stores only stable codes/positions.</en></lang>
|
|
5
20
|
const parserOptions = {
|
|
6
21
|
sourceCodeLocationInfo: true,
|
|
7
22
|
onParseError(error) {
|
|
@@ -13,6 +28,7 @@ export function parseHtml(source, options = {}) {
|
|
|
13
28
|
}
|
|
14
29
|
};
|
|
15
30
|
|
|
31
|
+
// <lang><zh-CN>模式只选择 parse5 document/fragment,不遍历 template.content 的额外语义。</zh-CN><en>Mode selects parse5 document/fragment only, adding no template.content traversal semantics.</en></lang>
|
|
16
32
|
const document = options.fragment
|
|
17
33
|
? parseFragment(source, parserOptions)
|
|
18
34
|
: parse(source, parserOptions);
|
|
@@ -24,7 +40,7 @@ export function parseHtml(source, options = {}) {
|
|
|
24
40
|
mode: options.fragment ? "fragment" : "document"
|
|
25
41
|
},
|
|
26
42
|
source: {
|
|
27
|
-
path:
|
|
43
|
+
path: sourcePath
|
|
28
44
|
},
|
|
29
45
|
document,
|
|
30
46
|
diagnostics: parseErrors.map((error) => ({
|
|
@@ -36,6 +52,14 @@ export function parseHtml(source, options = {}) {
|
|
|
36
52
|
};
|
|
37
53
|
}
|
|
38
54
|
|
|
55
|
+
/**
|
|
56
|
+
* @lang zh-CN 同步前序访问当前HTML节点及其childNodes,逐层将实际父节点引用交给回调。
|
|
57
|
+
* @lang en Visits the current HTML node and its childNodes synchronously in preorder, passing actual parent-node references to the callback.
|
|
58
|
+
* @param {object} node <lang><zh-CN>parse5 节点。</zh-CN><en>parse5 node.</en></lang>
|
|
59
|
+
* @param {Function} visitor <lang><zh-CN>同步前序回调(node,parent),异常传播。</zh-CN><en>Synchronous preorder callback(node,parent); exceptions propagate.</en></lang>
|
|
60
|
+
* @param {object|null} [parent] <lang><zh-CN>根父节点默认 null。</zh-CN><en>Root parent defaults to null.</en></lang>
|
|
61
|
+
* @returns {void} <lang><zh-CN>递归 childNodes;不自动遍历 template.content 或防循环。</zh-CN><en>Recurses childNodes without implicit template.content traversal or cycle protection.</en></lang>
|
|
62
|
+
*/
|
|
39
63
|
export function visitHtmlNodes(node, visitor, parent = null) {
|
|
40
64
|
visitor(node, parent);
|
|
41
65
|
for (const child of node.childNodes ?? []) {
|
|
@@ -43,26 +67,48 @@ export function visitHtmlNodes(node, visitor, parent = null) {
|
|
|
43
67
|
}
|
|
44
68
|
}
|
|
45
69
|
|
|
70
|
+
/**
|
|
71
|
+
* @lang zh-CN 根据字符串tagName属性判断候选节点是否具备HTML元素节点形状。
|
|
72
|
+
* @lang en Checks whether a candidate has the HTML element-node shape through a string-valued tagName property.
|
|
73
|
+
* @param {unknown} node <lang><zh-CN>候选节点。</zh-CN><en>Candidate node.</en></lang> @returns {boolean} <lang><zh-CN>存在字符串 tagName 时真;无 I/O。</zh-CN><en>True for a string tagName; no I/O.</en></lang>
|
|
74
|
+
*/
|
|
46
75
|
export function isHtmlElementNode(node) {
|
|
47
76
|
return typeof node?.tagName === "string";
|
|
48
77
|
}
|
|
49
78
|
|
|
79
|
+
/**
|
|
80
|
+
* @lang zh-CN 检查候选节点的nodeName是否精确为#comment,返回注释节点识别结果。
|
|
81
|
+
* @lang en Checks whether a candidate's nodeName is exactly #comment and returns the comment-node recognition result.
|
|
82
|
+
* @param {unknown} node <lang><zh-CN>候选节点。</zh-CN><en>Candidate node.</en></lang> @returns {boolean} <lang><zh-CN>仅 #comment 节点为真。</zh-CN><en>True only for a #comment node.</en></lang>
|
|
83
|
+
*/
|
|
50
84
|
export function isHtmlCommentNode(node) {
|
|
51
85
|
return node?.nodeName === "#comment";
|
|
52
86
|
}
|
|
53
87
|
|
|
88
|
+
/**
|
|
89
|
+
* @lang zh-CN 将HTML节点attrs中的name/value对收集为新属性记录,重复名称采用最后一项。
|
|
90
|
+
* @lang en Collects name/value pairs from an HTML node's attrs into a fresh attribute record, using the last item for duplicate names.
|
|
91
|
+
* @param {object} node <lang><zh-CN>parse5 节点。</zh-CN><en>parse5 node.</en></lang> @returns {object} <lang><zh-CN>新属性记录,缺 attrs 为空;不修改节点。</zh-CN><en>Fresh attribute record, empty without attrs; never mutates the node.</en></lang>
|
|
92
|
+
*/
|
|
54
93
|
export function getHtmlNodeAttributes(node) {
|
|
55
94
|
return Object.fromEntries((node.attrs ?? []).map((attr) => [attr.name, attr.value]));
|
|
56
95
|
}
|
|
57
96
|
|
|
97
|
+
/**
|
|
98
|
+
* @lang zh-CN 返回HTML节点原始sourceCodeLocation对象引用,缺少位置时返回null。
|
|
99
|
+
* @lang en Returns an HTML node's original sourceCodeLocation object reference, or null when its location is absent.
|
|
100
|
+
* @param {unknown} node <lang><zh-CN>候选节点。</zh-CN><en>Candidate node.</en></lang> @returns {object|null} <lang><zh-CN>原位置引用或 null,不补造位置。</zh-CN><en>Original location reference or null, without invented positions.</en></lang>
|
|
101
|
+
*/
|
|
58
102
|
export function getHtmlNodeLocation(node) {
|
|
59
103
|
return node?.sourceCodeLocation ?? null;
|
|
60
104
|
}
|
|
61
105
|
|
|
106
|
+
/** @param {unknown} sourcePath <lang><zh-CN>显式来源定位器。</zh-CN><en>Explicit source locator.</en></lang> @returns {string} <lang><zh-CN>正斜杠相对路径。</zh-CN><en>Slash-normalized relative path.</en></lang> @throws {TypeError} <lang><zh-CN>不安全或非字符串固定拒绝。</zh-CN><en>Fixed refusal for unsafe/nonstring values.</en></lang> */
|
|
62
107
|
function normalizeSourcePath(sourcePath) {
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
|
|
108
|
+
// <lang><zh-CN>与地图既有相对定位器边界一致;错误不包含用户来源。</zh-CN><en>Match the map's existing relative-locator boundary; errors exclude the caller's source.</en></lang>
|
|
109
|
+
const normalized = typeof sourcePath === "string" ? sourcePath.replaceAll("\\", "/") : "";
|
|
110
|
+
if (!normalized || normalized.startsWith("/") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(normalized) || normalized.split("/").includes("..")) {
|
|
111
|
+
throw new TypeError("Unsafe HTMDoc source path.");
|
|
66
112
|
}
|
|
67
113
|
return normalized;
|
|
68
114
|
}
|