@hia-doc/dotnetdoc-runner 0.1.12 → 1.0.0-rc.2

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 ADDED
@@ -0,0 +1,96 @@
1
+ # @hia-doc/dotnetdoc-runner API
2
+
3
+ Version: 1.0.0. Previous package line: 0.1.12.
4
+
5
+ 中文:本页列出全部真实运行时根导出。类型为保守的ESM结构声明,未知扩展须缩窄;公开权限、schema、源码精度仍由对应运行时验证负责,不能仅凭类型或metadata认定安全。
6
+
7
+ ## Entry points and types
8
+
9
+ Import from `@hia-doc/dotnetdoc-runner`; [ESM declarations](src/index.d.mts) provide exact root versions and conservative structures. The JavaScript runtime is unchanged by the declaration entry. TypeScript NodeNext resolves the explicit `types` export condition; no CommonJS entry is promised. Optional metadata and nested domain records remain `unknown` until validated.
10
+
11
+ | Export | Input / output / errors / effects |
12
+ | --- | --- |
13
+ | `DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT` | Exact exported constant; independent contract/package identities, see declaration literal and migration rules. |
14
+ | `DOTNETDOC_BUILD_WARNING_CLASSIFICATION_CONTRACT_VERSION` | Exact exported constant; independent contract/package identities, see declaration literal and migration rules. |
15
+ | `DOTNETDOC_CONFIG_JSON_SCHEMA` | Exact exported registry/schema; independent contract/package identities, see declaration literal and migration rules. |
16
+ | `DOTNETDOC_CONFIG_SCHEMA_ID` | Exact exported constant; independent contract/package identities, see declaration literal and migration rules. |
17
+ | `DOTNETDOC_CONFIG_SCHEMA_VERSION` | Exact exported constant; independent contract/package identities, see declaration literal and migration rules. |
18
+ | `DOTNETDOC_DOC_SOURCE_MAP_CONTRACT_VERSION` | Exact exported constant; independent contract/package identities, see declaration literal and migration rules. |
19
+ | `DOTNETDOC_INPUT_KINDS` | Exact exported registry/schema; independent contract/package identities, see declaration literal and migration rules. |
20
+ | `DOTNETDOC_LEGACY_CONFIG_JSON_SCHEMA` | Exact exported registry/schema; independent contract/package identities, see declaration literal and migration rules. |
21
+ | `DOTNETDOC_LEGACY_CONFIG_SCHEMA_ID` | Exact exported constant; independent contract/package identities, see declaration literal and migration rules. |
22
+ | `DOTNETDOC_LEGACY_CONFIG_SCHEMA_VERSION` | Exact exported constant; independent contract/package identities, see declaration literal and migration rules. |
23
+ | `DOTNETDOC_OUTPUT_KINDS` | Exact exported registry/schema; independent contract/package identities, see declaration literal and migration rules. |
24
+ | `DOTNETDOC_RUNNER_VERSION` | Exact exported constant; independent contract/package identities, see declaration literal and migration rules. |
25
+ | `classifyDotnetBuildDiagnostics` | String/object diagnostic array → current warning classification; pure metadata classification, not a release gate decision. |
26
+ | `createDotnetDocSourceMap` | record + caller realpath-verified path set + producerVersion → doc-source-map 1.1.0; pure lexical checks, no source reads or XML-to-code guesses. |
27
+ | `getDotnetDocConfigSchema` | Exact version or schema id → bundled config schema or undefined; no network lookup. |
28
+ | `loadDotnetDocConfig` | Config path + optional cwd → Promise<resolved request>; reads JSON; workspace relative to config, output relative to workspace; does not execute the request. |
29
+ | `migrateDotnetDocConfig` | Exact legacy config → independent current config; root identity only; non-lossless null/coercion-dependent values rejected. |
30
+ | `readDotnetDocConfig` | unknown → original exact config; legacy omission/null defaults retained, current null/wrong types rejected; pure/no I/O. |
31
+ | `runDotnetDoc` | Request + optional abort/progress context → Promise<SDK result>; reads inputs, writes output/helper caches; per-input errors yield failed/partial, invalid preflight may reject. |
32
+
33
+ ## Bundled schemas
34
+
35
+ The existing `./schemas/*` subpath exposes local JSON resources: seven artifacts × two exact versions in the spec package; two config schemas in the runner. Schema IDs do not assert online availability. Unknown identities are not coerced or downloaded. Legacy config schema bytes remain unchanged; its old required-directory rules differ from the preserved runtime defaults.
36
+
37
+ ## Command line
38
+
39
+ Both `hia-dotnetdoc` and `dotnetdoc` run the same CLI. Use `--config/-c`, `--out-dir/-o`, `--workspace-root`, `--title`, `--help/-h`, or `--version/-v`; positional XML paths are also supported. Success exits 0; partial/failed/request errors exit 1. Errors use controlled text without host paths/stacks.
40
+
41
+ 中文。配置模式和直接 XML 模式按下表处理参数。配置文件相对于调用目录定位,其 workspaceRoot 相对于配置目录解析,outputDirectory 相对于工作区解析。输出默认 `dist/dotnetdoc`。命令会写出产物,partial/failed 也可能已写出部分文件。
42
+
43
+ English. Config and direct XML modes apply the options below. Resolve the config path from the invocation directory, its workspaceRoot from the config directory, and outputDirectory from the workspace. The default output is `dist/dotnetdoc`. Execution writes artifacts, and partial/failed runs may have written files.
44
+
45
+ | Input | With `--config` / 配置模式 | Without `--config` / 直接模式 |
46
+ | --- | --- | --- |
47
+ | `--workspace-root` | Ignored; use configured root / 忽略,采用配置值 | Relative to cwd, default `.` / 相对调用目录,默认 `.` |
48
+ | `--out-dir/-o` | Overrides output, relative to configured workspace / 覆盖输出,相对配置工作区 | Relative to selected workspace / 相对选定工作区 |
49
+ | `--title` | Ignored; use each configured input title / 忽略,采用各输入配置标题 | Applies to every XML input / 应用于各 XML 输入 |
50
+ | Positional XML paths / 位置参数 | Ignored; use configured inputs / 忽略,采用配置输入 | XML inputs relative to workspace / 相对工作区的 XML 输入 |
51
+
52
+ 例如在调用目录执行 `hia-dotnetdoc --config settings/config.json --out-dir reports --workspace-root ignored --title ignored extra.xml`,若配置的 workspaceRoot 为 `workspace`,则只读取配置输入,写入 `settings/workspace/reports`,标题保持配置值。
53
+
54
+ For that command, a configured workspaceRoot of `workspace` selects configured inputs and titles and writes to `settings/workspace/reports`. The other three supplied values have no effect in config mode.
55
+
56
+ ## Boundaries
57
+
58
+ Node.js 22/24; source helper requires stable .NET SDK/runtime 10 and uses its bundled SDK policy. Target projects are read as static inputs, including older target frameworks; full MSBuild project compilation/runtime endpoint discovery is outside this API. Source ranges are provenance unless the dedicated map declares and validates their precision. Documentation text and arbitrary metadata still require host publication permission. Progress cancellation does not kill active helpers or roll back files already written.
59
+
60
+ See [README](README.md) for examples and [migration](MIGRATION.md) for compatibility.
61
+
62
+ ## Pure metadata entry
63
+
64
+ Subpath `./metadata` exports `DOTNETDOC_RUNNER_VERSION`, `DOTNETDOC_INPUT_KINDS` and `DOTNETDOC_OUTPUT_KINDS` from pure definitions. The arrays are frozen, and the root API exposes the same references. This entry performs no runner operations.
65
+
66
+ 中文说明。metadata子入口提供同一版本与冻结输入/输出种类,适用于发现和文档工具。声明分支与运行分支分别提供,构建使用原运行API。
67
+
68
+ ## Type-only declarations
69
+
70
+ The declaration entry also exports these types. Their source comments retain
71
+ English and Simplified Chinese descriptions for roots and explicit members.
72
+ The [declaration source](src/api-types.d.mts) defines optionality, unions and generic defaults.
73
+
74
+ | Type | Meaning |
75
+ | --- | --- |
76
+ | `DotnetDocConfig` | Dual-generation reading union; explicit migration separately returns the current version. |
77
+ | `DotnetDocContext` | Optional cancellation checks the aborted state without killing helpers or rolling back written files. |
78
+ | `DotnetDocCurrentConfig` | Current config identity, with directory safety enforced by schema and loader. |
79
+ | `DotnetDocDiagnostic` | Controlled runner diagnostics; arbitrary metadata still requires host publication review. |
80
+ | `DotnetDocInput` | At least one locator; paths are relative expressions whose actual safety still requires runtime checks. |
81
+ | `DotnetDocInputKind` | Five explicit inputs, with unknown kinds rejected at runtime. |
82
+ | `DotnetDocLegacyConfig` | Legacy config retains null-default compatibility while still refusing behavioral inputs. |
83
+ | `DotnetDocOptions` | Output controls default the first two to true and maps to false, without implicit source-body publication. |
84
+ | `DotnetDocOutputArtifact` | Output-file declaration without content; path is relative to the output directory. |
85
+ | `DotnetDocProgress` | Progress numbers count input items rather than percentages; callbacks may throw. |
86
+ | `DotnetDocRequest` | In-memory requests may omit directories for cwd/dist defaults; host context paths must not be directly serialized as public wire data. |
87
+ | `DotnetDocResult` | SDK 1.0.0 result; partial failures retain successful outputs without automatic rollback. |
88
+
89
+ 中文说明。以上类型通过声明入口公开,根及显式成员的双语说明随源码维护。
90
+ 类型签名保留联合、交叉和可选性,具体运行时输入仍由相应reader及schema检查。
91
+
92
+ ## Command artifacts
93
+
94
+ The bundled `src/command-documentation/` directory describes both executable names, six switches and conditional XML positionals. It contains the original field-level locale data, source digests, actual parser observations, standard HiaDocument and self-contained schemas. `dotnetdoc` uses an explicit `aliasOf` link to `hia-dotnetdoc`. CLI execution and package root exports retain their documented entry points.
95
+
96
+ 中文。七份命令资产完整保留双名、六参数、条件位置输入与原字段语言/来源,别名使用既有aliasOf。真实执行及编程API继续由原入口裁决。
package/MIGRATION.md ADDED
@@ -0,0 +1,31 @@
1
+ # Migrating @hia-doc/dotnetdoc-runner to 1.0.0
2
+
3
+ Previous package release: 0.1.12.
4
+
5
+ 中文:六个包与其内部精确依赖协调升级为1.0.0;这是源码候选版本,实际registry可用性应另行核验。不要仅改旧工件版本号,或把类型检查当隐私/导航精度验收。
6
+
7
+ ## Package and runtime changes
8
+
9
+ Upgrade the six-package cohort together. Internal dependencies use exact 1.0.0, with MIT packages and the existing permissive dependency review retained. Node.js 22/24 and .NET SDK/runtime 10 are the supported tool environment. The bundled helper SDK policy is selected independently from an input project's `global.json`. Reading an old project does not execute it or require changing its target framework.
10
+
11
+ ## Wire compatibility
12
+
13
+ Package version, domain contract, configuration, SDK producer/result, HIA document, i18n and source-map identities are independent. New config and seven domain artifacts use 1.0.0; exact 0.1.0-draft data remains readable. SDK producer/result use 1.0.0; HIA document/i18n remain 0.2.0; documentation source maps remain 1.1.0. Unknown or mismatched identities are rejected.
14
+
15
+ Use `readDotnetDocArtifact` / `migrateDotnetDocArtifact` from `@hia-doc/dotnetdoc-spec` for seven domain artifacts, and `readDotnetDocConfig` / `migrateDotnetDocConfig` from `@hia-doc/dotnetdoc-runner` for configs. Reading returns the original; explicit migration returns an independent object and changes only root identity plus an existing root schema reference. Nested provenance still identifies the real old producer/artifact. Already-current or non-lossless input is rejected by migration. No automatic migration occurs in adapters or loaders.
16
+
17
+ Current config may omit directories for existing defaults but refuses explicit null and wrong types. Legacy reading retains omission/null defaults; legacy values that depend on coercion/null and cannot be represented losslessly are not migrated. Input kind remains explicit; no new syntax or analyzer scope is implied.
18
+
19
+ ## TypeScript and callers
20
+
21
+ The new `.d.mts` entry models actual ESM root exports. Compile with NodeNext and strict checking. Callers formerly relying on implicit JS types must narrow unknown metadata/nested domain fields and handle the exact legacy/current union. No deep private-module imports or CommonJS declaration promise is added. Types do not replace JSON validation.
22
+
23
+ ## Verification before adoption
24
+
25
+ Install original cohort archives with ordinary npm resolution, run your real config through the owned helper, validate SDK output through the SDK, and compare bilingual content and source-map reading. Do not treat XML file locations as code definitions; hosts still authorize source previews separately. See [API](API.md) and [README](README.md).
26
+
27
+ ## Metadata subpath
28
+
29
+ Tools can import pure runner metadata from `@hia-doc/dotnetdoc-runner/metadata`. Existing root imports continue to expose the same version and array objects. Producer descriptors retain mutable shallow copies of the arrays; staged descriptors keep their existing shared references.
30
+
31
+ 中文说明。工具发现可采用metadata子入口;原根入口继续引用同一定义。生产器的数组副本仍可变,暂存描述符继续共享基础副本。
package/README.md CHANGED
@@ -1,5 +1,28 @@
1
1
  # @hia-doc/dotnetdoc-runner
2
2
 
3
+ ## Configuration Compatibility
4
+
5
+ Current configuration uses `schemaVersion: "1.0.0"`; exact `0.1.0-draft`
6
+ configuration remains readable. `readDotnetDocConfig(value)` returns the original
7
+ relative config, while `loadDotnetDocConfig(path)` reads a file and resolves its
8
+ runtime directories. `migrateDotnetDocConfig(value)` explicitly creates a new
9
+ current object without materializing omitted defaults or modifying input.
10
+
11
+ New config requires nonempty `inputs` with explicit supported `kind`. Omitted
12
+ directories retain `.` / `dist/dotnetdoc`; explicit null and wrong types are
13
+ rejected. Legacy omission/null runtime behavior remains readable despite its
14
+ original schema's required-directory fields; lossy null/coercion-dependent
15
+ migrations are refused. `getDotnetDocConfigSchema(identity)` selects an exact
16
+ version or matching ID, returning `undefined` otherwise. Both schemas ship under
17
+ `@hia-doc/dotnetdoc-runner/schemas/dotnetdoc-config-<version>.schema.json`.
18
+
19
+ 新旧配置精确读取,不自动改号;新版本允许目录省略但拒绝null,旧默认按原运行语义保留。
20
+ 显式迁移无法无损表示时拒绝;不填默认、删字段或执行抽取来凑通过。
21
+ 主SDK结果使用1.0.0,领域wire与源码地图版本独立;失败结果/CLI不回显底层路径和堆栈。
22
+
23
+ See the [compatibility guide](https://github.com/mandolin/hia-dotnetdoc/blob/main/COMPATIBILITY.md)
24
+ for all seven domain artifacts, original-schema preservation and runtime requirements.
25
+
3
26
  Standalone runner and CLI for compiler-generated .NET XML documentation files,
4
27
  C# source inputs, ASP.NET endpoint surface inputs, ASP.NET/Razor markup comment
5
28
  inputs and `.sln`/`.csproj` structure discovery.
@@ -16,6 +39,45 @@ This package emits DotNetDoc extraction artifacts, HIA document artifacts,
16
39
  optional source relation artifacts, ASP.NET endpoint extraction artifacts and a
17
40
  documentation producer result manifest without embedding private source text.
18
41
 
42
+ ## Documentation source map (opt in)
43
+
44
+ Set `options.writeDocSourceMapArtifact: true` in `dotnetdoc.config.json` to emit
45
+ an independent `doc-source-map@1.1.0` file alongside each XML or C# member
46
+ document. The default is `false`. The runner exports the pure
47
+ `createDotnetDocSourceMap()` writer from its existing package; this does not add
48
+ a separately published npm package. The result manifest and
49
+ `document.metadata.docSourceMaps` reference the emitted file and its actual
50
+ contract version only while the option is enabled.
51
+
52
+ ```json
53
+ {
54
+ "schemaVersion": "1.0.0",
55
+ "workspaceRoot": ".",
56
+ "outputDirectory": "dist/dotnetdoc",
57
+ "inputs": [
58
+ { "kind": "dotnet-xml-doc", "path": "bin/Sample.xml", "projectPath": "Sample.csproj" }
59
+ ],
60
+ "options": { "writeDocSourceMapArtifact": true }
61
+ }
62
+ ```
63
+
64
+ Only uniquely matched XML members and native C# members with verified Roslyn
65
+ declaration ranges can carry C# source references. Valid declarations use an
66
+ exclusive end and UTF-16 code-unit columns; recovered syntax or incomplete
67
+ range precision remains explicitly unknown. XML-only inputs without a matching
68
+ project keep symbol entries with no code source reference. The map embeds no
69
+ source text, XML comments or arbitrary producer diagnostics. ASP.NET surface,
70
+ markup comment and project-discovery inputs remain outside this first map
71
+ scope. The older source-relation artifact remains independent and may be
72
+ disabled while source-map emission is enabled.
73
+
74
+ 中文:在配置的 `options` 中显式设置 `writeDocSourceMapArtifact: true` 才生成
75
+ `doc-source-map@1.1.0`。纯数据 writer 从现有 runner 包导出,本轮不增加 npm 包。
76
+ XML 注释来源不会伪装成代码位置;只有唯一匹配的 Roslyn 声明和原生 C# 成员可引用
77
+ 已核工作区内 `.cs` 文件。有效声明逐条写明排除终点及 UTF-16 列单位;恢复解析或
78
+ 列精度不足时标记未知,不能精确查询。映射不包含源码正文或 XML 注释;关系工件与
79
+ 源码映射各有独立用途,关闭映射时结果清单与 HIA 文档也不保留悬空引用。
80
+
19
81
  It also exposes `classifyDotnetBuildDiagnostics()` for target scripts that need
20
82
  to turn compiler XML documentation warnings such as `CS1591` into a
21
83
  generated/designer/manual-source evidence summary.
@@ -85,11 +147,89 @@ execute the target build, download source, parse Windows/Portable PDBs or grant
85
147
  permission. Existing source preview settings still require explicit publication consent.
86
148
 
87
149
  中文:XML是文档出处;代码定位来自已配置项目中的唯一真实Roslyn声明。缺失/歧义保持未定位,
88
- 不会回退XML或按名称猜文件。需要现有.NET 8 SDK/helper;本轮不实现PDB读取,尤其不能把传统
89
- Windows PDB当作Portable PDB。范围与语言随真实声明输出,所有XML注释/本地化字段保持。
150
+ 不会回退XML或按名称猜文件。C# 提取及 XML 的项目源码解析需要稳定的 .NET 10 SDK/runtime 和随包
151
+ Roslyn helper(net10.0,SDK 基线 10.0.100、latestFeature、禁止预览版);仅安装 runtime 无法构建 helper。
152
+ 纯 XML 提取及不调用 helper 的静态扫描无需该 SDK。输入项目可以使用更早的目标框架。
153
+ 不读取 PDB;范围与语言随真实声明输出,所有 XML 注释/本地化字段保持。
154
+
155
+ English. C# extraction and XML project-source resolution require the bundled net10.0 Roslyn helper and a stable
156
+ .NET 10 SDK/runtime (10.0.100 baseline, latestFeature roll-forward, prereleases disabled). A runtime-only install
157
+ cannot build the helper. Plain XML extraction and static scans that do not invoke the helper need no SDK.
158
+ Input projects may target older frameworks. PDB reading is unsupported.
90
159
 
91
160
  ### Coverage diagnostics (0.1.12)
92
161
 
93
162
  Read `document.metadata.sourceLocationResolution` for coverage counts and reference-warning codes, and each `symbol.diagnostics` for `data.symbolId`, `memberName`, `reason` (`missing`/`ambiguous`) and detail. Proven partial types prefer a non-generated declaration, then stable path/start position; the selected rule and candidate count appear in `symbol.metadata.dotnetdoc.sourceLocationResolution`. Duplicate inputs are not silently collapsed. Re-extract artifacts after upgrading; source publication still requires the existing explicit authorization.
94
163
 
95
164
  中文:计数在metadata层;未定位成员逐项带诊断,合法partial记录主声明选择。升级后重新抽取,不改变公开授权。
165
+
166
+ ## API and migration
167
+
168
+ See the [API reference](API.md), [migration guide](MIGRATION.md), and bundled ESM declarations for 1.0.0.
169
+
170
+ 中文:API、精确新旧读取和迁移规则随包提供;类型不替代运行时校验或公开权限。
171
+
172
+ ## Pure metadata
173
+
174
+ ```js
175
+ import { DOTNETDOC_RUNNER_VERSION, DOTNETDOC_INPUT_KINDS, DOTNETDOC_OUTPUT_KINDS } from "@hia-doc/dotnetdoc-runner/metadata";
176
+ ```
177
+
178
+ This entry exposes the runner version and frozen input/output kind arrays from the same definitions used by the root API. It contains pure data definitions, with no runner execution dependencies.
179
+
180
+ 中文说明。metadata子入口提供版本及冻结的输入/输出种类,根入口与该入口引用同一定义。执行构建继续使用原运行API。
181
+
182
+ ## Command reference
183
+
184
+ 中文。本包同时提供hia-dotnetdoc和dotnetdoc,两者选项、输出和退出码相同。在本地npm脚本调用,或 `npm exec --offline -- hia-dotnetdoc --help`。帮助退出0,version输出运行器版本;构建仅success退出0,partial/failed或参数/配置错误退出1。未知参数拒绝,错误文本受控。
185
+
186
+ English. The package provides hia-dotnetdoc and dotnetdoc with identical options, output, and exit codes. Invoke from a local npm script or `npm exec --offline -- hia-dotnetdoc --help`. Help exits 0 and version prints the runner version. Only successful builds exit 0; partial/failed builds and argument/config errors exit 1. Unknown options are rejected with controlled errors.
187
+
188
+ | Option | 中文 | English |
189
+ | --- | --- | --- |
190
+ | `--config/-c <file>` | 调用目录下的JSON配置 | JSON config resolved from cwd |
191
+ | `--workspace-root <dir>` | 仅直接XML模式,相对调用目录,默认`.` | Direct XML only, cwd-relative, default `.` |
192
+ | `--out-dir/-o <dir>` | 两模式覆盖,相对有效工作区 | Override in both modes, relative to effective workspace |
193
+ | `--title <text>` | 仅直接模式,应用于各XML输入 | Direct mode only, applies to every XML input |
194
+ | `--help/-h` | 帮助,退出0 | Help, exit 0 |
195
+ | `--version/-v` | 运行器实现版本 | Runner implementation version |
196
+ | 位置XML / positional XML | 无配置时必填,相对工作区 | Required without config, workspace-relative |
197
+
198
+ ### Config and direct modes
199
+
200
+ 中文。配置模式仅out-dir可覆盖,workspace-root、title与位置输入均忽略。配置workspaceRoot相对配置目录,outputDirectory相对工作区,默认dist/dotnetdoc。详细矩阵与示例见API。以下配置保存为项目根dotnetdoc.config.json并准备获准sample.xml。
201
+
202
+ English. Only out-dir overrides config mode; workspace-root, title, and positionals are ignored. Config workspaceRoot uses the config directory and outputDirectory the workspace, defaulting to dist/dotnetdoc. See the API matrix for detail. Save this as dotnetdoc.config.json at the project root and prepare authorized sample.xml.
203
+
204
+ ```json
205
+ {"schemaVersion":"1.0.0","workspaceRoot":".","outputDirectory":"dist/dotnetdoc","inputs":[{"kind":"dotnet-xml-doc","path":"sample.xml","title":"Sample API"}]}
206
+ ```
207
+
208
+ ```sh
209
+ npm exec --offline -- hia-dotnetdoc --config dotnetdoc.config.json
210
+ npm exec --offline -- dotnetdoc --workspace-root . --out-dir dist/dotnet-direct --title "Sample API" sample.xml
211
+ ```
212
+
213
+ 中文。两条命令均会写出工件与结果清单,可能覆盖旧文件,失败或partial可留有写入。此纯XML示例无需Roslyn helper。C#提取与XML项目源码解析按前文要求稳定.NET10 SDK/helper,输入项目目标框架单独管理。
214
+
215
+ English. Both commands write artifacts and a result manifest, may replace old files, and may leave writes after failure or partial success. This XML-only example needs no Roslyn helper. C# extraction and XML project-source resolution require the stable .NET10 SDK/helper described above, independently of the input project's target framework.
216
+
217
+ ### Installation and version routing
218
+
219
+ 中文。本页为1.0.0源码候选。候选归档须与配套内部依赖一起安装,离线安装另需第三方依赖缓存。注册表路线先用 `npm view @hia-doc/dotnetdoc-runner@1.0.0 version` 并核配套版本,再安装。`npm list @hia-doc/dotnetdoc-runner --depth=0` 核本地包。旧0.1.x快速指南及draft配置按旧包阅读,新配置身份1.0.0与源码地图等产物身份独立。
220
+
221
+ English. This is the 1.0.0 source candidate. Install its archive with matching internal dependencies and prepare a third-party cache for offline installs. For registry installation, check `npm view @hia-doc/dotnetdoc-runner@1.0.0 version` and matching dependencies first. Use `npm list @hia-doc/dotnetdoc-runner --depth=0` for the installed package. Older 0.1.x quickstarts and draft configs retain their scope. Current config identity 1.0.0 is independent from source-map and other artifact versions.
222
+
223
+ ## Generated command documentation and help
224
+
225
+ 中文。hia-dotnetdoc与dotnetdoc的完整参数和别名关系采用同一字段级双语描述,输出16个标准HiaDocument符号。两个正常入口共用规范帮助,真实宽TTY使用120列,其余及重定向使用80列。Node严格解析先于帮助,未知开关/缺值返回固定stderr/1;重复带值选项取最后值,--后均作XML位置输入。合法help跳过配置读取、文件处理及helper启动。
226
+
227
+ English. hia-dotnetdoc and dotnetdoc share field-level bilingual content for complete parameters and their alias relationship, producing 16 standard HiaDocument symbols. Both normal entries use canonical help, at 120 columns on wide TTYs and 80 elsewhere and for redirection. Strict Node parsing precedes help, with unknown switches and missing values producing fixed stderr/1. Repeated value options use the last value, and tokens after -- are positional XML inputs. Valid help skips configuration loading, file processing and helper startup.
228
+
229
+ 中文。配置模式仅非空out-dir覆盖输出,空值保留原配置,workspace-root/title/位置输入忽略。直接模式空输出选择工作区根,实际写入继续遵守运行器边界;省略title由适配器默认规则生成。运行可覆盖已有工件,partial/failed可能保留成功写入。
230
+
231
+ English. Config mode accepts only nonempty out-dir overrides; empty values retain configured output, and workspace-root/title/positionals are ignored. An empty direct-mode output selects the workspace root, with actual writes governed by runner boundaries. Omitted title uses adapter defaults. Runs may replace existing artifacts and retain successful writes after partial or failed results.
232
+
233
+ Seven files ship in `src/command-documentation/`: `description.json`, `observations.json`, `document.hia.json`, `command.schema.json`, `document.schema.json`, `help.mjs` and `generation.json`. Maintainers run `npm run commands:check` to verify current sources, actual parser declarations, schemas and snapshots offline. Regeneration uses `npm run commands:build -- --core-module <core-entry>` with an explicitly selected compatible core. Each invocation has its own declaration observation and the alias uses the existing `aliasOf` relation. Source digests use original package-relative bytes under scoped LF attributes. Line anchors identify only the actual parser call, with unknown endpoint and column units.
234
+
235
+ 中文。运行时只加载随包静态帮助,开发期显式选择core投影并复用现有Ajv校验。两个调用名各有真实声明观察与来源,列单位和终点未知。纯XML无需SDK,配置选择C#或项目来源解析时使用既有.NET10 SDK/helper;dotnet build可能按SDK设置隐式还原并下载工作负载清单。
package/package.json CHANGED
@@ -1,9 +1,12 @@
1
1
  {
2
2
  "name": "@hia-doc/dotnetdoc-runner",
3
- "version": "0.1.12",
3
+ "version": "1.0.0-rc.2",
4
4
  "description": "Standalone .NET XML documentation runner and CLI.",
5
5
  "type": "module",
6
6
  "license": "MIT",
7
+ "engines": {
8
+ "node": "^22.0.0 || ^24.0.0"
9
+ },
7
10
  "keywords": [
8
11
  "hia",
9
12
  "dotnetdoc",
@@ -21,24 +24,37 @@
21
24
  },
22
25
  "homepage": "https://github.com/mandolin/hia-dotnetdoc/tree/main/packages/dotnetdoc-runner#readme",
23
26
  "exports": {
24
- ".": "./src/index.mjs"
27
+ ".": {
28
+ "types": "./src/index.d.mts",
29
+ "default": "./src/index.mjs"
30
+ },
31
+ "./schemas/*": "./src/schemas/*",
32
+ "./metadata": {
33
+ "types": "./src/metadata-types.d.mts",
34
+ "default": "./src/metadata.mjs"
35
+ }
25
36
  },
26
37
  "bin": {
27
38
  "hia-dotnetdoc": "src/cli.mjs",
28
39
  "dotnetdoc": "src/cli.mjs"
29
40
  },
30
41
  "publishConfig": {
31
- "access": "public"
42
+ "access": "public",
43
+ "provenance": true
32
44
  },
33
45
  "files": [
34
46
  "src",
35
47
  "README.md",
36
- "LICENSE"
48
+ "LICENSE",
49
+ "API.md",
50
+ "MIGRATION.md"
37
51
  ],
38
52
  "dependencies": {
39
- "@hia-doc/dotnet-source-extractor": "0.1.12",
40
- "@hia-doc/dotnet-xml-doc-extractor": "0.1.12",
41
- "@hia-doc/dotnetdoc-adapter": "0.1.12",
42
- "@hia-doc/dotnetdoc-spec": "0.1.12"
43
- }
53
+ "@hia-doc/dotnet-source-extractor": "1.0.0-rc.2",
54
+ "@hia-doc/dotnet-xml-doc-extractor": "1.0.0-rc.2",
55
+ "@hia-doc/dotnetdoc-adapter": "1.0.0-rc.2",
56
+ "@hia-doc/dotnetdoc-spec": "1.0.0-rc.2",
57
+ "ajv": "8.20.0"
58
+ },
59
+ "types": "./src/index.d.mts"
44
60
  }