import assert from 'node:assert/strict' import { registerHooks } from 'node:module' import { DatabaseSync } from 'node:sqlite' import { beforeEach, describe, it } from 'node:test' /** * Scoped docs-freshness / keep-tests-tight runs through runNow with fake * kody: imports: in-memory SQLite storage, a scripted GitHub, a scripted Jev, * and a recording createAgent. Nothing reaches GitHub, Cloudflare, or Cursor. */ const fakes = { db: new DatabaseSync(':memory:'), head: 'h'.repeat(40), files: [] as Array>, pulls: [] as Array>, commits24h: [{ sha: 'c1', parents: [{ sha: 'b'.repeat(40) }] }] as Array>, jevStatus: 200, agents: [] as Array<{ prompt: string }>, ghPaths: [] as string[], } ;(globalThis as Record).__scopedFakes = fakes const fakeModules: Record = { 'kody:runtime': ` const f = globalThis.__scopedFakes export function packageStorage() { return { async sql(q, b = []) { return { rows: f.db.prepare(q).all(...b).map((r) => ({ ...r })) } } } } `, 'kody:@kentcdodds/cursor/agents': ` const f = globalThis.__scopedFakes export async function createAgent(input) { f.agents.push({ prompt: input.prompt.text }) return { agent: { id: 'bc-' + f.agents.length, url: 'https://cursor.com/agents/bc-' + f.agents.length } } } `, 'kody:@kentcdodds/devin/request': ` export async function resolveOrgId() { return null } export async function devinRequest() { throw new Error('no devin') } `, 'kody:@kentcdodds/jev/evaluate': ` const f = globalThis.__scopedFakes export default async function evaluate(input) { if (f.jevStatus !== 200) return { ok: false, status: f.jevStatus, error: 'Insufficient balance' } const answers = {} for (const [id, q] of Object.entries(input.questions)) { const keys = Object.keys(q.criteria) const file = input.state.files.find((x) => x.id === id) const work = /stale/.test(file?.path ?? '') const choice = work ? keys[0] : (keys.includes('fine') ? 'fine' : keys[0]) answers[id] = { type: 'choice', choice, confidence: 0.9, probabilities: { [choice]: 0.9 } } } return { ok: true, answers } } `, 'kody:@kentcdodds/github/request': ` const f = globalThis.__scopedFakes export default async function githubRequest({ path }) { f.ghPaths.push(path) if (path.includes('/branches/')) return { ok: true, status: 200, data: { commit: { sha: f.head } } } if (path.includes('/pulls?')) return { ok: true, status: 200, data: path.includes('page=1') ? f.pulls : [] } if (path.includes('/commits?')) return { ok: true, status: 200, data: f.commits24h } if (path.includes('/compare/')) return { ok: true, status: 200, data: { status: 'ahead', total_commits: 2, commits: [], files: f.files } } throw new Error('unexpected GitHub path ' + path) } `, } registerHooks({ resolve(specifier, context, nextResolve) { if (specifier in fakeModules) return { url: `fake-kody:${specifier}`, shortCircuit: true } return nextResolve(specifier, context) }, load(url, context, nextLoad) { if (url.startsWith('fake-kody:')) return { format: 'module', source: fakeModules[url.slice('fake-kody:'.length)], shortCircuit: true } return nextLoad(url, context) }, }) const { default: runNow } = await import('./run.ts') const { set } = await import('./config.ts') const { getLastScannedSha, listRecentLaunches } = await import('./storage.ts') const tuesday = new Date('2026-11-03T17:00:00Z') beforeEach(async () => { for (const t of ['launches', 'scan_state', 'config']) { try { fakes.db.exec(`DELETE FROM ${t}`) } catch {} } fakes.agents = [] fakes.files = [] fakes.pulls = [] fakes.ghPaths = [] fakes.jevStatus = 200 await set({ automation: 'docs-freshness', enabled: true, repos: ['acme/widgets'], fullSweepWeekday: null }) }) const doc = (path: string) => ({ filename: path, status: 'modified', additions: 3, deletions: 1, patch: '+x' }) describe('scoped docs-freshness', () => { it('no relevant changes: spawns nothing, records the skip, and advances the floor', async () => { fakes.files = [doc('docs/fine.md'), { filename: 'src/x.ts', status: 'modified', additions: 1, deletions: 0, patch: '+const a = 1' }] const result = (await runNow({ automation: 'docs-freshness' })) as any assert.equal(result.results[0].skipped, 'no-relevant-changes') assert.equal(result.results[0].considered, 1) assert.equal(fakes.agents.length, 0) assert.equal(await getLastScannedSha('acme/widgets', 'docs-freshness'), fakes.head) const [launch] = (await listRecentLaunches(1)) as any[] assert.equal(launch.outcome, 'no-relevant-changes') }) it('hands only kept files to the agent, with the branch prefix, and starts from the last cleanup merge', async () => { fakes.pulls = [ { number: 7, head: { ref: 'cleanup/docs-freshness-2026-11-01' }, merged_at: '2026-11-01T10:00:00Z', merge_commit_sha: 'm'.repeat(40) }, { number: 8, head: { ref: 'feature/x' }, merged_at: '2026-11-02T10:00:00Z', merge_commit_sha: 'z'.repeat(40) }, ] fakes.files = [doc('docs/stale-a.md'), doc('docs/fine.md')] const result = (await runNow({ automation: 'docs-freshness' })) as any const run = result.results[0] assert.equal(run.range.base, 'm'.repeat(40)) assert.deepEqual(run.kept.map((k: any) => k.path), ['docs/stale-a.md']) assert.equal(fakes.agents.length, 1) assert.match(fakes.agents[0].prompt, /docs\/stale-a\.md/) assert.doesNotMatch(fakes.agents[0].prompt, /docs\/fine\.md/) assert.match(fakes.agents[0].prompt, /cleanup\/docs-freshness-\d{4}-\d{2}-\d{2}/) const [launch] = (await listRecentLaunches(1)) as any[] assert.deepEqual(JSON.parse(launch.files), ['docs/stale-a.md']) }) it('caps agents per day and keeps the floor when chunks are left over', async () => { await set({ automation: 'docs-freshness', maxAgentsPerDay: 1, chunkMin: 2, chunkMax: 2 }) fakes.files = ['a', 'b', 'c', 'd'].map((n) => doc(`docs/${n}/stale.md`)) const result = (await runNow({ automation: 'docs-freshness' })) as any assert.equal(fakes.agents.length, 1) assert.equal(result.results[0].chunks.length, 2) assert.equal(result.results[0].launches[1].skipped, 'over-daily-cap') assert.equal(await getLastScannedSha('acme/widgets', 'docs-freshness'), null) }) it('falls back to the heuristic when Jev returns 402', async () => { fakes.jevStatus = 402 fakes.files = [{ filename: 'docs/a.md', status: 'modified', additions: 2, deletions: 0, patch: '+We now support OAuth' }] const result = (await runNow({ automation: 'docs-freshness', dryRun: true })) as any const run = result.results[0] assert.equal(run.triage.source, 'heuristic') assert.equal(run.kept[0].reason, 'temporal-language') assert.equal(fakes.agents.length, 0) assert.equal(await getLastScannedSha('acme/widgets', 'docs-freshness'), null) }) it('runs the full-repo prompt on the sweep weekday', async () => { await set({ automation: 'docs-freshness', fullSweepWeekday: 2 }) const { runScoped } = await import('./scoped-run.ts') const { getAutomation } = await import('./storage.ts') const prompts: string[] = [] const result = await runScoped({ automation: 'docs-freshness', repo: 'acme/widgets', config: await getAutomation('docs-freshness'), dryRun: true, now: tuesday, spawn: async (l) => { prompts.push(l.prompt) return { ok: true } }, }) assert.equal(result.mode, 'full-sweep') assert.match(prompts[0], /# Docs freshness\n/) assert.match(prompts[0], /cleanup\/docs-freshness-2026-11-03/) }) })