@hia-doc/dotnetdoc-runner 0.1.12 → 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.
@@ -0,0 +1,12 @@
1
+ {
2
+ "coreContractVersion": "1.0.0",
3
+ "commandContractVersion": "0.1.0-draft",
4
+ "outputs": {
5
+ "description.json": "fa1a0863c14b08ff03efbd452158d10f9a60be0d87c96ba9632603ea190ab943",
6
+ "observations.json": "c809e96f9726ca3f2bc3d91ca2beddc222fcbedd1bc914b3bf68d65aee21e4f6",
7
+ "document.hia.json": "470737974bc4ce1035d58d317710a26c34f374637e7eba87cbb44f566a9507e3",
8
+ "command.schema.json": "c291f19d9bdbbd61db167edb9d268af83e7f36ec320263b13e211c798db70c32",
9
+ "document.schema.json": "404d90c3bd2b2b90e4723767c75c3a3bf8e713786a81c9583f7c93f5f4938895",
10
+ "help.mjs": "f614793b1fef696c10bcde356bdc5093526c7487cda7903c20a79274d88bc59b"
11
+ }
12
+ }
@@ -0,0 +1,16 @@
1
+ /**
2
+ * @file
3
+ * @lang zh-CN 由共享命令内容生成的静态帮助,通过commands:build重新生成。
4
+ * @lang en Static help generated from shared command content, regenerated with commands:build.
5
+ */
6
+ /**
7
+ * @lang zh-CN 80列纯文本命令帮助。
8
+ * @lang en 80-column plain-text command help.
9
+ */
10
+ export const DOTNETDOC_HELP_80 = "HIA-Documentation-Sys · hia-dotnetdoc\n生成.NET XML及配置驱动文档\nGenerate .NET XML and configuration-driven documentation\n\n用法 / Usage\n hia-dotnetdoc --config dotnetdoc.config.json\n hia-dotnetdoc [options] <documentation.xml...>\n\n参数 / Options\n -c, --config <path>\n 从JSON配置构造请求。 / Build a request from JSON configuration.\n -o, --out-dir <path>\n 输出相对工作区,直接模式缺省dist/dotnetdoc;直接空字符串指向工作区根。\n Output is workspace-relative and defaults to dist/dotnetdoc in direct mode;\n an empty direct-mode string selects the workspace root.\n --workspace-root <path>\n 直接模式相对调用目录,省略时为当前目录;配置模式忽略。\n Direct mode resolves from cwd and defaults to cwd; ignored in config mode.\n --title <title>\n 仅直接模式,为每个XML输入提供同一标题;省略时沿适配器默认,配置模式忽略。\n Direct mode only, giving every XML input the same title; omission uses\n adapter defaults and config mode ignores it.\n -h, --help\n 输出帮助并退出0。 / Print help and exit 0.\n -v, --version\n 输出运行器版本并退出0。 / Print runner version and exit 0.\n\n位置输入 / Positional inputs\n <documentation.xml...>\n 直接模式至少一个相对工作区的XML输入;配置模式忽略。\n Direct mode requires at least one workspace-relative XML input; ignored in\n config mode.\n\n配置与副作用 / Configuration and effects\n dotnetdoc与hia-dotnetdoc是同一实现的等价调用名,帮助展示规范入口。\n dotnetdoc and hia-dotnetdoc are equivalent names for one implementation; help\n displays the canonical entry.\n 配置模式仅非空out-dir覆盖输出;空字符串保留配置。\n In config mode only a nonempty out-dir overrides output; an empty string\n retains the configuration.\n workspace-root、title及XML位置输入仅用于直接模式,配置模式忽略。\n workspace-root, title and positional XML inputs apply only to direct mode and\n are ignored in config mode.\n 配置路径相对调用目录,配置工作区相对配置目录;直接工作区相对调用目录,输出相对\n 工作区。\n Config paths use cwd and configured workspaces use the config directory;\n direct workspaces use cwd and output uses the workspace.\n 运行会创建目录、覆盖工件并写结果清单;partial或failed可能保留已成功写入。\n Runs create directories, replace artifacts and write a result manifest;\n partial or failed results may retain successful writes.\n Node严格解析先于帮助,未知开关或缺值返回1;重复带值选项取末值,--后作为XML位置\n 输入。\n Node strict parsing precedes help; unknown switches or missing values exit 1.\n Repeated value options use the last value, and tokens after -- are\n positional XML inputs.\n 纯XML抽取无需SDK。配置中的C#抽取或项目源码解析使用.NET10\n SDK/helper,其构建可能按SDK设置进行还原及工作负载清单下载。\n Plain XML extraction needs no SDK. Configured C# extraction or project source\n resolution uses the .NET 10 SDK/helper; its build may restore dependencies\n or download workload manifests according to SDK settings.\n\n退出码 / Exit codes\n 0 成功、帮助或版本 / Success, help or version\n 1 参数、配置或构建失败 / Argument, configuration or build failure\n\n示例 / Example\n hia-dotnetdoc --config dotnetdoc.config.json\n dotnetdoc --title SampleAPI sample.xml\n\n离线完整说明 / Complete offline reference\n @hia-doc/dotnetdoc-runner/README.md\n";
11
+
12
+ /**
13
+ * @lang zh-CN 120列纯文本命令帮助。
14
+ * @lang en 120-column plain-text command help.
15
+ */
16
+ export const DOTNETDOC_HELP_120 = "HIA-Documentation-Sys · hia-dotnetdoc\n生成.NET XML及配置驱动文档\nGenerate .NET XML and configuration-driven documentation\n\n用法 / Usage\n hia-dotnetdoc --config dotnetdoc.config.json\n hia-dotnetdoc [options] <documentation.xml...>\n\n参数 / Options\n -c, --config <path>\n 从JSON配置构造请求。 / Build a request from JSON configuration.\n -o, --out-dir <path>\n 输出相对工作区,直接模式缺省dist/dotnetdoc;直接空字符串指向工作区根。\n Output is workspace-relative and defaults to dist/dotnetdoc in direct mode; an empty direct-mode string selects the\n workspace root.\n --workspace-root <path>\n 直接模式相对调用目录,省略时为当前目录;配置模式忽略。\n Direct mode resolves from cwd and defaults to cwd; ignored in config mode.\n --title <title>\n 仅直接模式,为每个XML输入提供同一标题;省略时沿适配器默认,配置模式忽略。\n Direct mode only, giving every XML input the same title; omission uses adapter defaults and config mode ignores it.\n -h, --help\n 输出帮助并退出0。 / Print help and exit 0.\n -v, --version\n 输出运行器版本并退出0。 / Print runner version and exit 0.\n\n位置输入 / Positional inputs\n <documentation.xml...>\n 直接模式至少一个相对工作区的XML输入;配置模式忽略。\n Direct mode requires at least one workspace-relative XML input; ignored in config mode.\n\n配置与副作用 / Configuration and effects\n dotnetdoc与hia-dotnetdoc是同一实现的等价调用名,帮助展示规范入口。\n dotnetdoc and hia-dotnetdoc are equivalent names for one implementation; help displays the canonical entry.\n 配置模式仅非空out-dir覆盖输出;空字符串保留配置。\n In config mode only a nonempty out-dir overrides output; an empty string retains the configuration.\n workspace-root、title及XML位置输入仅用于直接模式,配置模式忽略。\n workspace-root, title and positional XML inputs apply only to direct mode and are ignored in config mode.\n 配置路径相对调用目录,配置工作区相对配置目录;直接工作区相对调用目录,输出相对工作区。\n Config paths use cwd and configured workspaces use the config directory; direct workspaces use cwd and output uses the\n workspace.\n 运行会创建目录、覆盖工件并写结果清单;partial或failed可能保留已成功写入。\n Runs create directories, replace artifacts and write a result manifest; partial or failed results may retain\n successful writes.\n Node严格解析先于帮助,未知开关或缺值返回1;重复带值选项取末值,--后作为XML位置输入。\n Node strict parsing precedes help; unknown switches or missing values exit 1. Repeated value options use the last\n value, and tokens after -- are positional XML inputs.\n 纯XML抽取无需SDK。配置中的C#抽取或项目源码解析使用.NET10 SDK/helper,其构建可能按SDK设置进行还原及工作负载清单下载。\n Plain XML extraction needs no SDK. Configured C# extraction or project source resolution uses the .NET 10 SDK/helper;\n its build may restore dependencies or download workload manifests according to SDK settings.\n\n退出码 / Exit codes\n 0 成功、帮助或版本 / Success, help or version\n 1 参数、配置或构建失败 / Argument, configuration or build failure\n\n示例 / Example\n hia-dotnetdoc --config dotnetdoc.config.json\n dotnetdoc --title SampleAPI sample.xml\n\n离线完整说明 / Complete offline reference\n @hia-doc/dotnetdoc-runner/README.md\n";
@@ -0,0 +1,104 @@
1
+ [
2
+ {
3
+ "commandId": "hia-dotnetdoc",
4
+ "sourceDigests": {
5
+ "src/cli.mjs": "98bbcbfc17e37feee2e243690ace48fc0f77d1e7c3fdbe6c850e9da83a38d1d7",
6
+ "src/command-content.mjs": "3c7282a7503da5b6c99f3785e6390636a8fc6be4b8c126f84201e94211e9db43",
7
+ "src/metadata.mjs": "6d27ddcfccfdac5e941cf983645b5fac76114383d5df566edbcec999eda37bfb",
8
+ "src/index.mjs": "7bdec377cb2069878db55e7931898b0759b3f69ee7eea39afd052340db2da0a6",
9
+ "src/schema.mjs": "fc58dc8eff5312ce359b1bcad5550fa10b59310768c30558b19888b2e0ff5699",
10
+ "src/config-compatibility.mjs": "5d29bed6587ab1d2a430815e36264ed94e9332c38acbc002ae2437b7bdab79d6",
11
+ "src/schemas/dotnetdoc-config-0.1.0-draft.schema.json": "1b97dc60616d2ea2c1215c1dcc04a6e9e396abcfc5d11f5cff6bae1e8559c0bf",
12
+ "src/schemas/dotnetdoc-config-1.0.0.schema.json": "2518b2807e9f5703526e8c32cd49826dd1adf50cbf7006ee323b40067d92019d",
13
+ "README.md": "c62a8f8515e753d331822330cad02a4d5fcc968251800b0156b2f9a9d641ccd6",
14
+ "package.json": "243e9b2bcbe5aaeabf4a11c276e1b687bb31be4754872e04457d2bcd1e4c28b2"
15
+ },
16
+ "options": [
17
+ {
18
+ "name": "config",
19
+ "valueType": "string",
20
+ "short": "c"
21
+ },
22
+ {
23
+ "name": "help",
24
+ "valueType": "boolean",
25
+ "short": "h"
26
+ },
27
+ {
28
+ "name": "out-dir",
29
+ "valueType": "string",
30
+ "short": "o"
31
+ },
32
+ {
33
+ "name": "title",
34
+ "valueType": "string"
35
+ },
36
+ {
37
+ "name": "version",
38
+ "valueType": "boolean",
39
+ "short": "v"
40
+ },
41
+ {
42
+ "name": "workspace-root",
43
+ "valueType": "string"
44
+ }
45
+ ],
46
+ "positionals": [
47
+ {
48
+ "name": "positionals",
49
+ "valueType": "string"
50
+ }
51
+ ]
52
+ },
53
+ {
54
+ "commandId": "dotnetdoc",
55
+ "sourceDigests": {
56
+ "src/cli.mjs": "98bbcbfc17e37feee2e243690ace48fc0f77d1e7c3fdbe6c850e9da83a38d1d7",
57
+ "src/command-content.mjs": "3c7282a7503da5b6c99f3785e6390636a8fc6be4b8c126f84201e94211e9db43",
58
+ "src/metadata.mjs": "6d27ddcfccfdac5e941cf983645b5fac76114383d5df566edbcec999eda37bfb",
59
+ "src/index.mjs": "7bdec377cb2069878db55e7931898b0759b3f69ee7eea39afd052340db2da0a6",
60
+ "src/schema.mjs": "fc58dc8eff5312ce359b1bcad5550fa10b59310768c30558b19888b2e0ff5699",
61
+ "src/config-compatibility.mjs": "5d29bed6587ab1d2a430815e36264ed94e9332c38acbc002ae2437b7bdab79d6",
62
+ "src/schemas/dotnetdoc-config-0.1.0-draft.schema.json": "1b97dc60616d2ea2c1215c1dcc04a6e9e396abcfc5d11f5cff6bae1e8559c0bf",
63
+ "src/schemas/dotnetdoc-config-1.0.0.schema.json": "2518b2807e9f5703526e8c32cd49826dd1adf50cbf7006ee323b40067d92019d",
64
+ "README.md": "c62a8f8515e753d331822330cad02a4d5fcc968251800b0156b2f9a9d641ccd6",
65
+ "package.json": "243e9b2bcbe5aaeabf4a11c276e1b687bb31be4754872e04457d2bcd1e4c28b2"
66
+ },
67
+ "options": [
68
+ {
69
+ "name": "config",
70
+ "valueType": "string",
71
+ "short": "c"
72
+ },
73
+ {
74
+ "name": "help",
75
+ "valueType": "boolean",
76
+ "short": "h"
77
+ },
78
+ {
79
+ "name": "out-dir",
80
+ "valueType": "string",
81
+ "short": "o"
82
+ },
83
+ {
84
+ "name": "title",
85
+ "valueType": "string"
86
+ },
87
+ {
88
+ "name": "version",
89
+ "valueType": "boolean",
90
+ "short": "v"
91
+ },
92
+ {
93
+ "name": "workspace-root",
94
+ "valueType": "string"
95
+ }
96
+ ],
97
+ "positionals": [
98
+ {
99
+ "name": "positionals",
100
+ "valueType": "string"
101
+ }
102
+ ]
103
+ }
104
+ ]
@@ -0,0 +1,40 @@
1
+ /** @file 两代.NET配置的精确身份/新schema验证与纯迁移辅助;旧运行语义由runner纯规范化继续裁决。 @lang en Exact identity/current-schema validation and pure migration support for two .NET config generations; the runner's pure normalization retains authority over legacy runtime semantics. */
2
+ import Ajv2020 from 'ajv/dist/2020.js';
3
+ import { cloneDotnetDocJson } from '@hia-doc/dotnetdoc-spec';
4
+ import { DOTNETDOC_CONFIG_JSON_SCHEMA, DOTNETDOC_CONFIG_SCHEMA_ID } from './schema.mjs';
5
+ import { DOTNETDOC_CONFIG_JSON_SCHEMA as legacySchema, DOTNETDOC_CONFIG_SCHEMA_ID as legacyId } from './schema-legacy.mjs';
6
+
7
+ /** 固定失败不回显文件名、原始配置或validator错误。 @lang en Fixed failure without echoing filenames, raw config or validator errors. */
8
+ const failure = 'DotNetDoc config must match an exact supported identity and structure.';
9
+ /** 当前schema仅本地编译,不启用coercion/defaults/删除扩展或远端schema。 @lang en Compile only the current local schema without coercion, defaults, extension removal or remote schemas. */
10
+ const validateCurrent = new Ajv2020({ strict: false, allErrors: true }).compile(DOTNETDOC_CONFIG_JSON_SCHEMA);
11
+
12
+ /**
13
+ * @lang zh-CN 选择精确新/旧配置schema;旧schema原required保留,不宣称它覆盖运行时省略默认。
14
+ * @lang en Selects exact current/legacy config schemas, preserving original legacy required fields without claiming they cover runtime omission defaults.
15
+ * @param {string} identity <lang><zh-CN>精确版本或schema ID。</zh-CN><en>Exact version or schema ID.</en></lang>
16
+ * @returns {object|undefined} <lang><zh-CN>对应schema,未知返回undefined;不访问网络。</zh-CN><en>Matching schema, or undefined for unknown identities; no network access.</en></lang>
17
+ */
18
+ export function getDotnetDocConfigSchema(identity) {
19
+ if (identity === '1.0.0' || identity === DOTNETDOC_CONFIG_SCHEMA_ID) return DOTNETDOC_CONFIG_JSON_SCHEMA;
20
+ if (identity === '0.1.0-draft' || identity === legacyId) return legacySchema;
21
+ return undefined;
22
+ }
23
+
24
+ /**
25
+ * 验证JSON与精确schema配对;新版本按schema,旧版由调用者继续按原运行语义校验。
26
+ * @lang en Validates JSON and exact schema pairing, checking current schema while leaving legacy runtime validation to the caller.
27
+ * @param {unknown} value <lang><zh-CN>候选配置,不执行访问器。</zh-CN><en>Candidate config, with no accessor execution.</en></lang>
28
+ * @returns {object} <lang><zh-CN>独立JSON视图,调用方不得当作已执行请求。</zh-CN><en>Independent JSON view, never an executed request.</en></lang>
29
+ * @throws {TypeError} <lang><zh-CN>未知/错配/非JSON或新结构错误时固定拒绝。</zh-CN><en>Fixed refusal for unknown/mismatched/non-JSON/current-structure errors.</en></lang>
30
+ */
31
+ export function inspectDotnetDocConfig(value) {
32
+ try {
33
+ // <lang><zh-CN>先复制才能安全读取版本与$schema;不触发用户getter或JSON钩子。</zh-CN><en>Copy before reading version/$schema, avoiding user getters and JSON hooks.</en></lang>
34
+ const json = cloneDotnetDocJson(value);
35
+ const schema = getDotnetDocConfigSchema(json?.schemaVersion);
36
+ if (!schema || (json.$schema !== undefined && json.$schema !== schema.$id)) throw new TypeError(failure);
37
+ if (json.schemaVersion === '1.0.0' && !validateCurrent(json)) throw new TypeError(failure);
38
+ return json;
39
+ } catch { throw new TypeError(failure); }
40
+ }
@@ -0,0 +1,176 @@
1
+ /**
2
+ * @file
3
+ * @lang zh-CN 只从本次 DotNetDoc 抽取与已核 HIA 声明构造独立文档源码映射,不读取代码正文或推断 XML 位置。
4
+ * @lang en Builds an independent documentation source map only from this DotNetDoc extraction and verified HIA declarations, without reading source bodies or inferring XML positions.
5
+ */
6
+
7
+ /**
8
+ * @lang zh-CN 独立映射产物身份,与 runner 包版本分离。
9
+ * @lang en Independent map artifact identity, separate from the runner package version.
10
+ */
11
+ export const DOTNETDOC_DOC_SOURCE_MAP_CONTRACT_VERSION = '1.1.0';
12
+ const XML_CONTRACT = 'dotnetdoc-xml-doc-extraction';
13
+ const CSHARP_CONTRACT = 'dotnetdoc-csharp-source-extraction';
14
+ const EXACT_CONVENTION = Object.freeze({ endBoundary: 'exclusive', columnUnit: 'utf16-code-unit' });
15
+ const UNKNOWN_CONVENTION = Object.freeze({ endBoundary: 'unknown', columnUnit: 'unknown' });
16
+
17
+ /**
18
+ * @lang zh-CN 纯数据地构造单个 HIA 文档的源码映射;只有 runner 已核真实路径的 Roslyn 范围可成为代码引用。
19
+ * @lang en Purely builds a source map for one HIA document; only Roslyn ranges with runner-verified real paths can become code references.
20
+ * @param {{record: object, verifiedSourcePaths: Set<string>, producerVersion: string}} options <lang><zh-CN>本次抽取记录、可信调用方已用真实路径核验的工作区相对路径断言,以及实际 runner 包版本。纯函数本身只做词法拒绝,不做 realpath I/O。</zh-CN><en>Current extraction record, workspace-relative paths asserted as real-path verified by the trusted caller, and actual runner package version. This pure function applies lexical rejection only; it does not perform realpath I/O.</en></lang>
21
+ * @returns {object} <lang><zh-CN>无源码正文的 `doc-source-map@1.1.0` 工件。</zh-CN><en>A source-body-free `doc-source-map@1.1.0` artifact.</en></lang>
22
+ * @throws {TypeError} <lang><zh-CN>非成员抽取、缺少工件或不安全输出路径被拒绝。</zh-CN><en>Rejects non-member extraction, missing artifacts, and unsafe output paths.</en></lang>
23
+ */
24
+ export function createDotnetDocSourceMap({ record, verifiedSourcePaths, producerVersion }) {
25
+ if (![XML_CONTRACT, CSHARP_CONTRACT].includes(record?.artifact?.contract) || !Array.isArray(record?.hiaDocument?.symbols)
26
+ || !Array.isArray(record?.artifact?.members) || record.artifact.members.length !== record.hiaDocument.symbols.length
27
+ || !(verifiedSourcePaths instanceof Set) || typeof producerVersion !== 'string' || !producerVersion || hasUnpairedSurrogate(producerVersion)) {
28
+ throw new TypeError('DotNetDoc source map requires a member extraction and HIA document.');
29
+ }
30
+ // <lang><zh-CN>在任何 URI 编码前检查全部成员身份;不接受损坏的 UTF-16,也不把非法身份隐式修复。</zh-CN><en>Check every member identity before URI encoding; reject malformed UTF-16 rather than silently repairing it.</en></lang>
31
+ if (record.hiaDocument.symbols.some(symbol => typeof symbol?.id !== 'string' || hasUnpairedSurrogate(symbol.id))) {
32
+ throw new TypeError('Unsafe DotNetDoc map member identity.');
33
+ }
34
+ const extractionPath = safePath(record.artifactPath);
35
+ const documentPath = safePath(record.hiaPath);
36
+ const extractionId = `artifact:dotnetdoc:${encodeURIComponent(extractionPath)}`;
37
+ const documentId = `artifact:hia:${encodeURIComponent(documentPath)}`;
38
+ const sources = new Map();
39
+
40
+ // <lang><zh-CN>每个符号按数组序号建立可逆身份,防止重载、程序集或压缩 slug 相撞。</zh-CN><en>Array ordinals give symbols reversible identities without overload, assembly, or collapsed-slug collisions.</en></lang>
41
+ const entries = record.hiaDocument.symbols.map((symbol, index) => {
42
+ const sourceRefs = [];
43
+ const location = symbol?.source?.definedIn;
44
+ const resolution = symbol?.metadata?.dotnetdoc?.sourceLocationResolution;
45
+ const rawMember = record.artifact.members?.[index];
46
+ const exactXml = record.artifact.contract === XML_CONTRACT && resolution?.status === 'resolved'
47
+ && rawMember?.id === symbol.id && rawMember?.memberName === symbol?.metadata?.dotnetdoc?.memberName;
48
+ const exactCsharp = record.artifact.contract === CSHARP_CONTRACT
49
+ && rawMember?.id === symbol.id
50
+ && rawMember?.source?.path?.replaceAll('\\', '/') === location?.relativePath
51
+ && JSON.stringify(rawMember?.source?.range) === JSON.stringify(location?.range)
52
+ && record.artifact.producer?.name === '@hia-doc/dotnet-source-extractor'
53
+ && record.artifact.producer?.engine === 'roslyn';
54
+ const sourceRangeSource = exactXml ? resolution?.sourceRangeSource : exactCsharp ? rawMember?.source?.rangeSource : null;
55
+ const recovered = exactXml ? resolution?.sourceHasErrors === true : (record.artifact.diagnostics ?? []).some(item => item.severity === 'error');
56
+ const range = boundedRange(location?.range);
57
+ const relativePath = typeof location?.relativePath === 'string' ? location.relativePath.replaceAll('\\', '/') : '';
58
+
59
+ // <lang><zh-CN>XML 文本、文件名回退及越根路径都不产生代码 sourceRef;损坏解析的范围保留事实但精度未知。</zh-CN><en>XML text, filename fallbacks, and escaping paths produce no code sourceRef; recovered syntax may retain a range only with unknown precision.</en></lang>
60
+ if ((exactXml || exactCsharp) && location?.language === 'csharp' && sourceRangeSource === 'roslyn-syntax' && range && safeSourcePath(relativePath) && verifiedSourcePaths.has(relativePath)) {
61
+ const sourceId = `source:csharp:${encodeURIComponent(relativePath)}`;
62
+ if (!sources.has(sourceId)) {
63
+ sources.set(sourceId, { id: sourceId, kind: 'csharp-source', path: relativePath, language: 'csharp', role: 'original', sourcesContentPolicy: 'none' });
64
+ }
65
+ const known = !recovered && isPositiveColumnRange(range);
66
+ sourceRefs.push({
67
+ sourceId,
68
+ range,
69
+ rangeConvention: known ? { ...EXACT_CONVENTION } : { ...UNKNOWN_CONVENTION },
70
+ rangeSource: 'compiler',
71
+ rangeSourceDetail: known ? 'roslyn-syntax' : 'roslyn-syntax-unverified',
72
+ confidence: known ? 'medium' : 'low'
73
+ });
74
+ }
75
+
76
+ // <lang><zh-CN>诊断仅使用固定公开安全文案;不复用 XML 注释、异常文本或外来 producer 名称。</zh-CN><en>Diagnostics use fixed public-safe text rather than XML comments, exception text, or foreign producer names.</en></lang>
77
+ return {
78
+ id: `entry:${encodeURIComponent(documentPath)}:${index}`,
79
+ kind: 'symbol',
80
+ symbolId: symbol.id,
81
+ symbolKind: symbol.kind,
82
+ sourceRefs,
83
+ artifactRefs: [
84
+ { artifactId: extractionId, rangeSource: 'adapter', confidence: 'high' },
85
+ { artifactId: documentId, rangeSource: 'adapter', confidence: 'high' }
86
+ ],
87
+ diagnostics: sourceRefs.length ? [] : [{ code: 'DOTNETDOC_SOURCE_MAP_CODE_LOCATION_UNAVAILABLE', message: 'No verified C# declaration range is available for this member.', severity: 'warning' }]
88
+ };
89
+ });
90
+
91
+ return {
92
+ contract: 'doc-source-map',
93
+ contractVersion: DOTNETDOC_DOC_SOURCE_MAP_CONTRACT_VERSION,
94
+ id: `docmap:dotnetdoc:${encodeURIComponent(documentPath)}`,
95
+ producer: { name: '@hia-doc/dotnetdoc-runner', version: producerVersion },
96
+ artifacts: [
97
+ { id: extractionId, kind: 'extraction-artifact', path: extractionPath, format: 'json', role: 'generated', contractRefs: [{ contract: record.artifact.contract, contractVersion: record.artifact.contractVersion, path: extractionPath }] },
98
+ { id: documentId, kind: 'hia-document', path: documentPath, format: 'json', role: 'generated' }
99
+ ],
100
+ sources: [...sources.values()],
101
+ sourceMaps: [],
102
+ chains: [],
103
+ entries,
104
+ privacy: { sourcesContentPolicy: 'none', allowAbsolutePaths: false, allowUncPaths: false, allowPathTraversal: false },
105
+ diagnostics: []
106
+ };
107
+ }
108
+
109
+ /**
110
+ * @lang zh-CN 检查字符串是否含孤立 UTF-16 代理项,避免可逆 URI 编码抛出原生异常。
111
+ * @lang en Detects unpaired UTF-16 surrogates before reversible URI encoding can throw a raw exception.
112
+ * @param {string} value <lang><zh-CN>待编码的路径或身份文本。</zh-CN><en>Path or identity text to be encoded.</en></lang>
113
+ * @returns {boolean} <lang><zh-CN>存在孤立代理项时为 true。</zh-CN><en>True when an unpaired surrogate is present.</en></lang>
114
+ */
115
+ export function hasUnpairedSurrogate(value) {
116
+ for (let index = 0; index < value.length; index += 1) {
117
+ const code = value.charCodeAt(index);
118
+ if (code >= 0xD800 && code <= 0xDBFF) {
119
+ const next = value.charCodeAt(index + 1);
120
+ if (!(next >= 0xDC00 && next <= 0xDFFF)) return true;
121
+ index += 1;
122
+ } else if (code >= 0xDC00 && code <= 0xDFFF) {
123
+ return true;
124
+ }
125
+ }
126
+ return false;
127
+ }
128
+
129
+ /**
130
+ * @lang zh-CN 限制工件引用为安全、可编码的相对路径。
131
+ * @lang en Restricts artifact references to safe, encodable relative paths.
132
+ * @param {unknown} value <lang><zh-CN>候选工件路径。</zh-CN><en>Candidate artifact path.</en></lang>
133
+ * @returns {string} <lang><zh-CN>统一斜杠的安全相对路径。</zh-CN><en>Safe relative path with normalized slashes.</en></lang>
134
+ * @throws {TypeError} <lang><zh-CN>绝对路径、上级跳转、冒号或孤立代理项被拒绝。</zh-CN><en>Rejects absolute paths, traversal, colons, and unpaired surrogates.</en></lang>
135
+ */
136
+ function safePath(value) {
137
+ if (typeof value !== 'string' || !value || hasUnpairedSurrogate(value) || value.includes(':') || /^(?:[/\\]|[a-z][a-z0-9+.-]*:)/iu.test(value) || value.replaceAll('\\', '/').split('/').includes('..')) throw new TypeError('Unsafe DotNetDoc map artifact path.');
138
+ return value.replaceAll('\\', '/');
139
+ }
140
+
141
+ /**
142
+ * @lang zh-CN C# 原文件引用再限制扩展名与工作区相对形式;真实路径核验仍由可信调用方负责。
143
+ * @lang en Further restricts C# source references by extension and workspace-relative form; the trusted caller remains responsible for real-path verification.
144
+ * @param {unknown} value <lang><zh-CN>候选源码相对路径。</zh-CN><en>Candidate relative source path.</en></lang>
145
+ * @returns {boolean} <lang><zh-CN>路径词法安全时为 true。</zh-CN><en>True when the path is lexically safe.</en></lang>
146
+ */
147
+ function safeSourcePath(value) {
148
+ return typeof value === 'string' && /\.cs$/iu.test(value) && value !== '' && !hasUnpairedSurrogate(value) && !value.includes(':') && !/^(?:[/\\]|[a-z][a-z0-9+.-]*:)/iu.test(value) && !value.split('/').includes('..');
149
+ }
150
+
151
+ /**
152
+ * @lang zh-CN 复制完整有序的一基范围,不借 HIA position 的缺省列。
153
+ * @lang en Copies a complete ordered one-based range without borrowing a default column from HIA position.
154
+ * @param {unknown} value <lang><zh-CN>候选声明范围。</zh-CN><en>Candidate declaration range.</en></lang>
155
+ * @returns {object|null} <lang><zh-CN>有效一基范围或 null。</zh-CN><en>Valid one-based range or null.</en></lang>
156
+ */
157
+ function boundedRange(value) {
158
+ const start = value?.start;
159
+ const end = value?.end;
160
+ if (!Number.isSafeInteger(start?.line) || start.line < 1 || !Number.isSafeInteger(end?.line) || end.line < start.line) return null;
161
+ if (start.column !== undefined && (!Number.isSafeInteger(start.column) || start.column < 1)) return null;
162
+ if (end.column !== undefined && (!Number.isSafeInteger(end.column) || end.column < 1)) return null;
163
+ if (end.line === start.line && start.column !== undefined && end.column !== undefined && end.column < start.column) return null;
164
+ return { start: { line: start.line, ...(start.column === undefined ? {} : { column: start.column }) }, end: { line: end.line, ...(end.column === undefined ? {} : { column: end.column }) } };
165
+ }
166
+
167
+ /**
168
+ * @lang zh-CN 只有完整列且严格正长度的范围可采用已证排除终点/UTF-16 约定。
169
+ * @lang en Only complete-column, strictly positive ranges may use the proven exclusive/UTF-16 convention.
170
+ * @param {object} range <lang><zh-CN>已核的一基范围。</zh-CN><en>Validated one-based range.</en></lang>
171
+ * @returns {boolean} <lang><zh-CN>范围有完整列且长度为正时为 true。</zh-CN><en>True when columns are complete and the span has positive length.</en></lang>
172
+ */
173
+ function isPositiveColumnRange(range) {
174
+ return Number.isSafeInteger(range.start.column) && Number.isSafeInteger(range.end.column)
175
+ && (range.end.line > range.start.line || range.end.column > range.start.column);
176
+ }
@@ -0,0 +1,125 @@
1
+ /**
2
+ * @file
3
+ * @lang zh-CN 运行器公开ESM入口,配置读取与执行严格分开。
4
+ * @lang en Public runner ESM entry separating config reading from execution.
5
+ */
6
+ export type * from './api-types.mjs';
7
+ import type { DotnetDocRecord, DotnetDocArtifact, DotnetDocWarningArtifact, DotnetDocHiaDocument } from '@hia-doc/dotnetdoc-spec';
8
+ import type { DotnetDocRequest, DotnetDocConfig, DotnetDocCurrentConfig, DotnetDocContext, DotnetDocResult } from './api-types.mjs';
9
+ /**
10
+ * @lang zh-CN 领域合同名称,用于精确读写身份匹配(DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT)。
11
+ * @lang en Exact DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT registry value, independent from other version, authority and precision decisions.
12
+ */
13
+ export const DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT: "dotnetdoc-build-warning-classification";
14
+ /**
15
+ * @lang zh-CN 独立的精确版本身份,不用于推断其它契约版本(DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT_VERSION)。
16
+ * @lang en Exact DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT_VERSION registry value, independent from other version, authority and precision decisions.
17
+ */
18
+ export const DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT_VERSION: "1.0.0";
19
+ /**
20
+ * @lang zh-CN 本地schema资源,不代表在线发布或授权执行(DOTNETDOC_CONFIG_JSON_SCHEMA)。
21
+ * @lang en Exact DOTNETDOC_CONFIG_JSON_SCHEMA registry value, independent from other version, authority and precision decisions.
22
+ */
23
+ export const DOTNETDOC_CONFIG_JSON_SCHEMA: Readonly<Record<string, unknown>>;
24
+ /**
25
+ * @lang zh-CN 本地schema资源,不代表在线发布或授权执行(DOTNETDOC_CONFIG_SCHEMA_ID)。
26
+ * @lang en Exact DOTNETDOC_CONFIG_SCHEMA_ID registry value, independent from other version, authority and precision decisions.
27
+ */
28
+ export const DOTNETDOC_CONFIG_SCHEMA_ID: "https://mandolin.github.io/HIA-Documentation/schemas/dotnetdoc-config-1.0.0.schema.json";
29
+ /**
30
+ * @lang zh-CN 独立的精确版本身份,不用于推断其它契约版本(DOTNETDOC_CONFIG_SCHEMA_VERSION)。
31
+ * @lang en Exact DOTNETDOC_CONFIG_SCHEMA_VERSION registry value, independent from other version, authority and precision decisions.
32
+ */
33
+ export const DOTNETDOC_CONFIG_SCHEMA_VERSION: "1.0.0";
34
+ /**
35
+ * @lang zh-CN 独立的精确版本身份,不用于推断其它契约版本(DOTNETDOC_DOC_SOURCE_MAP_CONTRACT_VERSION)。
36
+ * @lang en Exact DOTNETDOC_DOC_SOURCE_MAP_CONTRACT_VERSION registry value, independent from other version, authority and precision decisions.
37
+ */
38
+ export const DOTNETDOC_DOC_SOURCE_MAP_CONTRACT_VERSION: "1.1.0";
39
+ /**
40
+ * @lang zh-CN 当前支持的固定登记集合,不推断额外语法(DOTNETDOC_INPUT_KINDS)。
41
+ * @lang en Exact DOTNETDOC_INPUT_KINDS registry value, independent from other version, authority and precision decisions.
42
+ */
43
+ export const DOTNETDOC_INPUT_KINDS: readonly ["dotnet-xml-doc","dotnet-csharp-source","dotnet-aspnet-surface","dotnet-markup-comments","dotnet-project"];
44
+ /**
45
+ * @lang zh-CN 保留旧身份或schema,不原位更新历史(DOTNETDOC_LEGACY_CONFIG_JSON_SCHEMA)。
46
+ * @lang en Exact DOTNETDOC_LEGACY_CONFIG_JSON_SCHEMA registry value, independent from other version, authority and precision decisions.
47
+ */
48
+ export const DOTNETDOC_LEGACY_CONFIG_JSON_SCHEMA: Readonly<Record<string, unknown>>;
49
+ /**
50
+ * @lang zh-CN 保留旧身份或schema,不原位更新历史(DOTNETDOC_LEGACY_CONFIG_SCHEMA_ID)。
51
+ * @lang en Exact DOTNETDOC_LEGACY_CONFIG_SCHEMA_ID registry value, independent from other version, authority and precision decisions.
52
+ */
53
+ export const DOTNETDOC_LEGACY_CONFIG_SCHEMA_ID: "https://mandolin.github.io/HIA-Documentation/schemas/dotnetdoc-config-0.1.0-draft.schema.json";
54
+ /**
55
+ * @lang zh-CN 保留旧身份或schema,不原位更新历史(DOTNETDOC_LEGACY_CONFIG_SCHEMA_VERSION)。
56
+ * @lang en Exact DOTNETDOC_LEGACY_CONFIG_SCHEMA_VERSION registry value, independent from other version, authority and precision decisions.
57
+ */
58
+ export const DOTNETDOC_LEGACY_CONFIG_SCHEMA_VERSION: "0.1.0-draft";
59
+ /**
60
+ * @lang zh-CN 当前支持的固定登记集合,不推断额外语法(DOTNETDOC_OUTPUT_KINDS)。
61
+ * @lang en Exact DOTNETDOC_OUTPUT_KINDS registry value, independent from other version, authority and precision decisions.
62
+ */
63
+ export const DOTNETDOC_OUTPUT_KINDS: readonly ["dotnetdoc-extraction","hia-document","doc-source-map","dotnetdoc-source-relation","dotnetdoc-aspnet-endpoint-extraction","dotnetdoc-markup-comment-extraction","dotnetdoc-project-discovery"];
64
+ /**
65
+ * @lang zh-CN 独立的精确版本身份,不用于推断其它契约版本(DOTNETDOC_RUNNER_VERSION)。
66
+ * @lang en Exact DOTNETDOC_RUNNER_VERSION registry value, independent from other version, authority and precision decisions.
67
+ */
68
+ export const DOTNETDOC_RUNNER_VERSION: "1.0.0";
69
+ /**
70
+ * @lang zh-CN 显式请求执行;默认cwd/dist目录,写结果/关系默认true、地图false;读输入/写输出与helper缓存;前置拒绝/I/O可reject,单项错误归partial/failed。
71
+ * @lang en Executes explicit requests with cwd/dist defaults, result/relation writes true and maps false; reads inputs and writes outputs/helper caches, may reject preflight/I/O errors, and reports per-input failures as partial/failed.
72
+ * @param request <lang><zh-CN>调用方明确提供的请求,路径与输入范围由对应运行入口继续校验。</zh-CN><en>The explicit caller request, with paths and input scope checked by the corresponding runtime entry.</en></lang>
73
+ * @param context <lang><zh-CN>可选宿主服务上下文,宿主仍负责执行及公开权限。</zh-CN><en>Optional host-service context, with execution and publication authority retained by the host.</en></lang>
74
+ * @returns <lang><zh-CN>每项输入的状态、输出工件与诊断汇总。</zh-CN><en>Aggregated per-input statuses, output artifacts and diagnostics.</en></lang>
75
+ * @throws <lang><zh-CN>请求、源读取或所需工具不满足此入口已声明边界时,Promise拒绝。</zh-CN><en>The promise rejects when requests, source reads or required tools violate this entry's declared boundaries.</en></lang>
76
+ */
77
+ export function runDotnetDoc(request: DotnetDocRequest, context?: DotnetDocContext): Promise<DotnetDocResult>;
78
+ /**
79
+ * @lang zh-CN 同步纯诊断分类,无构建/源码I/O,不是门禁通过认证;非数组TypeError。
80
+ * @lang en Synchronous pure diagnostic classification without builds/source I/O or gate-pass certification; nonarrays throw TypeError.
81
+ * @param diagnostics <lang><zh-CN>待纯分类的构建诊断字符串或记录数组。</zh-CN><en>Array of build-diagnostic strings or records for pure classification.</en></lang>
82
+ * @returns <lang><zh-CN>当前版本的纯构建警告分类工件。</zh-CN><en>A current-version pure build-warning classification artifact.</en></lang>
83
+ * @throws <lang><zh-CN>输入不满足此入口的已声明身份、结构或数据边界时抛出错误。</zh-CN><en>Throws when input violates this entry's declared identity, structure or data boundaries.</en></lang>
84
+ */
85
+ export function classifyDotnetBuildDiagnostics(diagnostics: Array<string | DotnetDocRecord>): DotnetDocWarningArtifact<'1.0.0'>;
86
+ /**
87
+ * @lang zh-CN 读取JSON并相对配置目录解析workspace,输出相对workspace;默认cwd为进程cwd,不执行输入项目;I/O/身份/结构错误reject。
88
+ * @lang en Reads JSON and resolves workspace relative to the config directory and output relative to workspace; defaults cwd to process cwd without input-project execution, rejecting I/O/identity/shape errors.
89
+ * @param configPath <lang><zh-CN>相对于可选cwd解析的JSON配置文件定位器。</zh-CN><en>JSON config file locator resolved relative to the optional cwd.</en></lang>
90
+ * @param options <lang><zh-CN>可选cwd,省略使用当前进程目录。</zh-CN><en>Optional cwd, defaulting to the current process directory.</en></lang>
91
+ * @returns <lang><zh-CN>相对目录已解析的显式运行请求。</zh-CN><en>An explicit run request with relative directories resolved.</en></lang>
92
+ * @throws <lang><zh-CN>请求、源读取或所需工具不满足此入口已声明边界时,Promise拒绝。</zh-CN><en>The promise rejects when requests, source reads or required tools violate this entry's declared boundaries.</en></lang>
93
+ */
94
+ export function loadDotnetDocConfig(configPath: string, options?: { cwd?: string }): Promise<DotnetDocRequest & { workspaceRoot: string; outputDirectory: string }>;
95
+ /**
96
+ * @lang zh-CN 纯读取返回原对象,旧版保留默认规则,新版拒绝null/错型;未知身份TypeError,不填目录或执行。
97
+ * @lang en Purely reads and returns the original, retaining legacy defaults while current config rejects null/wrong types; unknown identities throw TypeError without filling directories or executing.
98
+ * @param value <lang><zh-CN>需按对应读取、复制或迁移入口校验的外部数据。</zh-CN><en>External data validated by the corresponding read, clone or migration entry.</en></lang>
99
+ * @returns <lang><zh-CN>已通过精确身份和结构读取的原配置对象。</zh-CN><en>The original config after exact identity and structural reading.</en></lang>
100
+ * @throws <lang><zh-CN>输入不满足此入口的已声明身份、结构或数据边界时抛出错误。</zh-CN><en>Throws when input violates this entry's declared identity, structure or data boundaries.</en></lang>
101
+ */
102
+ export function readDotnetDocConfig(value: unknown): DotnetDocConfig;
103
+ /**
104
+ * @lang zh-CN 仅精确旧配置显式迁移,新对象只改根身份,不能无损表达则TypeError。
105
+ * @lang en Explicitly migrates exact legacy configs into a new object with root-only identity changes, throwing TypeError when lossless representation is impossible.
106
+ * @param value <lang><zh-CN>需按对应读取、复制或迁移入口校验的外部数据。</zh-CN><en>External data validated by the corresponding read, clone or migration entry.</en></lang>
107
+ * @returns <lang><zh-CN>显式迁移后的独立当前配置。</zh-CN><en>An independent current config produced by explicit migration.</en></lang>
108
+ * @throws <lang><zh-CN>输入不满足此入口的已声明身份、结构或数据边界时抛出错误。</zh-CN><en>Throws when input violates this entry's declared identity, structure or data boundaries.</en></lang>
109
+ */
110
+ export function migrateDotnetDocConfig(value: unknown): DotnetDocCurrentConfig;
111
+ /**
112
+ * @lang zh-CN 按精确版本/schemaID选择本地schema,未知undefined,无网络I/O。
113
+ * @lang en Selects a local schema by exact version/schema ID, returning undefined for unknown values without network I/O.
114
+ * @param identity <lang><zh-CN>精确版本或Schema身份,不执行模糊版本选择。</zh-CN><en>Exact version or schema identity, without fuzzy version selection.</en></lang>
115
+ * @returns <lang><zh-CN>匹配的只读本地Schema,未知身份为undefined。</zh-CN><en>The matching readonly local schema, or undefined for an unknown identity.</en></lang>
116
+ */
117
+ export function getDotnetDocConfigSchema(identity: string): Readonly<Record<string, unknown>> | undefined;
118
+ /**
119
+ * @lang zh-CN 纯构造1.1.0文档源码地图,调用方必须先realpath核验verifiedSourcePaths;非法身份/路径/错配TypeError,不读取源码或推断XML位置。
120
+ * @lang en Purely builds a 1.1.0 documentation source map; callers must realpath-verify verifiedSourcePaths first; invalid identities/paths/mismatches throw TypeError without source reads or XML-position inference.
121
+ * @param options <lang><zh-CN>本次工件与文档定位、预先核验的源码路径集合及生产器版本。</zh-CN><en>Current artifact/document locators, previously verified source paths and producer version.</en></lang>
122
+ * @returns <lang><zh-CN>声明与文档来源分别登记的1.1.0地图工件。</zh-CN><en>A 1.1.0 map artifact recording declaration and documentation provenance separately.</en></lang>
123
+ * @throws <lang><zh-CN>输入不满足此入口的已声明身份、结构或数据边界时抛出错误。</zh-CN><en>Throws when input violates this entry's declared identity, structure or data boundaries.</en></lang>
124
+ */
125
+ export function createDotnetDocSourceMap(options: { record: { artifact: DotnetDocArtifact; hiaDocument: DotnetDocHiaDocument; artifactPath: string; hiaPath: string }; verifiedSourcePaths: Set<string>; producerVersion: string }): DotnetDocRecord & { contract: 'doc-source-map'; contractVersion: '1.1.0' };