工具函数（纯函数）测试计划

概述

覆盖 src/utils/ 下所有可独立单元测试的纯函数。这些函数无外部依赖，输入输出确定性强，是测试金字塔的底层基石。

被测文件

文件	状态	关键导出
`src/utils/array.ts`	已有测试	intersperse, count, uniq
`src/utils/set.ts`	已有测试	difference, intersects, every, union
`src/utils/xml.ts`	待测	escapeXml, escapeXmlAttr
`src/utils/hash.ts`	待测	djb2Hash, hashContent, hashPair
`src/utils/stringUtils.ts`	待测	escapeRegExp, capitalize, plural, firstLineOf, countCharInString, normalizeFullWidthDigits, normalizeFullWidthSpace, safeJoinLines, truncateToLines, EndTruncatingAccumulator
`src/utils/semver.ts`	待测	gt, gte, lt, lte, satisfies, order
`src/utils/uuid.ts`	待测	validateUuid, createAgentId
`src/utils/format.ts`	待测	formatFileSize, formatSecondsShort, formatDuration, formatNumber, formatTokens, formatRelativeTime, formatRelativeTimeAgo
`src/utils/json.ts`	待测	safeParseJSON, safeParseJSONC, parseJSONL, addItemToJSONCArray
`src/utils/truncate.ts`	待测	truncatePathMiddle, truncateToWidth, truncateStartToWidth, truncateToWidthNoEllipsis, truncate, wrapText
`src/utils/diff.ts`	待测	adjustHunkLineNumbers, getPatchFromContents
`src/utils/frontmatterParser.ts`	待测	parseFrontmatter, splitPathInFrontmatter, parsePositiveIntFromFrontmatter, parseBooleanFrontmatter, parseShellFrontmatter
`src/utils/file.ts`	待测（纯函数部分）	convertLeadingTabsToSpaces, addLineNumbers, stripLineNumberPrefix, pathsEqual, normalizePathForComparison
`src/utils/glob.ts`	待测（纯函数部分）	extractGlobBaseDirectory
`src/utils/tokens.ts`	待测	getTokenCountFromUsage
`src/utils/path.ts`	待测（纯函数部分）	containsPathTraversal, normalizePathForConfigKey

测试用例

src/utils/xml.ts — 测试文件: `src/utils/tests/xml.test.ts`

describe('escapeXml')

test('escapes ampersand') — & → &
test('escapes less-than') — < → <
test('escapes greater-than') — > → >
test('does not escape quotes') — " 和 ' 保持原样
test('handles empty string') — "" → ""
test('handles string with no special chars') — "hello" 原样返回
test('escapes multiple special chars in one string') — <a & b> → <a & b>

describe('escapeXmlAttr')

test('escapes all xml chars plus quotes') — " → ", ' → '
test('escapes double quotes') — he said "hi" 正确转义
test('escapes single quotes') — it's 正确转义

src/utils/hash.ts — 测试文件: `src/utils/tests/hash.test.ts`

describe('djb2Hash')

test('returns consistent hash for same input') — 相同输入返回相同结果
test('returns different hashes for different inputs') — 不同输入大概率不同
test('returns a 32-bit integer') — 结果在 int32 范围内
test('handles empty string') — 空字符串有确定的哈希值
test('handles unicode strings') — 中文/emoji 等正确处理

describe('hashContent')

test('returns consistent hash for same content') — 确定性
test('returns string result') — 返回值为字符串

describe('hashPair')

test('returns consistent hash for same pair') — 确定性
test('order matters') — hashPair(a, b) ≠ hashPair(b, a)
test('handles empty strings')

src/utils/stringUtils.ts — 测试文件: `src/utils/tests/stringUtils.test.ts`

describe('escapeRegExp')

test('escapes dots') — . → \\.
test('escapes asterisks') — * → \\*
test('escapes brackets') — [ → \\[
test('escapes all special chars') — .*+?^${}()|[]\ 全部转义
test('leaves normal chars unchanged') — hello 原样
test('escaped string works in RegExp') — new RegExp(escapeRegExp('a.b')) 精确匹配 a.b

describe('capitalize')

test('uppercases first char') — "foo" → "Foo"
test('does NOT lowercase rest') — "fooBar" → "FooBar"（区别于 lodash capitalize）
test('handles single char') — "a" → "A"
test('handles empty string') — "" → ""
test('handles already capitalized') — "Foo" → "Foo"

describe('plural')

test('returns singular for n=1') — plural(1, 'file') → 'file'
test('returns plural for n=0') — plural(0, 'file') → 'files'
test('returns plural for n>1') — plural(3, 'file') → 'files'
test('uses custom plural form') — plural(2, 'entry', 'entries') → 'entries'

describe('firstLineOf')

test('returns first line of multi-line string') — "a\nb\nc" → "a"
test('returns full string when no newline') — "hello" → "hello"
test('handles empty string') — "" → ""
test('handles string starting with newline') — "\nhello" → ""

describe('countCharInString')

test('counts occurrences') — countCharInString("aabac", "a") → 3
test('returns 0 when char not found') — countCharInString("hello", "x") → 0
test('handles empty string') — countCharInString("", "a") → 0
test('respects start position') — countCharInString("aaba", "a", 2) → 1

describe('normalizeFullWidthDigits')

test('converts full-width digits to half-width') — "０１２３" → "0123"
test('leaves half-width digits unchanged') — "0123" → "0123"
test('mixed content') — "port ８０８０" → "port 8080"

describe('normalizeFullWidthSpace')

test('converts ideographic space to regular space') — "\u3000" → " "
test('converts multiple spaces') — "a\u3000b\u3000c" → "a b c"

describe('safeJoinLines')

test('joins lines with default delimiter') — ["a","b"] → "a,b"
test('truncates when exceeding maxSize') — 超限时截断并添加 ...[truncated]
test('handles empty array') — [] → ""
test('uses custom delimiter') — delimiter 为 "\n" 时按行连接

describe('truncateToLines')

test('returns full text when within limit') — 行数不超限时原样返回
test('truncates and adds ellipsis') — 超限时截断并加 …
test('handles exact limit') — 刚好等于 maxLines 时不截断
test('handles single line') — 单行文本不截断

describe('EndTruncatingAccumulator')

test('accumulates strings normally within limit')
test('truncates when exceeding maxSize')
test('reports truncated status correctly')
test('reports totalBytes including truncated content')
test('toString includes truncation marker')
test('clear resets all state')
test('append with Buffer works') — 接受 Buffer 类型

src/utils/semver.ts — 测试文件: `src/utils/tests/semver.test.ts`

describe('gt / gte / lt / lte')

test('gt: 2.0.0 > 1.0.0') → true
test('gt: 1.0.0 > 1.0.0') → false
test('gte: 1.0.0 >= 1.0.0') → true
test('lt: 1.0.0 < 2.0.0') → true
test('lte: 1.0.0 <= 1.0.0') → true
test('handles pre-release versions') — 1.0.0-beta < 1.0.0

describe('satisfies')

test('version satisfies caret range') — satisfies('1.2.3', '^1.0.0') → true
test('version does not satisfy range') — satisfies('2.0.0', '^1.0.0') → false
test('exact match') — satisfies('1.0.0', '1.0.0') → true

describe('order')

test('returns -1 for lesser') — order('1.0.0', '2.0.0') → -1
test('returns 0 for equal') — order('1.0.0', '1.0.0') → 0
test('returns 1 for greater') — order('2.0.0', '1.0.0') → 1

src/utils/uuid.ts — 测试文件: `src/utils/tests/uuid.test.ts`

describe('validateUuid')

test('accepts valid v4 UUID') — '550e8400-e29b-41d4-a716-446655440000' → 返回 UUID
test('returns null for invalid format') — 'not-a-uuid' → null
test('returns null for empty string') — '' → null
test('returns null for null/undefined input')
test('accepts uppercase UUIDs') — 大写字母有效

describe('createAgentId')

test('returns string starting with "a"') — 前缀为 a
test('has correct length') — 前缀 + 16 hex 字符
test('generates unique ids') — 连续两次调用结果不同

src/utils/format.ts — 测试文件: `src/utils/tests/format.test.ts`

describe('formatFileSize')

test('formats bytes') — 500 → "500 bytes"
test('formats kilobytes') — 1536 → "1.5KB"
test('formats megabytes') — 1572864 → "1.5MB"
test('formats gigabytes') — 1610612736 → "1.5GB"
test('removes trailing .0') — 1024 → "1KB" (不是 "1.0KB")

describe('formatSecondsShort')

test('formats milliseconds to seconds') — 1234 → "1.2s"
test('formats zero') — 0 → "0.0s"

describe('formatDuration')

test('formats seconds') — 5000 → "5s"
test('formats minutes and seconds') — 65000 → "1m 5s"
test('formats hours') — 3661000 → "1h 1m 1s"
test('formats days') — 90061000 → "1d 1h 1m"
test('returns "0s" for zero') — 0 → "0s"
test('hideTrailingZeros omits zero components') — 3600000 + hideTrailingZeros → "1h"
test('mostSignificantOnly returns largest unit') — 3661000 + mostSignificantOnly → "1h"

describe('formatNumber')

test('formats thousands') — 1321 → "1.3k"
test('formats small numbers as-is') — 900 → "900"
test('lowercase output') — 1500 → "1.5k" (不是 "1.5K")

describe('formatTokens')

test('strips .0 suffix') — 1000 → "1k" (不是 "1.0k")
test('keeps non-zero decimal') — 1500 → "1.5k"

describe('formatRelativeTime')

test('formats past time') — now - 3600s → "1h ago" (narrow style)
test('formats future time') — now + 3600s → "in 1h" (narrow style)
test('formats less than 1 second') — now → "0s ago"
test('uses custom now parameter for deterministic output')

src/utils/json.ts — 测试文件: `src/utils/tests/json.test.ts`

describe('safeParseJSON')

test('parses valid JSON') — '{"a":1}' → { a: 1 }
test('returns null for invalid JSON') — 'not json' → null
test('returns null for null input') — null → null
test('returns null for undefined input') — undefined → null
test('returns null for empty string') — "" → null
test('handles JSON with BOM') — BOM 前缀不影响解析
test('caches results for repeated calls') — 同一输入不重复解析

describe('safeParseJSONC')

test('parses JSON with comments') — 含 // 注释的 JSON 正确解析
test('parses JSON with trailing commas') — 宽松模式
test('returns null for invalid input')
test('returns null for null input')

describe('parseJSONL')

test('parses multiple JSON lines') — '{"a":1}\n{"b":2}' → [{a:1}, {b:2}]
test('skips malformed lines') — 含错误行时跳过该行
test('handles empty input') — "" → []
test('handles trailing newline') — 尾部换行不产生空元素
test('accepts Buffer input') — Buffer 类型同样工作
test('handles BOM prefix')

describe('addItemToJSONCArray')

test('adds item to existing array') — [1, 2] + 3 → [1, 2, 3]
test('creates new array for empty content') — "" + item → [item]
test('creates new array for non-array content') — '"hello"' + item → [item]
test('preserves comments in JSONC') — 注释不被丢弃
test('handles empty array') — "[]" + item → [item]

src/utils/diff.ts — 测试文件: `src/utils/tests/diff.test.ts`

describe('adjustHunkLineNumbers')

test('shifts line numbers by positive offset') — 所有 hunk 的 oldStart/newStart 增加 offset
test('shifts by negative offset') — 负 offset 减少行号
test('handles empty hunk array') — [] → []

describe('getPatchFromContents')

test('returns empty array for identical content') — 相同内容无差异
test('detects added lines') — 新内容多出行
test('detects removed lines') — 旧内容缺少行
test('detects modified lines') — 行内容变化
test('handles empty old content') — 从空文件到有内容
test('handles empty new content') — 删除所有内容

src/utils/frontmatterParser.ts — 测试文件: `src/utils/tests/frontmatterParser.test.ts`

describe('parseFrontmatter')

test('extracts YAML frontmatter between --- delimiters') — 正确提取 frontmatter 并返回 body
test('returns empty frontmatter for content without ---') — 无 frontmatter 时 data 为空
test('handles empty content') — "" 正确处理
test('handles frontmatter-only content') — 只有 frontmatter 无 body
test('falls back to quoting on YAML parse error') — 无效 YAML 不崩溃

describe('splitPathInFrontmatter')

test('splits comma-separated paths') — "a.ts, b.ts" → ["a.ts", "b.ts"]
test('expands brace patterns') — "*.{ts,tsx}" → ["*.ts", "*.tsx"]
test('handles string array input') — ["a.ts", "b.ts"] → ["a.ts", "b.ts"]
test('respects braces in comma splitting') — 大括号内的逗号不作为分隔符

describe('parsePositiveIntFromFrontmatter')

test('returns number for valid positive int') — 5 → 5
test('returns undefined for negative') — -1 → undefined
test('returns undefined for non-number') — "abc" → undefined
test('returns undefined for float') — 1.5 → undefined

describe('parseBooleanFrontmatter')

test('returns true for true') — true → true
test('returns true for "true"') — "true" → true
test('returns false for false') — false → false
test('returns false for other values') — "yes", 1 → false

describe('parseShellFrontmatter')

test('returns bash for "bash"') — 正确识别
test('returns powershell for "powershell"')
test('returns undefined for invalid value') — "zsh" → undefined

src/utils/file.ts（纯函数部分）— 测试文件: `src/utils/tests/file.test.ts`

describe('convertLeadingTabsToSpaces')

test('converts single tab to 2 spaces') — "\thello" → " hello"
test('converts multiple leading tabs') — "\t\thello" → " hello"
test('does not convert tabs within line') — "a\tb" 保持原样
test('handles mixed content')

describe('addLineNumbers')

test('adds line numbers starting from 1') — 每行添加 N\t 前缀
test('respects startLine parameter') — 从指定行号开始
test('handles empty content')

describe('stripLineNumberPrefix')

test('strips tab-prefixed line number') — "1\thello" → "hello"
test('strips padded line number') — " 1\thello" → "hello"
test('returns line unchanged when no prefix')

describe('pathsEqual')

test('returns true for identical paths')
test('handles trailing slashes') — 带/不带尾部斜杠视为相同
test('handles case sensitivity based on platform')

describe('normalizePathForComparison')

test('normalizes forward slashes')
test('resolves path for comparison')

src/utils/glob.ts（纯函数部分）— 测试文件: `src/utils/tests/glob.test.ts`

describe('extractGlobBaseDirectory')

test('extracts static prefix from glob') — "src/**/*.ts" → { baseDir: "src", relativePattern: "**/*.ts" }
test('handles root-level glob') — "*.ts" → { baseDir: ".", relativePattern: "*.ts" }
test('handles deep static path') — "src/utils/model/*.ts" → baseDir 为 "src/utils/model"
test('handles Windows drive root') — "C:\\Users\\**\\*.ts" 正确分割

src/utils/tokens.ts（纯函数部分）— 测试文件: `src/utils/tests/tokens.test.ts`

describe('getTokenCountFromUsage')

test('sums input and output tokens') — { input_tokens: 100, output_tokens: 50 } → 150
test('includes cache tokens') — cache_creation + cache_read 加入总数
test('handles zero values') — 全 0 时返回 0

src/utils/path.ts（纯函数部分）— 测试文件: `src/utils/tests/path.test.ts`

describe('containsPathTraversal')

test('detects ../ traversal') — "../etc/passwd" → true
test('detects mid-path traversal') — "foo/../../bar" → true
test('returns false for safe paths') — "src/utils/file.ts" → false
test('returns false for paths containing .. in names') — "foo..bar" → false

describe('normalizePathForConfigKey')

test('converts backslashes to forward slashes') — "src\\utils" → "src/utils"
test('leaves forward slashes unchanged')

Mock 需求

本计划中的函数大部分为纯函数，不需要 mock。少数例外：

函数	依赖	处理
`hashContent` / `hashPair`	`Bun.hash`	Bun 运行时下自动可用
`formatRelativeTime`	`Date`	使用 `now` 参数注入确定性时间
`safeParseJSON`	`logError`	可通过 `shouldLogError: false` 跳过
`safeParseJSONC`	`logError`	mock `logError` 避免测试输出噪音