fix(contract): address crosscheck findings — atomic writes, exit code handling, snapshot validation

Author: Astro-Han

.github/workflows/contract-check.yml

@@ -52,9 +52,9 @@ jobs:
           retention-days: 90
           overwrite: true
 
-      # Upload drift report when drift detected
+      # Upload drift report only when checker detected drift (not on other failures)
       - uses: actions/upload-artifact@v7
-        if: failure()
+        if: failure() && hashFiles('contract-snapshots/drift-report.json') != ''
         with:
           name: drift-report
           path: contract-snapshots/drift-report.json

tests/contract/checker.ts

@@ -60,6 +60,7 @@ const TARGETS: CheckTarget[] = [
   { site: 'wikipedia', command: 'trending', args: ['--limit', '10'] },
   { site: 'sinafinance', command: 'news', args: ['--limit', '10'] },
   { site: 'weread', command: 'ranking', args: ['--limit', '10'] },
+  // "不开玩笑 Jokes Aside" podcast by 猫头鹰喜剧
   { site: 'xiaoyuzhou', command: 'podcast', args: ['61791d921989541784257779'] },
   { site: 'yollomi', command: 'models' },
 ];
@@ -74,17 +75,30 @@ function loadSnapshot(site: string, command: string): CommandSchema | null {
   const p = snapshotPath(site, command);
   if (!fs.existsSync(p)) return null;
   try {
-    return JSON.parse(fs.readFileSync(p, 'utf8'));
+    const data = JSON.parse(fs.readFileSync(p, 'utf8'));
+    // Validate snapshot structure to avoid crashes in diffSchemas
+    if (!data || typeof data !== 'object' || typeof data.fields !== 'object' || typeof data.rowCount !== 'number') {
+      console.warn(`Warning: invalid snapshot structure for ${site}/${command}, treating as first run`);
+      return null;
+    }
+    return data as CommandSchema;
   } catch (err) {
     console.warn(`Warning: corrupt snapshot for ${site}/${command}, treating as first run:`, err);
     return null;
   }
 }
 
+/** 原子写入：先写临时文件再 rename，防止 CI cancel 导致截断 JSON */
+function atomicWrite(filePath: string, content: string): void {
+  const tmp = filePath + '.tmp';
+  fs.writeFileSync(tmp, content);
+  fs.renameSync(tmp, filePath);
+}
+
 /** 保存命令快照 */
 function saveSnapshot(schema: CommandSchema, site: string, command: string): void {
   fs.mkdirSync(SNAPSHOT_DIR, { recursive: true });
-  fs.writeFileSync(snapshotPath(site, command), JSON.stringify(schema, null, 2) + '\n');
+  atomicWrite(snapshotPath(site, command), JSON.stringify(schema, null, 2) + '\n');
 }
 
 /** 失败元数据目录（与快照分离，跨 drift 事件保留） */
@@ -112,7 +126,7 @@ function saveFailureCount(site: string, command: string, count: number): void {
   if (count === 0) {
     if (fs.existsSync(metaPath)) fs.unlinkSync(metaPath);
   } else {
-    fs.writeFileSync(metaPath, JSON.stringify({ count }) + '\n');
+    atomicWrite(metaPath, JSON.stringify({ count }) + '\n');
   }
 }
 
@@ -130,7 +144,8 @@ async function runCommand(target: CheckTarget): Promise<{ data: unknown[] | null
     return { data: parsed };
   } catch (err: any) {
     const msg = err.stderr?.trim() || err.message || 'Unknown error';
-    return { data: null, error: `Exit code ${err.code ?? 1}: ${msg.slice(0, 200)}` };
+    const exitCode = err.status ?? err.code ?? 'unknown';
+    return { data: null, error: `Exit code ${exitCode}: ${msg.slice(0, 200)}` };
   }
 }
 
@@ -195,13 +210,16 @@ async function main(): Promise<void> {
     }
   }
 
+  // 统一时间戳，避免跨日不一致
+  const now = new Date();
+
   // 输出人类可读摘要
-  console.log(formatReport(results));
+  console.log(formatReport(results, now));
 
   // 写入 JSON 报告（供 CI artifact 上传）
   fs.mkdirSync(SNAPSHOT_DIR, { recursive: true });
-  const report = buildReport(results);
-  fs.writeFileSync(
+  const report = buildReport(results, now);
+  atomicWrite(
     path.join(SNAPSHOT_DIR, 'drift-report.json'),
     JSON.stringify(report, null, 2) + '\n',
   );

tests/contract/schema.ts

@@ -164,18 +164,19 @@ const DEGRADED_THRESHOLD = 7;
  * Format contract check results as human-readable console output.
  * No ANSI colors — CI logs render plain text fine.
  */
-export function formatReport(results: ContractResult[]): string {
+export function formatReport(results: ContractResult[], now?: Date): string {
   const lines: string[] = [];
-  const date = new Date().toISOString().slice(0, 10);
+  const date = (now ?? new Date()).toISOString().slice(0, 10);
   lines.push(`Schema Contract Check -- ${date}`);
   lines.push('');
 
   for (const r of results) {
     if (r.status === 'passed') {
       lines.push(`  ✓ ${r.command.padEnd(24)} -- no drift`);
     } else if (r.status === 'drifted') {
-      lines.push(`  ✗ ${r.command.padEnd(24)} -- ${r.diffs!.length} drift(s) detected`);
-      for (const d of r.diffs!) {
+      const diffs = r.diffs ?? [];
+      lines.push(`  ✗ ${r.command.padEnd(24)} -- ${diffs.length} drift(s) detected`);
+      for (const d of diffs) {
         // 各 diff 类型对应前缀符号
         const prefix = d.type === 'field_added' ? '+' :
                        d.type === 'field_removed' ? '-' :
@@ -208,9 +209,9 @@ export function formatReport(results: ContractResult[]): string {
 /**
  * Build the full JSON drift report from results.
  */
-export function buildReport(results: ContractResult[]): DriftReport {
+export function buildReport(results: ContractResult[], now?: Date): DriftReport {
   return {
-    timestamp: new Date().toISOString(),
+    timestamp: (now ?? new Date()).toISOString(),
     summary: {
       total: results.length,
       passed: results.filter(r => r.status === 'passed').length,