补齐测试框架 JSDoc 并应用 eslint 自动修复

steve02081504 · steve02081504 · commit a009838e24f5 · 2026-07-08T12:51:31.000+08:00
diff --git a/src/public/parts/shells/chat/src/chat/lib/utils.mjs b/src/public/parts/shells/chat/src/chat/lib/utils.mjs
@@ -100,7 +100,7 @@ export async function safeRm(path, options) {
 		}
 		catch (e) {
 			if (isEnoent(e)) return
-			lastError = /** @type {NodeJS.ErrnoException} */ (e)
+			lastError = /** @type {NodeJS.ErrnoException} */ e
 			if (!RM_TRANSIENT_CODES.has(lastError.code)) throw lastError
 		}
 	}
diff --git a/src/public/parts/shells/social/src/endpoints/posts.mjs b/src/public/parts/shells/social/src/endpoints/posts.mjs
@@ -40,7 +40,7 @@ export function registerPostsRoutes(router) {
 		const draftContent = {
 			text: String(req.body.text),
 			mediaRefs: [
-				...(req.body.mediaRefs ?? []),
+				...req.body.mediaRefs ?? [],
 				...await buildEmojiMediaRefsForPost(username, String(req.body.text)),
 			],
 			replyTo: req.body.replyTo,
diff --git a/src/scripts/p2p/test/pure/link_handshake_reorder.test.mjs b/src/scripts/p2p/test/pure/link_handshake_reorder.test.mjs
@@ -49,13 +49,19 @@ class MockDataChannel {
 		this._listeners = new Map()
 	}
 
-	/** @param {string} type 事件名 @param {Function} handler 处理器 */
+	/**
+	 * @param {string} type 事件名
+	 * @param {Function} handler 处理器
+	 */
 	addEventListener(type, handler) {
 		if (!this._listeners.has(type)) this._listeners.set(type, new Set())
 		this._listeners.get(type).add(handler)
 	}
 
-	/** @param {string} type 事件名 @param {Function} handler 处理器 */
+	/**
+	 * @param {string} type 事件名
+	 * @param {Function} handler 处理器
+	 */
 	removeEventListener(type, handler) {
 		this._listeners.get(type)?.delete(handler)
 	}
@@ -65,6 +71,7 @@ class MockDataChannel {
 		this.sent.push(typeof data === 'string' ? data : Buffer.from(data).toString('utf8'))
 	}
 
+	/** 关闭通道。 */
 	close() {
 		this.readyState = 'closed'
 	}
@@ -77,11 +84,14 @@ class MockDataChannel {
 
 /**
  * answerer 侧最小 RTCPeerConnection mock：收到 offer 后就绪双通道，答复 answer。
+ * @returns {{ RTCPeerConnection: typeof MockPC, getInstance: () => MockPC | null }} rtc 工厂与实例取回器
  */
 function createAnswererRtc() {
 	/** @type {MockPC | null} */
 	let instance = null
+	/** 最小 RTCPeerConnection mock。 */
 	class MockPC {
+		/** 初始化为已连接的稳定状态。 */
 		constructor() {
 			this.localDescription = null
 			this.remoteDescription = null
@@ -121,10 +131,16 @@ function createAnswererRtc() {
 			else this.signalingState = 'stable'
 		}
 
-		async addIceCandidate() { /* trickle 关闭时不经此路径 */ }
+		/** trickle 关闭时不经此路径。 */
+		async addIceCandidate() { }
+		/** 标记连接关闭。 */
 		async close() { this.connectionState = 'closed' }
 	}
-	return { RTCPeerConnection: MockPC, getInstance: () => instance }
+	return {
+		RTCPeerConnection: MockPC,
+		/** @returns {MockPC | null} 最近创建的 mock 实例 */
+		getInstance: () => instance,
+	}
 }
 
 Deno.test({
@@ -145,7 +161,10 @@ Deno.test({
 		const signal = {
 			/** @param {unknown} _message 出站信令（answer/ice，测试中忽略） */
 			send(_message) {},
-			/** @param {(message: unknown) => void} handler 入站信令处理器 @returns {() => void} */
+			/**
+			 * @param {(message: unknown) => void} handler 入站信令处理器
+			 * @returns {() => void} 取消订阅
+			 */
 			onRemote(handler) { signalHandler = handler; return () => { signalHandler = null } },
 		}
 
diff --git a/src/scripts/test/core/baseline.mjs b/src/scripts/test/core/baseline.mjs
@@ -32,7 +32,7 @@ export function nextBaselineEma(current, sample, emaN, opts = {}) {
 /**
  * @param {number | null | undefined} current 当前基线 ms
  * @param {number | null | undefined} durationMs 本次耗时
- * @returns {number | null}
+ * @returns {number | null} 新基线 ms
  */
 export function nextBaselineDurationMs(current, durationMs) {
 	return nextBaselineEma(current, durationMs, BASELINE_EMA_DURATION, { min: 0, allowZero: false })
@@ -41,7 +41,7 @@ export function nextBaselineDurationMs(current, durationMs) {
 /**
  * @param {number | null | undefined} current 当前基线 MB
  * @param {number | null | undefined} measuredMb 本次峰值 MB
- * @returns {number | null}
+ * @returns {number | null} 新基线 MB
  */
 export function nextBaselineMemMb(current, measuredMb) {
 	const sample = measuredMb == null ? null : Math.ceil(measuredMb)
@@ -51,7 +51,7 @@ export function nextBaselineMemMb(current, measuredMb) {
 /**
  * @param {number | null | undefined} current 当前基线 %
  * @param {number | null | undefined} avgCpuPct 本次运行期间平均全机 CPU %
- * @returns {number | null}
+ * @returns {number | null} 新基线 %
  */
 export function nextBaselineCpuPct(current, avgCpuPct) {
 	const sample = avgCpuPct == null ? null : Math.round(avgCpuPct * 10) / 10
diff --git a/src/scripts/test/core/deps.mjs b/src/scripts/test/core/deps.mjs
@@ -159,7 +159,7 @@ function topoSortKeys(keys, deps, compareTieBreak) {
  * @param {string} b 键
  * @param {Map<string, number>} dependentCount 被依赖计数
  * @param {Map<string, number>} depCount 依赖计数
- * @returns {number}
+ * @returns {number} 排序比较值（<0 表示 a 在前）
  */
 function compareTopoTieBreak(a, b, dependentCount, depCount) {
 	const depByA = dependentCount.get(a) ?? 0
@@ -178,7 +178,7 @@ function compareTopoTieBreak(a, b, dependentCount, depCount) {
 /**
  * 全库 suite 依赖计数（tie-break 用）。
  * @param {SuiteDef[]} allSuites 全部 suite
- * @returns {{ depCount: Map<string, number>, dependentCount: Map<string, number> }}
+ * @returns {{ depCount: Map<string, number>, dependentCount: Map<string, number> }} 各 suite 的依赖数与被依赖数
  */
 function buildSuiteMetrics(allSuites) {
 	/** @type {Map<string, number>} */
@@ -208,7 +208,7 @@ function buildSuiteMetrics(allSuites) {
 /**
  * suite 直接依赖边（越界边由 topoSortKeys 内部按 keySet 过滤）。
  * @param {SuiteDef[]} suites 待排序 suite
- * @returns {Map<string, Set<string>>}
+ * @returns {Map<string, Set<string>>} suite 键 → 直接依赖键集合
  */
 function buildSuiteDeps(suites) {
 	return new Map(suites.map(suite => [
@@ -241,7 +241,7 @@ export function topoSortSuites(suites, allSuites = suites) {
 /**
  * 从 suite 依赖构建 manifest 级图（同 manifest 内边忽略）。
  * @param {SuiteDef[]} suites 全部 suite
- * @returns {{ depCount: Map<string, number>, dependentCount: Map<string, number>, deps: Map<string, Set<string>> }}
+ * @returns {{ depCount: Map<string, number>, dependentCount: Map<string, number>, deps: Map<string, Set<string>> }} manifest 级依赖计数与边
  */
 function buildManifestGraph(suites) {
 	const ids = [...new Set(suites.map(s => s.manifestId))]
diff --git a/src/scripts/test/core/manifest.mjs b/src/scripts/test/core/manifest.mjs
@@ -6,8 +6,8 @@ import { join, relative } from 'node:path'
 
 import { attachDependencies, sortManifestIds } from './deps.mjs'
 import { matchGlob } from './glob.mjs'
-import { filterTriggerRelevantFiles, mergeTriggerFilter } from './trigger_filter.mjs'
 import { parseManifestResources } from './resources.mjs'
+import { filterTriggerRelevantFiles, mergeTriggerFilter } from './trigger_filter.mjs'
 /**
  * manifest 中单个 suite 的解析结果。
  * @typedef {object} SuiteDef
diff --git a/src/scripts/test/core/proc_sample.mjs b/src/scripts/test/core/proc_sample.mjs
@@ -12,7 +12,8 @@ import { meanSample } from './baseline.mjs'
 let osUtilsModule = null
 
 /**
- * @returns {Promise<import('npm:node-os-utils').default>}
+ * 惰性加载并缓存 node-os-utils 实例。
+ * @returns {Promise<import('npm:node-os-utils').default>} OSUtils 单例
  */
 async function getOsUtils() {
 	if (!osUtilsModule) {
@@ -26,7 +27,7 @@ async function getOsUtils() {
 /**
  * @param {object[]} list node-os-utils ProcessInfo[]
  * @param {number} rootPid 根 PID
- * @returns {number[]}
+ * @returns {number[]} 根及其全部子孙 PID
  */
 export function treePidsFromProcessList(list, rootPid) {
 	/** @type {Map<number, number[]>} */
@@ -53,8 +54,9 @@ export function treePidsFromProcessList(list, rootPid) {
 }
 
 /**
+ * Windows 下经 PowerShell 枚举进程树 PID（回退路径）。
  * @param {number} rootPid 根 PID
- * @returns {Promise<number[]>}
+ * @returns {Promise<number[]>} 根及其全部子孙 PID
  */
 async function collectTreePidsWindows(rootPid) {
 	try {
@@ -138,7 +140,7 @@ export async function samplePidsUsage(pids) {
 /**
  * pidusage 多核 CPU% 压到调度语义 0–100。
  * @param {number} cpu pidusage 聚合 cpu
- * @returns {number}
+ * @returns {number} 归一化后的 0–100 CPU%
  */
 export function normalizePidusageCpuPct(cpu) {
 	const cores = Math.max(1, os.cpus().length)
@@ -174,7 +176,7 @@ export class ProcessUsageTracker {
 	}
 
 	/**
-	 * @returns {{ peakMemMb?: number, avgCpuPct?: number }}
+	 * @returns {{ peakMemMb?: number, avgCpuPct?: number }} 采样汇总（峰值内存 MB、平均 CPU%）
 	 */
 	finish() {
 		const peakMemMb = this.#memBytesSamples.length
diff --git a/src/scripts/test/core/resources.mjs b/src/scripts/test/core/resources.mjs
@@ -22,8 +22,8 @@ import { MiB } from './concurrency.mjs'
 export function parseManifestResources(raw) {
 	if (!raw || typeof raw !== 'object') return {}
 	return {
-		...(Number.isFinite(raw.memMb) && raw.memMb > 0 ? { memMb: Math.floor(raw.memMb) } : {}),
-		...(Number.isFinite(raw.cpuPct) && raw.cpuPct >= 0 ? { cpuPct: Math.min(100, raw.cpuPct) } : {}),
+		...Number.isFinite(raw.memMb) && raw.memMb > 0 ? { memMb: Math.floor(raw.memMb) } : {},
+		...Number.isFinite(raw.cpuPct) && raw.cpuPct >= 0 ? { cpuPct: Math.min(100, raw.cpuPct) } : {},
 	}
 }
 
@@ -95,7 +95,7 @@ export function suiteSchedulePriority(suite, entry) {
 /**
  * suite 是否通过 serial.mjs 在内部并行跑多文件（应下放 CPU/内存预算）。
  * @param {SuiteDef} suite suite
- * @returns {boolean}
+ * @returns {boolean} 是否经 serial.mjs 内部并行多文件
  */
 export function suiteUsesSerialRunner(suite) {
 	return suite.run.some(arg => String(arg).includes('serial.mjs'))
diff --git a/src/scripts/test/core/trigger_filter.mjs b/src/scripts/test/core/trigger_filter.mjs
@@ -23,17 +23,17 @@ const DEFAULT_IGNORE_PATTERNS = [
 
 /**
  * Merge manifest- and suite-level triggerFilter.
- * @param {TriggerFilter | undefined} manifestFilter
- * @param {TriggerFilter | undefined} suiteFilter
- * @returns {TriggerFilter | undefined}
+ * @param {TriggerFilter | undefined} manifestFilter manifest-level filter
+ * @param {TriggerFilter | undefined} suiteFilter suite-level filter (overrides manifest)
+ * @returns {TriggerFilter | undefined} merged filter, or undefined when defaults apply unchanged
  */
 export function mergeTriggerFilter(manifestFilter, suiteFilter) {
 	if (!manifestFilter && !suiteFilter) return undefined
 	const m = manifestFilter ?? {}
 	const s = suiteFilter ?? {}
 	const ignoreDefaults = s.ignoreDefaults ?? m.ignoreDefaults ?? true
-	const ignore = [...(m.ignore ?? []), ...(s.ignore ?? [])]
-	const unignore = [...(m.unignore ?? []), ...(s.unignore ?? [])]
+	const ignore = [...m.ignore ?? [], ...s.ignore ?? []]
+	const unignore = [...m.unignore ?? [], ...s.unignore ?? []]
 	if (ignoreDefaults !== false && !ignore.length && !unignore.length)
 		return undefined
 	/** @type {TriggerFilter} */
@@ -45,8 +45,8 @@ export function mergeTriggerFilter(manifestFilter, suiteFilter) {
 
 /**
  * @param {string} path repo-relative path
- * @param {TriggerFilter | undefined} [filter]
- * @returns {boolean}
+ * @param {TriggerFilter | undefined} [filter] merged trigger filter
+ * @returns {boolean} true when the path counts as a trigger-relevant change
  */
 function isTriggerRelevantPath(path, filter) {
 	if (filter?.unignore?.some(pat => matchGlob(pat, path)))
@@ -62,8 +62,8 @@ function isTriggerRelevantPath(path, filter) {
 
 /**
  * @param {string[]} files changed paths
- * @param {TriggerFilter | undefined} [filter]
- * @returns {string[]}
+ * @param {TriggerFilter | undefined} [filter] merged trigger filter
+ * @returns {string[]} paths that survive filtering (trigger-relevant)
  */
 export function filterTriggerRelevantFiles(files, filter) {
 	return files.filter(file => isTriggerRelevantPath(file, filter))
diff --git a/src/scripts/test/runner/run_command.mjs b/src/scripts/test/runner/run_command.mjs
@@ -173,9 +173,7 @@ export async function runCommand(command, extraEnv = {}, options) {
 		usageTracker.sample().finally(() => { usageSampling = false })
 	}, WATCH_INTERVAL_MS)
 
-	/**
-	 *
-	 */
+	/** @returns {{ peakMemMb?: number, avgCpuPct?: number }} 采样汇总 */
 	const usageResult = () => usageTracker.finish()
 
 	const watchdog = setInterval(() => {
@@ -208,8 +206,8 @@ export async function runCommand(command, extraEnv = {}, options) {
 		signal: abortController.signal,
 		no_output_record: true,
 		/**
-		 *
-		 * @param child
+		 * @param {import('node:child_process').ChildProcess} child spawn 子进程
+		 * @returns {void}
 		 */
 		on_spawn: child => usageTracker.setRootFromChild(child),
 		/**
diff --git a/src/scripts/test/runner/suite_run.mjs b/src/scripts/test/runner/suite_run.mjs
@@ -3,10 +3,10 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 
 import { applyBudgetToEnv } from '../core/concurrency.mjs'
-import { suiteUsesSerialRunner } from '../core/resources.mjs'
 import { filterTestOutput } from '../core/output_filter.mjs'
 import { readFailuresOutFile, toRepoRelative } from '../core/protocol.mjs'
 import { REPO_ROOT } from '../core/repo_root.mjs'
+import { suiteUsesSerialRunner } from '../core/resources.mjs'
 
 import { runCommand } from './run_command.mjs'
 
diff --git a/src/scripts/test/selftest/deno_panic.test.mjs b/src/scripts/test/selftest/deno_panic.test.mjs
@@ -24,7 +24,7 @@ const SAMPLE = [
 	'View stack trace at:',
 	'https://panic.deno.com/v2.9.1/x86_64-pc-windows-msvc/abc123',
 	'',
-	"thread 'tokio-runtime-worker' (69808) panicked at C:\\Users\\runneradmin\\.cargo\\registry\\v8-149.4.0\\src\\handle.rs:628:9:",
+	'thread \'tokio-runtime-worker\' (69808) panicked at C:\\Users\\runneradmin\\.cargo\\registry\\v8-149.4.0\\src\\handle.rs:628:9:',
 	'attempt to access Handle hosted by disposed Isolate',
 	'stack backtrace:',
 ].join('\n')
diff --git a/src/scripts/test/selftest/deps_state.test.mjs b/src/scripts/test/selftest/deps_state.test.mjs
@@ -5,6 +5,7 @@ import { join } from 'node:path'
 
 import { assertEquals, assertStringIncludes } from 'https://deno.land/std@0.224.0/assert/mod.ts'
 
+import { MiB } from '../core/concurrency.mjs'
 import {
 	detectDependencyCycle,
 	expandWithDependencies,
@@ -14,7 +15,6 @@ import {
 	sortManifestIds,
 	topoSortSuites,
 } from '../core/deps.mjs'
-import { MiB } from '../core/concurrency.mjs'
 import { listManifestIds, loadAllSuites, selectSuitesByDiff } from '../core/manifest.mjs'
 import { REPO_ROOT } from '../core/repo_root.mjs'
 import {
diff --git a/src/scripts/test/tools/probe_pid_sampling.mjs b/src/scripts/test/tools/probe_pid_sampling.mjs
diff --git a/src/server/auth/index.mjs b/src/server/auth/index.mjs

Original file line number	Diff line number	Diff line change
`@@ -100,7 +100,7 @@ export async function safeRm(path, options) {`
`100`	`100`	`}`
`101`	`101`	`catch (e) {`
`102`	`102`	`if (isEnoent(e)) return`
`103`		`- lastError = /** @type {NodeJS.ErrnoException} */ (e)`
	`103`	`+ lastError = /** @type {NodeJS.ErrnoException} */ e`
`104`	`104`	`if (!RM_TRANSIENT_CODES.has(lastError.code)) throw lastError`
`105`	`105`	`}`
`106`	`106`	`}`