dsh-flakefinder 0.1.0

package/lib/parse.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 测试报告解析：vitest / jest 的 JSON reporter 与 node:test 的 TAP 输出统一成
+ * 一次运行的扁平用例列表。
+ *
+ * @module dsh-flakefinder/parse
+ */
+export type TestStatus = 'passed' | 'failed' | 'skipped';
+export interface NormalizedTest {
+    id: string;
+    file: string;
+    name: string;
+    status: TestStatus;
+    durationMs: number;
+}
+export interface NormalizedRun {
+    framework: string;
+    success: boolean;
+    total: number;
+    passed: number;
+    failed: number;
+    skipped: number;
+    tests: NormalizedTest[];
+}
+/** vitest 与 jest 的 JSON 结构高度接近，这里统一读取。 */
+export declare function parseJsonReport(text: string, framework: string): NormalizedRun;
+/** 解析 node:test 的 TAP 输出；子测试行忽略，只保留顶层用例。 */
+export declare function parseTapReport(text: string): NormalizedRun;

package/lib/parse.js

@@ -0,0 +1,105 @@
+/**
+ * 测试报告解析：vitest / jest 的 JSON reporter 与 node:test 的 TAP 输出统一成
+ * 一次运行的扁平用例列表。
+ *
+ * @module dsh-flakefinder/parse
+ */
+function asNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) ? value : null;
+}
+function normalizeStatus(value) {
+    if (value === 'passed')
+        return 'passed';
+    if (value === 'failed')
+        return 'failed';
+    if (value === 'pending' || value === 'skipped' || value === 'todo' || value === 'disabled')
+        return 'skipped';
+    return 'failed';
+}
+/** vitest 与 jest 的 JSON 结构高度接近，这里统一读取。 */
+export function parseJsonReport(text, framework) {
+    let root;
+    try {
+        root = JSON.parse(text);
+    }
+    catch {
+        throw new Error(framework + ' 报告不是合法 JSON。请确认项目安装的是支持 --reporter=json 的版本。');
+    }
+    const obj = (root ?? {});
+    const suites = Array.isArray(obj.testResults) ? obj.testResults : [];
+    const tests = [];
+    for (const suite of suites) {
+        const file = typeof suite.name === 'string' && suite.name !== '' ? suite.name : '(unknown)';
+        const assertions = Array.isArray(suite.assertionResults) ? suite.assertionResults : [];
+        if (assertions.length > 0) {
+            for (const item of assertions) {
+                const fullName = typeof item.fullName === 'string' && item.fullName !== ''
+                    ? item.fullName
+                    : (typeof item.title === 'string' ? item.title : '(unnamed)');
+                const status = normalizeStatus(item.status);
+                tests.push({
+                    id: file + ' > ' + fullName,
+                    file,
+                    name: fullName,
+                    status,
+                    durationMs: Math.max(0, asNumber(item.duration) ?? 0),
+                });
+            }
+        }
+        else {
+            const status = normalizeStatus(suite.status);
+            tests.push({
+                id: file + ' > (suite)',
+                file,
+                name: '(suite)',
+                status,
+                durationMs: 0,
+            });
+        }
+    }
+    return {
+        framework,
+        success: obj.success === true,
+        total: reportedCount(obj.numTotalTests, tests.length),
+        passed: reportedCount(obj.numPassedTests, tests.filter(test => test.status === 'passed').length),
+        failed: reportedCount(obj.numFailedTests, tests.filter(test => test.status === 'failed').length),
+        skipped: reportedCount(obj.numPendingTests, tests.filter(test => test.status === 'skipped').length),
+        tests,
+    };
+}
+function reportedCount(reported, fallback) {
+    if (typeof reported === 'number' && Number.isFinite(reported))
+        return Math.round(reported);
+    return fallback;
+}
+/** 解析 node:test 的 TAP 输出；子测试行忽略，只保留顶层用例。 */
+export function parseTapReport(text) {
+    const tests = [];
+    const lines = text.split(/\r?\n/);
+    let index = 0;
+    for (const line of lines) {
+        const match = /^(not ok|ok)\s+(\d+)\s+-\s*(.+?)\s*$/.exec(line.trim());
+        if (match === null)
+            continue;
+        const failed = match[1] === 'not ok';
+        index += 1;
+        const name = (match[3] ?? '(unnamed)').replace(/\s+#.*$/, '');
+        tests.push({
+            id: 'node:' + String(index) + ' > ' + name,
+            file: '(node:test)',
+            name,
+            status: failed ? 'failed' : 'passed',
+            durationMs: 0,
+        });
+    }
+    const failed = tests.filter(item => item.status === 'failed').length;
+    return {
+        framework: 'node',
+        success: failed === 0 && tests.length > 0,
+        total: tests.length,
+        passed: tests.length - failed,
+        failed,
+        skipped: 0,
+        tests,
+    };
+}

package/lib/runner.d.ts

@@ -0,0 +1,66 @@
+/**
+ * 进程执行层：复用 dsh-docker 同款 subprocess 包装，并按计划读取 JSON 报告。
+ *
+ * @module dsh-flakefinder/runner
+ */
+import type { TestPlan } from './args.js';
+import { type NormalizedRun } from './parse.js';
+export interface RunResult {
+    exitCode: number | null;
+    signal: string | null;
+    stdout: string;
+    stderr: string;
+}
+export interface ProcessRunner {
+    run(argv: readonly string[], options?: {
+        timeoutMs?: number;
+    }): Promise<RunResult>;
+}
+export interface SubprocessHandleLike {
+    done: Promise<{
+        exitCode: number | null;
+        signal: string | null;
+    }>;
+    collected: {
+        stdout?: {
+            readFrom(offset: number): {
+                text: string;
+            };
+        };
+        stderr?: {
+            readFrom(offset: number): {
+                text: string;
+            };
+        };
+    };
+    terminate(): void;
+}
+export interface SubprocessSpawnLike {
+    (spec: {
+        argv: readonly string[];
+        cwd: string;
+        stdio: {
+            stdin: 'ignore';
+            stdout: {
+                maxBytes: number;
+            };
+            stderr: {
+                maxBytes: number;
+            };
+        };
+        graceMs: number;
+        signal?: AbortSignal;
+    }): SubprocessHandleLike;
+}
+/** 用 DSH subprocess 服务构造 ProcessRunner。 */
+export declare function createSubprocessRunner(spawn: SubprocessSpawnLike, graceMs: number, defaultTimeoutMs: number): ProcessRunner;
+export interface FlakeRun {
+    index: number;
+    report: NormalizedRun | null;
+    durationMs: number;
+    exitCode: number | null;
+    stderr: string;
+    error?: string;
+}
+/** 执行一个测试计划并读取报告；进程失败但报告存在时仍返回报告。 */
+export declare function executePlan(runner: ProcessRunner, plan: TestPlan, index: number, timeoutMs: number): Promise<FlakeRun>;

package/lib/runner.js

@@ -0,0 +1,98 @@
+/**
+ * 进程执行层：复用 dsh-docker 同款 subprocess 包装，并按计划读取 JSON 报告。
+ *
+ * @module dsh-flakefinder/runner
+ */
+import fs from 'node:fs/promises';
+import { parseJsonReport, parseTapReport } from './parse.js';
+const COLLECT_BYTES = 4 * 1024 * 1024;
+/** 用 DSH subprocess 服务构造 ProcessRunner。 */
+export function createSubprocessRunner(spawn, graceMs, defaultTimeoutMs) {
+    return {
+        async run(argv, options) {
+            const timeoutMs = options?.timeoutMs ?? defaultTimeoutMs;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(new Error('flakefinder test run timed out')), timeoutMs);
+            let handle;
+            try {
+                handle = spawn({
+                    argv,
+                    cwd: process.cwd(),
+                    stdio: {
+                        stdin: 'ignore',
+                        stdout: { maxBytes: COLLECT_BYTES },
+                        stderr: { maxBytes: COLLECT_BYTES },
+                    },
+                    graceMs,
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            const outcome = await handle.done;
+            const stdout = handle.collected.stdout?.readFrom(0).text ?? '';
+            const stderr = handle.collected.stderr?.readFrom(0).text ?? '';
+            return { exitCode: outcome.exitCode, signal: outcome.signal, stdout, stderr };
+        },
+    };
+}
+function stderrTail(stderr) {
+    const tail = stderr.trim().split(/\r?\n/).slice(-5).join(' | ');
+    return tail || '无错误输出';
+}
+/** 执行一个测试计划并读取报告；进程失败但报告存在时仍返回报告。 */
+export async function executePlan(runner, plan, index, timeoutMs) {
+    const started = Date.now();
+    const result = await runner.run(plan.argv, { timeoutMs });
+    const durationMs = Date.now() - started;
+    if (plan.reportKind === 'tap') {
+        return {
+            index,
+            report: parseTapReport(result.stdout),
+            durationMs,
+            exitCode: result.exitCode,
+            stderr: result.stderr,
+        };
+    }
+    let fileText = '';
+    let fileError = '';
+    try {
+        fileText = await fs.readFile(plan.reportPath, 'utf8');
+    }
+    catch (error) {
+        fileError = error instanceof Error ? error.message : String(error);
+    }
+    finally {
+        await fs.rm(plan.reportPath, { force: true }).catch(() => { });
+    }
+    if (fileText.trim() === '') {
+        return {
+            index,
+            report: null,
+            durationMs,
+            exitCode: result.exitCode,
+            stderr: result.stderr,
+            error: plan.framework + ' 没有写出 JSON 报告（' + fileError + '）。进程退出码：' + String(result.exitCode ?? 'null') + '；stderr：' + stderrTail(result.stderr),
+        };
+    }
+    try {
+        return {
+            index,
+            report: parseJsonReport(fileText, plan.framework),
+            durationMs,
+            exitCode: result.exitCode,
+            stderr: result.stderr,
+        };
+    }
+    catch (error) {
+        return {
+            index,
+            report: null,
+            durationMs,
+            exitCode: result.exitCode,
+            stderr: result.stderr,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}

package/lib/store.d.ts

@@ -0,0 +1,58 @@
+/**
+ * 历史与隔离清单存储：JSON 文件、原子写入、零运行时依赖。
+ *
+ * @module dsh-flakefinder/store
+ */
+export interface HistoryEntry {
+    timestamp: string;
+    target: string;
+    framework: string;
+    runs: number;
+    durationMs: number;
+    verdict: string;
+    stablePassCount: number;
+    stableFailCount: number;
+    flakyCount: number;
+    skippedCount: number;
+    flakyTests: Array<{
+        file: string;
+        name: string;
+        failureRate: number;
+    }>;
+}
+export interface QuarantineEntry {
+    file: string;
+    name: string | null;
+    reason: string;
+    since: string;
+}
+export interface QuarantineDocument {
+    version: 1;
+    quarantined: QuarantineEntry[];
+}
+export interface Store {
+    appendHistory(entry: HistoryEntry): Promise<void>;
+    listHistory(target: string | undefined, limit: number): Promise<HistoryEntry[]>;
+    loadQuarantine(): Promise<QuarantineDocument>;
+    addQuarantine(refs: ParsedRef[], reason: string): Promise<{
+        added: QuarantineEntry[];
+        file: string;
+    }>;
+    removeQuarantine(refs: ParsedRef[]): Promise<{
+        removed: QuarantineEntry[];
+        file: string;
+    }>;
+    quarantinePath: string;
+}
+export interface ParsedRef {
+    file: string;
+    name: string | null;
+}
+export declare function createStore(dataDir: string, quarantineFile: string): Store;
+/** 解析 "file.test.mjs" 或 "file.test.mjs > 用例名" 形式的引用。 */
+export declare function parseRef(raw: string): ParsedRef;
+/** 隔离清单条目的可读格式。 */
+export declare function formatRef(entry: {
+    file: string;
+    name: string | null;
+}): string;

package/lib/store.js

@@ -0,0 +1,123 @@
+/**
+ * 历史与隔离清单存储：JSON 文件、原子写入、零运行时依赖。
+ *
+ * @module dsh-flakefinder/store
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+const HISTORY_FILE = 'history.json';
+const HISTORY_LIMIT = 200;
+export function createStore(dataDir, quarantineFile) {
+    const historyPath = path.join(dataDir, HISTORY_FILE);
+    async function ensureDir() {
+        await fs.mkdir(dataDir, { recursive: true });
+    }
+    async function readHistory() {
+        try {
+            const text = await fs.readFile(historyPath, 'utf8');
+            const parsed = JSON.parse(text);
+            return Array.isArray(parsed) ? parsed : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    async function appendHistory(entry) {
+        await ensureDir();
+        const list = await readHistory();
+        list.unshift(entry);
+        const trimmed = list.slice(0, HISTORY_LIMIT);
+        const tmp = historyPath + '.tmp-' + process.pid;
+        await fs.writeFile(tmp, JSON.stringify(trimmed, null, 2), 'utf8');
+        await fs.rename(tmp, historyPath);
+    }
+    async function listHistory(target, limit) {
+        const list = await readHistory();
+        const filtered = target === undefined ? list : list.filter(entry => entry.target === target || entry.target.includes(target));
+        return filtered.slice(0, limit);
+    }
+    async function readQuarantine() {
+        try {
+            const text = await fs.readFile(quarantineFile, 'utf8');
+            const parsed = JSON.parse(text);
+            const obj = (parsed ?? {});
+            return {
+                version: 1,
+                quarantined: Array.isArray(obj.quarantined) ? obj.quarantined : [],
+            };
+        }
+        catch {
+            return { version: 1, quarantined: [] };
+        }
+    }
+    async function writeQuarantine(doc) {
+        await fs.mkdir(path.dirname(quarantineFile), { recursive: true });
+        const tmp = quarantineFile + '.tmp-' + process.pid;
+        await fs.writeFile(tmp, JSON.stringify(doc, null, 2) + '\n', 'utf8');
+        await fs.rename(tmp, quarantineFile);
+    }
+    async function addQuarantine(refs, reason) {
+        const doc = await readQuarantine();
+        const now = new Date().toISOString();
+        const added = [];
+        for (const ref of refs) {
+            const existing = doc.quarantined.find(item => sameRef(item, ref));
+            if (existing !== undefined) {
+                existing.reason = reason;
+                existing.since = now;
+                continue;
+            }
+            const entry = { file: ref.file, name: ref.name, reason, since: now };
+            doc.quarantined.push(entry);
+            added.push(entry);
+        }
+        doc.quarantined.sort((a, b) => a.file.localeCompare(b.file) || (a.name ?? '').localeCompare(b.name ?? ''));
+        await writeQuarantine(doc);
+        return { added, file: quarantineFile };
+    }
+    async function removeQuarantine(refs) {
+        const doc = await readQuarantine();
+        const removed = [];
+        doc.quarantined = doc.quarantined.filter(item => {
+            const hit = refs.some(ref => sameRef(item, ref));
+            if (hit)
+                removed.push(item);
+            return !hit;
+        });
+        await writeQuarantine(doc);
+        return { removed, file: quarantineFile };
+    }
+    return {
+        appendHistory,
+        listHistory,
+        loadQuarantine: readQuarantine,
+        addQuarantine,
+        removeQuarantine,
+        quarantinePath: quarantineFile,
+    };
+}
+function sameRef(item, ref) {
+    if (item.file !== ref.file)
+        return false;
+    if (ref.name === null)
+        return true;
+    return item.name === ref.name;
+}
+/** 解析 "file.test.mjs" 或 "file.test.mjs > 用例名" 形式的引用。 */
+export function parseRef(raw) {
+    const trimmed = raw.trim();
+    if (trimmed === '')
+        throw new Error('测试引用不能为空。格式：文件路径，或 "文件路径 > 用例名"。');
+    const index = trimmed.indexOf(' > ');
+    if (index === -1)
+        return { file: trimmed, name: null };
+    const file = trimmed.slice(0, index).trim();
+    const name = trimmed.slice(index + 3).trim();
+    if (file === '')
+        throw new Error('测试引用缺少文件路径：' + raw);
+    return { file, name: name === '' ? null : name };
+}
+/** 隔离清单条目的可读格式。 */
+export function formatRef(entry) {
+    return entry.name === null ? entry.file : entry.file + ' > ' + entry.name;
+}

package/lib/tools.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 五个面向模型的测试稳定性工具：
+ * flaky_detect / flaky_history / flaky_quarantine / flaky_clear / flaky_report。
+ *
+ * @module dsh-flakefinder/tools
+ */
+import { type ResolvedFlakeConfig } from './config.js';
+import { type ProcessRunner } from './runner.js';
+import { type Store } from './store.js';
+export interface ContentBlock {
+    type: 'text';
+    text: string;
+}
+export interface FlakeToolDefinition {
+    name: string;
+    description: string;
+    parameters: {
+        type: 'object';
+        properties: Record<string, unknown>;
+        required?: string[];
+    };
+    output: {
+        schema: Record<string, unknown>;
+        render(args: unknown, value: unknown): ContentBlock[];
+    };
+    execute(args: unknown, exec: unknown): Promise<unknown>;
+    gate?(exec: unknown, next: () => Promise<unknown>): Promise<unknown>;
+    timeoutMs?: number;
+}
+/** 构建五个工具定义。 */
+export declare function buildFlakeTools(cfg: ResolvedFlakeConfig, runner: ProcessRunner, store: Store): FlakeToolDefinition[];