@linkdesk/plugin-sdk 0.1.58 → 0.1.60

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/package.json CHANGED
@@ -1,78 +1,85 @@
1
- {
2
- "name": "@linkdesk/plugin-sdk",
3
- "version": "0.1.58",
4
- "description": "@linkdesk/plugin-sdk——LinkDesk 插件作者 SDK(对标 @types/vscode):window.linkdesk.* 类型 + 一键 build(.linkdesk-plugin) + dev 宿主 + plugin.json 验证 + eslint 门禁(E6#54d)。作者 npm i 后零壳源码依赖。",
5
- "type": "module",
6
- "main": "./dist/index.js",
7
- "types": "./dist/index.d.ts",
8
- "exports": {
9
- ".": {
10
- "types": "./dist/index.d.ts",
11
- "default": "./dist/index.js"
12
- },
13
- "./eslint": {
14
- "types": "./dist/eslint/index.d.ts",
15
- "default": "./dist/eslint/index.js"
16
- },
17
- "./vitest-setup": {
18
- "types": "./dist/vitest-setup.d.ts",
19
- "default": "./dist/vitest-setup.js"
20
- },
21
- "./test-audit": {
22
- "types": "./test-audit.d.ts",
23
- "default": "./test-audit.mjs"
24
- },
25
- "./package.json": "./package.json"
26
- },
27
- "files": [
28
- "dist",
29
- "schemas",
30
- "dev-host",
31
- "test-audit.mjs",
32
- "test-audit.d.ts"
33
- ],
34
- "sideEffects": false,
35
- "bin": {
36
- "linkdesk-plugin-sdk": "./dist/bin.js"
37
- },
38
- "publishConfig": {
39
- "access": "public"
40
- },
41
- "engines": {
42
- "node": ">=20.0.0"
43
- },
44
- "scripts": {
45
- "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
46
- "typecheck": "tsc -p tsconfig.json --noEmit",
47
- "prepack": "npm run build"
48
- },
49
- "dependencies": {
50
- "@linkdesk/contracts": "^0.1.1",
51
- "@typescript-eslint/eslint-plugin": "^8.0.0",
52
- "@typescript-eslint/parser": "^8.0.0",
53
- "@vitejs/plugin-react": "^4.3.4",
54
- "ajv": "^8.17.1",
55
- "eslint": "^9.0.0",
56
- "eslint-import-resolver-typescript": "^4.4.5",
57
- "eslint-plugin-import-x": "^4.17.1",
58
- "eslint-plugin-react-hooks": "^7.1.1",
59
- "i18next": "^26.3.6",
60
- "jsonc-parser": "^3.3.1",
61
- "jszip": "^3.10.1",
62
- "react": "^18.3.1",
63
- "react-dom": "^18.3.1",
64
- "react-i18next": "^17.0.10",
65
- "vite": "^6.0.0"
66
- },
67
- "devDependencies": {
68
- "@types/node": "^24.0.0",
69
- "typescript": "^5.9.0"
70
- },
71
- "keywords": [
72
- "linkdesk",
73
- "plugin",
74
- "sdk",
75
- "vite"
76
- ],
77
- "license": "MIT"
78
- }
1
+ {
2
+ "name": "@linkdesk/plugin-sdk",
3
+ "version": "0.1.60",
4
+ "description": "@linkdesk/plugin-sdk——LinkDesk 插件作者 SDK(对标 @types/vscode):window.linkdesk.* 类型 + 一键 build(.linkdesk-plugin) + dev 宿主 + plugin.json 验证 + eslint 门禁(E6#54d)。作者 npm i 后零壳源码依赖。",
5
+ "type": "module",
6
+ "main": "./dist/index.js",
7
+ "types": "./dist/index.d.ts",
8
+ "exports": {
9
+ ".": {
10
+ "types": "./dist/index.d.ts",
11
+ "default": "./dist/index.js"
12
+ },
13
+ "./eslint": {
14
+ "types": "./dist/eslint/index.d.ts",
15
+ "default": "./dist/eslint/index.js"
16
+ },
17
+ "./vitest-setup": {
18
+ "types": "./dist/vitest-setup.d.ts",
19
+ "default": "./dist/vitest-setup.js"
20
+ },
21
+ "./test-audit": {
22
+ "types": "./test-audit.d.ts",
23
+ "default": "./test-audit.mjs"
24
+ },
25
+ "./svg-wellformed": {
26
+ "types": "./svg-wellformed.d.ts",
27
+ "default": "./svg-wellformed.mjs"
28
+ },
29
+ "./package.json": "./package.json"
30
+ },
31
+ "files": [
32
+ "dist",
33
+ "schemas",
34
+ "dev-host",
35
+ "test-audit.mjs",
36
+ "test-audit.d.ts",
37
+ "svg-wellformed.mjs",
38
+ "svg-wellformed.d.ts"
39
+ ],
40
+ "sideEffects": false,
41
+ "bin": {
42
+ "linkdesk-plugin-sdk": "./dist/bin.js"
43
+ },
44
+ "publishConfig": {
45
+ "access": "public"
46
+ },
47
+ "engines": {
48
+ "node": ">=20.0.0"
49
+ },
50
+ "scripts": {
51
+ "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
52
+ "typecheck": "tsc -p tsconfig.json --noEmit",
53
+ "prepack": "npm run build"
54
+ },
55
+ "dependencies": {
56
+ "@linkdesk/contracts": "^0.1.1",
57
+ "@typescript-eslint/eslint-plugin": "^8.0.0",
58
+ "@typescript-eslint/parser": "^8.0.0",
59
+ "@vitejs/plugin-react": "^4.3.4",
60
+ "ajv": "^8.17.1",
61
+ "eslint": "^9.0.0",
62
+ "eslint-import-resolver-typescript": "^4.4.5",
63
+ "eslint-plugin-import-x": "^4.17.1",
64
+ "eslint-plugin-react-hooks": "^7.1.1",
65
+ "i18next": "^26.3.6",
66
+ "jsonc-parser": "^3.3.1",
67
+ "jszip": "^3.10.1",
68
+ "react": "^18.3.1",
69
+ "react-dom": "^18.3.1",
70
+ "react-i18next": "^17.0.10",
71
+ "saxes": "^6.0.0",
72
+ "vite": "^6.0.0"
73
+ },
74
+ "devDependencies": {
75
+ "@types/node": "^24.0.0",
76
+ "typescript": "^5.9.0"
77
+ },
78
+ "keywords": [
79
+ "linkdesk",
80
+ "plugin",
81
+ "sdk",
82
+ "vite"
83
+ ],
84
+ "license": "MIT"
85
+ }
@@ -0,0 +1,51 @@
1
+ /**
2
+ * @linkdesk/plugin-sdk/svg-wellformed 的类型声明(实现 = 同目录 svg-wellformed.mjs,免构建直发)。
3
+ * 判据出处与两条判据的域内外声明见 .mjs 头注——那里是单一真源,这里不重述。
4
+ */
5
+
6
+ export interface SvgViolation {
7
+ /** 相对 `absRoot` 的 POSIX 斜杠路径 */
8
+ file: string;
9
+ /** 1-based;取不到位置时为 null(⛔ 不编造行号) */
10
+ line: number | null;
11
+ column: number | null;
12
+ message: string;
13
+ /** xml = 不是合法 XML;root = 根元素不是 svg */
14
+ kind: "xml" | "root";
15
+ }
16
+
17
+ export interface SvgCheckOptions {
18
+ /** 跳过的目录名集合(半角精确匹配);缺省 = DEFAULT_SKIP_DIRS */
19
+ skipDirs?: Set<string>;
20
+ /** 文件级豁免(给相对路径,返回 true 即跳过);缺省 = DEFAULT_EXEMPT_RE(`*.fixture.svg` / `*.mock.svg`) */
21
+ isExempt?: (relPath: string) => boolean;
22
+ }
23
+
24
+ export interface SvgCheckResult {
25
+ /** 实际扫描的 .svg 份数 */
26
+ scanned: number;
27
+ violations: SvgViolation[];
28
+ }
29
+
30
+ /** 单份 XML 源 → 第一处 well-formedness 错误(合法 ⇒ null)。纯函数,不读盘。 */
31
+ export declare function xmlWellformedError(
32
+ source: string,
33
+ ): { line: number | null; column: number | null; message: string } | null;
34
+
35
+ /** 走查一棵树,返回其中的 `.svg`(相对 `absRoot`、POSIX 斜杠、字典序)。 */
36
+ export declare function listSvgFiles(absRoot: string, options?: SvgCheckOptions): string[];
37
+
38
+ /** 巡检一棵树里所有 `.svg`(两条判据:well-formedness + 根元素 = svg)。 */
39
+ export declare function checkSvgWellformed(absRoot: string, options?: SvgCheckOptions): SvgCheckResult;
40
+
41
+ /** 违规 → 人类可读一行(两轴打印同款,免得同一条错两种说法)。 */
42
+ export declare function formatSvgViolation(v: SvgViolation): string;
43
+
44
+ /** 违规 → 修法提示(按 kind 给因)。 */
45
+ export declare function svgViolationHint(v: SvgViolation): string;
46
+
47
+ /** 口径一句话——门禁与文档互钉用。 */
48
+ export declare const SVG_CALIBER: string;
49
+
50
+ export declare const DEFAULT_SKIP_DIRS: Set<string>;
51
+ export declare const DEFAULT_EXEMPT_RE: RegExp;
@@ -0,0 +1,208 @@
1
+ /**
2
+ * SVG 资源**合法性**判据——「SVG 是 XML 文档」这一件事的机械尺。
3
+ *
4
+ * ═══ 为什么必须有它(出处:2026-09-30「市场图标破图」案)═══
5
+ * 2026-09 首次由外部独立 AI 作者用本工程 npm 包(脚手架 + SDK + UI 包)制作一只插件时,
6
+ * 它的图标在插件市场里显示为**破图**,排查结论不是「画得不好看」,而是
7
+ * **整份 SVG 根本不是合法 XML**——浏览器以 `image/svg+xml` 解析 `<img src>` 时用的是
8
+ * **严格 XML 解析器**:注释里出现连续两个连字符、或用 `&nbsp;` 这类 XML 里不存在的实体,
9
+ * 都会在那一行**致命报错**,整份文档被拒绝渲染。表现就是破图,而且**哪个环节都不报错**
10
+ * (文件在、HTTP 200、`plugin.json` 声明正确 ⇒ 三道「存在性」检查全绿)。
11
+ *
12
+ * 那条注释里的话是「不能用 CSS 变量的字面量」——**它自己就是被那个字面量弄坏的**。
13
+ * 这不是某一只插件的笔误,是**判据缺位**:本仓此前的门禁只查「声明的图在不在」,
14
+ * 从不查「图是不是一张能读的图」。本模块补的就是那半张。
15
+ *
16
+ * ═══ 判据(两条,各自都是**精确判定**不是启发式)═══
17
+ * ① **well-formedness**:整份文档能被严格 XML 解析器读完(`saxes`,与 jsdom 解析 XML
18
+ * 同一实现;本轮实证它能逐条抓出「注释里的连续连字符」「未定义实体」「标签不闭合」
19
+ * 「裸 `<`」四类,且对 147 份合法 SVG 零误报)。
20
+ * ② **根元素 = `svg`**:`.svg` 文件里装的必须是一张 SVG(拿 HTML 改名成 .svg 是另一类
21
+ * 常见破图)——根元素名不是 `svg` 即报。
22
+ * ⛔ 域外(**本判据不管**,别以为漏了):XML 语义层面的问题——如 `id` 撞车、
23
+ * `clipPath`/`viewBox` 算错、颜色不合主题。那些是「图能读但画得不对」,不是破图。
24
+ *
25
+ * ═══ 消费方(两轴同一份实现,⛔ 不许各写一份)═══
26
+ * · 作者侧:`create-linkdesk-plugin` 模板的 `scripts/ci-verify.mjs` 第 ⑦ 段——插件仓 CI 判红
27
+ * (经 `@linkdesk/plugin-sdk/svg-wellformed` subpath 引入:插件仓**零新增 devDependency**,
28
+ * 纯数据插件仓也在覆盖内)。
29
+ * · 壳侧:`scripts/check-svg-wellformed.mjs`(以相对路径 import 本文件,与
30
+ * `scripts/audit-plugin-tests.mjs` 引 `test-audit.mjs` 同款)——扫模板 / 仓内插件 / 资源。
31
+ *
32
+ * 用法:
33
+ * import { checkSvgWellformed, xmlWellformedError } from "@linkdesk/plugin-sdk/svg-wellformed";
34
+ * const r = checkSvgWellformed(process.cwd()); // ⇒ { scanned, violations: [...] }
35
+ */
36
+
37
+ import { readdirSync, readFileSync } from "node:fs";
38
+ import { join, sep } from "node:path";
39
+ import { SaxesParser } from "saxes";
40
+
41
+ /** 口径一句话——门禁与文档互钉用(改判据就改这句,两处锚词比对会跟着红) */
42
+ export const SVG_CALIBER =
43
+ "SVG 是 XML 文档:整份必须能被严格 XML 解析器读完且根元素为 svg;否则浏览器按 image/svg+xml 解析失败 ⇒ 静默破图。";
44
+
45
+ /** 默认跳过的目录名——构建产物 / 依赖 / 编辑器临时目录(它们不是「作者写的资源」) */
46
+ export const DEFAULT_SKIP_DIRS = new Set([
47
+ "node_modules",
48
+ "dist",
49
+ "dist-electron",
50
+ ".git",
51
+ ".vite",
52
+ "coverage",
53
+ "__tests__",
54
+ "build",
55
+ ]);
56
+
57
+ /**
58
+ * 默认豁免的文件名形态——**测试夹具常故意放非法样本**(拿坏图验自己的错误分支),
59
+ * 那是合法的。豁免靠**文件名自我声明**(`.fixture.svg` / `.mock.svg`),不靠目录猜测:
60
+ * 与壳仓 `check-empty-dirs` / os.tmpdir 夹具、ci-verify `isSourceFile` 的既有词汇一致。
61
+ */
62
+ export const DEFAULT_EXEMPT_RE = /\.(fixture|mock)\.svg$/i;
63
+
64
+ /**
65
+ * 单份 XML 源 → **第一处** well-formedness 错误(合法 ⇒ `null`)。纯函数,不读盘。
66
+ *
67
+ * 只报第一处:XML 的第一处致命错会让后续解析失去意义(错误会串成一片),逐份报一个
68
+ * 足够定位,也避免同一根因刷出十几行噪音。
69
+ */
70
+ export function xmlWellformedError(source) {
71
+ if (typeof source !== "string") return null;
72
+ const parser = new SaxesParser({ fragment: false });
73
+ /** 错误回调是**同步**触发的:抓住第一处就够,后面的必然是它的余波 */
74
+ let first = null;
75
+ parser.on("error", (e) => {
76
+ if (!first) first = e;
77
+ });
78
+ try {
79
+ parser.write(source).close();
80
+ } catch (e) {
81
+ if (!first) first = e;
82
+ }
83
+ if (!first) return null;
84
+ // ⚠️ saxes 把位置**编进 message 前缀**(`"4:26: malformed comment."`),不是独立字段——
85
+ // 本仓实测 `first.line`/`first.column` 恒 undefined。故从消息里摘,摘不到就留 null
86
+ // (⛔ 不编造位置:宁可只报「这份文件坏了」,也不报一个会把人带偏的行号)。
87
+ const raw = String(first.message ?? first).trim();
88
+ const m = /^(\d+):(\d+):\s*([\s\S]*)$/.exec(raw);
89
+ return {
90
+ line: m ? Number(m[1]) : null,
91
+ column: m ? Number(m[2]) : null,
92
+ message: m ? m[3].trim() : raw,
93
+ };
94
+ }
95
+
96
+ /** 读一份盘的 `.svg` → 违规对象(合规 ⇒ `null`)。文件读不动(权限/竞态)同样返回 `null`:不阻断门禁。 */
97
+ function checkOneFile(absPath, fileRel) {
98
+ let source;
99
+ try {
100
+ source = readFileSync(absPath, "utf8");
101
+ } catch {
102
+ return null; // 读不动不是本判据的事(存在性由别的门禁管)
103
+ }
104
+ const err = xmlWellformedError(source);
105
+ if (err) {
106
+ return { file: fileRel, line: err.line, column: err.column, message: err.message, kind: "xml" };
107
+ }
108
+ return null;
109
+ }
110
+
111
+ /** 根元素名(只看第一个开标签;判据本身已保证解析成功过) */
112
+ function rootElementName(source) {
113
+ const m = /<([A-Za-z_][\w.:-]*)/.exec(source.replace(/<!--[\s\S]*?-->/g, "").replace(/<\?[\s\S]*?\?>/g, ""));
114
+ return m ? m[1] : null;
115
+ }
116
+
117
+ /**
118
+ * 走查一棵树,收集其中的 `.svg`(工程相对、正斜杠、字典序)。
119
+ * `absRoot` 不存在 / 不可读 ⇒ 空数组(约定根缺失不是本判据的事)。
120
+ */
121
+ export function listSvgFiles(absRoot, options = {}) {
122
+ const skipDirs = options.skipDirs ?? DEFAULT_SKIP_DIRS;
123
+ const isExempt = options.isExempt ?? ((rel) => DEFAULT_EXEMPT_RE.test(rel));
124
+ const out = [];
125
+ const walk = (absDir, relDir) => {
126
+ let entries;
127
+ try {
128
+ entries = readdirSync(absDir, { withFileTypes: true });
129
+ } catch {
130
+ return;
131
+ }
132
+ for (const e of entries) {
133
+ const rel = relDir ? `${relDir}/${e.name}` : e.name;
134
+ if (e.isDirectory()) {
135
+ if (skipDirs.has(e.name) || e.name.startsWith(".")) continue;
136
+ walk(join(absDir, e.name), rel);
137
+ continue;
138
+ }
139
+ if (!e.isFile()) continue;
140
+ if (!/\.svg$/i.test(e.name)) continue;
141
+ if (isExempt(rel)) continue;
142
+ out.push(rel);
143
+ }
144
+ };
145
+ walk(absRoot, "");
146
+ return out.sort();
147
+ }
148
+
149
+ /**
150
+ * 巡检一棵树里所有 `.svg` —— 返回 `{ scanned, violations }`。
151
+ *
152
+ * `violations[i]` 形状:`{ file, line, column, message, kind }`(`file` = 相对 `absRoot` 的正斜杠路径)。
153
+ * 两个 `kind`:`"xml"`(不是合法 XML)/ `"root"`(根元素不是 svg)。
154
+ */
155
+ export function checkSvgWellformed(absRoot, options = {}) {
156
+ const files = listSvgFiles(absRoot, options);
157
+ const violations = [];
158
+ for (const fileRel of files) {
159
+ const abs = join(absRoot, fileRel.split("/").join(sep));
160
+ const bad = checkOneFile(abs, fileRel);
161
+ if (bad) {
162
+ violations.push(bad);
163
+ continue;
164
+ }
165
+ let source = "";
166
+ try {
167
+ source = readFileSync(abs, "utf8");
168
+ } catch {
169
+ continue;
170
+ }
171
+ const root = rootElementName(source);
172
+ if (root !== "svg") {
173
+ violations.push({
174
+ file: fileRel,
175
+ line: 1,
176
+ column: 1,
177
+ message: `根元素是 <${root ?? "?"}>,不是 <svg>——.svg 文件里装的必须是一张 SVG`,
178
+ kind: "root",
179
+ });
180
+ }
181
+ }
182
+ return { scanned: files.length, violations };
183
+ }
184
+
185
+ /**
186
+ * 违规 → 人类可读一行。两轴(作者侧 CI / 壳侧门禁)打印同款,免得同一条错两种说法。
187
+ */
188
+ export function formatSvgViolation(v) {
189
+ const where = v.line == null ? v.file : `${v.file}:${v.line}${v.column == null ? "" : `:${v.column}`}`;
190
+ return `${where} ${v.message}`;
191
+ }
192
+
193
+ /**
194
+ * 违规 → 修法提示(**按 kind 给因**:破图这个病的两种成因,修法完全不同)。
195
+ * 供两轴打印用;⛔ 别在调用处另写一份文案。
196
+ */
197
+ export function svgViolationHint(v) {
198
+ if (v.kind === "root") {
199
+ return "拿 HTML/别的 XML 改名成 .svg 了?重画成 <svg xmlns=\"http://www.w3.org/2000/svg\"> 根元素。";
200
+ }
201
+ if (/malformed comment/i.test(v.message)) {
202
+ return 'XML 注释里禁止出现**连续两个连字符**——最常见是「不能用 CSS 变量的字面量」这句话被原样写进了注释;改成写「CSS 变量」即可。';
203
+ }
204
+ if (/undefined entity/i.test(v.message)) {
205
+ return "XML 只有 amp/lt/gt/quot/apos 五个预定义实体——`&nbsp;` 这类要写成数字引用(如 `&#160;`)。";
206
+ }
207
+ return "用严格 XML 解析器定位那一行后修掉;改完再跑一次本判据(它是唯一的验收)。";
208
+ }