@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 +108 -0
- package/LICENSE +21 -0
- package/MIGRATION.md +81 -0
- package/README.md +165 -2
- package/package.json +50 -4
- package/src/cli.mjs +91 -0
- package/src/command-content.mjs +218 -0
- package/src/command-documentation/command.schema.json +1466 -0
- package/src/command-documentation/description.json +1860 -0
- package/src/command-documentation/document.hia.json +2699 -0
- package/src/command-documentation/document.schema.json +817 -0
- package/src/command-documentation/generation.json +12 -0
- package/src/command-documentation/help.mjs +16 -0
- package/src/command-documentation/observations.json +62 -0
- package/src/config-compatibility.mjs +99 -0
- package/src/index.mjs +405 -0
- package/src/metadata.mjs +27 -0
- package/src/schema-legacy.mjs +57 -0
- package/src/schema.mjs +86 -0
- package/src/schemas/cssdoc-config-0.1.0-draft.schema.json +116 -0
- package/src/schemas/cssdoc-config-1.0.0.schema.json +115 -0
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
|
-
#
|
|
1
|
+
# @hia-doc/cssdoc-runner
|
|
2
2
|
|
|
3
|
-
|
|
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": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
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
|
+
}
|