Skip to content

feat: add schema drift detection (#50)#99

Open
Astro-Han wants to merge 2 commits intojackwener:mainfrom
Astro-Han:worktree-schema-drift
Open

feat: add schema drift detection (#50)#99
Astro-Han wants to merge 2 commits intojackwener:mainfrom
Astro-Han:worktree-schema-drift

Conversation

@Astro-Han
Copy link
Contributor

@Astro-Han Astro-Han commented Mar 19, 2026

Description

Add runtime schema drift detection that warns users when command output fields are suspiciously empty, indicating upstream API structure changes.

Related issue: #50

How it works

After a command executes and before output renders, detectDrift() checks each declared column's empty-value ratio (null, undefined, ''). If any column is >= 80% empty across valid object rows (minimum 3), a yellow warning is printed to stderr:

⚠ Schema drift detected (bilibili/hot):
  • field 'author' — empty in 15/15 rows (100%)
  • field 'danmaku' — empty in 12/15 rows (80%)

New src/drift.ts module with detectDrift() and formatDriftWarning() — standalone, no side effects. Integrated into cli.ts between command execution and output rendering (warning only, no exit code change).

Closes #50 (core detection layer — CI cron and LLM repair interface deferred to follow-up)

Type of Change

  • 🐛 Bug fix
  • ✨ New feature
  • 🌐 New site adapter
  • 📝 Documentation
  • ♻️ Refactor
  • 🔧 CI / build / tooling

Checklist

  • I ran the checks relevant to this PR
  • I updated tests or docs if needed
  • I included output or screenshots when useful

Screenshots / Output

$ npm run dev -- hackernews top --limit 3

  hackernews/top
┌──────┬──────────────────────────────────────┬───────┬─────────────┬──────────┐
│ Rank │ Title                                │ Score │ Author      │ Comments │
├──────┼──────────────────────────────────────┼───────┼─────────────┼──────────┤
│ 1    │ Astral to Join OpenAI                │ 307   │ ibraheemdev │ 136      │
├──────┼──────────────────────────────────────┼───────┼─────────────┼──────────┤
│ 2    │ OpenBSD: PF queues break 4 Gbps      │ 32    │ defrost     │ 8        │
├──────┼──────────────────────────────────────┼───────┼─────────────┼──────────┤
│ 3    │ Juggalo Makeup Blocks Facial Recog...│ 61    │ speckx      │ 18       │
└──────┴──────────────────────────────────────┴───────┴─────────────┴──────────┘
3 items · 9.7s · hackernews/top

No drift warning (all fields populated) — expected behavior for healthy adapters.

Test results

$ npx vitest run src/drift.test.ts
 ✓ 14 tests passed (drift.test.ts)

$ npm run typecheck
 tsc --noEmit (no errors)

$ npm run build
 ✅ Manifest compiled: 213 entries

- New `src/drift.ts` module with `detectDrift()` and `formatDriftWarning()`
- Warns on stderr when columns have >= 80% empty values
- Integrated into main.ts between command execution and output rendering
- 13 unit tests covering all edge cases
@Astro-Han Astro-Han force-pushed the worktree-schema-drift branch from 8ffa8e7 to f68c71a Compare March 20, 2026 03:28
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Feature Request: daily contract check for API schema drift with test accounts

1 participant