@hia-doc/css-doc-source-map 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,70 @@
1
+ # CSS Doc Source Map API
2
+
3
+ 中文:以显式工件和逐引用证据生成文档源码映射,不加载或嵌入源码,也不验证外部授权。
4
+
5
+ ## Public exports
6
+
7
+ - `CSS_DOC_SOURCE_CONTENT_POLICIES`: frozen `none`, `reference`, `embed` list.
8
+ - `CSS_DOC_SOURCE_MAP_CONTRACT_VERSION`: current map identity `1.1.0`.
9
+ - `normalizeSourcesContentPolicy(policy)`: exact policy or fixed TypeError.
10
+ - `createCssDocSourceMapRef(options?)`: creates a ref with href and policy;
11
+ does not fetch or validate the href as a filesystem target.
12
+ - `createCssDocumentationSourceMap(options)`: validates `options.extraction`
13
+ as an exact supported CSSDoc JSON artifact, then projects a direct map.
14
+
15
+ Only `.` is exported; no binary or JSON resource subpaths.
16
+
17
+ ## Inputs
18
+
19
+ Map options: `extraction`, optional public relative `extractionPath`,
20
+ `hiaDocumentPath`, `sourcesContentPolicy`, `id`. Ref options: `href`,
21
+ `sourcesContentPolicy`. Use ordinary objects and suitable strings for paths/id.
22
+ The writer performs lexical path checks, not file existence or path resolution.
23
+
24
+ ## Returns
25
+
26
+ The ref is `{ kind: "hia-doc-source-map-ref", href, sourcesContentPolicy }`.
27
+ The map is `doc-source-map@1.1.0` with generated artifacts, original source,
28
+ chains, entries, privacy and diagnostics. It does not include source bodies.
29
+ Maps are new objects but range objects may share input references; clone before
30
+ mutating them. A policy label alone is not evidence of embedded or fetched data.
31
+
32
+ ## Defaults
33
+
34
+ Ref href is `null`, policy `none`. Map paths default to `document.cssdoc.json`
35
+ and `document.hia.json`; source language is JSON for design-tokens and CSS
36
+ otherwise. Policy uses explicit option, extraction ref policy, then `none`.
37
+ Ids derive from the existing path/symbol slug convention; callers supplying
38
+ custom imported ids must ensure the resulting entry identities are unique.
39
+
40
+ ## Errors
41
+
42
+ Invalid exact extraction throws fixed TypeError; unsafe map locators throw
43
+ `Unsafe doc-source-map path.`. Invalid content policy is refused. These errors
44
+ do not echo the rejected value. This writer does not replace the main map
45
+ semantic validator for arbitrary caller-created extraction metadata/id values.
46
+
47
+ ## Effects
48
+
49
+ Pure synchronous projection: no I/O, source-map URL reads, ordinary map lookup,
50
+ compiler execution, source loading or publishing.
51
+
52
+ ## Compatibility
53
+
54
+ Accepts exact extraction/profile `0.1.0-draft` and `1.0.0`; output map remains
55
+ `1.1.0`. Package version `1.0.0` is independent. See [migration](MIGRATION.md).
56
+
57
+ ## Source linkage
58
+
59
+ Each symbol links original source to extraction selector and core selector.
60
+ Proven `css`/PostCSS stylesheet/rule coordinates declare inclusive UTF-16;
61
+ other node kinds and Vue styles remain unknown. Design-token `1:1` is synthetic,
62
+ adapter/low confidence, with unknown bounds/units. Missing range omits both
63
+ range and convention. No range convention is inferred from a version or tag.
64
+
65
+ ## Privacy
66
+
67
+ Map output excludes source bodies even when policy is `embed`. Sources are
68
+ relative to workspaceRoot, artifacts to outputDirectory. Lexical path checks
69
+ are not a symlink sandbox or permission grant. Caller-supplied annotations,
70
+ ids and metadata still require public disclosure review.
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 is 1.0.0; map contract stays 1.1.0. Exact legacy/current extraction readers and unknown coordinate conventions remain. No source body is fetched or embedded.
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,43 @@
1
- # Temporary Holding Version
1
+ # CSS Doc Source Map
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
+ Creates safe documentation source-map references and direct-source manifests
13
+ for CSSDoc extraction artifacts.
14
+
15
+ ```js
16
+ import { createCssDocumentationSourceMap } from "@hia-doc/css-doc-source-map";
17
+
18
+ const manifest = createCssDocumentationSourceMap({
19
+ extraction,
20
+ extractionPath: "artifacts/button.cssdoc.json",
21
+ hiaDocumentPath: "artifacts/button.hia.json"
22
+ });
23
+ ```
24
+
25
+ Source paths are workspace-relative, artifact paths are output-relative and
26
+ source content is not embedded by default.
27
+
28
+ The writer emits `doc-source-map@1.1.0`. Each ranged source reference carries
29
+ `rangeConvention`. Only PostCSS rule locations with verified columns declare
30
+ `inclusive` and `utf16-code-unit`; declarations, at-rules and design-token
31
+ placeholder ranges declare `unknown` for both fields. Missing ranges omit the
32
+ convention. The contract identity is independent of the npm package version.
33
+
34
+ Current writers/readers coordinate `hia-cssdoc-extraction@1.0.0` with exact `0.1.0-draft` JSON compatibility; unsupported or invalid reader inputs fail. See the repository migration guide for structure and source-precision limits.
35
+
36
+
37
+ ## API and compatibility
38
+
39
+ See the packaged [API reference](API.md) and [migration notes](MIGRATION.md) for
40
+ all public entries, ownership, defaults, effects, source precision and privacy.
41
+ The package is a 1.0.0 source candidate; registry availability is a separate gate.
42
+
43
+ 中文:公开责任与迁移文档随包提供;源码候选不代表已经发布npm。
package/package.json CHANGED
@@ -1,6 +1,41 @@
1
1
  {
2
2
  "name": "@hia-doc/css-doc-source-map",
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": "CSS documentation source-map linkage.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "exports": {
8
+ ".": "./src/index.mjs"
9
+ },
10
+ "engines": {
11
+ "node": "^22.23.4 || ^24.22.1"
12
+ },
13
+ "files": [
14
+ "src",
15
+ "README.md",
16
+ "API.md",
17
+ "MIGRATION.md",
18
+ "LICENSE"
19
+ ],
20
+ "dependencies": {
21
+ "@hia-doc/cssdoc-spec": "1.0.0-rc.2"
22
+ },
23
+ "publishConfig": {
24
+ "access": "public",
25
+ "registry": "https://registry.npmjs.org/"
26
+ },
27
+ "repository": {
28
+ "type": "git",
29
+ "url": "git+https://github.com/mandolin/hia-cssdoc.git",
30
+ "directory": "packages/css-doc-source-map"
31
+ },
32
+ "homepage": "https://github.com/mandolin/hia-cssdoc/tree/main/packages/css-doc-source-map",
33
+ "bugs": {
34
+ "url": "https://github.com/mandolin/hia-cssdoc/issues"
35
+ },
36
+ "keywords": [
37
+ "documentation",
38
+ "css",
39
+ "hia"
40
+ ]
41
+ }
@@ -0,0 +1,7 @@
1
+ /** @file @lang zh-CN 包内冻结数组纯数据定义,无导入和运行器副作用。 @lang en Owner-local frozen-array plain-data definitions without imports or runner side effects. */
2
+
3
+ /**
4
+ * @lang zh-CN 精确内容策略白名单,不代表授权或实际嵌入正文。
5
+ * @lang en Exact content-policy allowlist, not authorization or evidence of embedded text.
6
+ */
7
+ export const CSS_DOC_SOURCE_CONTENT_POLICIES = Object.freeze(["none", "reference", "embed"]);
package/src/index.mjs ADDED
@@ -0,0 +1,219 @@
1
+ /** @file CSSDoc到直接文档源码映射的纯投影,不读取正文。 @lang en Pure CSSDoc to direct documentation-source-map projection without source-body reads. */
2
+ import { validateCssDocExtraction } from "@hia-doc/cssdoc-spec";
3
+ /** @lang zh-CN 复用包内纯数据定义的同一冻结对象。 @lang en Reuses the same frozen objects from owner-local plain-data definitions. */
4
+ import {CSS_DOC_SOURCE_CONTENT_POLICIES} from './frozen-arrays.mjs';
5
+ export {CSS_DOC_SOURCE_CONTENT_POLICIES};
6
+ /**
7
+ * @lang zh-CN 当前 CSSDoc 映射写入器所发出的文档源码映射契约身份。
8
+ * @lang en The documentation source-map contract identity emitted by the current CSSDoc map writer.
9
+ */
10
+ export const CSS_DOC_SOURCE_MAP_CONTRACT_VERSION = "1.1.0";
11
+
12
+ /**
13
+ * @lang zh-CN 按调用方链接与精确内容策略构造新的CSS文档源码映射引用,缺省链接为null且策略为none。
14
+ * @lang en Constructs a fresh CSS documentation source-map reference from the caller's link and exact content policy, defaulting the link to null and policy to none.
15
+ * @param {object} [options] <lang><zh-CN>href默认null,policy默认none;href由调用方负责有效/公开。</zh-CN><en>href defaults to null, policy to none; the caller owns href validity/disclosure.</en></lang> @returns {object} <lang><zh-CN>新引用对象,不读取href。</zh-CN><en>Fresh reference without reading href.</en></lang> @throws {TypeError} <lang><zh-CN>策略无效时固定拒绝。</zh-CN><en>Fixed refusal for invalid policy.</en></lang>
16
+ */
17
+ export function createCssDocSourceMapRef(options = {}) {
18
+ return {
19
+ kind: "hia-doc-source-map-ref",
20
+ href: options.href ?? null,
21
+ sourcesContentPolicy: normalizeSourcesContentPolicy(options.sourcesContentPolicy ?? "none")
22
+ };
23
+ }
24
+
25
+ /**
26
+ * @lang zh-CN 精确校验CSS源码内容策略none、reference或embed,返回同一有效策略值。
27
+ * @lang en Validates the exact CSS source-content policies none, reference or embed and returns the same valid policy value.
28
+ * @param {string} policy <lang><zh-CN>精确none/reference/embed。</zh-CN><en>Exact none/reference/embed.</en></lang> @returns {string} <lang><zh-CN>同一有效策略。</zh-CN><en>The same valid policy.</en></lang> @throws {TypeError} <lang><zh-CN>固定拒绝,不打印原文。</zh-CN><en>Fixed refusal without raw text.</en></lang>
29
+ */
30
+ export function normalizeSourcesContentPolicy(policy) {
31
+ if (!CSS_DOC_SOURCE_CONTENT_POLICIES.includes(policy)) {
32
+ throw new TypeError("Unsupported CSSDoc sourcesContent policy.");
33
+ }
34
+ return policy;
35
+ }
36
+
37
+ /**
38
+ * @lang zh-CN 从 CSSDoc 提取工件生成直接来源映射;逐条引用保留范围精度证据。
39
+ 已证的 PostCSS 规则使用包含式 UTF-16 列,其余节点和设计令牌占位范围保持未知。
40
+ * @lang en Builds a direct-source map from a CSSDoc extraction artifact. Proven PostCSS rule locations use inclusive UTF-16 columns; unproven nodes and synthetic design-token ranges stay unknown per reference.
41
+ * @param {Object} options <lang><zh-CN>提取工件及公开安全的相对路径、内容策略。</zh-CN><en>Extraction artifact, public-safe relative paths and content policy.</en></lang>
42
+ * @param {Object} options.extraction <lang><zh-CN>必需的 CSS 提取件。</zh-CN><en>Required CSS extraction.</en></lang>
43
+ * @param {string} [options.extractionPath] <lang><zh-CN>提取件相对路径;省略时使用函数内默认路径。</zh-CN><en>Relative extraction path; omission uses the function's default path.</en></lang>
44
+ * @param {string} [options.hiaDocumentPath] <lang><zh-CN>HIA 文档相对路径;省略时使用函数内默认路径。</zh-CN><en>Relative HIA document path; omission uses the function's default path.</en></lang>
45
+ * @param {string} [options.sourcesContentPolicy] <lang><zh-CN>none/reference/embed;省略时继承提取件策略,再回退 none。</zh-CN><en>none/reference/embed; omission inherits the extraction policy, then falls back to none.</en></lang>
46
+ * @param {string} [options.id] <lang><zh-CN>映射身份;省略时由来源路径派生。</zh-CN><en>Map identity; derived from the source path when omitted.</en></lang>
47
+ * @returns {object} <lang><zh-CN>不嵌入源码正文的 1.1.0 映射工件。</zh-CN><en>A 1.1.0 map artifact without embedded source content.</en></lang>
48
+ * @throws {Error} <lang><zh-CN>提取契约、路径或内容策略无效时抛出。</zh-CN><en>Throws for an invalid extraction contract, path or content policy.</en></lang>
49
+ */
50
+ export function createCssDocumentationSourceMap(options = {}) {
51
+ const extraction = options.extraction;
52
+ if (validateCssDocExtraction(extraction).length) {
53
+ throw new TypeError("Unsupported or invalid CSSDoc extraction.");
54
+ }
55
+
56
+ const extractionPath = normalizeSafePath(options.extractionPath ?? "document.cssdoc.json");
57
+ const hiaDocumentPath = normalizeSafePath(options.hiaDocumentPath ?? "document.hia.json");
58
+ const sourcePath = normalizeSafePath(extraction.source?.path ?? "input.css");
59
+ const sourceLanguage = extraction.source?.kind === "design-tokens" ? "json" : "css";
60
+ const sourceId = `source:${sourceLanguage}:${slug(sourcePath)}`;
61
+ const extractionArtifactId = "artifact:cssdoc:extraction";
62
+ const hiaArtifactId = "artifact:hia:document";
63
+ const entryIds = extraction.symbols.map((symbol) => `entry:${slug(symbol.id)}`);
64
+ const sourcesContentPolicy = normalizeSourcesContentPolicy(
65
+ options.sourcesContentPolicy ?? extraction.sourceMap?.sourcesContentPolicy ?? "none"
66
+ );
67
+
68
+ return {
69
+ contract: "doc-source-map",
70
+ contractVersion: CSS_DOC_SOURCE_MAP_CONTRACT_VERSION,
71
+ id: options.id ?? `docmap:cssdoc:${slug(sourcePath)}`,
72
+ producer: {
73
+ name: "@hia-doc/css-doc-source-map",
74
+ version: "1.0.0",
75
+ runtime: "node",
76
+ profile: "cssdoc-direct-source"
77
+ },
78
+ pathBases: {
79
+ artifacts: "outputDirectory",
80
+ sources: "workspaceRoot"
81
+ },
82
+ artifacts: [
83
+ {
84
+ id: extractionArtifactId,
85
+ kind: "extraction-artifact",
86
+ path: extractionPath,
87
+ language: "json",
88
+ role: "generated",
89
+ contractRefs: [{
90
+ contract: extraction.contract,
91
+ contractVersion: extraction.contractVersion,
92
+ path: extractionPath
93
+ }]
94
+ },
95
+ {
96
+ id: hiaArtifactId,
97
+ kind: "hia-document",
98
+ path: hiaDocumentPath,
99
+ language: "json",
100
+ role: "generated"
101
+ }
102
+ ],
103
+ sources: [{
104
+ id: sourceId,
105
+ kind: extraction.source?.kind ?? "css",
106
+ path: sourcePath,
107
+ language: sourceLanguage,
108
+ role: "original",
109
+ sourcesContentPolicy
110
+ }],
111
+ sourceMaps: [],
112
+ chains: [{
113
+ id: `chain:cssdoc:${slug(sourcePath)}`,
114
+ stages: [
115
+ {
116
+ from: sourceId,
117
+ to: extractionArtifactId,
118
+ transform: extraction.source?.kind === "design-tokens" ? "design-token-to-cssdoc" : "css-to-cssdoc",
119
+ sourceMap: null,
120
+ linkage: entryIds
121
+ },
122
+ {
123
+ from: extractionArtifactId,
124
+ to: hiaArtifactId,
125
+ transform: "cssdoc-to-hia-core",
126
+ sourceMap: null,
127
+ linkage: entryIds
128
+ }
129
+ ]
130
+ }],
131
+ entries: extraction.symbols.map((symbol, index) => ({
132
+ id: entryIds[index],
133
+ kind: symbol.kind === "design-token" ? "design-token-link" : "symbol",
134
+ symbolId: symbol.id,
135
+ symbolKind: symbol.kind,
136
+ ...(symbol.metadata?.tag
137
+ ? { annotation: { tag: symbol.metadata.tag, value: symbol.metadata.value ?? "" } }
138
+ : {}),
139
+ sourceRefs: [createCssSourceRef(symbol, extraction, sourceId)],
140
+ artifactRefs: [
141
+ {
142
+ artifactId: extractionArtifactId,
143
+ selector: `/symbols/${index}`,
144
+ rangeSource: "adapter",
145
+ confidence: "high"
146
+ },
147
+ {
148
+ artifactId: hiaArtifactId,
149
+ selector: `/symbols/${index}`,
150
+ rangeSource: "adapter",
151
+ confidence: "high"
152
+ }
153
+ ],
154
+ diagnostics: []
155
+ })),
156
+ privacy: {
157
+ sourcesContentPolicy,
158
+ allowAbsolutePaths: false,
159
+ allowUncPaths: false,
160
+ allowPathTraversal: false,
161
+ releaseGate: {
162
+ requireExplicitEmbedOptIn: true,
163
+ failOnUnsafePath: true,
164
+ failOnUnexpectedSourcesContent: true
165
+ }
166
+ },
167
+ diagnostics: []
168
+ };
169
+ }
170
+
171
+ /**
172
+ * 为单个符号声明源码范围约定;仅已测 PostCSS 规则获得精确列语义。
173
+ *
174
+ * @lang en Declares source-range conventions for one symbol; only probed PostCSS rule locations receive exact column semantics.
175
+ * @param {object} symbol <lang><zh-CN>包含范围及目标节点类别的 CSSDoc 符号。</zh-CN><en>CSSDoc symbol with its range and target node kind.</en></lang>
176
+ * @param {object} extraction <lang><zh-CN>提供解析器来源的提取工件。</zh-CN><en>Extraction artifact carrying parser provenance.</en></lang>
177
+ * @param {string} sourceId <lang><zh-CN>映射来源标识。</zh-CN><en>Map source identity.</en></lang>
178
+ * @returns {object} <lang><zh-CN>带范围时必有约定的源码引用;缺范围时两字段均省略。</zh-CN><en>A source reference with a convention iff ranged.</en></lang>
179
+ */
180
+ function createCssSourceRef(symbol, extraction, sourceId) {
181
+ // <lang><zh-CN>设计令牌桥接器的 1:1 范围是人工占位,不能推断它的终点或列单位。</zh-CN><en>The design-token bridge uses a synthetic 1:1 range, which proves neither endpoint nor column unit.</en></lang>
182
+ const syntheticToken = extraction.source?.kind === "design-tokens";
183
+ // <lang><zh-CN>提取器透传的节点范围;缺失时不能写出 1.1.0 的范围约定。</zh-CN><en>The extractor-provided node range; an absent range must not have a 1.1.0 convention.</en></lang>
184
+ const range = symbol.source?.range;
185
+ // <lang><zh-CN>仅匹配实测的 PostCSS 规则行列路径,不按标签或通用来源类别猜测其它分支。</zh-CN><en>Match only the probed PostCSS rule line/column path, never extrapolating from tags or a generic source category.</en></lang>
186
+ const provenRule = !syntheticToken
187
+ && extraction.source?.kind === "css"
188
+ && extraction.metadata?.parser?.name === "postcss"
189
+ && extraction.metadata.parser.mode === "stylesheet"
190
+ && symbol.metadata?.target?.type === "rule"
191
+ && Number.isSafeInteger(range?.start?.column)
192
+ && Number.isSafeInteger(range?.end?.column);
193
+
194
+ return {
195
+ sourceId,
196
+ ...(range ? {
197
+ range,
198
+ rangeConvention: provenRule
199
+ ? { endBoundary: "inclusive", columnUnit: "utf16-code-unit" }
200
+ : { endBoundary: "unknown", columnUnit: "unknown" }
201
+ } : {}),
202
+ rangeSource: syntheticToken ? "adapter" : "parser",
203
+ rangeSourceDetail: syntheticToken ? "design-token-placeholder" : provenRule ? "postcss-rule-location" : "unproven-css-node-location",
204
+ confidence: syntheticToken ? "low" : provenRule ? "high" : "medium"
205
+ };
206
+ }
207
+
208
+ /** @param {string} value <lang><zh-CN>映射相对定位器。</zh-CN><en>Relative map locator.</en></lang> @returns {string} <lang><zh-CN>词法安全路径。</zh-CN><en>Lexically safe path.</en></lang> @throws {TypeError} <lang><zh-CN>固定失败不回显。</zh-CN><en>Fixed failure without echo.</en></lang> */
209
+ function normalizeSafePath(value) {
210
+ const normalized = String(value).replaceAll("\\", "/");
211
+ if (!normalized || normalized.startsWith("/") || /^[A-Za-z][A-Za-z0-9+.-]*:/.test(normalized) || normalized.split("/").includes("..")) {
212
+ throw new TypeError("Unsafe doc-source-map path.");
213
+ }
214
+ return normalized;
215
+ }
216
+
217
+ function slug(value) {
218
+ return String(value).trim().toLowerCase().replace(/[^a-z0-9_-]+/g, "-").replace(/^-|-$/g, "") || "unnamed";
219
+ }