@linkdesk/plugin-sdk 0.1.70 → 0.1.71

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.
@@ -0,0 +1,58 @@
1
+ /**
2
+ * @linkdesk/plugin-sdk/check-config-titles 的类型声明(实现 = 同目录 check-config-titles.mjs,免构建直发)。
3
+ * 三族判据与 severity 归属见 .mjs 头注——那里是单一真源,这里不重述。
4
+ */
5
+
6
+ export interface TitleGapBase {
7
+ /** 配置键(contributes.configuration.properties 的键) */
8
+ key: string;
9
+ /** 声明的节名(group,未声明 = 空串) */
10
+ group: string;
11
+ }
12
+
13
+ export interface NoTitleGap extends TitleGapBase {}
14
+
15
+ export interface MissingEnGap extends TitleGapBase {
16
+ /** 声明的 title 原文(中文原文 = i18n key) */
17
+ title: string;
18
+ }
19
+
20
+ export interface MissingEnumDescriptionsGap extends TitleGapBase {
21
+ /** enum 档位数 */
22
+ enumCount: number;
23
+ }
24
+
25
+ export interface ConfigTitleGaps {
26
+ scanned: { properties: number; enums: number };
27
+ /** ① 无 title */
28
+ noTitle: NoTitleGap[];
29
+ /** ② title 缺本仓字典译名(dictKeys 未传 = 空数组——⑧ 段 own-dict 红管辖同域) */
30
+ missingEn: MissingEnGap[];
31
+ /** ③ 有 enum 缺 enumDescriptions */
32
+ missingEnumDescriptions: MissingEnumDescriptionsGap[];
33
+ /** 是否存在非空 contributes.configuration.properties(false = 无判据对象) */
34
+ hasConfiguration: boolean;
35
+ }
36
+
37
+ /**
38
+ * 三族缺口收集——**纯函数**(不读盘)。dictKeys = 本仓自有字典 key 集(⑧ 段 cov.dict.keys);
39
+ * 不传 = 跳过 ② 族(无字典可对,缺译归 ⑧ 红)。
40
+ */
41
+ export declare function collectConfigTitleGaps(
42
+ manifest: unknown,
43
+ options?: { dictKeys?: Set<string> },
44
+ ): ConfigTitleGaps;
45
+
46
+ /** 黄单一行——三族同款格式(两轴打印同款,免得同一条错两种说法)。 */
47
+ export declare function formatTitleGap(
48
+ family: "noTitle" | "missingEn" | "missingEnumDescriptions",
49
+ gap: TitleGapBase & Partial<MissingEnGap & MissingEnumDescriptionsGap>,
50
+ ): string;
51
+
52
+ /** 修法指路——按族给因。 */
53
+ export declare function titleGapHint(
54
+ family: "noTitle" | "missingEn" | "missingEnumDescriptions",
55
+ ): string;
56
+
57
+ /** 口径一句话——门禁与文档互钉用。 */
58
+ export declare const CONFIG_TITLES_CALIBER: string;
@@ -0,0 +1,91 @@
1
+ /**
2
+ * `check-config-titles`——配置项短名(`contributes.configuration.properties.*.title`)三族判据。
3
+ * **D6 分级门禁的插件侧「黄灯腿」判据本体**(2026-10-04 配置项短名案,层 1)。
4
+ *
5
+ * ── 三族判据(01 层 1)──
6
+ * ① 无 `title` —— 声明了 configuration.properties 却没给行名短名 ⇒ 黄
7
+ * (设置页/市场功能页只能裸显英文配置键,D1 的「人话行名」缺位)
8
+ * ② 有 `title` 缺译名 —— title 值(中文原文 = i18n key)不在本仓自有字典 ⇒ 黄
9
+ * ⚠️ **本族与 own-dict-coverage ⑧ 段同域**——⑧ 对「可渲染串缺译」判**红**
10
+ * (manifest 腿),此处只作黄灯汇总;且 ⑧ 连「本仓零字典声明」的形态一起管。
11
+ * 调用方把 ⑧ 的 `dict.keys` 传进来即可复用(⛔ 不在两处各自读盘,两把尺子同一份实现)。
12
+ * ③ 有 enum 缺 `enumDescriptions` —— 枚举值无显示名 ⇒ 设置页下拉裸显英文值(取证 ⑦)
13
+ *
14
+ * ── severity 归调用方 ──
15
+ * 本模块是**纯判据**(无 fs、无 process.exit):官方各仓 CI(ci-verify ⑨ 段)内测期按 **warn** 消费
16
+ * ——列黄单不判红;预留 `--strict`(v1 正式版统一切红,E21——黄单清零前 ⛔ 无预告判红)。
17
+ * 壳是软件本体、一步红灯不设黄灯——壳侧红门禁(壳 scripts/check-config-titles.mjs 默认模式)
18
+ * 只借本模块的 `--plugin` 模式(同一份三族判据),壳四文件的 TS 提取与「无 title 判红」住壳侧脚本。
19
+ *
20
+ * 自测口径(⛔ 空转判据 ≠ 零存量):真缺 title 的 fixture 必须出黄、齐全 fixture 必须安静
21
+ * ——见 src/check-config-titles.test.ts。
22
+ */
23
+
24
+ /** 一句话口径——报错文案与文档同源引用 */
25
+ export const CONFIG_TITLES_CALIBER =
26
+ "配置项短名(title)= 设置页与市场功能页的行级人话名——谁的声明谁补名,缺省时渲染回退显配置键(D1/D2)。";
27
+
28
+ /**
29
+ * 从 manifest 收集三族缺口。**纯函数**(不读盘):
30
+ * @param manifest 已解析的 plugin.json(任意形状——形状不对按「无 configuration」处理)
31
+ * @param options.dictKeys 本仓自有字典的 key 集合(⑧ 段 cov.dict.keys);不传 = 跳过 ② 族(无字典可对)
32
+ * @returns {{ scanned: {properties: number, enums: number}, noTitle: Array<{key: string, group: string}>,
33
+ * missingEn: Array<{key: string, title: string}>, missingEnumDescriptions: Array<{key: string, group: string, enumCount: number}>,
34
+ * hasConfiguration: boolean }}
35
+ */
36
+ export function collectConfigTitleGaps(manifest, options = {}) {
37
+ const props = manifest?.contributes?.configuration?.properties;
38
+ const out = {
39
+ scanned: { properties: 0, enums: 0 },
40
+ noTitle: [],
41
+ missingEn: [],
42
+ missingEnumDescriptions: [],
43
+ hasConfiguration: Boolean(
44
+ props && typeof props === "object" && Object.keys(props).length > 0,
45
+ ),
46
+ };
47
+ if (!out.hasConfiguration) return out;
48
+ const dictKeys = options.dictKeys instanceof Set ? options.dictKeys : null;
49
+ for (const [key, prop] of Object.entries(props)) {
50
+ // E6#151 同口径:形状不可信——非对象条目剔出判域(manifest 校验拦形状,这里不重复报)
51
+ if (!prop || typeof prop !== "object" || Array.isArray(prop)) continue;
52
+ out.scanned.properties += 1;
53
+ const group = typeof prop.group === "string" ? prop.group : "";
54
+ if (typeof prop.title !== "string" || prop.title.trim() === "") {
55
+ out.noTitle.push({ key, group });
56
+ } else if (dictKeys && !dictKeys.has(prop.title)) {
57
+ out.missingEn.push({ key, title: prop.title });
58
+ }
59
+ const hasEnum = Array.isArray(prop.enum) && prop.enum.length > 0;
60
+ if (hasEnum) {
61
+ out.scanned.enums += 1;
62
+ const ed = prop.enumDescriptions;
63
+ // 空对象/空数组 = 没给(占位也算缺——下拉照样裸显英文值)
64
+ const edUsable =
65
+ Array.isArray(ed)
66
+ ? ed.length > 0
67
+ : ed !== null && typeof ed === "object" && Object.keys(ed).length > 0;
68
+ if (!edUsable) {
69
+ out.missingEnumDescriptions.push({ key, group, enumCount: prop.enum.length });
70
+ }
71
+ }
72
+ }
73
+ return out;
74
+ }
75
+
76
+ /** 黄单一行——三族同款格式(key 打头,组名随行) */
77
+ export function formatTitleGap(family, gap) {
78
+ const at = gap.group ? `(节:${gap.group})` : "";
79
+ if (family === "noTitle") return `无 title——设置页/市场只能裸显配置键:${gap.key}${at}`;
80
+ if (family === "missingEn") return `title「${gap.title}」缺 en 译名(配置键 ${gap.key})——英文界面回退显中文`;
81
+ return `enum ${gap.enumCount} 档全无 enumDescriptions——下拉裸显英文值:${gap.key}${at}`;
82
+ }
83
+
84
+ /** 修法指路——三族各一句(文案与 own-dict 的 hint 同风格:说清落点,不让人猜) */
85
+ export function titleGapHint(family) {
86
+ if (family === "noTitle")
87
+ return `在本仓 plugin.json 的该条声明里加 "title": "<中文短名>"(≤12 字名词短语、去插件前缀;renderHint "action" 行按按钮语义起动词名),en 译名进本仓 i18n/en.json。`;
88
+ if (family === "missingEn")
89
+ return `把 title 的中文原文作为 key 补进本仓 i18n/en.json(谁声明谁供译——英译不进壳的语言包)。`;
90
+ return `给该条声明补 "enumDescriptions"(对象形态:enum 值 → 中文显示名),en 译名同笔进 i18n/en.json。`;
91
+ }
@@ -106,6 +106,11 @@ export const RENDERABLE_MANIFEST_FIELDS = [
106
106
  field: "description",
107
107
  consumer: "设置项说明(settings 仓 t(prop.description))",
108
108
  },
109
+ {
110
+ steps: ["contributes", "configuration", "properties", "*"],
111
+ field: "title",
112
+ consumer: "设置项行名短名(配置项短名案 D1/D4,2026-10-04——settings 仓 t(prop.title),缺省回退显配置键)",
113
+ },
109
114
  {
110
115
  steps: ["contributes", "configuration", "properties", "*"],
111
116
  field: "group",
package/package.json CHANGED
@@ -1,91 +1,97 @@
1
- {
2
- "name": "@linkdesk/plugin-sdk",
3
- "version": "0.1.70",
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
- "./own-dict-coverage": {
31
- "types": "./own-dict-coverage.d.ts",
32
- "default": "./own-dict-coverage.mjs"
33
- }
34
- },
35
- "files": [
36
- "dist",
37
- "schemas",
38
- "dev-host",
39
- "test-audit.mjs",
40
- "test-audit.d.ts",
41
- "svg-wellformed.mjs",
42
- "svg-wellformed.d.ts",
43
- "own-dict-coverage.mjs",
44
- "own-dict-coverage.d.ts"
45
- ],
46
- "sideEffects": false,
47
- "bin": {
48
- "linkdesk-plugin-sdk": "./dist/bin.js"
49
- },
50
- "publishConfig": {
51
- "access": "public"
52
- },
53
- "engines": {
54
- "node": ">=20.0.0"
55
- },
56
- "scripts": {
57
- "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
58
- "typecheck": "tsc -p tsconfig.json --noEmit",
59
- "prepack": "npm run build"
60
- },
61
- "dependencies": {
62
- "@linkdesk/contracts": "^0.1.1",
63
- "@typescript-eslint/eslint-plugin": "^8.0.0",
64
- "@typescript-eslint/parser": "^8.0.0",
65
- "@vitejs/plugin-react": "^4.3.4",
66
- "ajv": "^8.17.1",
67
- "eslint": "^9.0.0",
68
- "eslint-import-resolver-typescript": "^4.4.5",
69
- "eslint-plugin-import-x": "^4.17.1",
70
- "eslint-plugin-react-hooks": "^7.1.1",
71
- "i18next": "^26.3.6",
72
- "jsonc-parser": "^3.3.1",
73
- "jszip": "^3.10.1",
74
- "react": "^18.3.1",
75
- "react-dom": "^18.3.1",
76
- "react-i18next": "^17.0.10",
77
- "saxes": "^6.0.0",
78
- "vite": "^6.0.0"
79
- },
80
- "devDependencies": {
81
- "@types/node": "^24.0.0",
82
- "typescript": "^5.9.0"
83
- },
84
- "keywords": [
85
- "linkdesk",
86
- "plugin",
87
- "sdk",
88
- "vite"
89
- ],
90
- "license": "MIT"
91
- }
1
+ {
2
+ "name": "@linkdesk/plugin-sdk",
3
+ "version": "0.1.71",
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
+ "./own-dict-coverage": {
31
+ "types": "./own-dict-coverage.d.ts",
32
+ "default": "./own-dict-coverage.mjs"
33
+ },
34
+ "./check-config-titles": {
35
+ "types": "./check-config-titles.d.ts",
36
+ "default": "./check-config-titles.mjs"
37
+ }
38
+ },
39
+ "files": [
40
+ "dist",
41
+ "schemas",
42
+ "dev-host",
43
+ "test-audit.mjs",
44
+ "test-audit.d.ts",
45
+ "svg-wellformed.mjs",
46
+ "svg-wellformed.d.ts",
47
+ "own-dict-coverage.mjs",
48
+ "own-dict-coverage.d.ts",
49
+ "check-config-titles.mjs",
50
+ "check-config-titles.d.ts"
51
+ ],
52
+ "sideEffects": false,
53
+ "bin": {
54
+ "linkdesk-plugin-sdk": "./dist/bin.js"
55
+ },
56
+ "publishConfig": {
57
+ "access": "public"
58
+ },
59
+ "engines": {
60
+ "node": ">=20.0.0"
61
+ },
62
+ "scripts": {
63
+ "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json",
64
+ "typecheck": "tsc -p tsconfig.json --noEmit",
65
+ "prepack": "npm run build"
66
+ },
67
+ "dependencies": {
68
+ "@linkdesk/contracts": "^0.1.1",
69
+ "@typescript-eslint/eslint-plugin": "^8.0.0",
70
+ "@typescript-eslint/parser": "^8.0.0",
71
+ "@vitejs/plugin-react": "^4.3.4",
72
+ "ajv": "^8.17.1",
73
+ "eslint": "^9.0.0",
74
+ "eslint-import-resolver-typescript": "^4.4.5",
75
+ "eslint-plugin-import-x": "^4.17.1",
76
+ "eslint-plugin-react-hooks": "^7.1.1",
77
+ "i18next": "^26.3.6",
78
+ "jsonc-parser": "^3.3.1",
79
+ "jszip": "^3.10.1",
80
+ "react": "^18.3.1",
81
+ "react-dom": "^18.3.1",
82
+ "react-i18next": "^17.0.10",
83
+ "saxes": "^6.0.0",
84
+ "vite": "^6.0.0"
85
+ },
86
+ "devDependencies": {
87
+ "@types/node": "^24.0.0",
88
+ "typescript": "^5.9.0"
89
+ },
90
+ "keywords": [
91
+ "linkdesk",
92
+ "plugin",
93
+ "sdk",
94
+ "vite"
95
+ ],
96
+ "license": "MIT"
97
+ }
@@ -371,6 +371,7 @@
371
371
  "enum": { "type": "array" },
372
372
  "enumDescriptions": { "type": "object", "description": "enum value → display name mapping" },
373
373
  "description": { "type": "string" },
374
+ "title": { "type": "string", "description": "Row display name — the short human-readable label shown as the settings row name and on the marketplace features tab (optional — omitted = the settings row falls back to showing the configuration key). Value convention matches description: the Chinese source text IS the i18n key; English translations go in your plugin's i18n/en.json. Keep it a noun phrase (≤12 characters, drop the plugin-name prefix); rows with renderHint \"action\" take a verb-phrase name instead (it reads as a button label)." },
374
375
  "uiHint": { "type": "string", "description": "Settings editor rendering hint — SettingsView picks the control from the hint. Known hints: slider, fontSize, color, fontFamily, file, directory, image, segmented, fontTone, accentSource, themePicker, select, stringList. A hint the installed renderer does not know is shown read-only — the current value plus a tooltip saying the declared control is unsupported (no editable fallback control, no error thrown). The value is an open string, so third parties may declare new hint names." },
375
376
  "renderHint": { "type": "string", "description": "Rendering hint for special rows — \"action\" renders a button (its text comes from description, clicking runs actionCommand); \"readonly\" renders a read-only status line whose value comes from executing statusCommand; \"color\" renders a read-only color row (swatch + value). \"readonly\"/\"action\" are shorthands meaning the row's primary control IS the status line/button: statusCommand and actionCommand may also be declared alongside any primary control, rendering as companions to its right ([primary control][companion button][companion readonly]). Known hints: readonly, action, color. An unknown hint is shown read-only (current value + explanatory tooltip). Open string." },
376
377
  "actionCommand": { "type": "string", "description": "Command executed when an \"action\" button is clicked — a shell command id or one of your own (resolved when clicked). May be declared alongside any primary control: it then renders as a companion button to the right of that control, with its text taken from description." },