@dsh-workbench/module-tools 0.2.12 → 0.2.14

package/src/font-scale.mjs

@@ -0,0 +1,213 @@
+// 字号口径（S5，用户 2026-10-17 定的那条）：**不禁大字号，只禁"刻度外手搓"**。
+//
+// 口径原文：「某个卡片的重点数字大是合法的（例如套餐余额那个 28px），只禁刻度外手搓。
+// 所以：先把**刻度**从令牌定义里读出来（那是唯一真相），再列出不在刻度上、且不是引用令牌的字面值。」
+//
+// 这个模块只**读**、只**归类**、只**拼 note**：它不判红、不改退出码、没有开关、也不写文件。
+// 今天这份清单落在 `checks/style.mjs` 通过时的那几行 note 上（黄）；真做成红要等棘轮那一半
+// 想清楚（口径与将来的形态写在 `.scratch/font-scale/spec.md`）。
+//
+// 三类的口径（同名同义，全程只用这三个词）：
+//   a) 引用令牌 —— `var(--dsw-font-*)` / `var(--wb-font-*)`，合规，只报总数；
+//   b) 刻度外字面值 —— 数值不在刻度上，**这份就是要的清单**；
+//   c) 刻度上字面值 —— 数值在刻度上但没写成 `var(...)`：最容易收进令牌的一批，但**不是错**。
+//
+// 为什么刻度要"读"而不是写死：令牌定义是唯一真相。外壳侧现读 `tokens/scale.css` 与
+// `tokens.css`；dsh 侧在外壳仓里解析不到（见下面 DSH_ALIAS_FONT_SIZES 那段），那一半是照抄的常量。
+// 两边都不发明档位 —— dsh 没有的档写在外壳自己的 token 里才算数。
+
+import { existsSync, readFileSync, readdirSync, statSync } from 'node:fs';
+import { join, relative } from 'node:path';
+
+/**
+ * dsh 别名刻度 —— `--dsw-font-*-font-size` 的**值**，7 档。
+ *
+ * 出处：装出来的 dsh 那份 `@deepseek-ai/dsh-client-ui-theme/lib/client.js:1425`
+ * （2026-10-17 实测，dsh 0.2.1；那一整行是 CSS 变量声明），逐条抄的值：
+ *   `--dsw-font-xxxs-11-font-size: 11px` · `--dsw-font-xxs-12-font-size: 12px` ·
+ *   `--dsw-font-xs-13-font-size: 13px` · `--dsw-font-s-14-font-size: 14px` ·
+ *   `--dsw-font-base-16-font-size: 16px` · `--dsw-font-l-20-font-size: 20px` ·
+ *   `--dsw-font-xl-24-font-size: 24px`
+ * 两个坑，抄的时候都按**值**收、不按名字：
+ *   · `--dsw-font-m-18` 的值其实是 **16px**（名字与值不一致），所以刻度里没有 18 这一档；
+ *   · markdown 那几个（h1 `calc(21px + delta)` / h2 19 / h3 18 / small 12 …）是**内容字号**，
+ *     跟着用户的 `--dsh-content-font-size` 走，不是面板排版的档，不收。
+ *
+ * 为什么是常量而不是现读：外壳仓里根本没有 dsh 的 theme 包（只有 `dsh-client-ui-primitives`），
+ * `require.resolve` 直接 MODULE_NOT_FOUND；`--dsw-*` 是 dsh 实例在**运行时**注入的，源码树里没有定义。
+ * 哪天真要它现读（在装齐 dsh 的环境里）：resolve 到 theme 之后解析同一批 `-font-size` 的值，
+ * 再把这份常量删掉 —— 别让它长成第二份真相。
+ */
+export const DSH_ALIAS_FONT_SIZES = [11, 12, 13, 14, 16, 20, 24];
+
+/** 外壳自己的字号令牌（`--wb-font-*: <n>px`）—— 刻度定义，不是手搓值。 */
+const SHELL_FONT_TOKEN = /--wb-font-[a-z0-9-]+\s*:\s*([0-9]+(?:\.[0-9]+)?)px/g;
+
+/** 从外壳的令牌文件里读出它自己的那几档（文件不在场就跳过：仓外的工作区读不到）。 */
+export function shellFontScaleIn(files) {
+  const sizes = new Set();
+  for (const file of files) {
+    if (!existsSync(file)) continue;
+    for (const hit of readFileSync(file, 'utf8').matchAll(SHELL_FONT_TOKEN)) {
+      sizes.add(Number(hit[1]));
+    }
+  }
+  return sizes;
+}
+
+/** 合起来的刻度：dsh 别名那 7 档 + 外壳自己 token 里的档（现读）。 */
+export function fontScaleOf(shellTokenFiles = []) {
+  return new Set([...DSH_ALIAS_FONT_SIZES, ...shellFontScaleIn(shellTokenFiles)]);
+}
+
+const CSS_FONT_SIZE = /(?:^|[;{\s])font-size\s*:\s*([^;{}]+)/g;
+const CSS_FONT_SHORTHAND = /(?:^|[;{\s])font\s*:\s*([^;{}]+)/g;
+const JS_FONT_SIZE = /\bfontSize\s*[:=]\s*\{?\s*(['"]?)([^,}'"\n]+)\1\s*\}?/g;
+const FONT_TOKEN_REF = /var\(\s*(--[a-z0-9-]*font[a-z0-9-]*)/g;
+// `--dsw-font-family` / `--dsw-font-mono` 也带 `font`，但它们是字族不是字号 ——
+// `font: 11px/18px var(--dsw-font-family)` 那行的字号是字面的 11px，不能算"引用令牌"。
+const FONT_FAMILY_TOKEN = /font-(?:family|mono)/;
+const NUMERIC_VALUE = /^([0-9]*\.?[0-9]+)(px|rem|em|%)?$/;
+
+/** 值里引用的**字号**令牌名（排掉字族/等宽那两族）。 */
+function sizeTokenRefs(value) {
+  const names = [];
+  for (const hit of value.matchAll(FONT_TOKEN_REF)) {
+    if (!FONT_FAMILY_TOKEN.test(hit[1])) names.push(hit[1]);
+  }
+  return names;
+}
+
+/**
+ * 把一个字号声明的值分成 ref / size / relative / keyword。
+ * `relative` 是 `em` / `%`（跟着父级走，判不了刻度外）、`keyword` 是 `inherit` / `unset` 这类。
+ * `rem` 按 1rem = 16px 折（本仓没有根字号覆盖；dsh 也没改 `html` 的 font-size）。
+ */
+export function classifyFontValue(value) {
+  const raw = String(value).trim();
+  const refs = sizeTokenRefs(raw);
+  if (refs.length > 0) return { kind: 'ref', refs };
+  const first = (raw.split(/\s+/)[0] ?? '').replace(/\/.*$/, '');
+  const hit = NUMERIC_VALUE.exec(first);
+  if (hit === null) return { kind: 'keyword', value: first };
+  const unit = hit[2] ?? 'px';
+  if (unit === 'em' || unit === '%') return { kind: 'relative', value: first };
+  const px = unit === 'rem' ? Number(hit[1]) * 16 : Number(hit[1]);
+  return { kind: 'size', px, value: first };
+}
+
+function isTestSource(file) {
+  return /(^|[\\/])__tests__[\\/]/.test(file) || /\.test\.[cm]?tsx?$/.test(file);
+}
+
+function walk(dir, acc = []) {
+  let entries;
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return acc;
+  }
+  for (const entry of entries) {
+    if (entry === 'node_modules' || entry === 'dist') continue;
+    const full = join(dir, entry);
+    if (statSync(full).isDirectory()) walk(full, acc);
+    else if (/\.(css|ts|tsx)$/.test(full)) acc.push(full);
+  }
+  return acc;
+}
+
+/**
+ * 扫一组根下的字号声明并归类。`roots` 是 `{ label, dir }`：label 是报出来的包名。
+ * 测试文件不扫（用例里那几处是断言用的字符串，不是界面字号）；`node_modules` / `dist` 不扫。
+ * 返回里 `refFiles` / `litFiles` 是**涉及文件数**（同一个文件只算一次）。
+ */
+export function auditFontSizes({ roots, scale }) {
+  const refs = [];
+  const offScale = [];
+  const onScale = [];
+  const relativeSizes = [];
+  const refFiles = new Set();
+  const litFiles = new Set();
+  for (const root of roots) {
+    for (const file of walk(root.dir)) {
+      if (!/\.css$/.test(file) && isTestSource(file)) continue;
+      let text;
+      try {
+        text = readFileSync(file, 'utf8');
+      } catch {
+        continue;
+      }
+      const rel = relative(root.dir, file);
+      text.split('\n').forEach((line, at) => {
+        const values = [];
+        for (const hit of line.matchAll(CSS_FONT_SIZE)) values.push({ value: hit[1], decl: hit[0] });
+        for (const hit of line.matchAll(CSS_FONT_SHORTHAND)) values.push({ value: hit[1], decl: hit[0] });
+        for (const hit of line.matchAll(JS_FONT_SIZE)) values.push({ value: hit[2], decl: hit[0] });
+        for (const one of values) {
+          const verdict = classifyFontValue(one.value);
+          if (verdict.kind === 'keyword') continue;
+          const where = {
+            pkg: root.label,
+            file: rel,
+            line: at + 1,
+            decl: one.decl.replace(/^[;{\s]+/, '').trim().slice(0, 56),
+          };
+          if (verdict.kind === 'ref') {
+            refFiles.add(`${root.label}:${rel}`);
+            refs.push(where);
+            continue;
+          }
+          litFiles.add(`${root.label}:${rel}`);
+          if (verdict.kind === 'relative') {
+            relativeSizes.push({ ...where, px: verdict.value });
+          } else if (scale.has(verdict.px)) {
+            onScale.push({ ...where, px: verdict.px });
+          } else {
+            offScale.push({ ...where, px: verdict.px });
+          }
+        }
+      });
+    }
+  }
+  return { refs, offScale, onScale, relative: relativeSizes, refFiles, litFiles };
+}
+
+const formatSize = (value) => String(value);
+
+/** 最多印十来行明细：刻度外的先印（那是这份清单要的东西），再印刻度上的。 */
+const DETAIL_LIMIT = 12;
+
+function detailOf(hit, verdict) {
+  const head = `${hit.pkg}: ${hit.file}:${hit.line} ${hit.decl}`;
+  return verdict === 'off'
+    ? `· ${head} —— ${formatSize(hit.px)} 不在刻度上（刻度外）`
+    : `· ${head} —— ${formatSize(hit.px)} 在刻度上，可收进令牌（但不是错）`;
+}
+
+/**
+ * 拼成 `checks/style.mjs` 通过时的那几行 note：第一行汇总（各类条数 + 涉及文件数 + 指路），
+ * 后面最多 `DETAIL_LIMIT` 行明细。零命中时只留一行"都是 0"。
+ */
+export function fontScaleNotes(report, scale, { doc = '.scratch/font-scale/spec.md' } = {}) {
+  const sizes = [...scale].sort((a, b) => a - b).map(formatSize).join(' / ');
+  const head =
+    `字号口径（黄，不判红）：刻度 ${sizes}（从 --dsw-font-* 与 --wb-font-* 的**定义**读出来，` +
+    `出处见 ${doc}）；引用令牌 ${report.refs.length} 处 / ${report.refFiles.size} 文件（合规，不列）；` +
+    `刻度外字面值 ${report.offScale.length} 处 / ${report.litFiles.size} 文件；` +
+    `刻度上字面值 ${report.onScale.length} 处；相对单位（em/%）判不了 ${report.relative.length} 处`;
+  const all = [
+    ...report.offScale.map((hit) => detailOf(hit, 'off')),
+    ...report.onScale.map((hit) => detailOf(hit, 'on')),
+  ];
+  if (all.length === 0) {
+    return [`${head} —— 面板的字号全走令牌，一处刻度外的字面值都没有`];
+  }
+  const notes = [head, ...all.slice(0, DETAIL_LIMIT)];
+  if (all.length > DETAIL_LIMIT) {
+    notes.push(
+      `…另有 ${all.length - DETAIL_LIMIT} 处（刻度外 ${report.offScale.length} / 刻度上 ${report.onScale.length}），` +
+        `完整清单见 ${doc}`,
+    );
+  }
+  return notes;
+}

package/template-diy/README.md.tpl

@@ -208,9 +208,9 @@ prefs: {
 }
 ```
 
-浏览器半侧：`useHostWrite({ channel: 'prefs', resource: 'your-module' })` + `Field` / `TextField`，外面套
-`SettingsSection`，保存用 `SaveBar`；存失败留在原地。（输入框内边距与"标签 + 提示"排布是外壳给的默认，
-不用为这个写 CSS。）语义：没写过 ≠ 选空、清空要把文件收掉、不认识的值报错并列出还认的候选。
+浏览器半侧：`useHostWrite({ channel: 'prefs', resource: 'your-module' })` + `FormRows` / `FormRow` /
+`TextField`，外面套 `SettingsSection`，保存用 `SaveBar`；存失败留在原地。（标签、行距与输入框内边距都是
+外壳给的默认，不用为这个写 CSS。）语义：没写过 ≠ 选空、清空要把文件收掉、不认识的值报错并列出还认的候选。
 
 ### 靠什么跑起来：`env`