@veren/utils AI Memo

这个包是一组无副作用、零依赖的小工具，主要给 monorepo 内部复用。 如果你是 AI/Agent，在修改或调用它之前，先按下面的约定理解，不要把它当成 Node path、Lodash 或更重型的 runtime 抽象层。

Public API

从 src/index.ts 导出的能力分为 5 类：

1. string helpers
   • capitalize
   • isFalsyOrWhitespace
   • compareIgnoreCase
   • equalsIgnoreCase
   • toCamelCase
   • toKebabCase
2. path helpers
   • normalizePath
   • joinPath
   • dirname
   • basename
   • extname
3. symbol helpers
   • createSymbol
   • createGlobalSymbol
   • getSymbolDescription
   • toSymbolKey
4. runtime helpers
   • detectPlatform
   • detectOS
   • isWindows
   • isMacOS
   • isLinux
5. guards + utility types
   • isFunction
   • isObject
   • isString
   • isNumber
   • isBoolean
   • isSymbol
   • Mutable<T>
   • DeepPartial<T>
   • NonNullableFields<T>

Behavior Notes

String helpers

• capitalize 只处理首字符，不会主动 trim，也不会处理整个单词序列。
• isFalsyOrWhitespace 对 ''、null、undefined、只含空白字符的字符串都返回 true。
• compareIgnoreCase / equalsIgnoreCase 基于 toLocaleLowerCase()，用于宽松大小写比较，不是自然排序器。
• toCamelCase / toKebabCase 会先拆分空格、下划线、连字符，并把 fooBar 这种 lowerCamelCase 拆成两个词。
• HTTPRequest 这种全大写缩写不会被智能拆成 http-request，当前实现更接近保守字符串归一化，而不是 NLP 式分词。

Path helpers

• 统一使用 / 作为分隔符，即使输入里有 Windows \。
• normalizePath 只做轻量字符串归一化：
  • 处理重复分隔符、.、..
  • 不访问文件系统
  • 不保留尾随 /
• 空字符串会被归一化成 .。
• 相对路径里的多余 .. 会被保留；绝对路径超出根目录的 .. 会被吞掉。
• extname('.gitignore') === ''，行为与常见 path 实现一致。

Symbol helpers

• createSymbol 返回局部 symbol，每次调用都不同。
• createGlobalSymbol 等价于 Symbol.for(key)。
• toSymbolKey 会把 string 或带 toString() 的对象转成全局 symbol。
• src/symbolRegistry.ts 里还有 SymbolMap，目前不是 public API，但可作为内部工具使用。它会把字符串 key 归一化成全局 symbol，因此 "x" 和 Symbol.for('x') 指向同一项。

Runtime helpers

• detectPlatform 只区分 browser、electron、node。
• 判断 Electron 的依据是 window.document 存在且 window.electron 为 truthy。
• detectOS 只识别 win32 / darwin / linux，其他平台一律返回 unknown。
• isWindows / isMacOS / isLinux 在模块加载时就计算一次，反映的是当前运行环境，不会随着 mock 自动刷新。

Guards and types

• 这些 guard 都是极薄封装，只做 typeof / null 检查。
• isNumber(NaN) 会返回 true，因为它本质上仍然是 number。
• DeepPartial<T> 对 object 递归可选化；对非 object 原样返回。

Testing Notes

• 测试文件在 tests/index.test.ts。
• 当前测试覆盖了字符串、路径、symbol、runtime、guard 的主要行为和边界。
• 若新增 public API，优先补这里的行为测试；不要再放模板残留测试。

Maintenance Rules For AI

• 优先保持函数纯度和零依赖。
• 除非明确需要，不要引入 Node 内置 path 来改变这里的跨平台字符串行为。
• 如果要调整 toCamelCase / toKebabCase 的缩写处理，先补测试，再确认是否会影响已有调用方。
• 如果要公开 SymbolMap，记得同步修改 src/index.ts、测试和这份 memo。