@hia-doc/jsondoc 0.0.0-stage → 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/LICENSE +21 -0
- package/README.md +61 -2
- package/dist/index.d.ts +8 -0
- package/dist/index.d.ts.map +1 -0
- package/dist/index.js +8 -0
- package/dist/index.js.map +1 -0
- package/dist/producer.d.ts +7 -0
- package/dist/producer.d.ts.map +1 -0
- package/dist/producer.js +176 -0
- package/dist/producer.js.map +1 -0
- package/dist/resource.d.ts +55 -0
- package/dist/resource.d.ts.map +1 -0
- package/dist/resource.js +190 -0
- package/dist/resource.js.map +1 -0
- package/package.json +39 -3
package/LICENSE
ADDED
|
@@ -0,0 +1,21 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 HIA
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
package/README.md
CHANGED
|
@@ -1,3 +1,62 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @hia-doc/jsondoc
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Generate complete JSON resource documentation with HIA core documents and exact source maps. Objects, arrays, unknown fields and scalar lexemes retain their original identities and source positions.
|
|
4
|
+
|
|
5
|
+
中文摘要。本包为JSON资源生成完整值树文档和精确来源。原始数值、特殊键、数组和未知字段均保留,调用方负责授权与公开审查。
|
|
6
|
+
|
|
7
|
+
## Install
|
|
8
|
+
|
|
9
|
+
```sh
|
|
10
|
+
npm install @hia-doc/jsondoc
|
|
11
|
+
```
|
|
12
|
+
|
|
13
|
+
Requires Node.js `^22.23.4 || ^24.22.1`. Package version `1.0.0` is a release candidate in the source distribution. Registry availability follows the release manifest.
|
|
14
|
+
|
|
15
|
+
## In-memory API
|
|
16
|
+
|
|
17
|
+
```js
|
|
18
|
+
import { generateJsonDocumentation } from '@hia-doc/jsondoc';
|
|
19
|
+
|
|
20
|
+
const result = generateJsonDocumentation(
|
|
21
|
+
'{"count":9007199254740993,"values":[true,null]}',
|
|
22
|
+
{ path: 'schemas/example.json', locale: 'en' }
|
|
23
|
+
);
|
|
24
|
+
|
|
25
|
+
// HIA core 1.0.0, doc-source-map 1.1.0, and one unchanged source text.
|
|
26
|
+
console.log(result.document, result.sourceMap, result.sourceText);
|
|
27
|
+
```
|
|
28
|
+
|
|
29
|
+
`locale` explicitly identifies the actual content language. Values retain their original text. Translation is supplied by the resource owner. Each value becomes a symbol and navigation node, identified by the resource path and RFC 6901 JSON Pointer. Scalar `metadata.json.lexeme` preserves numeric precision, exponent spelling, negative zero and original string escaping. Containers retain ordered children. `sourceText` holds the complete original resource once.
|
|
30
|
+
|
|
31
|
+
Source positions use one-based physical CRLF/LF/CR lines, one-based UTF16 columns and exclusive endpoints. The source map declares `utf16-code-unit`. Unicode separators inside JSON strings retain their physical column positions.
|
|
32
|
+
|
|
33
|
+
`$ref` and `$dynamicRef` occurrences retain their original values and pointer context as `lexical-occurrence`. Schema vocabulary evaluation and reference traversal require a separately verified schema-aware consumer. Processing performs no network requests.
|
|
34
|
+
|
|
35
|
+
## SDK producer
|
|
36
|
+
|
|
37
|
+
```js
|
|
38
|
+
import { jsonDocumentationProducer } from '@hia-doc/jsondoc';
|
|
39
|
+
import { runDocumentationProducer } from '@hia-doc/plugin-sdk';
|
|
40
|
+
|
|
41
|
+
const result = await runDocumentationProducer(jsonDocumentationProducer, {
|
|
42
|
+
workspaceRoot: '/authorized/project',
|
|
43
|
+
outputDirectory: '/authorized/output',
|
|
44
|
+
inputs: [{ kind: 'json-resource', path: 'schemas/example.json', locale: 'en' }]
|
|
45
|
+
});
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
The producer writes a unique batch directory containing a core document, a source map and an exact `.source.json` snapshot per input. It processes resources individually, validates the SDK result and commits the batch by renaming its staging directory. Failed batches remove their own staging directory. Concurrent calls and retries retain independent batches. Cancellation is checked before each resource and before commit. The SDK may report late cancellation after a completed filesystem commit, so callers retain responsibility for abandoned successful batches.
|
|
49
|
+
|
|
50
|
+
The existing `hia docs build --project-manifest` loader accepts the built module and `exportName: "jsonDocumentationProducer"` as an explicit producer. The manifest uses `inputs` with the same `kind`, `path` and `locale` fields.
|
|
51
|
+
|
|
52
|
+
## Input and publication boundaries
|
|
53
|
+
|
|
54
|
+
Inputs use strict UTF8 and JSON. Comments, trailing commas, BOMs, duplicate decoded object keys and malformed text are rejected. Each resource is limited to 4MiB, 128 container levels, 250,000 syntax tokens and 100,000 values. Aggregate per-value path and JSON Pointer length is limited to 2,000,000 UTF16 units per resource to bound expansion of deeply nested long keys. Public resource paths are limited to 4,096 UTF16 units. A producer batch accepts at most 100 explicit inputs.
|
|
55
|
+
|
|
56
|
+
File inputs must be single-link regular files beneath the authorized root. Directory junctions, symlinks, traversal and concurrent file changes are rejected. Output parents undergo physical-path checks. Diagnostics omit raw input and operating-system exception text.
|
|
57
|
+
|
|
58
|
+
The complete resource, including examples and unknown fields, appears in the generated content and source snapshot. Callers must review those resources for public disclosure. Runtime authorization comes from the host. API type declarations and package availability do not grant publication permission.
|
|
59
|
+
|
|
60
|
+
## License
|
|
61
|
+
|
|
62
|
+
MIT. JSON parsing uses Microsoft's `jsonc-parser@3.3.1` under MIT.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file
|
|
3
|
+
* @lang zh-CN 通用JSON资源的完整值文档与精确来源入口,调用方负责输入授权和内容公开审核。
|
|
4
|
+
* @lang en Complete-value documentation and exact provenance for generic JSON resources, with callers owning input authorization and publication review.
|
|
5
|
+
*/
|
|
6
|
+
export { generateJsonDocumentation, type JsonDocumentationOptions, type JsonDocumentationResult } from "./resource.js";
|
|
7
|
+
export { jsonDocumentationProducer } from "./producer.js";
|
|
8
|
+
//# sourceMappingURL=index.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,yBAAyB,EAAE,KAAK,wBAAwB,EAAE,KAAK,uBAAuB,EAAE,MAAM,eAAe,CAAC;AACvH,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC"}
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file
|
|
3
|
+
* @lang zh-CN 通用JSON资源的完整值文档与精确来源入口,调用方负责输入授权和内容公开审核。
|
|
4
|
+
* @lang en Complete-value documentation and exact provenance for generic JSON resources, with callers owning input authorization and publication review.
|
|
5
|
+
*/
|
|
6
|
+
export { generateJsonDocumentation } from "./resource.js";
|
|
7
|
+
export { jsonDocumentationProducer } from "./producer.js";
|
|
8
|
+
//# sourceMappingURL=index.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,yBAAyB,EAA+D,MAAM,eAAe,CAAC;AACvH,OAAO,EAAE,yBAAyB,EAAE,MAAM,eAAe,CAAC"}
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { type DocumentationProducer } from "@hia-doc/plugin-sdk";
|
|
2
|
+
/**
|
|
3
|
+
* @lang zh-CN JSON资源生产器。每项输入kind=json-resource,path为根内相对路径,locale为实际正文语言;不跟随链接或执行schema引用。
|
|
4
|
+
* @lang en JSON resource producer. Each input uses kind=json-resource, a root-relative path and actual content locale; links are not followed and schema references are not executed.
|
|
5
|
+
*/
|
|
6
|
+
export declare const jsonDocumentationProducer: DocumentationProducer;
|
|
7
|
+
//# sourceMappingURL=producer.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"producer.d.ts","sourceRoot":"","sources":["../src/producer.ts"],"names":[],"mappings":"AAQA,OAAO,EAGL,KAAK,qBAAqB,EAE3B,MAAM,qBAAqB,CAAC;AAG7B;;;GAGG;AACH,eAAO,MAAM,yBAAyB,EAAE,qBAQtC,CAAC"}
|
package/dist/producer.js
ADDED
|
@@ -0,0 +1,176 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file
|
|
3
|
+
* @lang zh-CN 显式授权JSON输入的SDK生产器,逐资源处理并以独立目录原子提交整批文件。
|
|
4
|
+
* @lang en SDK producer for explicitly authorized JSON inputs, processing per resource and atomically committing each batch in an independent directory.
|
|
5
|
+
*/
|
|
6
|
+
import path from "node:path";
|
|
7
|
+
import { randomUUID } from "node:crypto";
|
|
8
|
+
import { lstat, realpath, open, mkdir, writeFile, rename, rm } from "node:fs/promises";
|
|
9
|
+
import { defineDocumentationProducer, validateDocumentationProducerResult, DOCUMENTATION_PRODUCER_CONTRACT, DOCUMENTATION_PRODUCER_CONTRACT_VERSION, DOCUMENTATION_PRODUCER_RESULT_CONTRACT, DOCUMENTATION_PRODUCER_RESULT_CONTRACT_VERSION } from "@hia-doc/plugin-sdk";
|
|
10
|
+
import { generateJsonDocumentation, assertResourcePath } from "./resource.js";
|
|
11
|
+
/**
|
|
12
|
+
* @lang zh-CN JSON资源生产器。每项输入kind=json-resource,path为根内相对路径,locale为实际正文语言;不跟随链接或执行schema引用。
|
|
13
|
+
* @lang en JSON resource producer. Each input uses kind=json-resource, a root-relative path and actual content locale; links are not followed and schema references are not executed.
|
|
14
|
+
*/
|
|
15
|
+
export const jsonDocumentationProducer = defineDocumentationProducer({
|
|
16
|
+
descriptor: {
|
|
17
|
+
contract: DOCUMENTATION_PRODUCER_CONTRACT, contractVersion: DOCUMENTATION_PRODUCER_CONTRACT_VERSION,
|
|
18
|
+
id: "jsondoc", version: "1.0.0", displayName: "HIA JSON resource documentation",
|
|
19
|
+
inputKinds: ["json-resource"], outputKinds: ["hia-document", "doc-source-map", "json-resource"],
|
|
20
|
+
capabilities: { incremental: false, sourceLinkage: true, watch: false }
|
|
21
|
+
},
|
|
22
|
+
produce: produceJsonResources
|
|
23
|
+
});
|
|
24
|
+
/**
|
|
25
|
+
* @lang zh-CN 逐项读入资源并写暂存目录,全部成功后重命名提交;失败移除本次暂存,保留既有批次。
|
|
26
|
+
* @lang en Reads resources individually into a staging directory, renaming to commit after complete success; failure removes this staging batch while retaining existing batches.
|
|
27
|
+
* @param request <lang><zh-CN>宿主授权的输入根和输出根,最多100项资源。</zh-CN><en>Host-authorized input/output roots and at most 100 resources.</en></lang>
|
|
28
|
+
* @param context <lang><zh-CN>进度及中止上下文。</zh-CN><en>Progress and cancellation context.</en></lang>
|
|
29
|
+
* @returns <lang><zh-CN>完整批次清单或无产物的安全失败。</zh-CN><en>Complete batch manifest or artifact-free safe failure.</en></lang>
|
|
30
|
+
*/
|
|
31
|
+
async function produceJsonResources(request, context) {
|
|
32
|
+
// <lang><zh-CN>冻结本次所用字符串及输入记录的快照,进度回调修改调用方对象不能扩大已验证读取范围。</zh-CN><en>Snapshot this invocation's strings and input records so progress callbacks mutating caller objects cannot expand the validated read scope.</en></lang>
|
|
33
|
+
request = { ...request, inputs: request.inputs.map(input => ({ ...input })) };
|
|
34
|
+
// <lang><zh-CN>随机批次身份隔离重试和并行调用,最终目录及暂存目录都只由当前调用拥有。</zh-CN><en>A random batch identity isolates retries and concurrent calls; this invocation alone owns both final and staging directories.</en></lang>
|
|
35
|
+
const batch = `jsondoc-${randomUUID()}`;
|
|
36
|
+
const staging = path.join(request.outputDirectory, `.${batch}.tmp`);
|
|
37
|
+
let stagingCreated = false;
|
|
38
|
+
const artifacts = [];
|
|
39
|
+
try {
|
|
40
|
+
if (!request.inputs.length || request.inputs.length > 100)
|
|
41
|
+
throw new TypeError();
|
|
42
|
+
const seen = new Set();
|
|
43
|
+
for (const input of request.inputs) {
|
|
44
|
+
if (input.kind !== "json-resource" || typeof input.path !== "string" || typeof input.locale !== "string" || (input.language !== undefined && input.language !== "json"))
|
|
45
|
+
throw new TypeError();
|
|
46
|
+
assertResourcePath(input.path);
|
|
47
|
+
if (seen.has(input.path))
|
|
48
|
+
throw new TypeError();
|
|
49
|
+
seen.add(input.path);
|
|
50
|
+
}
|
|
51
|
+
context.signal?.throwIfAborted();
|
|
52
|
+
// <lang><zh-CN>创建前逐层检查既有目录,避免在重定向父目录下产生任何输出。</zh-CN><en>Check existing directory components before creation to avoid producing output under redirected parents.</en></lang>
|
|
53
|
+
await assertPhysicalPath(request.outputDirectory, true);
|
|
54
|
+
await mkdir(request.outputDirectory, { recursive: true });
|
|
55
|
+
await assertPhysicalPath(request.outputDirectory, false);
|
|
56
|
+
await mkdir(staging);
|
|
57
|
+
stagingCreated = true;
|
|
58
|
+
for (const [index, input] of request.inputs.entries()) {
|
|
59
|
+
context.signal?.throwIfAborted();
|
|
60
|
+
context.reportProgress?.({ phase: "json-resource", current: index, total: request.inputs.length });
|
|
61
|
+
context.signal?.throwIfAborted();
|
|
62
|
+
// <lang><zh-CN>一份原文在当前迭代内读取、解析和写入;前一资源的大值树无需常驻内存。</zh-CN><en>Read, parse and write one original resource within this iteration; large trees from earlier resources need not remain resident.</en></lang>
|
|
63
|
+
const bytes = await readAuthorizedResource(request.workspaceRoot, input.path);
|
|
64
|
+
const result = generateJsonDocumentation(bytes, { path: input.path, locale: input.locale });
|
|
65
|
+
const stem = `resource-${String(index + 1).padStart(3, "0")}`;
|
|
66
|
+
const documentPath = `${stem}.hia.json`;
|
|
67
|
+
const mapPath = `${stem}.doc-source-map.json`;
|
|
68
|
+
const snapshotPath = `${stem}.source.json`;
|
|
69
|
+
// <lang><zh-CN>地图中的产物相对地址以同目录文件为基准,源码身份继续保留授权根内的原路径。</zh-CN><en>Artifact addresses inside the map refer to sibling files, while source identities retain original paths within the authorized root.</en></lang>
|
|
70
|
+
const mappedArtifact = result.sourceMap.artifacts[0];
|
|
71
|
+
mappedArtifact.path = documentPath;
|
|
72
|
+
mappedArtifact.contractRefs[0].path = documentPath;
|
|
73
|
+
result.document.metadata.jsonResource.snapshotPath = snapshotPath;
|
|
74
|
+
await writeFile(path.join(staging, documentPath), JSON.stringify(result.document));
|
|
75
|
+
await writeFile(path.join(staging, mapPath), JSON.stringify(result.sourceMap));
|
|
76
|
+
await writeFile(path.join(staging, snapshotPath), bytes);
|
|
77
|
+
artifacts.push({ id: `${stem}-document`, kind: "hia-document", path: `${batch}/${documentPath}`, contract: "hia-core-document", contractVersion: "1.0.0", format: "json", language: "json", mediaType: "application/json" }, { id: `${stem}-map`, kind: "doc-source-map", path: `${batch}/${mapPath}`, contract: "doc-source-map", contractVersion: "1.1.0", format: "json", language: "json", mediaType: "application/json" }, { id: `${stem}-source`, kind: "json-resource", path: `${batch}/${snapshotPath}`, format: "json", language: "json", mediaType: "application/json" });
|
|
78
|
+
}
|
|
79
|
+
context.signal?.throwIfAborted();
|
|
80
|
+
// <lang><zh-CN>提交文件前执行SDK结果校验,避免文件已提交而声明因格式错误被宿主拒绝。</zh-CN><en>Validate the SDK result before committing files so malformed declarations cannot cause host rejection after files are committed.</en></lang>
|
|
81
|
+
const result = producerResult("success", artifacts);
|
|
82
|
+
if (validateDocumentationProducerResult(result, { descriptor: jsonDocumentationProducer.descriptor }).some(diagnostic => diagnostic.severity === "error"))
|
|
83
|
+
throw new TypeError();
|
|
84
|
+
await assertPhysicalPath(request.outputDirectory, false);
|
|
85
|
+
await rename(staging, path.join(request.outputDirectory, batch));
|
|
86
|
+
stagingCreated = false;
|
|
87
|
+
return result;
|
|
88
|
+
}
|
|
89
|
+
catch {
|
|
90
|
+
// <lang><zh-CN>只清理已由本次调用成功创建的确切暂存目录,输入正文与系统异常原文不进入公开诊断。</zh-CN><en>Clean only the exact staging directory successfully created by this invocation; neither input bodies nor raw system exceptions enter public diagnostics.</en></lang>
|
|
91
|
+
if (stagingCreated)
|
|
92
|
+
await rm(staging, { recursive: true, force: true });
|
|
93
|
+
return producerResult("failed", []);
|
|
94
|
+
}
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* @lang zh-CN 创建固定身份的SDK结果,失败文案不回显路径或资源正文。
|
|
98
|
+
* @lang en Creates an SDK result with fixed identity and failures that echo neither paths nor resource bodies.
|
|
99
|
+
* @param status <lang><zh-CN>整个批次的结果。</zh-CN><en>Outcome of the whole batch.</en></lang>
|
|
100
|
+
* @param artifacts <lang><zh-CN>成功提交的文件声明。</zh-CN><en>Declarations for successfully committed files.</en></lang>
|
|
101
|
+
* @returns <lang><zh-CN>SDK1.0.0结果。</zh-CN><en>SDK 1.0.0 result.</en></lang>
|
|
102
|
+
*/
|
|
103
|
+
function producerResult(status, artifacts) {
|
|
104
|
+
return {
|
|
105
|
+
contract: DOCUMENTATION_PRODUCER_RESULT_CONTRACT, contractVersion: DOCUMENTATION_PRODUCER_RESULT_CONTRACT_VERSION,
|
|
106
|
+
producer: { id: "jsondoc", version: "1.0.0" }, status, artifacts,
|
|
107
|
+
diagnostics: status === "failed" ? [{ code: "JSONDOC_BATCH_FAILED", severity: "error", message: "JSON resource batch failed validation, cancellation or file processing." }] : []
|
|
108
|
+
};
|
|
109
|
+
}
|
|
110
|
+
/**
|
|
111
|
+
* @lang zh-CN 逐层拒绝符号链接与目录联接,可选允许尚未创建的目录后缀。
|
|
112
|
+
* @lang en Rejects symlinks and junctions component by component, optionally allowing directory suffixes that do not yet exist.
|
|
113
|
+
* @param target <lang><zh-CN>宿主授权的绝对路径。</zh-CN><en>Host-authorized absolute path.</en></lang>
|
|
114
|
+
* @param allowMissing <lang><zh-CN>创建输出目录前允许缺省后缀。</zh-CN><en>Allows missing suffixes before output-directory creation.</en></lang>
|
|
115
|
+
* @throws {Error} <lang><zh-CN>重定向、非目录父项或文件系统错误。</zh-CN><en>Redirects, nondirectory parents or filesystem errors.</en></lang>
|
|
116
|
+
*/
|
|
117
|
+
async function assertPhysicalPath(target, allowMissing) {
|
|
118
|
+
// <lang><zh-CN>从卷根开始检查原绝对路径的全部组件,不能用realpath结果替代对链接本身的检查。</zh-CN><en>Check every component of the original absolute path from its volume root; resolving realpath cannot replace inspecting links themselves.</en></lang>
|
|
119
|
+
let current = path.parse(target).root;
|
|
120
|
+
const segments = path.relative(current, target).split(path.sep).filter(Boolean);
|
|
121
|
+
for (const [index, segment] of segments.entries()) {
|
|
122
|
+
current = path.join(current, segment);
|
|
123
|
+
try {
|
|
124
|
+
const state = await lstat(current);
|
|
125
|
+
if (state.isSymbolicLink() || (index < segments.length - 1 && !state.isDirectory()))
|
|
126
|
+
throw new TypeError("JSON resource physical path is invalid.");
|
|
127
|
+
}
|
|
128
|
+
catch (error) {
|
|
129
|
+
if (allowMissing && error.code === "ENOENT")
|
|
130
|
+
return;
|
|
131
|
+
throw error;
|
|
132
|
+
}
|
|
133
|
+
}
|
|
134
|
+
}
|
|
135
|
+
/**
|
|
136
|
+
* @lang zh-CN 从显式授权根读取有界单链接文件,并在打开及读取后核对物理身份。
|
|
137
|
+
* @lang en Reads a bounded single-link file from an explicitly authorized root, checking physical identity after opening and reading.
|
|
138
|
+
* @param root <lang><zh-CN>宿主授权根,先解析为物理目录。</zh-CN><en>Host-authorized root, first resolved to a physical directory.</en></lang>
|
|
139
|
+
* @param relative <lang><zh-CN>已校验的公开相对路径。</zh-CN><en>Validated public relative path.</en></lang>
|
|
140
|
+
* @returns <lang><zh-CN>最多4MiB的独立原始字节。</zh-CN><en>Independent original bytes, at most 4MiB.</en></lang>
|
|
141
|
+
* @throws {Error} <lang><zh-CN>链接、路径重定向、并发变更或超限。</zh-CN><en>Links, redirects, concurrent changes or exceeded limits.</en></lang>
|
|
142
|
+
*/
|
|
143
|
+
async function readAuthorizedResource(root, relative) {
|
|
144
|
+
assertResourcePath(relative);
|
|
145
|
+
const base = await realpath(root);
|
|
146
|
+
const file = path.join(base, relative);
|
|
147
|
+
await assertPhysicalPath(file, false);
|
|
148
|
+
const before = await lstat(file);
|
|
149
|
+
if (!before.isFile() || before.nlink !== 1 || before.size > 4 * 1024 * 1024)
|
|
150
|
+
throw new TypeError("JSON resource physical file is invalid.");
|
|
151
|
+
const handle = await open(file, "r");
|
|
152
|
+
try {
|
|
153
|
+
const opened = await handle.stat();
|
|
154
|
+
if (opened.ino !== before.ino || opened.dev !== before.dev)
|
|
155
|
+
throw new TypeError("JSON resource changed while opening.");
|
|
156
|
+
// <lang><zh-CN>额外一字节可检测读入期间增长,禁止readFile随输入无限分配。</zh-CN><en>One extra byte detects growth during reads, avoiding unbounded readFile allocations.</en></lang>
|
|
157
|
+
const buffer = Buffer.alloc(Math.min(before.size + 1, 4 * 1024 * 1024 + 1));
|
|
158
|
+
let count = 0;
|
|
159
|
+
while (count < buffer.length) {
|
|
160
|
+
const read = await handle.read(buffer, count, buffer.length - count, null);
|
|
161
|
+
if (!read.bytesRead)
|
|
162
|
+
break;
|
|
163
|
+
count += read.bytesRead;
|
|
164
|
+
}
|
|
165
|
+
const after = await handle.stat();
|
|
166
|
+
await assertPhysicalPath(file, false);
|
|
167
|
+
const current = await lstat(file);
|
|
168
|
+
if (count !== before.size || after.size !== before.size || after.mtimeMs !== before.mtimeMs || after.ctimeMs !== before.ctimeMs || after.nlink !== 1 || current.ino !== before.ino || current.dev !== before.dev)
|
|
169
|
+
throw new TypeError("JSON resource changed while reading.");
|
|
170
|
+
return Buffer.from(buffer.subarray(0, count));
|
|
171
|
+
}
|
|
172
|
+
finally {
|
|
173
|
+
await handle.close();
|
|
174
|
+
}
|
|
175
|
+
}
|
|
176
|
+
//# sourceMappingURL=producer.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"producer.js","sourceRoot":"","sources":["../src/producer.ts"],"names":[],"mappings":"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"}
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
import { type HiaDocument } from "@hia-doc/core";
|
|
2
|
+
/**
|
|
3
|
+
* @lang zh-CN 显式资源位置和真实正文语言;path为公开安全相对路径,locale由调用方确认。
|
|
4
|
+
* @lang en Explicit resource location and actual content locale; path is public-safe and relative, and callers confirm locale.
|
|
5
|
+
*/
|
|
6
|
+
export interface JsonDocumentationOptions {
|
|
7
|
+
/**
|
|
8
|
+
* @lang zh-CN 公开安全相对路径,也是稳定资源身份的来源;最大4096个UTF16单位。
|
|
9
|
+
* @lang en Public-safe relative path defining stable resource identity, at most 4096 UTF16 units.
|
|
10
|
+
*/
|
|
11
|
+
path: string;
|
|
12
|
+
/**
|
|
13
|
+
* @lang zh-CN 调用方确认的实际正文语言,未分类可显式使用und;无隐式翻译。
|
|
14
|
+
* @lang en Caller-confirmed actual content locale; und explicitly marks unclassified content, with no implicit translation.
|
|
15
|
+
*/
|
|
16
|
+
locale: string;
|
|
17
|
+
}
|
|
18
|
+
/**
|
|
19
|
+
* @lang zh-CN 核心1.0.0文档、源码映射1.1.0与单份原文;调用方负责存储、授权和公开审查。
|
|
20
|
+
* @lang en Core 1.0.0 document, source map 1.1.0 and a single original text, with callers owning storage, authorization and publication review.
|
|
21
|
+
*/
|
|
22
|
+
export interface JsonDocumentationResult {
|
|
23
|
+
/**
|
|
24
|
+
* @lang zh-CN 每个JSON值对应一个符号的核心文档,容器不嵌入重复原文。
|
|
25
|
+
* @lang en Core document with one symbol per JSON value, without repeated container source bodies.
|
|
26
|
+
*/
|
|
27
|
+
document: HiaDocument;
|
|
28
|
+
/**
|
|
29
|
+
* @lang zh-CN 现有1.1.0映射,逐值声明排除终点及UTF16单位,可交现有reader验证。
|
|
30
|
+
* @lang en Existing 1.1.0 mapping declaring exclusive UTF16 ranges per value, consumable by the existing reader.
|
|
31
|
+
*/
|
|
32
|
+
sourceMap: Record<string, unknown>;
|
|
33
|
+
/**
|
|
34
|
+
* @lang zh-CN 单份原始UTF8正文,调用方负责其存储和公开权限。
|
|
35
|
+
* @lang en One original UTF8 text, with callers owning storage and publication authority.
|
|
36
|
+
*/
|
|
37
|
+
sourceText: string;
|
|
38
|
+
}
|
|
39
|
+
/**
|
|
40
|
+
* @lang zh-CN 为一份已授权JSON生成所有值的层级文档,标量保存原始词法;容器正文集中于返回的sourceText。
|
|
41
|
+
* @lang en Generates hierarchical documentation for every value of authorized JSON, retaining raw scalar lexemes and centralizing container text in sourceText.
|
|
42
|
+
* @param input <lang><zh-CN>严格UTF8字节或可无损UTF8往返的原文,最多4MiB。</zh-CN><en>Strict UTF8 bytes or losslessly UTF8-round-trippable text, at most 4MiB.</en></lang>
|
|
43
|
+
* @param options <lang><zh-CN>公开相对路径与实际语言,不从路径推断授权。</zh-CN><en>Public relative path and actual locale, without inferring authorization from the path.</en></lang>
|
|
44
|
+
* @returns <lang><zh-CN>确定性文档、逐值来源和单份原文;引用只标记词法出现,未宣称schema求值。</zh-CN><en>Deterministic document, per-value provenance and one original text; references mark lexical occurrences without claiming schema evaluation.</en></lang>
|
|
45
|
+
* @throws {TypeError} <lang><zh-CN>路径、语言、UTF8、严格JSON、重复解码键或资源预算无效;消息不含输入正文。</zh-CN><en>Invalid path, locale, UTF8, strict JSON, duplicate decoded keys or resource budgets; messages omit input content.</en></lang>
|
|
46
|
+
*/
|
|
47
|
+
export declare function generateJsonDocumentation(input: string | Uint8Array, options: JsonDocumentationOptions): JsonDocumentationResult;
|
|
48
|
+
/**
|
|
49
|
+
* @lang zh-CN 校验资源公开相对路径,拒绝平台路径、编码分隔符及跳转片段。
|
|
50
|
+
* @lang en Validates public relative resource paths, rejecting platform paths, encoded separators and traversal segments.
|
|
51
|
+
* @param value <lang><zh-CN>调用方提供的路径。</zh-CN><en>Caller-provided path.</en></lang>
|
|
52
|
+
* @throws {TypeError} <lang><zh-CN>路径不安全。</zh-CN><en>Unsafe path.</en></lang>
|
|
53
|
+
*/
|
|
54
|
+
export declare function assertResourcePath(value: string): void;
|
|
55
|
+
//# sourceMappingURL=resource.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"AAOA,OAAO,EAAqB,KAAK,WAAW,EAAwD,MAAM,eAAe,CAAC;AAG1H;;;GAGG;AACH,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,MAAM,EAAE,MAAM,CAAC;CAChB;AAED;;;GAGG;AACH,MAAM,WAAW,uBAAuB;IACtC;;;OAGG;IACH,QAAQ,EAAE,WAAW,CAAC;IACtB;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC;;;OAGG;IACH,UAAU,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,UAAU,EAAE,OAAO,EAAE,wBAAwB,GAAG,uBAAuB,CA2GhI;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI,CAEtD"}
|
package/dist/resource.js
ADDED
|
@@ -0,0 +1,190 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* @file
|
|
3
|
+
* @lang zh-CN 严格JSON值树投影,原始数值、Pointer和物理UTF16范围均保留;不执行输入或读取网络。
|
|
4
|
+
* @lang en Strict JSON value-tree projection retaining raw numbers, pointers and physical UTF16 ranges, without executing input or accessing networks.
|
|
5
|
+
*/
|
|
6
|
+
import { createHash } from "node:crypto";
|
|
7
|
+
import { createScanner, parseTree } from "jsonc-parser";
|
|
8
|
+
import { createHiaDocument } from "@hia-doc/core";
|
|
9
|
+
import { DOC_SOURCE_MAP_CONTRACT, DOC_SOURCE_MAP_CONTRACT_VERSION } from "@hia-doc/source-linkage";
|
|
10
|
+
/**
|
|
11
|
+
* @lang zh-CN 为一份已授权JSON生成所有值的层级文档,标量保存原始词法;容器正文集中于返回的sourceText。
|
|
12
|
+
* @lang en Generates hierarchical documentation for every value of authorized JSON, retaining raw scalar lexemes and centralizing container text in sourceText.
|
|
13
|
+
* @param input <lang><zh-CN>严格UTF8字节或可无损UTF8往返的原文,最多4MiB。</zh-CN><en>Strict UTF8 bytes or losslessly UTF8-round-trippable text, at most 4MiB.</en></lang>
|
|
14
|
+
* @param options <lang><zh-CN>公开相对路径与实际语言,不从路径推断授权。</zh-CN><en>Public relative path and actual locale, without inferring authorization from the path.</en></lang>
|
|
15
|
+
* @returns <lang><zh-CN>确定性文档、逐值来源和单份原文;引用只标记词法出现,未宣称schema求值。</zh-CN><en>Deterministic document, per-value provenance and one original text; references mark lexical occurrences without claiming schema evaluation.</en></lang>
|
|
16
|
+
* @throws {TypeError} <lang><zh-CN>路径、语言、UTF8、严格JSON、重复解码键或资源预算无效;消息不含输入正文。</zh-CN><en>Invalid path, locale, UTF8, strict JSON, duplicate decoded keys or resource budgets; messages omit input content.</en></lang>
|
|
17
|
+
*/
|
|
18
|
+
export function generateJsonDocumentation(input, options) {
|
|
19
|
+
assertResourcePath(options?.path);
|
|
20
|
+
if (typeof options.locale !== "string" || !/^[a-zA-Z]{2,8}(?:-[a-zA-Z0-9]{1,8})*$/.test(options.locale))
|
|
21
|
+
throw new TypeError("JSON resource locale is invalid.");
|
|
22
|
+
if (typeof input !== "string" && !(input instanceof Uint8Array))
|
|
23
|
+
throw new TypeError("JSON resource input is invalid.");
|
|
24
|
+
// <lang><zh-CN>先限制调用者输入,避免为超限数据建立额外字节副本;正文为本次调用快照。</zh-CN><en>Bound caller input before allocating another byte copy; text is an invocation-local snapshot.</en></lang>
|
|
25
|
+
if ((typeof input === "string" ? Buffer.byteLength(input) : input.byteLength) > 4 * 1024 * 1024)
|
|
26
|
+
throw new TypeError("JSON resource byte limit exceeded.");
|
|
27
|
+
const bytes = Buffer.from(input);
|
|
28
|
+
const text = decodeResource(bytes, typeof input === "string" ? input : undefined);
|
|
29
|
+
checkSyntaxBudget(text);
|
|
30
|
+
// <lang><zh-CN>原生严格解析负责语法拒绝,其数值结果不用于文档,避免IEEE754精度损失。</zh-CN><en>Native strict parsing rejects grammar errors; its numeric result never supplies documentation, avoiding IEEE754 precision loss.</en></lang>
|
|
31
|
+
try {
|
|
32
|
+
JSON.parse(text);
|
|
33
|
+
}
|
|
34
|
+
catch {
|
|
35
|
+
throw new TypeError("JSON resource must contain strict JSON.");
|
|
36
|
+
}
|
|
37
|
+
const errors = [];
|
|
38
|
+
const root = parseTree(text, errors, { disallowComments: true, allowTrailingComma: false, allowEmptyContent: false });
|
|
39
|
+
if (!root || errors.length)
|
|
40
|
+
throw new TypeError("JSON resource syntax tree is invalid.");
|
|
41
|
+
// <lang><zh-CN>资源路径决定稳定身份,正文摘要单独描述内容版本,符号身份可在值变化后保持。</zh-CN><en>The resource path determines stable identity, while a separate digest identifies content versions so value changes retain symbol identity.</en></lang>
|
|
42
|
+
const identity = createHash("sha256").update(options.path).digest("hex");
|
|
43
|
+
const sourceId = `json-source:${identity}`;
|
|
44
|
+
const documentId = `json-document:${identity}`;
|
|
45
|
+
const symbols = [];
|
|
46
|
+
const entries = [];
|
|
47
|
+
// <lang><zh-CN>总Pointer预算约束深层长键重复展开,避免小输入形成过大的身份和导航字符串。</zh-CN><en>An aggregate pointer budget bounds repeated expansion of deeply nested long keys, preventing small inputs from creating oversized identity and navigation strings.</en></lang>
|
|
48
|
+
let identityUnits = 0;
|
|
49
|
+
const lineStarts = [0];
|
|
50
|
+
// <lang><zh-CN>仅JSON物理换行CRLF/LF/CR改变行号,字符串内Unicode分隔符保留列位置。</zh-CN><en>Only physical JSON CRLF/LF/CR newlines change line numbers; Unicode separators inside strings retain column positions.</en></lang>
|
|
51
|
+
for (const match of text.matchAll(/\r\n|\r|\n/g))
|
|
52
|
+
lineStarts.push(match.index + match[0].length);
|
|
53
|
+
/**
|
|
54
|
+
* @lang zh-CN 二分查找物理行首,将UTF16偏移转换为一基行列。
|
|
55
|
+
* @lang en Binary-searches physical line starts to convert UTF16 offsets into one-based coordinates.
|
|
56
|
+
* @param offset <lang><zh-CN>当前原文内的UTF16偏移。</zh-CN><en>UTF16 offset in the current original text.</en></lang>
|
|
57
|
+
* @returns <lang><zh-CN>一基行列。</zh-CN><en>One-based line and column.</en></lang>
|
|
58
|
+
*/
|
|
59
|
+
function positionAt(offset) {
|
|
60
|
+
// <lang><zh-CN>查找窗口逐步收缩到不晚于目标偏移的最后行首。</zh-CN><en>The search window shrinks to the last line start at or before the target offset.</en></lang>
|
|
61
|
+
let lower = 0;
|
|
62
|
+
let upper = lineStarts.length - 1;
|
|
63
|
+
while (lower < upper) {
|
|
64
|
+
const middle = Math.floor((lower + upper + 1) / 2);
|
|
65
|
+
if (lineStarts[middle] <= offset)
|
|
66
|
+
lower = middle;
|
|
67
|
+
else
|
|
68
|
+
upper = middle - 1;
|
|
69
|
+
}
|
|
70
|
+
return { line: lower + 1, column: offset - lineStarts[lower] + 1 };
|
|
71
|
+
}
|
|
72
|
+
/**
|
|
73
|
+
* @lang zh-CN 逐值建立节点、标量原文和来源,解码键仅作为数据参与Pointer构造。
|
|
74
|
+
* @lang en Builds per-value nodes, scalar source and provenance, treating decoded keys solely as data when constructing pointers.
|
|
75
|
+
* @param node <lang><zh-CN>jsonc-parser原始值节点。</zh-CN><en>Original jsonc-parser value node.</en></lang>
|
|
76
|
+
* @param pointer <lang><zh-CN>当前RFC6901 Pointer。</zh-CN><en>Current RFC6901 pointer.</en></lang>
|
|
77
|
+
* @param name <lang><zh-CN>原始键、数组下标或根路径。</zh-CN><en>Original key, array index or root path.</en></lang>
|
|
78
|
+
* @param parentId <lang><zh-CN>父值符号身份,根节点省略。</zh-CN><en>Parent value symbol identity, omitted for the root.</en></lang>
|
|
79
|
+
* @returns <lang><zh-CN>与符号树对应的导航节点。</zh-CN><en>Navigation node corresponding to the symbol tree.</en></lang>
|
|
80
|
+
* @throws {TypeError} <lang><zh-CN>重复键、无效AST或值数量超限。</zh-CN><en>Duplicate keys, invalid AST or exceeded value count.</en></lang>
|
|
81
|
+
*/
|
|
82
|
+
function visit(node, pointer, name, parentId) {
|
|
83
|
+
identityUnits += pointer.length + options.path.length;
|
|
84
|
+
if (identityUnits > 2000000)
|
|
85
|
+
throw new TypeError("JSON resource pointer budget exceeded.");
|
|
86
|
+
if (symbols.length >= 100000 || node.type === "property")
|
|
87
|
+
throw new TypeError("JSON resource value limit or structure is invalid.");
|
|
88
|
+
// <lang><zh-CN>来源范围与原文偏移共用排除终点,标量词法直接切片,容器不重复复制正文。</zh-CN><en>Source ranges and original offsets share exclusive endpoints; scalar lexemes are sliced directly while container bodies are never duplicated.</en></lang>
|
|
89
|
+
const id = `json:${identity}:${pointer}`;
|
|
90
|
+
const endOffset = node.offset + node.length;
|
|
91
|
+
const range = { start: positionAt(node.offset), end: positionAt(endOffset) };
|
|
92
|
+
const scalar = node.type !== "object" && node.type !== "array";
|
|
93
|
+
const json = { pointer, type: node.type, startOffset: node.offset, endOffset };
|
|
94
|
+
if (scalar)
|
|
95
|
+
json.lexeme = text.slice(node.offset, endOffset);
|
|
96
|
+
// <lang><zh-CN>引用键的出现与schema词汇表求值分开保留,const等数据上下文不会被误作可跳转schema。</zh-CN><en>Reference-key occurrences are retained separately from schema vocabulary evaluation so data contexts such as const never become guessed schema links.</en></lang>
|
|
97
|
+
if ((name === "$ref" || name === "$dynamicRef") && node.type === "string")
|
|
98
|
+
json.reference = { keyword: name, value: node.value, semantics: "lexical-occurrence" };
|
|
99
|
+
symbols.push({
|
|
100
|
+
id, name: name || '""', kind: `json-${node.type}`, ...(parentId ? { parentId } : {}), longname: `${options.path}#${pointer}`,
|
|
101
|
+
signature: scalar ? `${name || '""'} = ${json.lexeme}` : `${name || '""'} (${node.type})`,
|
|
102
|
+
source: { model: "hia-source", modelVersion: "1.0.0", mode: "link", definedIn: { kind: "defined-in", relativePath: options.path, language: "json", position: range.start, range } },
|
|
103
|
+
metadata: { json }
|
|
104
|
+
});
|
|
105
|
+
entries.push({
|
|
106
|
+
id: `entry:${id}`, kind: "symbol", symbolId: id, symbolKind: `json-${node.type}`,
|
|
107
|
+
sourceRefs: [{ sourceId, range, rangeConvention: { endBoundary: "exclusive", columnUnit: "utf16-code-unit" }, rangeSource: "parser", rangeSourceDetail: "jsonc-parser@3.3.1", confidence: "high" }],
|
|
108
|
+
artifactRefs: [{ artifactId: documentId, selector: id, rangeSource: "adapter", confidence: "high" }], diagnostics: []
|
|
109
|
+
});
|
|
110
|
+
// <lang><zh-CN>每个对象独立检查解码键唯一性,Map/Set避免特殊名称触发对象原型行为。</zh-CN><en>Each object checks decoded-key uniqueness independently, using Map/Set to avoid special-name prototype behavior.</en></lang>
|
|
111
|
+
const children = [];
|
|
112
|
+
const names = new Set();
|
|
113
|
+
for (const [index, child] of (node.children ?? []).entries()) {
|
|
114
|
+
const key = node.type === "object" ? child.children?.[0]?.value : String(index);
|
|
115
|
+
const value = node.type === "object" ? child.children?.[1] : child;
|
|
116
|
+
if (typeof key !== "string" || !value || names.has(key))
|
|
117
|
+
throw new TypeError("JSON resource has duplicate keys or an invalid tree.");
|
|
118
|
+
names.add(key);
|
|
119
|
+
const escaped = key.replaceAll("~", "~0").replaceAll("/", "~1");
|
|
120
|
+
children.push(visit(value, `${pointer}/${escaped}`, key, id));
|
|
121
|
+
}
|
|
122
|
+
return { id: `node:${id}`, kind: node.type, title: name || '""', symbolIds: [id], ...(children.length ? { children } : {}) };
|
|
123
|
+
}
|
|
124
|
+
// <lang><zh-CN>单份资源摘要记录原始UTF8字节;快照由调用方单独存储,核心文档不嵌入重复源码。</zh-CN><en>The single resource digest covers original UTF8 bytes; callers store the snapshot separately, and core documents embed no repeated source bodies.</en></lang>
|
|
125
|
+
const navigation = visit(root, "", options.path);
|
|
126
|
+
const sha256 = createHash("sha256").update(bytes).digest("hex");
|
|
127
|
+
const document = createHiaDocument({ id: documentId, title: options.path, defaultLocale: options.locale, locales: [options.locale], nodes: [navigation], symbols, metadata: { jsonResource: { path: options.path, sha256, byteLength: bytes.length } } });
|
|
128
|
+
return {
|
|
129
|
+
document, sourceText: text,
|
|
130
|
+
sourceMap: {
|
|
131
|
+
contract: DOC_SOURCE_MAP_CONTRACT, contractVersion: DOC_SOURCE_MAP_CONTRACT_VERSION, id: `map:${identity}`,
|
|
132
|
+
producer: { name: "@hia-doc/jsondoc", version: "1.0.0" },
|
|
133
|
+
artifacts: [{ id: documentId, kind: "hia-document", language: "json", contractRefs: [{ contract: "hia-core-document", contractVersion: "1.0.0", path: "document.hia.json" }] }],
|
|
134
|
+
sources: [{ id: sourceId, kind: "source", path: options.path, language: "json", sourcesContentPolicy: "none" }],
|
|
135
|
+
sourceMaps: [], chains: [], entries, privacy: { sourcesContentPolicy: "none" }, diagnostics: []
|
|
136
|
+
}
|
|
137
|
+
};
|
|
138
|
+
}
|
|
139
|
+
/**
|
|
140
|
+
* @lang zh-CN 校验资源公开相对路径,拒绝平台路径、编码分隔符及跳转片段。
|
|
141
|
+
* @lang en Validates public relative resource paths, rejecting platform paths, encoded separators and traversal segments.
|
|
142
|
+
* @param value <lang><zh-CN>调用方提供的路径。</zh-CN><en>Caller-provided path.</en></lang>
|
|
143
|
+
* @throws {TypeError} <lang><zh-CN>路径不安全。</zh-CN><en>Unsafe path.</en></lang>
|
|
144
|
+
*/
|
|
145
|
+
export function assertResourcePath(value) {
|
|
146
|
+
if (typeof value !== "string" || !value || value.length > 4096 || /[\\:%?#\u0000-\u001f\u007f]/u.test(value) || value.split("/").some(part => !part || part === "." || part === ".."))
|
|
147
|
+
throw new TypeError("JSON resource path is invalid.");
|
|
148
|
+
}
|
|
149
|
+
/**
|
|
150
|
+
* @lang zh-CN 严格解码UTF8并保持BOM,由后续严格JSON语法拒绝BOM。
|
|
151
|
+
* @lang en Strictly decodes UTF8 while retaining BOM for rejection by strict JSON grammar.
|
|
152
|
+
* @param bytes <lang><zh-CN>当前字节快照。</zh-CN><en>Current byte snapshot.</en></lang>
|
|
153
|
+
* @param original <lang><zh-CN>可选字符串输入,用于无损往返核对。</zh-CN><en>Optional string input for lossless round-trip checking.</en></lang>
|
|
154
|
+
* @returns <lang><zh-CN>精确保留的原文。</zh-CN><en>Exactly retained original text.</en></lang>
|
|
155
|
+
* @throws {TypeError} <lang><zh-CN>UTF8或往返无效。</zh-CN><en>Invalid UTF8 or round trip.</en></lang>
|
|
156
|
+
*/
|
|
157
|
+
function decodeResource(bytes, original) {
|
|
158
|
+
try {
|
|
159
|
+
// <lang><zh-CN>不替换无效字节,也不静默丢弃BOM或孤立代理项。</zh-CN><en>Never replace invalid bytes or silently discard BOMs or lone surrogates.</en></lang>
|
|
160
|
+
const text = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true }).decode(bytes);
|
|
161
|
+
if (original !== undefined && text !== original)
|
|
162
|
+
throw new TypeError();
|
|
163
|
+
return text;
|
|
164
|
+
}
|
|
165
|
+
catch {
|
|
166
|
+
throw new TypeError("JSON resource must contain valid UTF8.");
|
|
167
|
+
}
|
|
168
|
+
}
|
|
169
|
+
/**
|
|
170
|
+
* @lang zh-CN AST建立前限制扫描token及容器深度,避免病理输入耗尽栈或内存。
|
|
171
|
+
* @lang en Bounds scanned tokens and container depth before AST construction to avoid stack or memory exhaustion.
|
|
172
|
+
* @param text <lang><zh-CN>已解码原文。</zh-CN><en>Decoded original text.</en></lang>
|
|
173
|
+
* @throws {TypeError} <lang><zh-CN>超过250000 token或128层。</zh-CN><en>More than 250000 tokens or 128 container levels.</en></lang>
|
|
174
|
+
*/
|
|
175
|
+
function checkSyntaxBudget(text) {
|
|
176
|
+
// <lang><zh-CN>扫描器仅测预算,严格语法由后续JSON.parse及parseTree共同验证。</zh-CN><en>The scanner measures budgets only; subsequent JSON.parse and parseTree jointly validate strict grammar.</en></lang>
|
|
177
|
+
const scanner = createScanner(text, true);
|
|
178
|
+
let tokens = 0;
|
|
179
|
+
let depth = 0;
|
|
180
|
+
for (let token = scanner.scan(); token !== 17 /* SyntaxKind.EOF */; token = scanner.scan()) {
|
|
181
|
+
tokens++;
|
|
182
|
+
if (token === 1 /* SyntaxKind.OpenBraceToken */ || token === 3 /* SyntaxKind.OpenBracketToken */)
|
|
183
|
+
depth++;
|
|
184
|
+
if (token === 2 /* SyntaxKind.CloseBraceToken */ || token === 4 /* SyntaxKind.CloseBracketToken */)
|
|
185
|
+
depth--;
|
|
186
|
+
if (tokens > 250000 || depth > 128)
|
|
187
|
+
throw new TypeError("JSON resource syntax budget exceeded.");
|
|
188
|
+
}
|
|
189
|
+
}
|
|
190
|
+
//# sourceMappingURL=resource.js.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"resource.js","sourceRoot":"","sources":["../src/resource.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,42 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hia-doc/jsondoc",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
3
|
+
"version": "1.0.0-rc.1",
|
|
4
|
+
"description": "Lossless JSON resource documentation and exact source provenance for HIA.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"repository": {
|
|
7
|
+
"type": "git",
|
|
8
|
+
"url": "git+https://github.com/mandolin/HIA-Documentation.git",
|
|
9
|
+
"directory": "packages/jsondoc"
|
|
10
|
+
},
|
|
11
|
+
"engines": {
|
|
12
|
+
"node": "^22.23.4 || ^24.22.1"
|
|
13
|
+
},
|
|
14
|
+
"type": "module",
|
|
15
|
+
"main": "./dist/index.js",
|
|
16
|
+
"types": "./dist/index.d.ts",
|
|
17
|
+
"exports": {
|
|
18
|
+
".": {
|
|
19
|
+
"types": "./dist/index.d.ts",
|
|
20
|
+
"import": "./dist/index.js"
|
|
21
|
+
}
|
|
22
|
+
},
|
|
23
|
+
"files": [
|
|
24
|
+
"dist",
|
|
25
|
+
"README.md",
|
|
26
|
+
"LICENSE"
|
|
27
|
+
],
|
|
28
|
+
"publishConfig": {
|
|
29
|
+
"access": "public"
|
|
30
|
+
},
|
|
31
|
+
"dependencies": {
|
|
32
|
+
"jsonc-parser": "3.3.1",
|
|
33
|
+
"@hia-doc/plugin-sdk": "1.0.0-rc.1",
|
|
34
|
+
"@hia-doc/source-linkage": "1.0.0-rc.1",
|
|
35
|
+
"@hia-doc/core": "1.0.0-rc.1"
|
|
36
|
+
},
|
|
37
|
+
"sideEffects": false,
|
|
38
|
+
"scripts": {
|
|
39
|
+
"build": "tsc -p tsconfig.json",
|
|
40
|
+
"test": "cd ../.. && vitest run packages/jsondoc/src"
|
|
41
|
+
}
|
|
6
42
|
}
|