@hia-doc/css-doc-extractor 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 +70 -0
- package/LICENSE +21 -0
- package/MIGRATION.md +10 -0
- package/README.md +22 -2
- package/package.json +41 -4
- package/src/index.mjs +509 -0
package/API.md
ADDED
|
@@ -0,0 +1,70 @@
|
|
|
1
|
+
# CSS Doc Extractor API
|
|
2
|
+
|
|
3
|
+
中文:从实际CSS及其显式注释生成CSSDoc JSON;不会把所有选择器自动升级为文档符号。
|
|
4
|
+
|
|
5
|
+
## Public exports
|
|
6
|
+
|
|
7
|
+
- `extractCssDoc(source, options?)`: parses source and projects supported explicit
|
|
8
|
+
CSSDoc annotations attached to the next documentable rule/declaration/at-rule.
|
|
9
|
+
- `parseCssDocComment(rawComment, options?)`: parses a comment body into
|
|
10
|
+
annotations, summary and optional field-level i18n without parsing CSS.
|
|
11
|
+
|
|
12
|
+
Only `.` is exported; no binary or JSON resource subpaths.
|
|
13
|
+
|
|
14
|
+
## Inputs
|
|
15
|
+
|
|
16
|
+
Use a CSS string plus ordinary options `path`, `defaultLocale`,
|
|
17
|
+
`sourcesContentPolicy`. Comment parsing stringifies its body; provide text, not
|
|
18
|
+
objects with custom coercion. Both APIs accept a locale option.
|
|
19
|
+
Supported symbol tags are component/selector/modifier/cssprop/token/layer/media/
|
|
20
|
+
container/keyframes. `description`, canonical `@lang` and inline `<lang>/<l>`
|
|
21
|
+
provide text/i18n. Recognition in the spec's tag list is not a promise to emit
|
|
22
|
+
an independent symbol for every tag, e.g. `example`.
|
|
23
|
+
|
|
24
|
+
## Returns
|
|
25
|
+
|
|
26
|
+
Extraction produces `hia-cssdoc-extraction@1.0.0`, artifact profile `cssdoc@1.0.0`,
|
|
27
|
+
producer version `1.0.0`, symbols/annotations/diagnostics and a source-map ref.
|
|
28
|
+
Comment parsing returns `{ annotations, summary, i18n }`; absent prose yields
|
|
29
|
+
null summary/i18n. It is a comment parse result, not itself an extraction artifact.
|
|
30
|
+
New objects are allocated; source/annotation records can be shared among
|
|
31
|
+
symbols projected from one target. Clone before mutating shared nested data.
|
|
32
|
+
|
|
33
|
+
## Defaults
|
|
34
|
+
|
|
35
|
+
Path `input.css`, normalized default locale `en`, source-content policy `none`.
|
|
36
|
+
Only `embed` places the supplied full source in `source.sourcesContent`;
|
|
37
|
+
`reference` and `none` retain no body. A component parents supported secondary
|
|
38
|
+
annotations from that block. Repeated CSS symbol slugs receive numeric suffixes
|
|
39
|
+
within the call; unattached comments create no symbols.
|
|
40
|
+
|
|
41
|
+
## Errors
|
|
42
|
+
|
|
43
|
+
Path/policy failures use fixed TypeErrors; raw PostCSS syntax errors propagate
|
|
44
|
+
and may contain source/path data. Unknown syntactically valid annotation tags
|
|
45
|
+
can yield `CSSDOC_UNKNOWN_TAG` warnings with tag text. The API is an extractor,
|
|
46
|
+
not a general schema validator for arbitrary option objects.
|
|
47
|
+
|
|
48
|
+
## Effects
|
|
49
|
+
|
|
50
|
+
Synchronous in-memory parsing only, no reads/writes/network, plugins, file
|
|
51
|
+
discovery or publish action. Default extraction does not embed source.
|
|
52
|
+
|
|
53
|
+
## Compatibility
|
|
54
|
+
|
|
55
|
+
New output uses the current wire/profile pair; the spec's explicit migration
|
|
56
|
+
and exact readers retain `0.1.0-draft`. See [migration](MIGRATION.md). This is a
|
|
57
|
+
bounded CSSDoc subset, not complete CSS/Sass/DTCG semantic validation.
|
|
58
|
+
|
|
59
|
+
## Source linkage
|
|
60
|
+
|
|
61
|
+
Attached comments retain annotation locations; generated symbols point to the
|
|
62
|
+
target node. Multiple symbols may project the same target range. Only the
|
|
63
|
+
established PostCSS rule chain proves inclusive UTF-16 bounds; downstream maps
|
|
64
|
+
declare other targets unknown, and adapters emit no invented exact fragment.
|
|
65
|
+
|
|
66
|
+
## Privacy
|
|
67
|
+
|
|
68
|
+
The caller must authorize source embedding and publication of prose, tags and
|
|
69
|
+
diagnostics. Lexical source checks do not sanitize arbitrary CSS or annotation
|
|
70
|
+
text, and raw parser errors are not safe public error messages.
|
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,10 @@
|
|
|
1
|
+
# Compatibility and migration
|
|
2
|
+
|
|
3
|
+
Writer package provenance now uses 1.0.0; extraction/profile use their already coordinated 1.0.0 identities. Explicit annotation and i18n scope is unchanged. Legacy reading/migration belongs to cssdoc-spec.
|
|
4
|
+
|
|
5
|
+
This source candidate does not imply registry publication. Node.js support is
|
|
6
|
+
`^22.23.4 || ^24.22.1`. Internal runtime dependencies are pinned to the matching
|
|
7
|
+
1.0.0 candidate cohort. See [API responsibilities](API.md) for inputs, ownership,
|
|
8
|
+
defaults, errors, effects, precision and privacy before adopting the package.
|
|
9
|
+
|
|
10
|
+
中文:包候选与真实发布分开;保留已确认的稳定子集和旧读责任,不按包号推定源码精度。
|
package/README.md
CHANGED
|
@@ -1,3 +1,23 @@
|
|
|
1
|
-
#
|
|
1
|
+
# CSS Doc Extractor
|
|
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
|
+
Extracts documentation symbols, annotations, diagnostics and source references from CSS sources.
|
|
13
|
+
|
|
14
|
+
Current output uses `hia-cssdoc-extraction@1.0.0` and its paired artifact profile. The existing input subset is unchanged; this is not a full CSS/DTCG validator. See the repository migration guide for exact historical reading and source-precision limits.
|
|
15
|
+
|
|
16
|
+
|
|
17
|
+
## API and compatibility
|
|
18
|
+
|
|
19
|
+
See the packaged [API reference](API.md) and [migration notes](MIGRATION.md) for
|
|
20
|
+
all public entries, ownership, defaults, effects, source precision and privacy.
|
|
21
|
+
The package is a 1.0.0 source candidate; registry availability is a separate gate.
|
|
22
|
+
|
|
23
|
+
中文:公开责任与迁移文档随包提供;源码候选不代表已经发布npm。
|
package/package.json
CHANGED
|
@@ -1,6 +1,43 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@hia-doc/css-doc-extractor",
|
|
3
|
-
"version": "
|
|
4
|
-
"
|
|
5
|
-
"
|
|
6
|
-
|
|
3
|
+
"version": "1.0.0-rc.2",
|
|
4
|
+
"description": "Extracts CSSDoc artifacts from CSS sources.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"type": "module",
|
|
7
|
+
"exports": {
|
|
8
|
+
".": "./src/index.mjs"
|
|
9
|
+
},
|
|
10
|
+
"dependencies": {
|
|
11
|
+
"@hia-doc/css-doc-source-map": "1.0.0-rc.2",
|
|
12
|
+
"@hia-doc/css-parser": "1.0.0-rc.2",
|
|
13
|
+
"@hia-doc/cssdoc-spec": "1.0.0-rc.2"
|
|
14
|
+
},
|
|
15
|
+
"engines": {
|
|
16
|
+
"node": "^22.23.4 || ^24.22.1"
|
|
17
|
+
},
|
|
18
|
+
"files": [
|
|
19
|
+
"src",
|
|
20
|
+
"README.md",
|
|
21
|
+
"API.md",
|
|
22
|
+
"MIGRATION.md",
|
|
23
|
+
"LICENSE"
|
|
24
|
+
],
|
|
25
|
+
"publishConfig": {
|
|
26
|
+
"access": "public",
|
|
27
|
+
"registry": "https://registry.npmjs.org/"
|
|
28
|
+
},
|
|
29
|
+
"repository": {
|
|
30
|
+
"type": "git",
|
|
31
|
+
"url": "git+https://github.com/mandolin/hia-cssdoc.git",
|
|
32
|
+
"directory": "packages/css-doc-extractor"
|
|
33
|
+
},
|
|
34
|
+
"homepage": "https://github.com/mandolin/hia-cssdoc/tree/main/packages/css-doc-extractor",
|
|
35
|
+
"bugs": {
|
|
36
|
+
"url": "https://github.com/mandolin/hia-cssdoc/issues"
|
|
37
|
+
},
|
|
38
|
+
"keywords": [
|
|
39
|
+
"documentation",
|
|
40
|
+
"css",
|
|
41
|
+
"hia"
|
|
42
|
+
]
|
|
43
|
+
}
|
package/src/index.mjs
ADDED
|
@@ -0,0 +1,509 @@
|
|
|
1
|
+
/** @file 显式CSSDoc注释到版本化JSON工件,保留来源与字段级i18n。 @lang en Explicit CSSDoc comments to versioned JSON artifacts with source provenance and field-level i18n. */
|
|
2
|
+
import { createCssDocSourceMapRef, normalizeSourcesContentPolicy } from "@hia-doc/css-doc-source-map";
|
|
3
|
+
import { getCssNodeLocation, normalizeSourcePath, parseCss } from "@hia-doc/css-parser";
|
|
4
|
+
import {
|
|
5
|
+
CSSDOC_EXTRACTION_CONTRACT,
|
|
6
|
+
CSSDOC_EXTRACTION_CONTRACT_VERSION,
|
|
7
|
+
CSSDOC_PROFILE_VERSION,
|
|
8
|
+
getCssDocSymbolKind,
|
|
9
|
+
isCssDocTag
|
|
10
|
+
} from "@hia-doc/cssdoc-spec";
|
|
11
|
+
|
|
12
|
+
const PRIMARY_TAGS = ["component", "selector", "cssprop", "keyframes", "layer", "media", "container", "token"];
|
|
13
|
+
const DEFAULT_LOCALE = "en";
|
|
14
|
+
const HIA_TEXT_I18N_MODEL = "hia-text-i18n";
|
|
15
|
+
const HIA_TEXT_I18N_MODEL_VERSION = "0.2.0";
|
|
16
|
+
|
|
17
|
+
/**
|
|
18
|
+
* @lang zh-CN 将紧邻CSS目标的显式注释标签投影为文档符号,生成受源码内容策略控制的当前提取件。
|
|
19
|
+
* @lang en Projects explicit comment tags adjacent to CSS targets into documentation symbols, producing a current extraction governed by the source-content policy.
|
|
20
|
+
* @param {string} source <lang><zh-CN>显式CSS文本,不读文件。</zh-CN><en>Explicit CSS text without file reads.</en></lang>
|
|
21
|
+
* @param {object} [options] <lang><zh-CN>path默认input.css,defaultLocale默认en,sourcesContentPolicy默认none;仅embed保留正文。</zh-CN><en>path defaults to input.css, defaultLocale to en, sourcesContentPolicy to none; only embed retains the body.</en></lang>
|
|
22
|
+
* @returns {object} <lang><zh-CN>当前CSSDoc JSON,不改输入;同目标多个符号可共享嵌套来源/注释对象。</zh-CN><en>Current CSSDoc JSON without input mutation; multiple symbols on one target may share nested source/annotation objects.</en></lang>
|
|
23
|
+
* @throws {TypeError|Error} <lang><zh-CN>路径/策略固定拒绝;原生PostCSS语法错误可含源码,公开前须处理。</zh-CN><en>Fixed path/policy refusal; native PostCSS syntax errors may contain source and require handling before disclosure.</en></lang>
|
|
24
|
+
*/
|
|
25
|
+
export function extractCssDoc(source, options = {}) {
|
|
26
|
+
// <lang><zh-CN>定位器只做公开相对路径检查,不读取路径。</zh-CN><en>Check a public relative locator without reading its path.</en></lang>
|
|
27
|
+
const sourcePath = normalizeSourcePath(options.path ?? "input.css");
|
|
28
|
+
// <lang><zh-CN>无效locale沿用英语默认,不临时发明语言语法。</zh-CN><en>Invalid locale falls back to English without inventing locale syntax.</en></lang>
|
|
29
|
+
const defaultLocale = normalizeLocale(options.defaultLocale) || DEFAULT_LOCALE;
|
|
30
|
+
// <lang><zh-CN>本次原生AST与紧邻注释配对,只识别实际目标,不自动扫描生成其它符号。</zh-CN><en>This call's native AST and adjacent-comment pairs identify actual targets without automatically generating other symbols.</en></lang>
|
|
31
|
+
const parsed = parseCss(source, { path: sourcePath });
|
|
32
|
+
const pairs = collectAttachedCommentPairs(parsed.root);
|
|
33
|
+
// <lang><zh-CN>四组累积状态只属于本次提取,ID集合维护同一文档内唯一性。</zh-CN><en>Four accumulators belong to this extraction only; allocated ids maintain within-document uniqueness.</en></lang>
|
|
34
|
+
const symbols = [];
|
|
35
|
+
const annotations = [];
|
|
36
|
+
const diagnostics = [...parsed.diagnostics];
|
|
37
|
+
const usedIds = new Set();
|
|
38
|
+
|
|
39
|
+
for (const pair of pairs) {
|
|
40
|
+
// <lang><zh-CN>注释块携带标签及局部语言;无标签不构建符号。</zh-CN><en>The comment block carries tags/localized text; no tags means no symbols.</en></lang>
|
|
41
|
+
const block = parseCssDocComment(pair.comment.text ?? "", { defaultLocale });
|
|
42
|
+
if (block.annotations.length === 0) {
|
|
43
|
+
continue;
|
|
44
|
+
}
|
|
45
|
+
|
|
46
|
+
// <lang><zh-CN>同目标位置由其各标签共享,注释自身范围单列。</zh-CN><en>Tags on one target share its location while the comment's own range stays separate.</en></lang>
|
|
47
|
+
const target = createTargetInfo(pair.node, sourcePath);
|
|
48
|
+
annotations.push({
|
|
49
|
+
tags: block.annotations,
|
|
50
|
+
source: target.source,
|
|
51
|
+
annotation: toAnnotationRange(pair.comment)
|
|
52
|
+
});
|
|
53
|
+
|
|
54
|
+
// <lang><zh-CN>第一个component建父符号,其余支持标签可从属该父节点。</zh-CN><en>The first component creates a parent symbol for other supported tags.</en></lang>
|
|
55
|
+
const parentAnnotation = block.annotations.find((annotation) => annotation.tag === "component");
|
|
56
|
+
let parentId = null;
|
|
57
|
+
if (parentAnnotation) {
|
|
58
|
+
const symbol = createSymbolFromAnnotation(parentAnnotation, target, pair.comment, block, usedIds, null, defaultLocale);
|
|
59
|
+
symbols.push(symbol);
|
|
60
|
+
parentId = symbol.id;
|
|
61
|
+
}
|
|
62
|
+
|
|
63
|
+
for (const annotation of block.annotations) {
|
|
64
|
+
if (annotation.tag === "component" || annotation.tag === "description" || annotation.tag === "lang" || annotation.tag === "cssdoc") {
|
|
65
|
+
continue;
|
|
66
|
+
}
|
|
67
|
+
// <lang><zh-CN>只接受显式种类;识别标签并不自动承诺独立符号。</zh-CN><en>Accept only explicit kinds; recognizing a tag never automatically promises an independent symbol.</en></lang>
|
|
68
|
+
const kind = getCssDocSymbolKind(annotation.tag);
|
|
69
|
+
if (!kind) {
|
|
70
|
+
diagnostics.push(createDiagnostic("CSSDOC_UNKNOWN_TAG", `Unknown CSSDoc annotation tag: @${annotation.tag}`, "warning", target.source, { tag: annotation.tag }));
|
|
71
|
+
continue;
|
|
72
|
+
}
|
|
73
|
+
if (!PRIMARY_TAGS.includes(annotation.tag) && !parentId) {
|
|
74
|
+
continue;
|
|
75
|
+
}
|
|
76
|
+
symbols.push(createSymbolFromAnnotation(annotation, target, pair.comment, block, usedIds, parentId, defaultLocale));
|
|
77
|
+
}
|
|
78
|
+
}
|
|
79
|
+
|
|
80
|
+
// <lang><zh-CN>仅调用方明确embed才把已提供正文放进工件,引用不触发读取。</zh-CN><en>Only explicit embed puts the supplied body into the artifact; reference never triggers a read.</en></lang>
|
|
81
|
+
const sourcesContentPolicy = normalizeSourcesContentPolicy(options.sourcesContentPolicy ?? "none");
|
|
82
|
+
const sourceRecord = {
|
|
83
|
+
kind: "css",
|
|
84
|
+
path: sourcePath
|
|
85
|
+
};
|
|
86
|
+
if (sourcesContentPolicy === "embed") {
|
|
87
|
+
sourceRecord.sourcesContent = source;
|
|
88
|
+
}
|
|
89
|
+
|
|
90
|
+
return {
|
|
91
|
+
contract: CSSDOC_EXTRACTION_CONTRACT,
|
|
92
|
+
contractVersion: CSSDOC_EXTRACTION_CONTRACT_VERSION,
|
|
93
|
+
producer: {
|
|
94
|
+
name: "@hia-doc/css-doc-extractor",
|
|
95
|
+
version: "1.0.0"
|
|
96
|
+
},
|
|
97
|
+
profile: {
|
|
98
|
+
name: "cssdoc",
|
|
99
|
+
version: CSSDOC_PROFILE_VERSION
|
|
100
|
+
},
|
|
101
|
+
defaultLocale,
|
|
102
|
+
locales: collectLocales([defaultLocale, ...symbols.flatMap((symbol) => symbol.i18n?.locales ?? [])]),
|
|
103
|
+
source: sourceRecord,
|
|
104
|
+
symbols,
|
|
105
|
+
annotations,
|
|
106
|
+
diagnostics,
|
|
107
|
+
sourceMap: createCssDocSourceMapRef({ sourcesContentPolicy }),
|
|
108
|
+
metadata: {
|
|
109
|
+
parser: parsed.parser
|
|
110
|
+
}
|
|
111
|
+
};
|
|
112
|
+
}
|
|
113
|
+
|
|
114
|
+
/**
|
|
115
|
+
* @lang zh-CN 规范化CSS注释换行和行首星号,分离标签与普通正文,再生成摘要和字段级多语言信息。
|
|
116
|
+
* @lang en Normalizes CSS comment newlines and leading asterisks, separates tags from prose, and produces a summary and field-level localization.
|
|
117
|
+
* @param {string} rawComment <lang><zh-CN>注释正文;实现会字符串化,不宜传带自定义转换对象。</zh-CN><en>Comment body; implementation stringifies it, so avoid custom coercion objects.</en></lang>
|
|
118
|
+
* @param {Object} [options] <lang><zh-CN>提取语言配置。</zh-CN><en>Extraction locale options.</en></lang>
|
|
119
|
+
* @param {string} [options.defaultLocale="en"] <lang><zh-CN>默认文本语言。</zh-CN><en>Default text locale.</en></lang>
|
|
120
|
+
* @returns {object} <lang><zh-CN>标签、summary/null及i18n/null;无I/O,不是完整提取工件。</zh-CN><en>Annotations, summary/null and i18n/null; no I/O and not a complete extraction artifact.</en></lang>
|
|
121
|
+
*/
|
|
122
|
+
export function parseCssDocComment(rawComment, options = {}) {
|
|
123
|
+
// <lang><zh-CN>注释文本按既有逻辑规范化换行与星号;不用于原始源码片段切片。</zh-CN><en>Normalize comment newlines/asterisks by existing rules, never using this text to slice original source fragments.</en></lang>
|
|
124
|
+
const lines = String(rawComment)
|
|
125
|
+
.replaceAll("\r\n", "\n")
|
|
126
|
+
.replaceAll("\r", "\n")
|
|
127
|
+
.split("\n")
|
|
128
|
+
.map((line) => line.replace(/^\s*\* ?/, "").trim());
|
|
129
|
+
|
|
130
|
+
// <lang><zh-CN>标签与普通正文分开累积,保留顺序供字段级i18n投影。</zh-CN><en>Accumulate tags and prose separately, retaining order for field-level i18n projection.</en></lang>
|
|
131
|
+
const annotations = [];
|
|
132
|
+
const prose = [];
|
|
133
|
+
|
|
134
|
+
for (const line of lines) {
|
|
135
|
+
if (!line) {
|
|
136
|
+
continue;
|
|
137
|
+
}
|
|
138
|
+
// <lang><zh-CN>只识别行首标签,普通文字仍作为描述,不强行转语法。</zh-CN><en>Recognize line-leading tags only; ordinary text remains prose rather than forced syntax.</en></lang>
|
|
139
|
+
const match = /^@([A-Za-z][\w-]*)(?:\s+(.*))?$/.exec(line);
|
|
140
|
+
if (!match) {
|
|
141
|
+
prose.push(line);
|
|
142
|
+
continue;
|
|
143
|
+
}
|
|
144
|
+
// <lang><zh-CN>规范标签和值来自当前行,known只是识别结果,不是验证证明。</zh-CN><en>Canonical tag/value come from this line; known records recognition, not validation proof.</en></lang>
|
|
145
|
+
const tag = normalizeTag(match[1]);
|
|
146
|
+
const value = (match[2] ?? "").trim();
|
|
147
|
+
annotations.push({
|
|
148
|
+
tag,
|
|
149
|
+
value,
|
|
150
|
+
known: isCssDocTag(tag)
|
|
151
|
+
});
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
// <lang><zh-CN>显式description优于普通正文;字段语言按现有规则回退。</zh-CN><en>Explicit description precedes ordinary prose; field locale follows existing fallback rules.</en></lang>
|
|
155
|
+
const defaultLocale = normalizeLocale(options.defaultLocale) || DEFAULT_LOCALE;
|
|
156
|
+
const descriptionTag = annotations.find((annotation) => annotation.tag === "description");
|
|
157
|
+
const summary = descriptionTag?.value || prose.join(" ").trim() || null;
|
|
158
|
+
return {
|
|
159
|
+
annotations,
|
|
160
|
+
summary,
|
|
161
|
+
i18n: createDescriptionI18n(summary, annotations, defaultLocale, "cssdoc.comment")
|
|
162
|
+
};
|
|
163
|
+
}
|
|
164
|
+
|
|
165
|
+
function collectAttachedCommentPairs(container, pairs = []) {
|
|
166
|
+
let pendingComment = null;
|
|
167
|
+
|
|
168
|
+
for (const child of container.nodes ?? []) {
|
|
169
|
+
if (child.type === "comment") {
|
|
170
|
+
pendingComment = child;
|
|
171
|
+
continue;
|
|
172
|
+
}
|
|
173
|
+
|
|
174
|
+
if (pendingComment && isDocumentableCssNode(child)) {
|
|
175
|
+
pairs.push({ comment: pendingComment, node: child });
|
|
176
|
+
pendingComment = null;
|
|
177
|
+
} else if (child.type !== "comment") {
|
|
178
|
+
pendingComment = null;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
if (child.nodes) {
|
|
182
|
+
collectAttachedCommentPairs(child, pairs);
|
|
183
|
+
}
|
|
184
|
+
}
|
|
185
|
+
|
|
186
|
+
return pairs;
|
|
187
|
+
}
|
|
188
|
+
|
|
189
|
+
function isDocumentableCssNode(node) {
|
|
190
|
+
return node.type === "rule" || node.type === "decl" || node.type === "atrule";
|
|
191
|
+
}
|
|
192
|
+
|
|
193
|
+
function createTargetInfo(node, sourcePath) {
|
|
194
|
+
const location = getCssNodeLocation(node);
|
|
195
|
+
return {
|
|
196
|
+
type: node.type,
|
|
197
|
+
selector: node.selector ?? null,
|
|
198
|
+
prop: node.prop ?? null,
|
|
199
|
+
name: node.name ?? null,
|
|
200
|
+
params: node.params ?? null,
|
|
201
|
+
source: {
|
|
202
|
+
path: sourcePath,
|
|
203
|
+
range: toRange(location)
|
|
204
|
+
}
|
|
205
|
+
};
|
|
206
|
+
}
|
|
207
|
+
|
|
208
|
+
function createSymbolFromAnnotation(annotation, target, comment, block, usedIds, parentId = null, defaultLocale = DEFAULT_LOCALE) {
|
|
209
|
+
const kind = getCssDocSymbolKind(annotation.tag);
|
|
210
|
+
const name = getAnnotationName(annotation, target);
|
|
211
|
+
const id = allocateId(`css:${annotation.tag}:${slug(name)}`, usedIds);
|
|
212
|
+
const summary = annotation.tag === "component" ? block.summary ?? undefined : getAnnotationDescription(annotation);
|
|
213
|
+
const i18n = annotation.tag === "component"
|
|
214
|
+
? createDescriptionI18n(summary, block.annotations, defaultLocale, "cssdoc.comment")
|
|
215
|
+
: createDescriptionI18n(summary, [], defaultLocale, `cssdoc.${annotation.tag}`);
|
|
216
|
+
// <lang><zh-CN>新工件省略缺省摘要,不生成非JSON的undefined属性;不放宽null。</zh-CN><en>New artifacts omit absent summaries rather than creating non-JSON undefined properties; null is not widened.</en></lang>
|
|
217
|
+
const symbol = {
|
|
218
|
+
id,
|
|
219
|
+
kind,
|
|
220
|
+
name,
|
|
221
|
+
...((i18n?.fields.description?.defaultText ?? summary) === undefined ? {} : { summary: i18n?.fields.description?.defaultText ?? summary }),
|
|
222
|
+
source: target.source,
|
|
223
|
+
annotation: toAnnotationRange(comment),
|
|
224
|
+
metadata: {
|
|
225
|
+
tag: annotation.tag,
|
|
226
|
+
value: annotation.value,
|
|
227
|
+
target: {
|
|
228
|
+
type: target.type,
|
|
229
|
+
selector: target.selector,
|
|
230
|
+
prop: target.prop,
|
|
231
|
+
name: target.name,
|
|
232
|
+
params: target.params
|
|
233
|
+
}
|
|
234
|
+
}
|
|
235
|
+
};
|
|
236
|
+
if (parentId) {
|
|
237
|
+
symbol.parentId = parentId;
|
|
238
|
+
}
|
|
239
|
+
if (i18n) {
|
|
240
|
+
symbol.i18n = i18n;
|
|
241
|
+
}
|
|
242
|
+
return symbol;
|
|
243
|
+
}
|
|
244
|
+
|
|
245
|
+
// 中文:把 CSSDoc 的 `@lang` 与 inline `<lang>/<l>` 规整成 HIA field-level i18n。
|
|
246
|
+
// English: Normalizes CSSDoc `@lang` and inline `<lang>/<l>` into HIA field-level i18n.
|
|
247
|
+
function createDescriptionI18n(defaultText, annotations, defaultLocale, source) {
|
|
248
|
+
const blocks = collectLangBlocks(annotations, "description", source);
|
|
249
|
+
const segments = parseInlineSegments(defaultText, "description");
|
|
250
|
+
if (blocks.length === 0 && segments.length === 0) {
|
|
251
|
+
return null;
|
|
252
|
+
}
|
|
253
|
+
|
|
254
|
+
const field = createTextField({
|
|
255
|
+
fieldPath: "description",
|
|
256
|
+
kind: "text",
|
|
257
|
+
defaultLocale,
|
|
258
|
+
defaultText,
|
|
259
|
+
blocks,
|
|
260
|
+
segments,
|
|
261
|
+
source
|
|
262
|
+
});
|
|
263
|
+
|
|
264
|
+
return {
|
|
265
|
+
enabled: true,
|
|
266
|
+
model: HIA_TEXT_I18N_MODEL,
|
|
267
|
+
modelVersion: HIA_TEXT_I18N_MODEL_VERSION,
|
|
268
|
+
defaultLocale,
|
|
269
|
+
locales: collectLocales([defaultLocale, ...Object.keys(field.localizedText)]),
|
|
270
|
+
fields: {
|
|
271
|
+
description: field
|
|
272
|
+
}
|
|
273
|
+
};
|
|
274
|
+
}
|
|
275
|
+
|
|
276
|
+
function collectLangBlocks(annotations, fieldPath, source) {
|
|
277
|
+
return annotations
|
|
278
|
+
.filter((annotation) => annotation.tag === "lang")
|
|
279
|
+
.map((annotation) => parseLangBlock(annotation.value, fieldPath, source))
|
|
280
|
+
.filter(Boolean);
|
|
281
|
+
}
|
|
282
|
+
|
|
283
|
+
function parseLangBlock(value, fieldPath, source) {
|
|
284
|
+
const match = /^(\S+)(?:\s+([\s\S]+))?$/.exec(String(value ?? "").trim());
|
|
285
|
+
const locale = normalizeLocale(match?.[1]);
|
|
286
|
+
const text = compactWhitespace(match?.[2] ?? "");
|
|
287
|
+
if (!locale || !text) {
|
|
288
|
+
return null;
|
|
289
|
+
}
|
|
290
|
+
return {
|
|
291
|
+
kind: "lang-block",
|
|
292
|
+
locale,
|
|
293
|
+
fieldPath,
|
|
294
|
+
text,
|
|
295
|
+
source,
|
|
296
|
+
rangeInComment: null
|
|
297
|
+
};
|
|
298
|
+
}
|
|
299
|
+
|
|
300
|
+
function createTextField(options) {
|
|
301
|
+
const localizedText = {};
|
|
302
|
+
const locales = collectLocales([
|
|
303
|
+
options.defaultLocale,
|
|
304
|
+
...options.blocks.map((block) => block.locale),
|
|
305
|
+
...options.segments.flatMap((segment) => Object.keys(segment.localized))
|
|
306
|
+
]);
|
|
307
|
+
|
|
308
|
+
for (const locale of locales) {
|
|
309
|
+
const block = options.blocks.find((item) => item.locale === locale);
|
|
310
|
+
localizedText[locale] = block?.text ?? renderInlineText(options.defaultText, options.segments, locale, options.defaultLocale);
|
|
311
|
+
}
|
|
312
|
+
|
|
313
|
+
const defaultText = localizedText[options.defaultLocale] || firstLocalizedText(localizedText) || compactWhitespace(options.defaultText);
|
|
314
|
+
|
|
315
|
+
return {
|
|
316
|
+
fieldPath: options.fieldPath,
|
|
317
|
+
kind: options.kind,
|
|
318
|
+
defaultLocale: options.defaultLocale,
|
|
319
|
+
defaultText,
|
|
320
|
+
source: options.source,
|
|
321
|
+
localizedText,
|
|
322
|
+
...(options.blocks.length > 0 ? { blocks: options.blocks } : {}),
|
|
323
|
+
...(options.segments.length > 0 ? { segments: options.segments } : {}),
|
|
324
|
+
resolutions: Object.fromEntries(Object.keys(localizedText).map((locale) => [
|
|
325
|
+
locale,
|
|
326
|
+
{
|
|
327
|
+
requestedLocale: locale,
|
|
328
|
+
resolvedLocale: locale,
|
|
329
|
+
fallbackChain: fallbackChain(locale, options.defaultLocale),
|
|
330
|
+
usedFallback: false,
|
|
331
|
+
missing: false,
|
|
332
|
+
sourceKind: options.blocks.some((block) => block.locale === locale) ? "lang-block" : "default-text",
|
|
333
|
+
sourceLocale: locale,
|
|
334
|
+
source: options.source
|
|
335
|
+
}
|
|
336
|
+
])),
|
|
337
|
+
missingLocales: []
|
|
338
|
+
};
|
|
339
|
+
}
|
|
340
|
+
|
|
341
|
+
function parseInlineSegments(text, fieldPath) {
|
|
342
|
+
const sourceText = String(text ?? "");
|
|
343
|
+
const segments = [];
|
|
344
|
+
const pattern = /<(lang|l)\b([^>]*)>([\s\S]*?)<\/\1>/g;
|
|
345
|
+
let match;
|
|
346
|
+
while ((match = pattern.exec(sourceText))) {
|
|
347
|
+
const localized = parseInlineLocalizedValues(match[3]);
|
|
348
|
+
if (Object.keys(localized).length === 0) {
|
|
349
|
+
continue;
|
|
350
|
+
}
|
|
351
|
+
const attributes = parseAttributes(match[2]);
|
|
352
|
+
segments.push({
|
|
353
|
+
kind: "lang-inline",
|
|
354
|
+
id: `${fieldPath}.${segments.length}`,
|
|
355
|
+
key: attributes.key ?? "",
|
|
356
|
+
path: attributes.path ?? "",
|
|
357
|
+
fieldPath,
|
|
358
|
+
raw: match[0],
|
|
359
|
+
localized,
|
|
360
|
+
rangeInField: {
|
|
361
|
+
start: match.index,
|
|
362
|
+
end: match.index + match[0].length
|
|
363
|
+
}
|
|
364
|
+
});
|
|
365
|
+
}
|
|
366
|
+
return segments;
|
|
367
|
+
}
|
|
368
|
+
|
|
369
|
+
function parseInlineLocalizedValues(innerText) {
|
|
370
|
+
const localized = {};
|
|
371
|
+
const pattern = /<([A-Za-z]{2,3}(?:[-_][A-Za-z0-9]{2,8})*)>([\s\S]*?)<\/\1>/g;
|
|
372
|
+
let match;
|
|
373
|
+
while ((match = pattern.exec(innerText || ""))) {
|
|
374
|
+
const locale = normalizeLocale(match[1]);
|
|
375
|
+
const text = compactWhitespace(match[2]);
|
|
376
|
+
if (locale && text) {
|
|
377
|
+
localized[locale] = text;
|
|
378
|
+
}
|
|
379
|
+
}
|
|
380
|
+
return localized;
|
|
381
|
+
}
|
|
382
|
+
|
|
383
|
+
function renderInlineText(text, segments, locale, defaultLocale) {
|
|
384
|
+
let rendered = compactWhitespace(text);
|
|
385
|
+
for (const segment of segments) {
|
|
386
|
+
rendered = rendered.replace(segment.raw, resolveInlineLocalizedText(segment.localized, locale, defaultLocale));
|
|
387
|
+
}
|
|
388
|
+
return rendered;
|
|
389
|
+
}
|
|
390
|
+
|
|
391
|
+
function resolveInlineLocalizedText(localized, locale, defaultLocale) {
|
|
392
|
+
return localized[locale]
|
|
393
|
+
?? localized[getParentLocale(locale)]
|
|
394
|
+
?? localized[defaultLocale]
|
|
395
|
+
?? firstLocalizedText(localized)
|
|
396
|
+
?? "";
|
|
397
|
+
}
|
|
398
|
+
|
|
399
|
+
function parseAttributes(rawAttributes) {
|
|
400
|
+
const attributes = {};
|
|
401
|
+
const pattern = /([A-Za-z_:][\w:.-]*)\s*=\s*(?:"([^"]*)"|'([^']*)')/g;
|
|
402
|
+
let match;
|
|
403
|
+
while ((match = pattern.exec(rawAttributes || ""))) {
|
|
404
|
+
attributes[match[1]] = match[2] || match[3] || "";
|
|
405
|
+
}
|
|
406
|
+
return attributes;
|
|
407
|
+
}
|
|
408
|
+
|
|
409
|
+
function getAnnotationName(annotation, target) {
|
|
410
|
+
const [first] = annotation.value.split(/\s+/).filter(Boolean);
|
|
411
|
+
if (first) {
|
|
412
|
+
return first;
|
|
413
|
+
}
|
|
414
|
+
if (annotation.tag === "selector" || annotation.tag === "component" || annotation.tag === "modifier") {
|
|
415
|
+
return target.selector ?? annotation.tag;
|
|
416
|
+
}
|
|
417
|
+
if (annotation.tag === "cssprop") {
|
|
418
|
+
return target.prop ?? annotation.tag;
|
|
419
|
+
}
|
|
420
|
+
if (annotation.tag === "layer" || annotation.tag === "media" || annotation.tag === "container" || annotation.tag === "keyframes") {
|
|
421
|
+
return target.params || target.name || annotation.tag;
|
|
422
|
+
}
|
|
423
|
+
return annotation.tag;
|
|
424
|
+
}
|
|
425
|
+
|
|
426
|
+
function getAnnotationDescription(annotation) {
|
|
427
|
+
const [, ...rest] = annotation.value.split(/\s+/).filter(Boolean);
|
|
428
|
+
return rest.join(" ") || undefined;
|
|
429
|
+
}
|
|
430
|
+
|
|
431
|
+
function toAnnotationRange(comment) {
|
|
432
|
+
return {
|
|
433
|
+
range: toRange(getCssNodeLocation(comment))
|
|
434
|
+
};
|
|
435
|
+
}
|
|
436
|
+
|
|
437
|
+
function toRange(location) {
|
|
438
|
+
if (!location?.start || !location?.end) {
|
|
439
|
+
return null;
|
|
440
|
+
}
|
|
441
|
+
return {
|
|
442
|
+
start: {
|
|
443
|
+
line: location.start.line,
|
|
444
|
+
column: location.start.column
|
|
445
|
+
},
|
|
446
|
+
end: {
|
|
447
|
+
line: location.end.line,
|
|
448
|
+
column: location.end.column
|
|
449
|
+
}
|
|
450
|
+
};
|
|
451
|
+
}
|
|
452
|
+
|
|
453
|
+
function createDiagnostic(code, message, severity, source, data = {}) {
|
|
454
|
+
return {
|
|
455
|
+
code,
|
|
456
|
+
message,
|
|
457
|
+
severity,
|
|
458
|
+
path: source.path,
|
|
459
|
+
data: {
|
|
460
|
+
...data,
|
|
461
|
+
source
|
|
462
|
+
}
|
|
463
|
+
};
|
|
464
|
+
}
|
|
465
|
+
|
|
466
|
+
function normalizeTag(tag) {
|
|
467
|
+
return tag.toLowerCase().replace(/-/g, "");
|
|
468
|
+
}
|
|
469
|
+
|
|
470
|
+
function allocateId(baseId, usedIds) {
|
|
471
|
+
let id = baseId;
|
|
472
|
+
let index = 2;
|
|
473
|
+
while (usedIds.has(id)) {
|
|
474
|
+
id = `${baseId}-${index}`;
|
|
475
|
+
index += 1;
|
|
476
|
+
}
|
|
477
|
+
usedIds.add(id);
|
|
478
|
+
return id;
|
|
479
|
+
}
|
|
480
|
+
|
|
481
|
+
function slug(value) {
|
|
482
|
+
return String(value).trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-|-$/g, "") || "unnamed";
|
|
483
|
+
}
|
|
484
|
+
|
|
485
|
+
function collectLocales(values) {
|
|
486
|
+
return [...new Set(values.map((value) => normalizeLocale(value)).filter(Boolean))];
|
|
487
|
+
}
|
|
488
|
+
|
|
489
|
+
function normalizeLocale(value) {
|
|
490
|
+
const locale = String(value ?? "").trim().replace(/_/g, "-");
|
|
491
|
+
return /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/.test(locale) ? locale : "";
|
|
492
|
+
}
|
|
493
|
+
|
|
494
|
+
function getParentLocale(locale) {
|
|
495
|
+
return String(locale).split("-")[0] || locale;
|
|
496
|
+
}
|
|
497
|
+
|
|
498
|
+
function fallbackChain(locale, defaultLocale) {
|
|
499
|
+
const chain = collectLocales([locale, getParentLocale(locale), defaultLocale]);
|
|
500
|
+
return chain.length > 0 ? chain : [DEFAULT_LOCALE];
|
|
501
|
+
}
|
|
502
|
+
|
|
503
|
+
function firstLocalizedText(localizedText) {
|
|
504
|
+
return Object.values(localizedText).find((text) => typeof text === "string" && text.length > 0) ?? "";
|
|
505
|
+
}
|
|
506
|
+
|
|
507
|
+
function compactWhitespace(value) {
|
|
508
|
+
return String(value ?? "").replace(/\s+/g, " ").trim();
|
|
509
|
+
}
|