@hia-doc/cssdoc-runner 0.0.0-stage → 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,108 @@
1
+ # CSSDoc Runner API
2
+
3
+ 中文:仅处理显式输入文件,按确认配置生成提取件/核心文档/映射,支持逐输入失败与边界中止;不发现业务文件。
4
+
5
+ ## Public exports
6
+
7
+ - `runCssDoc(request, context?)`: async one-shot file generation/result.
8
+ - `loadCssDocConfig(configPath, options?)`: reads exact supported config JSON and
9
+ returns a normalized runtime request; does not build.
10
+ - `inferCssDocInputKind(inputPath)`: suffix-only kind inference, no I/O.
11
+ - `CSSDOC_RUNNER_VERSION`: package/producer version `1.0.0`.
12
+ - `CSSDOC_INPUT_KINDS`: frozen css/postcss-css/design-token list.
13
+ - `CSSDOC_OUTPUT_KINDS`: frozen cssdoc-extraction/hia-document/doc-source-map list.
14
+ - `CSSDOC_CONFIG_SCHEMA_VERSION`, `CSSDOC_CONFIG_SCHEMA_ID`,
15
+ `CSSDOC_CONFIG_JSON_SCHEMA`: current `1.0.0` config identity/schema.
16
+ - `CSSDOC_LEGACY_CONFIG_SCHEMA_VERSION`, `CSSDOC_LEGACY_CONFIG_SCHEMA_ID`,
17
+ `CSSDOC_LEGACY_CONFIG_JSON_SCHEMA`: exact original `0.1.0-draft` identity/schema.
18
+ - `getCssDocConfigSchema(identity)`: exact version/ID selector, unknown undefined.
19
+ - `migrateCssDocConfig(value)`: pure explicit legacy JSON copy/identity migration.
20
+
21
+ Root `.` and resources `./schemas/cssdoc-config-0.1.0-draft.schema.json`,
22
+ `./schemas/cssdoc-config-1.0.0.schema.json`; JSON imports use `with { type: "json" }`.
23
+ Bin `cssdoc` supports `--config/-c`, `--kind/-k`, `--out-dir/-o`,
24
+ `--workspace-root`, `--sources-content-policy`, `--no-doc-source-map`,
25
+ `--help/-h`, `--version/-v` and explicit positional inputs. Unknown arguments
26
+ fail; no config or positional input fails. No glob discovery is performed.
27
+
28
+ ## Inputs
29
+
30
+ Runtime requests require absolute `workspaceRoot`/`outputDirectory`, nonempty
31
+ inputs `{ path, kind?, language? }`, optional `profileIds` and options
32
+ `emitDocSourceMap`, `sourcesContentPolicy`, `writeResultManifest`. Input paths are
33
+ lexically safe relative locators; language is an optional nonempty label, not a
34
+ parser selector. Context supports AbortSignal and synchronous `reportProgress`.
35
+ External configs allow exact current/legacy schemaVersion and matching optional
36
+ $schema only, with relative directories; read relative config paths against
37
+ `options.cwd ?? process.cwd()`.
38
+
39
+ ## Returns
40
+
41
+ Runner returns `documentation-producer-result@1.0.0`, producer version `1.0.0`,
42
+ success/partial/failed, relative artifact descriptors and diagnostics. Each
43
+ successful input writes extraction/core plus optional map; output paths derive
44
+ from the source path, input kind and one-based input index. Config loading
45
+ returns fresh normalized input/profile arrays and absolute runtime roots in
46
+ memory. Selectors return shared read-only schemas; migration returns a deep JSON
47
+ copy without mutating input or adding default fields.
48
+
49
+ ## Defaults
50
+
51
+ Loader workspace root `.` relative to config directory; output `dist/cssdoc`
52
+ relative to workspace root. Suffix inference: `.json` design-token,
53
+ `.pcss`/`.postcss.css` postcss-css, otherwise css. Default profileIds `["cssdoc"]`;
54
+ map emission and result manifest true; source-content policy none. CLI paths
55
+ resolve from its workspace root and can override the loaded output/content/map
56
+ options. Profile lists must be nonempty unique lowercase ids.
57
+
58
+ ## Errors
59
+
60
+ Invalid requests/configs throw fixed TypeErrors; file read/parse errors use
61
+ public-safe messages. Per-input read/parse/write failures become
62
+ `CSSDOC_RUNNER_INPUT_FAILED`, allowing subsequent inputs to proceed. An error
63
+ with any returned artifacts yields partial, otherwise failed. Output-directory,
64
+ result-manifest or progress callback exceptions can reject the promise.
65
+ CLI prints a fixed failure and exits 1; help/version exit 0, builds exit 0 only
66
+ on success. The original old schema required fields the old loader could omit;
67
+ compatible old reading does not rewrite that schema's historical required list.
68
+
69
+ ## Effects
70
+
71
+ Creates output directories, reads explicit inputs, writes JSON and optionally
72
+ `cssdoc.producer-result.json`. Writes are non-atomic; partial files can remain
73
+ after failure. Signal is observed before each input, not during parsing/writing;
74
+ completed files remain. Callbacks execute synchronously and their exceptions
75
+ propagate. There is no watch/incremental execution or rollback transaction.
76
+
77
+ ## Compatibility
78
+
79
+ Exact old/current configs preserve loader defaults; migration coordinates only
80
+ schemaVersion and existing $schema. New generated extraction/profile use 1.0.0,
81
+ core/source models 0.2.0 and map 1.1.0. Package versions are independent. See
82
+ [migration](MIGRATION.md); neither full DTCG/CSS conformance nor Sass support is added.
83
+
84
+ ## Source linkage
85
+
86
+ Source policy controls CSS body embedding; token sources remain reference-only.
87
+ Rule fragments and per-reference map precision follow the adapter/map APIs.
88
+ Metadata coordinates and an embed label are not proof of external source access.
89
+
90
+ ## Privacy
91
+
92
+ Absolute runtime roots stay out of results; declared relative inputs remain
93
+ public locators. Paths are checked lexically, not as a symlink sandbox. Use an
94
+ authorized workspace. Source bodies, token metadata and documentation text must
95
+ be authorized/sanitized by the caller. Progress includes relative input paths;
96
+ provide a suitable callback sink. No npm or network publication is executed.
97
+
98
+ ## Pure metadata entry
99
+
100
+ Subpath `./metadata` exports `CSSDOC_RUNNER_VERSION`, `CSSDOC_INPUT_KINDS` and `CSSDOC_OUTPUT_KINDS` from pure definitions. The arrays are frozen, and the root API exposes the same references. This entry performs no runner operations.
101
+
102
+ 中文说明。metadata子入口提供同一版本与冻结输入/输出种类,适用于发现和文档工具。声明分支与运行分支分别提供,构建使用原运行API。
103
+
104
+ ## Command assets
105
+
106
+ The packaged `src/command-documentation/` directory contains draft command descriptions, observations, a standard HiaDocument, schemas and static bilingual help. Source maintainers regenerate through an explicitly selected core implementation and run the offline freshness gate. The existing root exports and metadata subpath retain their responsibilities.
107
+
108
+ 中文。命令资产记录八开关与条件位置输入、运行器版本、配置/直接模式及副作用。真实Node解析表独立观察,帮助经过严格参数解析后输出,来源为调用行级声明。详见[命令资产说明](README.md#command-documentation-assets)。
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/MIGRATION.md ADDED
@@ -0,0 +1,81 @@
1
+ # CSSDoc contract migration
2
+
3
+ ## Version layers
4
+
5
+ Current extraction (`hia-cssdoc-extraction`), config and artifact profile versions
6
+ are `1.0.0`. Exact `0.1.0-draft` JSON reading remains supported. Package versions
7
+ are source candidates at `1.0.0`, producer descriptor/result use `1.0.0`, and documentation
8
+ source maps use `1.1.0`. These numbers identify different contracts. No registry
9
+ release or complete CSS/DTCG conformance is implied.
10
+
11
+ ## Pure extraction migration
12
+
13
+ ```js
14
+ import {
15
+ migrateCssDocExtraction,
16
+ validateCssDocExtraction,
17
+ getCssDocExtractionSchema
18
+ } from "@hia-doc/cssdoc-spec";
19
+
20
+ const migrated = migrateCssDocExtraction(legacyJson);
21
+ const diagnostics = validateCssDocExtraction(migrated); // [] when valid
22
+ const oldSchema = getCssDocExtractionSchema("0.1.0-draft");
23
+ ```
24
+
25
+ Migration accepts an exact supported legacy JSON structure, creates a deep
26
+ copy, changes only `contractVersion` and `profile.version`, and validates the
27
+ target. All other fields and JSON extensions are retained. The input is never
28
+ rewritten. Current/unknown versions, incompatible profiles, invalid structures,
29
+ unsafe declared locators and non-JSON data fail with a fixed TypeError.
30
+ Validation returns fixed diagnostics instead of raw Ajv errors. Neither API
31
+ reads a file, schema URL or source body. Returned selector schemas are shared
32
+ read-only data; clone before modifying them.
33
+
34
+ Optional `parentId` and `summary` retain their original string types; they are
35
+ not broadened to null. Unknown source ranges remain `null` in extraction and
36
+ are omitted from map references. The map writer does not turn unknown ranges
37
+ into proven PostCSS rule coordinates. A future-version number alone never
38
+ establishes compatibility.
39
+
40
+ ## Pure config migration and defaults
41
+
42
+ ```js
43
+ import { migrateCssDocConfig, loadCssDocConfig } from "@hia-doc/cssdoc-runner";
44
+
45
+ const config = migrateCssDocConfig({
46
+ schemaVersion: "0.1.0-draft",
47
+ inputs: [{ path: "src/button.css" }]
48
+ });
49
+ ```
50
+
51
+ The fresh result coordinates `schemaVersion` and an existing `$schema`, retaining
52
+ omissions and every other supported field. No I/O or default insertion occurs.
53
+ The existing loader still resolves an omitted workspace root as `.`, output as
54
+ `dist/cssdoc`, and input kind from the suffix. The new `1.0.0` required list
55
+ matches those defaults; the original old schema required the directories and
56
+ kind. The old schema remains unchanged. Compatible legacy reading/migration
57
+ reflects the old loader behavior, not a claim that the old schema permits these
58
+ omissions. Version and `$schema`, when present, must be an exact pair.
59
+
60
+ ## Bundled schemas and readers
61
+
62
+ Each version has a JSON export under the spec or runner package:
63
+
64
+ - `@hia-doc/cssdoc-spec/schemas/hia-cssdoc-extraction-<version>.schema.json`
65
+ - `@hia-doc/cssdoc-runner/schemas/cssdoc-config-<version>.schema.json`
66
+
67
+ `getCssDocExtractionSchema(identity)` and `getCssDocConfigSchema(identity)` select
68
+ by exact version or schema ID, returning undefined for unknown identities.
69
+ The adapter and map writer validate supported old/current structures. New CSS,
70
+ DTCG and Vue CSS writers use the current pair. Sass's separate
71
+ `cssdoc-extraction` bridge is a different contract and is not silently renamed.
72
+ No complete DTCG resolver or arbitrary CSS syntax is added.
73
+
74
+ 中文:新旧身份、历史默认与schema差异、无损迁移及失败规则分别管理;迁移拒绝
75
+ 非JSON值,不能靠序列化丢字段。配置/提取毕业不等于包首次公开发行或整体正式版验收。
76
+
77
+ ## Metadata subpath
78
+
79
+ Tools can import pure runner metadata from `@hia-doc/cssdoc-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.
80
+
81
+ 中文说明。工具发现可采用metadata子入口;原根入口继续引用同一定义。生产器的数组副本仍可变,暂存描述符继续共享基础副本。
package/README.md CHANGED
@@ -1,3 +1,166 @@
1
- # Temporary Holding Version
1
+ # @hia-doc/cssdoc-runner
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ ## Supported runtime
4
+
5
+ Current source supports Node.js `^22.23.4 || ^24.22.1`. Release checks use
6
+ Node.js 22.23.4 and 24.22.1 on Windows and Ubuntu; actual package qualification
7
+ and npm availability remain separate. The repository default is Node.js 24.22.1.
8
+
9
+ 中文:当前源码运行范围为上述两条已确认版本线,CI/安装验收与实际npm发布分别核对。
10
+
11
+
12
+ Standalone API and CLI for CSS documentation projects.
13
+
14
+ JSON configs use `schemaVersion: "1.0.0"`. The package exports
15
+ `CSSDOC_CONFIG_JSON_SCHEMA` for validation and editor integration.
16
+
17
+ ```js
18
+ import path from "node:path";
19
+ import { runCssDoc } from "@hia-doc/cssdoc-runner";
20
+
21
+ const result = await runCssDoc({
22
+ workspaceRoot: process.cwd(),
23
+ outputDirectory: path.resolve("dist/cssdoc"),
24
+ inputs: [{ kind: "css", path: "src/components.css" }]
25
+ });
26
+ ```
27
+
28
+ The runner accepts `css`, `postcss-css` and `design-token` inputs. It writes
29
+ CSSDoc extraction artifacts, HIA documents, direct-source documentation maps
30
+ and a documentation producer result.
31
+
32
+ ```sh
33
+ cssdoc --config cssdoc.config.json
34
+ ```
35
+
36
+ Source content is not embedded unless `sourcesContentPolicy: "embed"` is set
37
+ explicitly in the config `options` object.
38
+ # Request, configuration and result contract
39
+
40
+ Current source emits `documentation-producer-result@1.0.0`. The producer
41
+ descriptor uses `documentation-producer@1.0.0`; these identities are independent
42
+ of the package candidate version `1.0.0` and CSSDoc extraction/config/profile
43
+ `1.0.0` (exact legacy JSON remains readable).
44
+
45
+ `runCssDoc(request, context?)` requires absolute `workspaceRoot` and
46
+ `outputDirectory`, and a nonempty `inputs` array of safe relative `path`s.
47
+ Kinds are `css`, `postcss-css`, `design-token`. Omitted kinds use suffix
48
+ inference: `.json` means design tokens, `.pcss`/`.postcss.css` means PostCSS,
49
+ otherwise CSS. An optional language must be a nonempty string. Unknown input
50
+ fields are refused; explicit null is not omission.
51
+
52
+ Options: `emitDocSourceMap` and `writeResultManifest` are booleans defaulting
53
+ to true; `sourcesContentPolicy` is `none` (default), `reference` or `embed`.
54
+ `profileIds` defaults to `["cssdoc"]` and must be nonempty, unique lowercase
55
+ identifiers. Runtime roots stay in memory. Output files and result locators
56
+ are relative to `outputDirectory`. The runner creates directories and writes
57
+ JSON artifacts, plus `cssdoc.producer-result.json` unless disabled. Writes are
58
+ not transactional; failed inputs may leave files, and per-input diagnostics
59
+ produce `partial` or `failed` results. `context.signal` is checked before each
60
+ input; synchronous `reportProgress` errors propagate. Input/profile arrays
61
+ are normalized into new arrays. No discovery, watch, incremental or symlink
62
+ sandbox is provided.
63
+
64
+ `loadCssDocConfig(path, {cwd}?)` reads JSON relative to cwd (process cwd by
65
+ default), then resolves `workspaceRoot` relative to the configuration file
66
+ and `outputDirectory` relative to that workspace. Historical defaults are
67
+ `.` and `dist/cssdoc`; the current schema matches these defaults.
68
+ The old schema is retained with its original required list. Pure migration and
69
+ exact schema selectors are available; see [MIGRATION.md](MIGRATION.md). Reads/parsing failures produce a fixed TypeError without raw paths
70
+ or configuration text. Invalid declared fields are rejected before writes.
71
+
72
+ The `cssdoc` CLI supports `--config`, positional inputs, `--kind`, `--out-dir`,
73
+ `--workspace-root`, `--sources-content-policy`, `--no-doc-source-map`, `--help`
74
+ and `--version`. Config and argument failures return exit code 1 with a fixed
75
+ public stderr message; successful help/version return 0. Partial/failed builds
76
+ also return 1. API users receive structured diagnostics for build failures.
77
+
78
+ 中文:本页声明现有 API 的默认值、所有权、写入/回调副作用与失败限制;主 SDK
79
+ 身份已采用,自有1.0.0已匹配既有默认,旧schema/兼容迁移分别保留,不据此声称全部候选稳定。
80
+
81
+
82
+ ## API and compatibility
83
+
84
+ See the packaged [API reference](API.md) and [migration notes](MIGRATION.md) for
85
+ all public entries, ownership, defaults, effects, source precision and privacy.
86
+ The package is a 1.0.0 source candidate; registry availability is a separate gate.
87
+
88
+ 中文:公开责任与迁移文档随包提供;源码候选不代表已经发布npm。
89
+
90
+ ## Pure metadata
91
+
92
+ ```js
93
+ import { CSSDOC_RUNNER_VERSION, CSSDOC_INPUT_KINDS, CSSDOC_OUTPUT_KINDS } from "@hia-doc/cssdoc-runner/metadata";
94
+ ```
95
+
96
+ 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.
97
+
98
+ 中文说明。metadata子入口提供版本及冻结的输入/输出种类,根入口与该入口引用同一定义。执行构建继续使用原运行API。
99
+
100
+ ## Command reference
101
+
102
+ 中文。`--help/-h`从共享双语命令内容生成的随包静态帮助读取,终端按实际宽度选择80/120列,重定向使用80列。Node严格参数解析先于帮助,因此help加未知或缺值选项仍返回固定stderr/1。帮助加缺失配置路径或业务kind值时先显示帮助,业务语义由正常执行另行核验。
103
+
104
+ English. `--help/-h` reads packaged static help generated from shared bilingual command content. TTY width selects an 80/120-column layout and redirected output uses 80 columns. Node strict argument parsing precedes help, so unknown or missing option values still produce controlled stderr/1. Help with a missing config path or a business kind value displays help before business validation.
105
+
106
+ 中文。在本地npm脚本调用,或用 `npm exec --offline -- cssdoc --help`。帮助退出0,version输出运行器版本。构建仅success退出0,partial/failed或参数/配置错误退出1。未知参数拒绝,错误文本受控。会写产物和结果清单,可能覆盖旧文件,失败或部分成功时可留有写入。
107
+
108
+ English. Invoke through a local npm script or `npm exec --offline -- cssdoc --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. Artifacts and a result manifest are written, existing files may be replaced, and failed/partial runs may leave writes.
109
+
110
+ | Option | 中文 | English |
111
+ | --- | --- | --- |
112
+ | `--config/-c <file>` | 调用目录下的JSON配置 | JSON config resolved from cwd |
113
+ | `--workspace-root <dir>` | 仅直接模式,相对调用目录,默认`.` | Direct mode only, cwd-relative, default `.` |
114
+ | `--kind/-k <kind>` | 仅直接模式,css/postcss-css/design-token | Direct mode only, css/postcss-css/design-token |
115
+ | `--out-dir/-o <dir>` | 两模式覆盖,相对工作区 | Override in both modes, workspace-relative |
116
+ | `--sources-content-policy <policy>` | 两模式覆盖,none/reference/embed,默认none | Override in both modes, none/reference/embed, default none |
117
+ | `--no-doc-source-map` | 两模式关闭地图,默认启用 | Disable maps in both modes, enabled by default |
118
+ | `--help/-h` | 帮助,退出0 | Help, exit 0 |
119
+ | `--version/-v` | 运行器实现版本 | Runner implementation version |
120
+ | 位置输入 / positional inputs | 仅直接模式,必填且相对工作区 | Direct mode only, required and workspace-relative |
121
+
122
+ ### Config and direct modes
123
+
124
+ 中文。配置workspaceRoot相对配置目录,默认`.`;outputDirectory相对工作区,默认dist/cssdoc。配置模式忽略workspace-root、kind和位置输入;out-dir、sources-content-policy与no-doc-source-map读取后生效。直接模式按文件名推断kind或采用显式值。embed会把源码正文写入产物,使用前须确认公开许可。
125
+
126
+ English. Config workspaceRoot uses the config directory and defaults to `.`; outputDirectory is workspace-relative and defaults to dist/cssdoc. Config mode ignores workspace-root, kind, and positionals, then applies out-dir, sources-content-policy, and no-doc-source-map. Direct mode infers kind from filenames unless supplied. Confirm publication permission before embed writes source bodies into artifacts.
127
+
128
+ 中文。配置模式中空字符串out-dir与sources-content-policy保留原配置;非空值覆盖。直接模式显式空out-dir解析为工作区根,省略则为dist/cssdoc;显式空sources-content-policy按无效策略拒绝。
129
+
130
+ English. In config mode empty out-dir and sources-content-policy strings retain configured values, while nonempty values override them. In direct mode an explicit empty out-dir resolves to the workspace root and omission uses dist/cssdoc. An explicit empty direct-mode source policy is rejected as invalid.
131
+
132
+ 保存为项目根的cssdoc.config.json,并准备获准sample.css。Save at the project root and prepare authorized sample.css.
133
+
134
+ ```json
135
+ {"schemaVersion":"1.0.0","workspaceRoot":".","outputDirectory":"dist/cssdoc","inputs":[{"kind":"css","path":"sample.css"}],"options":{"sourcesContentPolicy":"none"}}
136
+ ```
137
+
138
+ ```sh
139
+ npm exec --offline -- cssdoc --config cssdoc.config.json
140
+ npm exec --offline -- cssdoc --workspace-root . --kind css --out-dir dist/css-direct --sources-content-policy none --no-doc-source-map sample.css
141
+ ```
142
+
143
+ ### Installation and version routing
144
+
145
+ 中文。本页为1.0.0源码候选,候选归档连同配套内部依赖安装,离线安装另需第三方缓存。走注册表时先用 `npm view @hia-doc/cssdoc-runner@1.0.0 version` 并核配套版本,再安装。用 `npm list @hia-doc/cssdoc-runner --depth=0` 核本地版本。旧0.1.x教程保留原包范围,当前配置和提取/profile为1.0.0,源码地图版本独立。
146
+
147
+ 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/cssdoc-runner@1.0.0 version` and matching dependencies first. Use `npm list @hia-doc/cssdoc-runner --depth=0` for the local version. Older 0.1.x tutorials retain their scope. Current config/extraction/profile identities are 1.0.0, while source maps are versioned independently.
148
+
149
+ ### Command documentation assets
150
+
151
+ 中文。包内`src/command-documentation/`提供`description.json`、`observations.json`、`document.hia.json`、两份自包含schema、静态help模块及生成摘要。描述采用独立`command-documentation@0.1.0-draft`,生成核心文档采用`hia-core-document@1.0.0`。命令采用与CSS提取产物的版本分别读取。
152
+
153
+ English. `src/command-documentation/` contains a command description, actual declaration observations, a standard HiaDocument, two self-contained schemas, static help and generation digests. The command description uses `command-documentation@0.1.0-draft`, with its document using `hia-core-document@1.0.0`. Read CSS extraction artifacts against their own versions.
154
+
155
+ 中文。源码维护者运行`npm run commands:check`核实际来源、解析声明、快照和schema。修改相关源或命令内容后,使用已安装的`@hia-doc/core`运行`npm run commands:build`,或显式指定已编译核心入口。候选环境请准备匹配的核心归档或源码入口,安装资格按实际版本核对。
156
+
157
+ English. Source maintainers run `npm run commands:check` to verify actual sources, parser declarations, snapshots and schemas. After relevant source or content changes, regenerate with an installed `@hia-doc/core`, or explicitly select a compiled core entry. Prepare a matching core archive or source entry for candidate environments and verify the installed version separately.
158
+
159
+ ```sh
160
+ npm run commands:build -- --core-module <compiled-core-entry.js>
161
+ npm run commands:check
162
+ ```
163
+
164
+ 中文。开发期在一次性子进程核真实parseArgs表,执行core严格投影;日常CI离线核已生成快照。CLI使用静态帮助。来源文件按本仓限定LF属性保持跨平台原字节摘要一致,来源锚点只记录实际解析调用行。
165
+
166
+ English. Development-time generation observes actual parseArgs settings in a disposable process and runs strict core projection. Routine CI verifies the generated snapshot offline. CLI help consumes static content. Scoped repository LF attributes keep original-byte digests consistent across platforms, and source anchors record the actual parser-call line.
package/package.json CHANGED
@@ -1,6 +1,52 @@
1
1
  {
2
2
  "name": "@hia-doc/cssdoc-runner",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "1.0.0-rc.2",
4
+ "description": "Standalone CSSDoc project runner and CLI.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "exports": {
8
+ ".": "./src/index.mjs",
9
+ "./schemas/cssdoc-config-0.1.0-draft.schema.json": "./src/schemas/cssdoc-config-0.1.0-draft.schema.json",
10
+ "./schemas/cssdoc-config-1.0.0.schema.json": "./src/schemas/cssdoc-config-1.0.0.schema.json",
11
+ "./metadata": "./src/metadata.mjs"
12
+ },
13
+ "bin": {
14
+ "cssdoc": "./src/cli.mjs"
15
+ },
16
+ "files": [
17
+ "src",
18
+ "README.md",
19
+ "API.md",
20
+ "MIGRATION.md",
21
+ "LICENSE"
22
+ ],
23
+ "engines": {
24
+ "node": "^22.23.4 || ^24.22.1"
25
+ },
26
+ "dependencies": {
27
+ "@hia-doc/css-doc-adapter": "1.0.0-rc.2",
28
+ "@hia-doc/css-doc-extractor": "1.0.0-rc.2",
29
+ "@hia-doc/css-doc-source-map": "1.0.0-rc.2",
30
+ "@hia-doc/cssdoc-spec": "1.0.0-rc.2",
31
+ "@hia-doc/design-token-bridge": "1.0.0-rc.2",
32
+ "ajv": "8.20.0"
33
+ },
34
+ "publishConfig": {
35
+ "access": "public",
36
+ "registry": "https://registry.npmjs.org/"
37
+ },
38
+ "repository": {
39
+ "type": "git",
40
+ "url": "git+https://github.com/mandolin/hia-cssdoc.git",
41
+ "directory": "packages/cssdoc-runner"
42
+ },
43
+ "homepage": "https://github.com/mandolin/hia-cssdoc/tree/main/packages/cssdoc-runner",
44
+ "bugs": {
45
+ "url": "https://github.com/mandolin/hia-cssdoc/issues"
46
+ },
47
+ "keywords": [
48
+ "documentation",
49
+ "css",
50
+ "hia"
51
+ ]
52
+ }
package/src/cli.mjs ADDED
@@ -0,0 +1,91 @@
1
+ #!/usr/bin/env node
2
+
3
+ /**
4
+ * @file
5
+ * @lang zh-CN CSSDoc严格解析优先的命令入口,帮助使用随包生成的静态双语内容。
6
+ * @lang en CSSDoc's parse-first command entry, using packaged generated bilingual help.
7
+ */
8
+
9
+ import path from "node:path";
10
+ import { parseArgs } from "node:util";
11
+
12
+ import {
13
+ CSSDOC_RUNNER_VERSION,
14
+ inferCssDocInputKind,
15
+ loadCssDocConfig,
16
+ runCssDoc
17
+ } from "./index.mjs";
18
+
19
+ // <lang><zh-CN>命令解析与执行共享公开错误边界,未知参数也不能泄露原文/栈。</zh-CN><en>Argument parsing and execution share the public error boundary, including unknown options.</en></lang>
20
+ try {
21
+ const { values, positionals } = parseArgs({
22
+ options: {
23
+ config: { type: "string", short: "c" },
24
+ help: { type: "boolean", short: "h" },
25
+ kind: { type: "string", short: "k" },
26
+ "no-doc-source-map": { type: "boolean" },
27
+ "out-dir": { type: "string", short: "o" },
28
+ "sources-content-policy": { type: "string" },
29
+ version: { type: "boolean", short: "v" },
30
+ "workspace-root": { type: "string" }
31
+ },
32
+ allowPositionals: true,
33
+ strict: true
34
+ });
35
+
36
+ if (values.help) {
37
+ // <lang><zh-CN>严格参数解析完成后才读取随包静态帮助,列宽只选择已确认两画布。</zh-CN><en>Load packaged static help only after strict argument parsing, selecting only the two confirmed canvases.</en></lang>
38
+ const { CSSDOC_HELP_80, CSSDOC_HELP_120 } = await import("./command-documentation/help.mjs");
39
+ process.stdout.write(process.stdout.isTTY && process.stdout.columns >= 120 ? CSSDOC_HELP_120 : CSSDOC_HELP_80);
40
+ process.exit(0);
41
+ }
42
+
43
+ if (values.version) {
44
+ process.stdout.write(`${CSSDOC_RUNNER_VERSION}\n`);
45
+ process.exit(0);
46
+ }
47
+
48
+ // <lang><zh-CN>配置或显式输入建立内存运行请求,随后runner校验并写入。</zh-CN><en>Config or explicit inputs build the in-memory request before runner validation and writes.</en></lang>
49
+ const request = values.config
50
+ ? await loadCssDocConfig(values.config)
51
+ : createCliRequest(values, positionals);
52
+
53
+ if (values["out-dir"]) {
54
+ request.outputDirectory = path.resolve(request.workspaceRoot, values["out-dir"]);
55
+ }
56
+ if (values["sources-content-policy"]) {
57
+ request.options.sourcesContentPolicy = values["sources-content-policy"];
58
+ }
59
+ if (values["no-doc-source-map"]) {
60
+ request.options.emitDocSourceMap = false;
61
+ }
62
+
63
+ const result = await runCssDoc(request);
64
+ process.stdout.write(`CSSDoc ${result.status}: ${result.artifacts.length} artifact(s).\n`);
65
+ process.exitCode = result.status === "success" ? 0 : 1;
66
+ } catch {
67
+ process.stderr.write("CSSDoc failed: invalid arguments/configuration or build failure.\n");
68
+ process.exitCode = 1;
69
+ }
70
+
71
+ /** @param {object} cliValues <lang><zh-CN>parseArgs后的开关。</zh-CN><en>Options after parseArgs.</en></lang> @param {string[]} inputs <lang><zh-CN>相对输入。</zh-CN><en>Relative inputs.</en></lang> @returns {object} <lang><zh-CN>内存运行请求,绝对根不公开。</zh-CN><en>In-memory request whose absolute roots stay private.</en></lang> @throws {TypeError} <lang><zh-CN>没有输入时拒绝。</zh-CN><en>Refuses missing inputs.</en></lang> */
72
+ function createCliRequest(cliValues, inputs) {
73
+ if (inputs.length === 0) {
74
+ throw new TypeError("At least one input or --config is required.");
75
+ }
76
+ // <lang><zh-CN>进程工作目录只解析运行根,不进公开工件。</zh-CN><en>cwd resolves runtime roots only, never public artifacts.</en></lang>
77
+ const workspaceRoot = path.resolve(process.cwd(), cliValues["workspace-root"] ?? ".");
78
+ return {
79
+ workspaceRoot,
80
+ outputDirectory: path.resolve(workspaceRoot, cliValues["out-dir"] ?? "dist/cssdoc"),
81
+ inputs: inputs.map((inputPath) => ({
82
+ kind: cliValues.kind ?? inferCssDocInputKind(inputPath),
83
+ path: inputPath
84
+ })),
85
+ options: {
86
+ emitDocSourceMap: !cliValues["no-doc-source-map"],
87
+ sourcesContentPolicy: cliValues["sources-content-policy"] ?? "none",
88
+ writeResultManifest: true
89
+ }
90
+ };
91
+ }