跳到正文

把旧工具库迁到 es-toolkit:一次 sheng-tool 现代化改造(2):用 JSDoc 生成测试与公共文档

把旧工具库迁到 es-toolkit:一次 sheng-tool 现代化改造

  1. 依赖、API 与发布边界的迁移
  2. 用 JSDoc 生成测试与公共文档(当前)

sheng-tool 原来的 @example 同时服务读者、测试与文档,这次迁移继续保留这个设计,但改用 TypeScript compiler API 读取 JSDoc。依赖、公开 API 和发布入口的调整见第一篇;这里集中说明示例怎样生成用例,未解析内容怎样报告,以及 TSDoc、手写测试和 TypeDoc 文档各自承担什么。API 行为仍以最终发布的 0.1.1 为准。

注释还是测试,但生成器换一套

新版继续保留 @example 作为测试来源,但不再依赖 TypeDoc 的旧内部结构,而是用 TypeScript compiler API 读取源码前导 JSDoc。

生成器现在支持三种输入:

  • 表达式 // 期望值 或 表达式 // => 期望值:转成 expect(表达式).toEqual(期望值)。
  • 表达式 // throws ErrorName:转成 expect(() => 表达式).toThrow(ErrorName),适合说明不合理参数会报错。
  • 直接包含 expect(...) 的代码块:保留成兜底能力,用于少数确实需要放进文档的异常或复杂 setup。

源码里的 @example 默认仍然保持普通示例。如果异常是公开行为,就用 // throws RangeError 这种读者能直接理解的写法;类型推导、循环引用这类测试细节继续放在 tests/ 里。

核心解析大概是这样:

export function parseAssertionLine(line: string): ExampleAssertion | undefined {
  const normalizedLine = line.replace(/^\s*\*\s?/, '');
  const matched = /^(?<expression>.+?)\s{2,}\/\/(?:\s*=>)?\s*(?<expected>.+?)\s*$/.exec(normalizedLine);

  if (!matched?.groups) {
    return undefined;
  }

  const expression = matched.groups.expression.trim().replace(/;$/, '');
  const expected = matched.groups.expected.trim();
  const throwAssertion = parseThrowAssertion(expression, expected);

  if (throwAssertion) {
    return throwAssertion;
  }

  if (!expression || !isExpectedExpression(expected)) {
    return undefined;
  }

  return {
    kind: 'equal',
    expression,
    expected,
  };
}

无法解析的 @example 不会被悄悄忽略,而是写进 tests/generated/examples.report.json 并让生成命令失败。浏览器模块依然跳过自动生成,因为 DOM、剪贴板和视口判断更适合放在 tests/browser 的 happy-dom 用例里;但跳过原因也会写进 report。

当前 report 大概长这样:

{
  "generated": {
    "cases": 92,
    "assertions": 225,
    "executableBlocks": 0
  },
  "unparsed": []
}

生成结果放在 tests/generated/examples.test.ts,并加了提示:

// @ts-nocheck
// 这个文件由 scripts/generate-example-tests.ts 生成,不要手写修改。

这里选择 @ts-nocheck 是有意的。注释里的例子首先用于说明并验证运行行为,类型边界另写类型测试。若要求每个文档示例同时承担类型测试,就可能为了构造非法输入、标记预期错误而打断原本的用法说明。

同一份注释,分别生成文档与运行时示例测试

生成测试之外,运行环境、类型推导和循环引用等边界仍需手写用例;修复要保持函数原有的边界语义。完整内容见生成测试之外的手写用例弹窗。

注释也要写成公共契约

把 @example 接进测试以后,注释就不再只是 README 的素材了。它至少有三层身份:

  • 给人看的 API 文档。
  • 给 TypeDoc 生成站点的结构化输入。
  • 给 generate-example-tests 提取运行时示例的测试来源。

这也意味着注释不能只写「函数做什么」。迁移后我又补了一轮 TSDoc,把已经由测试固定下来的边界写进公开文档。

第一类是导出的类型。PositiveInteger、ValidationMode、CamelCaseObject 这些类型会出现在 TypeDoc 里,读者会把它们当成公开 API 阅读。比如 PositiveInteger 需要明确说明它只能拦住数字字面量:

/**
 * 正整数字面量类型。
 *
 * 常见数字字面量中的 `0`、负数和带小数点的值会被收窄为 `never`;普通 `number` 仍然会保留为 `number`,
 * 因为 TypeScript 无法在静态阶段证明运行时数字一定是正整数。
 */
export type PositiveInteger<N extends number> = number extends N
  ? N
  : `${N}` extends '0' | `-${string}` | `${string}.${string}`
    ? never
    : N;

这样读者不会误以为有了类型就能删掉运行时边界。everyNth 自己也要写清楚:类型只能拦住数字字面量,动态非法值会返回空数组;这属于公开行为,不是测试里的偶然细节。

第二类是模式参数。ValidationMode 如果只在每个函数里零散解释,读者很难知道这是不是统一设计。现在它在类型定义上先给总口径:loose 是默认模式,偏向业务表单里的实用形态判断;strict 才在形态之外增加更强约束,例如 URL parser、银行卡 Luhn、身份证校验码和 Base64 payload。

第三类是对象转换和浏览器 API 的运行时边界:

  • camelCaseObject 这类 key 转换函数只递归普通对象和数组,Date、RegExp、Map、Set、函数等内建对象保持原引用。
  • replaceValueFromObject 会克隆普通对象 / 数组、保留循环引用关系,不修改输入对象。
  • copyHTML 依赖 navigator.clipboard.write 和 ClipboardItem,不支持时会 reject,而且不能像纯文本复制那样用 textarea 兜底。

凡是会影响调用方接入、失败处理、类型使用、输入对象是否被修改或运行环境兼容性的行为,都应该进入 TSDoc。单测负责证明这些行为没有退化,注释负责让读者在写代码前就知道这些行为存在。

这类注释会进入声明文件,也会让 npm tarball 稍微变大。这里我选择接受这点体积增长,因为 sheng-tool 本来就是给人直接 import 的工具库;调用方在编辑器里 hover 到 API 时能看到边界,比少几 KB 更重要。

TypeDoc 继续生成文档,GitHub Pages 负责分发;生成的 docs 与测试文件不作为源码或 npm 包内容提交。完整内容见文档部署与路径配置弹窗。

TypeScript 没有追最新

这次把 TypeScript 锁到 ~6.0.3。当时安装的 TypeDoc 版本声明支持 5.x || 6.0.x,没有覆盖 TS 7;这是这轮迁移的版本组合,不是长期升级上限。

版本选择要受整条工具链的兼容范围约束。这里按 TypeDoc 等依赖的支持范围选择能共同工作的最高版本,再用 pnpm peers check 确认没有 peer dependency 问题,将这组版本固定下来。

pnpm-workspace.yaml 里还记录了 pnpm 对构建脚本的允许项:

allowBuilds:
  esbuild: true

这是因为开发脚本里的 tsx 会用到 esbuild,pnpm 新版会对 install scripts 更谨慎。为了避免每台机器安装时弹交互,最好在仓库里明确记录。

总结

原有「注释即测试」的设计得以保留,生成器改用 TypeScript compiler API,无法解析的示例会报告并失败;手写测试补充类型、浏览器环境、循环引用和边界语义。公开注释说明默认模式、非法输入、输入对象是否被修改及运行环境要求,TypeDoc 将这些契约生成文档,再由 GitHub Pages 分发。示例测试与类型测试分别承担自己的验证职责,读者看到的用法和边界也有了对应的检查依据。

上一篇:依赖、API 与发布边界的迁移。

生成测试之外的手写用例

手写测试补生成器管不到的地方

生成测试现在能覆盖大多数短示例,但运行时环境、类型推导和复杂对象引用关系仍然更适合手写测试。改造时我又补了几组用例:

  • replaceValueFromObject:确保替换不会把不匹配的 primitive 误删,也能按 predicate 转换嵌套值。
  • replaceEmptyValueFromObject:确认只有存在默认值的 key 才会替换空值。
  • camelCaseObject:确认循环引用不会爆栈,并且转换后的引用关系仍然闭合。
  • camelCaseObject / pascalCaseObject / snakeCaseObject:用 expectTypeOf 和 @ts-expect-error 确认 key 转换类型是真的。
  • everyNth:确认数字字面量里的 0 和小数会被类型拦住,动态传入的 0、负数、小数、NaN、Infinity 和非数字值都会返回空数组。
  • format-validation:覆盖宽松 / 严格模式下 URL、Base64、MAC、身份证、银行卡等差异。
  • generate-example-tests:确认简单断言、可执行 expect 代码块、显式跳过和无法解析的 report 都能工作。
  • toFiniteNumber:确认千分位字符串、空字符串、Infinity 和 fallback 行为。
  • date / string / extra:补 getWeeksInMonth 的日历行数分支、SQL 模板转义分支、URL pattern 分支和中文数字递归补零。
  • 浏览器函数:用 happy-dom 跑 getQueryString、getFullUrl、动态 script 注入、滚动锁定、复制、等待、轮询和 viewport 判断。
  • 浏览器类型判断:通过替换 UA 覆盖微信、小程序、移动端、桌面端、QQ 浏览器、爬虫、iOS 和 Android。

这次迁移里,测试确实暴露了旧实现的小问题。比如 replaceValueFromObject 原本递归到 primitive 时,如果没有命中替换条件,可能返回 undefined。这个在示例测试和手写测试一起跑时很容易看出来。

修完后还顺手加上了循环引用保护。核心结构是:先判断当前值是否需要替换,再用 WeakMap 记录已经克隆过的对象 / 数组,遇到回环时复用克隆对象。

export const replaceValueFromObject = (obj: any, from: any, to: any, autoExecuteFunction = true): any => {
  const shouldReplace = (value: any) => (autoExecuteFunction && isFunction(from) ? from(value) : isEqual(value, from));
  const getReplacement = (value: any) => (autoExecuteFunction && isFunction(to) ? to(value) : to);
  const visit = (value: any, seen: WeakMap<object, any>): any => {
    if (shouldReplace(value)) {
      return getReplacement(value);
    }

    if (Array.isArray(value)) {
      if (seen.has(value)) {
        return seen.get(value);
      }

      const result: any[] = [];
      seen.set(value, result);

      for (const item of value) {
        result.push(visit(item, seen));
      }

      return result;
    }

    if (!isPlainObject(value)) {
      return value;
    }

    if (seen.has(value)) {
      return seen.get(value);
    }

    const result: Record<string, unknown> = {};
    seen.set(value, result);

    for (const [key, nestedValue] of Object.entries(value)) {
      result[key] = visit(nestedValue, seen);
    }

    return result;
  };

  return visit(obj, new WeakMap());
};
文档部署与路径配置

文档改到 GitHub Pages

TypeDoc 继续生成 HTML 文档,GitHub Pages 负责分发,docs/ 不再随 npm 包发布。

配置也收敛成普通 typedoc.json:

{
  "$schema": "https://typedoc.org/schema.json",
  "entryPoints": ["src/index.ts"],
  "out": "docs",
  "readme": "readme.md",
  "excludeInternal": true,
  "excludePrivate": true,
  "navigationLinks": {
    "GitHub": "https://github.com/dev-itsheng/sheng-tool"
  }
}

CI 里分两条线:

  • CI:安装依赖、类型检查、测试、构建、package smoke、publint、npm pack --dry-run。
  • Docs:安装依赖、pnpm run docs:build、上传 Pages artifact、部署 GitHub Pages。

本地 .gitignore 加了 docs/ 和 tests/generated/。这两个目录都应该可再生成,不应该让人 review HTML、搜索索引和生成测试文件。

迁移中 TypeDoc 还帮忙抓了一个小拼写:src/string.ts 里有一处写成了 @params str,新版会提示 unknown block tag。这个错误不影响运行时,但会污染文档结构;既然文档也进 CI,就顺手修掉。