@hia-doc/html-doc-source-map 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 +12 -0
- package/package.json +23 -6
- package/src/index.mjs +72 -8
package/API.md
ADDED
|
@@ -0,0 +1,58 @@
|
|
|
1
|
+
# HTML documentation source-map API
|
|
2
|
+
|
|
3
|
+
## Public exports
|
|
4
|
+
|
|
5
|
+
| Export | Responsibility |
|
|
6
|
+
| --- | --- |
|
|
7
|
+
| `HTML_DOC_SOURCE_CONTENT_POLICIES` | Frozen none/reference/embed list. |
|
|
8
|
+
| `normalizeSourcesContentPolicy(policy)` | Exact enum check, returns the same supported string. |
|
|
9
|
+
| `createHtmlDocSourceMapRef(options)` | Pure placeholder reference, not a generated map. |
|
|
10
|
+
| `createHtmlDocumentationSourceMap(options)` | Builds an ordinary map from an existing extraction and relative output paths. |
|
|
11
|
+
|
|
12
|
+
## Inputs
|
|
13
|
+
|
|
14
|
+
Reference options: optional href and content policy. Map options: materialized
|
|
15
|
+
`extraction`, `extractionPath`, `hiaDocumentPath`, optional `id` and policy.
|
|
16
|
+
The map builder requires the exact old/current extraction contract identity;
|
|
17
|
+
full extraction schema checking belongs to spec/adapter, not this lightweight helper.
|
|
18
|
+
|
|
19
|
+
## Returns
|
|
20
|
+
|
|
21
|
+
Reference `{kind,href,sourcesContentPolicy}`; href can be null. A map contains
|
|
22
|
+
producer, pathBases, artifacts, sources, chains, symbol entries, privacy and
|
|
23
|
+
diagnostics. Each symbol links extraction/core selectors to the original source.
|
|
24
|
+
|
|
25
|
+
## Defaults
|
|
26
|
+
|
|
27
|
+
Reference href null, policy none. Output paths document.htmdoc.json and
|
|
28
|
+
document.hia.json. Map policy can inherit the extraction reference. IDs derive
|
|
29
|
+
deterministically from relative paths/symbols unless supplied explicitly.
|
|
30
|
+
|
|
31
|
+
## Errors
|
|
32
|
+
|
|
33
|
+
Unknown policy and unsafe paths produce fixed TypeError without raw values.
|
|
34
|
+
Wrong/unknown extraction identity or unsupported input structure throws.
|
|
35
|
+
Inputs must be materialized records; this helper does not parse arbitrary maps.
|
|
36
|
+
|
|
37
|
+
## Effects
|
|
38
|
+
|
|
39
|
+
No filesystem/network/host access. It returns a new map and does not copy source
|
|
40
|
+
content into map records. The runner writes the map and registers its exact version.
|
|
41
|
+
|
|
42
|
+
## Compatibility
|
|
43
|
+
|
|
44
|
+
Package 1.0.0 writes doc-source-map 1.1.0, accepting exact extraction
|
|
45
|
+
0.1.0-draft/1.0.0. It does not promote handoff or coordinate-profile capabilities.
|
|
46
|
+
|
|
47
|
+
## Source linkage
|
|
48
|
+
|
|
49
|
+
Only the known parse5 HTML branch without recovery diagnostics and with complete
|
|
50
|
+
columns claims exclusive UTF-16 ranges. CEM placeholders and unproven branches
|
|
51
|
+
retain unknown conventions. File existence, transformed-map same-point evidence
|
|
52
|
+
and symbol identity across edits are not verified here.
|
|
53
|
+
|
|
54
|
+
## Privacy
|
|
55
|
+
|
|
56
|
+
Paths are lexical safe-relative locators, not filesystem sandbox proof. No
|
|
57
|
+
source is read; content policy is metadata, not permission. Documentation/tag
|
|
58
|
+
values and caller IDs are domain content that requires owner review.
|
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
|
@@ -19,3 +19,15 @@ const manifest = createHtmlDocumentationSourceMap({
|
|
|
19
19
|
|
|
20
20
|
Source paths are workspace-relative, artifact paths are output-relative and
|
|
21
21
|
source content is not embedded by default.
|
|
22
|
+
|
|
23
|
+
The source checkout emits `doc-source-map@1.1.0`. Each ranged `sourceRef`
|
|
24
|
+
includes `rangeConvention` with `endBoundary` and `columnUnit`. Proven parse5
|
|
25
|
+
HTML element ranges use `exclusive` and `utf16-code-unit`. The synthetic `1:1`
|
|
26
|
+
positions from Custom Elements Manifest, parser recovery paths and unverified
|
|
27
|
+
origins use `unknown` for both fields; consumers should treat them as source
|
|
28
|
+
relations rather than exact cursor positions. A source reference without a
|
|
29
|
+
range has no `rangeConvention`.
|
|
30
|
+
|
|
31
|
+
## Public API and migration
|
|
32
|
+
|
|
33
|
+
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,38 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hia-doc/html-doc-source-map",
|
|
3
|
-
"version": "0.1
|
|
3
|
+
"version": "1.0.0-rc.1",
|
|
4
4
|
"description": "HTML documentation source-map linkage.",
|
|
5
5
|
"license": "MIT",
|
|
6
|
-
"keywords": [
|
|
6
|
+
"keywords": [
|
|
7
|
+
"documentation",
|
|
8
|
+
"html",
|
|
9
|
+
"source-map",
|
|
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-doc-source-map"
|
|
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-doc-source-map#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
|
}
|
package/src/index.mjs
CHANGED
|
@@ -1,8 +1,31 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @lang zh-CN 源码内容策略闭集;none不嵌入、reference仅引用、embed显式嵌入,列表不授予读取或公开权限。
|
|
3
|
+
* @lang en Closed source-content policies: none omits content, reference links it, and embed explicitly embeds it; the list grants no read or publication permission.
|
|
4
|
+
*/
|
|
1
5
|
export const HTML_DOC_SOURCE_CONTENT_POLICIES = Object.freeze(["none", "reference", "embed"]);
|
|
2
6
|
|
|
3
|
-
// <lang><zh-CN
|
|
4
|
-
const HTML_DOC_SOURCE_MAP_VERSION = "
|
|
7
|
+
// <lang><zh-CN>生产者包版本与映射契约版本分别记录;本次只更新逐引用范围契约。</zh-CN><en>The producer package version and map contract version are separate; this change updates per-reference range semantics only.</en></lang>
|
|
8
|
+
const HTML_DOC_SOURCE_MAP_VERSION = "1.0.0";
|
|
5
9
|
|
|
10
|
+
/**
|
|
11
|
+
* @lang zh-CN 已实测的 parse5 HTML 元素范围使用排除终点和 UTF-16 列;未知来源不得借工具名推断。
|
|
12
|
+
* @lang en Proven parse5 HTML element ranges use exclusive ends and UTF-16 columns; unknown origins cannot inherit that claim from a tool name.
|
|
13
|
+
*/
|
|
14
|
+
const PARSE5_RANGE_CONVENTION = Object.freeze({ endBoundary: "exclusive", columnUnit: "utf16-code-unit" });
|
|
15
|
+
/**
|
|
16
|
+
* @lang zh-CN CEM 人工占位及尚未实测的解析分支只表达可追溯线索,不提供精确位置声明。
|
|
17
|
+
* @lang en CEM placeholders and unproven parser branches remain provenance hints without exact-position claims.
|
|
18
|
+
*/
|
|
19
|
+
const UNKNOWN_RANGE_CONVENTION = Object.freeze({ endBoundary: "unknown", columnUnit: "unknown" });
|
|
20
|
+
|
|
21
|
+
/**
|
|
22
|
+
* @param {Object} [options] <lang><zh-CN>提取件内的可选链接与源码内容策略。</zh-CN><en>Optional extraction-level link and source-content policy.</en></lang>
|
|
23
|
+
* @param {(string|null)} [options.href=null] <lang><zh-CN>可选映射链接,null 表示未绑定。</zh-CN><en>Optional map link; null means unbound.</en></lang>
|
|
24
|
+
* @param {string} [options.sourcesContentPolicy="none"] <lang><zh-CN>精确 none/reference/embed;其它值拒绝。</zh-CN><en>Exact none/reference/embed; other values are rejected.</en></lang>
|
|
25
|
+
* @returns {{kind:string,href:(string|null),sourcesContentPolicy:string}} <lang><zh-CN>kind 固定为 hia-doc-source-map-ref;不宣称具体映射版本或存在性。</zh-CN><en>Kind is fixed to hia-doc-source-map-ref; claims neither a map version nor its existence.</en></lang>
|
|
26
|
+
* @lang zh-CN `href:null` 表示尚未绑定输出映射;runner 是否产出映射由独立选项决定。
|
|
27
|
+
* @lang en `href:null` means no output map is bound; the runner's separate option determines whether one is emitted.
|
|
28
|
+
*/
|
|
6
29
|
export function createHtmlDocSourceMapRef(options = {}) {
|
|
7
30
|
return {
|
|
8
31
|
kind: "hia-doc-source-map-ref",
|
|
@@ -11,16 +34,33 @@ export function createHtmlDocSourceMapRef(options = {}) {
|
|
|
11
34
|
};
|
|
12
35
|
}
|
|
13
36
|
|
|
37
|
+
/**
|
|
38
|
+
* @lang zh-CN 精确校验HTML源码内容策略none、reference或embed,返回同一有效策略值。
|
|
39
|
+
* @lang en Validates the exact HTML source-content policies none, reference or embed and returns the same valid policy value.
|
|
40
|
+
* @param {string} policy <lang><zh-CN>精确 none/reference/embed。</zh-CN><en>Exact none/reference/embed.</en></lang> @returns {string} <lang><zh-CN>不改输入的同一合法值。</zh-CN><en>The same valid value without mutation.</en></lang> @throws {TypeError} <lang><zh-CN>未知值固定拒绝,不回显原文。</zh-CN><en>Fixed refusal for unknown values without raw text.</en></lang>
|
|
41
|
+
*/
|
|
14
42
|
export function normalizeSourcesContentPolicy(policy) {
|
|
15
43
|
if (!HTML_DOC_SOURCE_CONTENT_POLICIES.includes(policy)) {
|
|
16
|
-
throw new
|
|
44
|
+
throw new TypeError("Unsupported HTMDoc sourcesContent policy.");
|
|
17
45
|
}
|
|
18
46
|
return policy;
|
|
19
47
|
}
|
|
20
48
|
|
|
49
|
+
/**
|
|
50
|
+
* @param {Object} [options] <lang><zh-CN>已生成的 HTMDoc 提取件及安全相对输出路径。</zh-CN><en>Materialized HTMDoc extraction and safe relative output paths.</en></lang>
|
|
51
|
+
* @param {Object.<string,*>} options.extraction <lang><zh-CN>必需的已生成提取件。</zh-CN><en>Required materialized extraction.</en></lang>
|
|
52
|
+
* @param {string} [options.extractionPath="document.htmdoc.json"] <lang><zh-CN>提取件安全相对路径。</zh-CN><en>Safe relative extraction path.</en></lang>
|
|
53
|
+
* @param {string} [options.hiaDocumentPath="document.hia.json"] <lang><zh-CN>HIA 文档安全相对路径。</zh-CN><en>Safe relative HIA document path.</en></lang>
|
|
54
|
+
* @param {string} [options.sourcesContentPolicy] <lang><zh-CN>none/reference/embed;省略时继承提取件策略,再回退 none。</zh-CN><en>none/reference/embed; omission inherits the extraction policy, then falls back to none.</en></lang>
|
|
55
|
+
* @param {string} [options.id] <lang><zh-CN>映射身份;省略时由来源路径派生。</zh-CN><en>Map identity; derived from the source path when omitted.</en></lang>
|
|
56
|
+
* @returns {Record<string,unknown>} <lang><zh-CN>`doc-source-map@1.1.0`,逐个有范围的来源引用声明端点与列单位。</zh-CN><en>A `doc-source-map@1.1.0` with endpoint and column-unit declarations on each ranged source reference.</en></lang>
|
|
57
|
+
* @throws {Error} <lang><zh-CN>提取契约、相对路径或源码内容策略无效时抛出。</zh-CN><en>Throws for an invalid extraction contract, relative path, or source-content policy.</en></lang>
|
|
58
|
+
* @lang zh-CN 已证 parse5 分支声明精确 UTF-16 半开范围;CEM 合成位置、错误恢复及缺列分支明确保持未知,不读取源码或执行主机动作。
|
|
59
|
+
* @lang en Proven parse5 branches declare precise exclusive UTF-16 ranges; CEM placeholders, parser recovery, and missing-column branches stay unknown without reading source or invoking a host.
|
|
60
|
+
*/
|
|
21
61
|
export function createHtmlDocumentationSourceMap(options = {}) {
|
|
22
62
|
const extraction = options.extraction;
|
|
23
|
-
if (!extraction || extraction.contract !== "hia-htmdoc-extraction") {
|
|
63
|
+
if (!extraction || extraction.contract !== "hia-htmdoc-extraction" || !["0.1.0-draft", "1.0.0"].includes(extraction.contractVersion)) {
|
|
24
64
|
throw new Error("Expected hia-htmdoc-extraction artifact.");
|
|
25
65
|
}
|
|
26
66
|
|
|
@@ -35,10 +75,16 @@ export function createHtmlDocumentationSourceMap(options = {}) {
|
|
|
35
75
|
const sourcesContentPolicy = normalizeSourcesContentPolicy(
|
|
36
76
|
options.sourcesContentPolicy ?? extraction.sourceMap?.sourcesContentPolicy ?? "none"
|
|
37
77
|
);
|
|
78
|
+
// <lang><zh-CN>只接受本提取器且无 parse5 恢复诊断的 HTML 分支为实测精度;CEM 与外来提取件均保守标未知。</zh-CN><en>Only this extractor's HTML branch without parse5 recovery diagnostics receives proven precision; CEM and external extraction artifacts stay unknown.</en></lang>
|
|
79
|
+
const provenParse5 = extraction.source?.kind === "html"
|
|
80
|
+
&& ["0.1.0-draft", "1.0.0"].includes(extraction.contractVersion)
|
|
81
|
+
&& extraction.producer?.name === "@hia-doc/html-doc-extractor"
|
|
82
|
+
&& extraction.metadata?.parser?.name === "parse5"
|
|
83
|
+
&& !extraction.diagnostics?.some((diagnostic) => typeof diagnostic?.code === "string" && diagnostic.code.startsWith("HTML_PARSE_"));
|
|
38
84
|
|
|
39
85
|
return {
|
|
40
86
|
contract: "doc-source-map",
|
|
41
|
-
contractVersion: "
|
|
87
|
+
contractVersion: "1.1.0",
|
|
42
88
|
id: options.id ?? `docmap:htmdoc:${slug(sourcePath)}`,
|
|
43
89
|
producer: {
|
|
44
90
|
name: "@hia-doc/html-doc-source-map",
|
|
@@ -109,9 +155,16 @@ export function createHtmlDocumentationSourceMap(options = {}) {
|
|
|
109
155
|
: {}),
|
|
110
156
|
sourceRefs: [{
|
|
111
157
|
sourceId,
|
|
112
|
-
|
|
158
|
+
...(symbol.source?.range ? {
|
|
159
|
+
range: symbol.source.range,
|
|
160
|
+
rangeConvention: provenParse5 && hasCompleteColumns(symbol.source.range)
|
|
161
|
+
? { ...PARSE5_RANGE_CONVENTION }
|
|
162
|
+
: { ...UNKNOWN_RANGE_CONVENTION }
|
|
163
|
+
} : {}),
|
|
113
164
|
rangeSource: extraction.source?.kind === "custom-elements-manifest" ? "adapter" : "parser",
|
|
114
|
-
confidence:
|
|
165
|
+
confidence: extraction.source?.kind === "custom-elements-manifest" && symbol.source?.range
|
|
166
|
+
? "low"
|
|
167
|
+
: symbol.source?.range ? "high" : "medium"
|
|
115
168
|
}],
|
|
116
169
|
artifactRefs: [
|
|
117
170
|
{
|
|
@@ -144,10 +197,21 @@ export function createHtmlDocumentationSourceMap(options = {}) {
|
|
|
144
197
|
};
|
|
145
198
|
}
|
|
146
199
|
|
|
200
|
+
/**
|
|
201
|
+
* @param {unknown} range <lang><zh-CN>上游给出的可选范围。</zh-CN><en>Optional upstream range.</en></lang>
|
|
202
|
+
* @returns {boolean} <lang><zh-CN>起止列均为一基安全整数时为真。</zh-CN><en>True when both columns are one-based safe integers.</en></lang>
|
|
203
|
+
* @lang zh-CN 只有列精度完整的引用才能声明 UTF-16 单位;缺列时保留未知而不补造坐标。
|
|
204
|
+
* @lang en Only column-complete references may claim UTF-16 units; missing columns remain unknown without fabricated positions.
|
|
205
|
+
*/
|
|
206
|
+
function hasCompleteColumns(range) {
|
|
207
|
+
return Number.isSafeInteger(range?.start?.column) && range.start.column > 0
|
|
208
|
+
&& Number.isSafeInteger(range?.end?.column) && range.end.column > 0;
|
|
209
|
+
}
|
|
210
|
+
|
|
147
211
|
function normalizeSafePath(value) {
|
|
148
212
|
const normalized = String(value).replaceAll("\\", "/");
|
|
149
213
|
if (!normalized || normalized.startsWith("/") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(normalized) || normalized.split("/").includes("..")) {
|
|
150
|
-
throw new
|
|
214
|
+
throw new TypeError("Unsafe doc-source-map path.");
|
|
151
215
|
}
|
|
152
216
|
return normalized;
|
|
153
217
|
}
|