@iceinvein/agent-skills 0.3.0 → 0.4.0

package/skills/migrate/scripts/__tests__/adapter-github.test.ts

@@ -0,0 +1,232 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { github } from '../adapters/github.ts'
+import type { Config } from '../config.ts'
+import { buildWorkItems, type HandoffInput } from '../handoff.ts'
+import type { Capability, Requirement } from '../types.ts'
+
+const FAKE_GH = join(import.meta.dir, '..', '..', 'fixtures', 'fake-gh.ts')
+
+let root: string
+let statePath: string
+let logPath: string
+
+const config = (): Config => ({
+  source: {
+    path: join(root, 'legacy'),
+    scope: 'x',
+    stack: 'unknown',
+    vcs: 'none',
+    basis: 'source-only',
+  },
+  target: {
+    name: 'target',
+    stack: 'unknown',
+    parity_test_path: 'tests/parity/{capability}/{fr_slug}.test.ts',
+    layout: {},
+    commands: {},
+  },
+  surfaces: ['routes'],
+  surfaceSingular: {},
+  closers: [],
+  handoff: { adapter: 'github' },
+})
+
+function cap(slug: string, title: string, elements: string[]): Capability {
+  return { slug, title, ns: slug.slice(0, 2).toUpperCase(), elements }
+}
+
+function req(id: string, capSlug: string, text: string, cites: string[] = []): Requirement {
+  return {
+    id,
+    cap: capSlug,
+    requirement: text,
+    actors: 'User',
+    objects: 'Thing',
+    rules: 'none',
+    origin: 'intended',
+    confidence: { kind: 'confirmed' },
+    citations: cites.map((c) => ({ kind: 'ledger' as const, id: c })),
+    parity: { kind: 'rubric', level: 'high' },
+    batch: 'b-1',
+  }
+}
+
+const CAPS = [
+  cap('billing', 'Billing', ['el-b']),
+  cap('user-management', 'User management', ['el-u']),
+]
+const REQS = [
+  req('UM-001', 'user-management', 'Authenticate a user', ['el-b']),
+  req('UM-002', 'user-management', 'Lock an account'),
+  req('BI-001', 'billing', 'Raise an invoice'),
+]
+
+function input(reqs = REQS): HandoffInput {
+  return {
+    requirements: reqs,
+    capabilities: CAPS,
+    deltas: [],
+    config: config(),
+    root,
+    gitBin: 'git',
+    ghBin: FAKE_GH,
+  }
+}
+
+async function log(): Promise<string[]> {
+  const text = await readFile(logPath, 'utf8')
+  return text.split('\n').filter((l) => l.length > 0)
+}
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'migrate-gh-adapter-'))
+  await Bun.write(join(root, 'legacy', 'app.js'), '// legacy\n')
+  // The fake gh keys its state and log off its working directory, which the
+  // adapter sets to the target root.
+  statePath = join(root, 'gh-state.json')
+  logPath = join(root, 'gh-log.txt')
+  await writeFile(logPath, '')
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+test('apply creates one milestone per capability and one issue per requirement', async () => {
+  const result = await github.apply(buildWorkItems(CAPS, REQS), input())
+
+  expect(result.created.sort()).toEqual(['billing', 'user-management'])
+  // The ref is the milestone the capability's issues were filed under.
+  expect(result.refs['billing']).toBe('milestone:1')
+
+  const lines = await log()
+  expect(lines.filter((l) => l.includes('-X POST'))).toHaveLength(2)
+  expect(lines.filter((l) => l.startsWith('issue create'))).toHaveLength(3)
+  // Every issue body carries the marker that makes the next run idempotent.
+  const state = JSON.parse(await readFile(statePath, 'utf8'))
+  expect(state.issues).toHaveLength(3)
+  expect(state.issues[0].body).toContain('<!-- migrate:fr=')
+  // The milestone is keyed on the slug as well as the title: two capabilities
+  // can share a title and can never share a slug.
+  expect(state.issues.map((i: { milestone: string }) => i.milestone).sort()).toEqual([
+    'Billing (billing)',
+    'User management (user-management)',
+    'User management (user-management)',
+  ])
+})
+
+test('a second apply creates nothing and reports every item unchanged', async () => {
+  const items = buildWorkItems(CAPS, REQS)
+  await github.apply(items, input())
+  await writeFile(logPath, '')
+
+  const second = await github.apply(items, input())
+  expect(second.created).toEqual([])
+  expect(second.updated).toEqual([])
+  expect(second.unchanged.sort()).toEqual(['billing', 'user-management'])
+
+  const lines = await log()
+  expect(lines.filter((l) => l.startsWith('issue create'))).toHaveLength(0)
+  expect(lines.filter((l) => l.includes('-X POST'))).toHaveLength(0)
+})
+
+test('an issue found only by its marker is edited rather than duplicated', async () => {
+  await github.apply(buildWorkItems(CAPS, REQS), input())
+
+  // The requirement's text changes, so its issue body must be brought up to
+  // date. The adapter has no stored ref for the issue: the marker in the body
+  // is the whole identity mechanism, which is what makes this safe after a
+  // lost handoff.json.
+  const edited = [
+    req('UM-001', 'user-management', 'Authenticate a user against stored credentials', ['el-b']),
+    req('UM-002', 'user-management', 'Lock an account'),
+    req('BI-001', 'billing', 'Raise an invoice'),
+  ]
+  await writeFile(logPath, '')
+  const second = await github.apply(buildWorkItems(CAPS, edited), input(edited))
+
+  expect(second.updated).toEqual(['user-management'])
+  expect(second.unchanged).toEqual(['billing'])
+  const lines = await log()
+  expect(lines.filter((l) => l.startsWith('issue create'))).toHaveLength(0)
+  expect(lines.filter((l) => l.startsWith('issue edit'))).toHaveLength(1)
+
+  const state = JSON.parse(await readFile(statePath, 'utf8'))
+  expect(state.issues).toHaveLength(3)
+  const um1 = state.issues.filter((i: { body: string }) => i.body.includes('migrate:fr=UM-001'))
+  // Exactly one issue still carries the marker: the edit updated it in place
+  // rather than filing a second issue for the same requirement.
+  expect(um1).toHaveLength(1)
+  expect(um1[0].body).toContain('against stored credentials')
+})
+
+test('throughput reads closed issues and dates them from closedAt', async () => {
+  await github.apply(buildWorkItems(CAPS, REQS), input())
+
+  // Found by marker, not by index: billing sorts first in dependency order, so
+  // issue 0 is BI-001.
+  const state = JSON.parse(await readFile(statePath, 'utf8'))
+  const target = state.issues.find((i: { body: string }) => i.body.includes('migrate:fr=UM-001'))
+  target.state = 'CLOSED'
+  target.closedAt = '2026-08-12T04:11:00Z'
+  await writeFile(statePath, JSON.stringify(state, null, 2))
+
+  const t = await github.throughput?.(input())
+  expect(t?.completions).toEqual([{ fr: 'UM-001', doneAt: '2026-08-12' }])
+  expect(t?.basis).toContain('closed')
+})
+
+test('an issue with no marker is ignored rather than mistaken for a requirement', async () => {
+  await github.apply(buildWorkItems(CAPS, REQS), input())
+  const state = JSON.parse(await readFile(statePath, 'utf8'))
+  state.issues.push({
+    number: 500,
+    title: 'Someone else’s issue',
+    body: 'Nothing to do with the migration.',
+    state: 'CLOSED',
+    closedAt: '2026-08-01T00:00:00Z',
+    milestone: null,
+  })
+  await writeFile(statePath, JSON.stringify(state, null, 2))
+
+  const t = await github.throughput?.(input())
+  expect(t?.completions).toEqual([])
+})
+
+test('an issue that merely mentions a marker is not hijacked', async () => {
+  await github.apply(buildWorkItems(CAPS, REQS), input())
+  const state = JSON.parse(await readFile(statePath, 'utf8'))
+  const foreign = {
+    number: 900,
+    title: 'Investigate the flaky login test',
+    body: 'Related to the auth work at <!-- migrate:fr=UM-999 --> which is not this issue.\nA week of repro steps.',
+    state: 'OPEN',
+    closedAt: null,
+    milestone: null,
+  }
+  state.issues.push(foreign)
+  await writeFile(statePath, JSON.stringify(state, null, 2))
+  await writeFile(logPath, '')
+
+  await github.apply(buildWorkItems(CAPS, REQS), input())
+  const after = JSON.parse(await readFile(statePath, 'utf8'))
+  const kept = after.issues.find((i: { number: number }) => i.number === 900)
+  expect(kept.body).toBe(foreign.body)
+  expect(kept.milestone).toBeNull()
+})
+
+test('a human note below the fence survives a re-run', async () => {
+  await github.apply(buildWorkItems(CAPS, REQS), input())
+  const state = JSON.parse(await readFile(statePath, 'utf8'))
+  const target = state.issues.find((i: { body: string }) => i.body.includes('migrate:fr=UM-001'))
+  target.body = `${target.body}\n\n## Delivery notes\n\nSee PR #77.`
+  await writeFile(statePath, JSON.stringify(state, null, 2))
+
+  await github.apply(buildWorkItems(CAPS, REQS), input())
+  const after = JSON.parse(await readFile(statePath, 'utf8'))
+  const kept = after.issues.find((i: { body: string }) => i.body.includes('migrate:fr=UM-001'))
+  expect(kept.body).toContain('See PR #77.')
+})

package/skills/migrate/scripts/__tests__/adapter-markdown.test.ts

@@ -0,0 +1,183 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { markdown, parseRoadmap } from '../adapters/markdown.ts'
+import type { Config } from '../config.ts'
+import { buildWorkItems, type HandoffInput } from '../handoff.ts'
+import type { Capability, Requirement } from '../types.ts'
+
+let root: string
+
+const config = (): Config => ({
+  source: {
+    path: join(root, 'legacy'),
+    scope: 'x',
+    stack: 'unknown',
+    vcs: 'none',
+    basis: 'source-only',
+  },
+  target: {
+    name: 'target',
+    stack: 'unknown',
+    parity_test_path: 'tests/parity/{capability}/{fr_slug}.test.ts',
+    layout: {},
+    commands: {},
+  },
+  surfaces: ['routes'],
+  surfaceSingular: {},
+  closers: [],
+  handoff: { adapter: 'markdown' },
+})
+
+function cap(slug: string, title: string, elements: string[]): Capability {
+  return { slug, title, ns: slug.slice(0, 2).toUpperCase(), elements }
+}
+
+function req(id: string, capSlug: string, text: string, cites: string[] = []): Requirement {
+  return {
+    id,
+    cap: capSlug,
+    requirement: text,
+    actors: 'User',
+    objects: 'Thing',
+    rules: 'none',
+    origin: 'intended',
+    confidence: { kind: 'confirmed' },
+    citations: cites.map((c) => ({ kind: 'ledger' as const, id: c })),
+    parity: { kind: 'rubric', level: 'high' },
+    batch: 'b-1',
+  }
+}
+
+const CAPS = [
+  cap('billing', 'Billing', ['el-b']),
+  cap('user-management', 'User management', ['el-u']),
+]
+const REQS = [
+  req('UM-001', 'user-management', 'Authenticate a user against stored credentials', ['el-b']),
+  req('UM-002', 'user-management', 'Lock an account after five failed attempts'),
+  req('BI-001', 'billing', 'Raise an invoice for a completed booking'),
+]
+
+function input(caps = CAPS, reqs = REQS): HandoffInput {
+  return {
+    requirements: reqs,
+    capabilities: caps,
+    deltas: [],
+    config: config(),
+    root,
+    gitBin: 'git',
+    ghBin: 'gh',
+  }
+}
+
+const roadmapPath = (): string => join(root, 'docs', 'migrate', 'roadmap.md')
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'migrate-md-adapter-'))
+  await Bun.write(join(root, 'legacy', 'app.js'), '// legacy\n')
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+test('apply writes a roadmap in dependency order and one file per capability', async () => {
+  const items = buildWorkItems(CAPS, REQS)
+  const result = await markdown.apply(items, input())
+
+  expect(result.created.sort()).toEqual(['billing', 'user-management'])
+  expect(result.unchanged).toEqual([])
+  expect(result.refs['billing']).toBe('docs/migrate/capabilities/billing.md')
+
+  const roadmap = await readFile(roadmapPath(), 'utf8')
+  // billing owns the element user-management cites, so it comes first.
+  expect(roadmap.indexOf('Billing')).toBeLessThan(roadmap.indexOf('User management'))
+  expect(roadmap).toContain('- [ ] BI-001 Raise an invoice for a completed booking')
+  expect(roadmap).toContain('- [ ] UM-001 Authenticate a user against stored credentials')
+
+  const capFile = await readFile(
+    join(root, 'docs', 'migrate', 'capabilities', 'user-management.md'),
+    'utf8',
+  )
+  expect(capFile).toContain('# User management')
+  expect(capFile).toContain('UM-001')
+  expect(capFile).toContain('billing')
+})
+
+test('re-applying preserves every ticked box and its date', async () => {
+  const items = buildWorkItems(CAPS, REQS)
+  await markdown.apply(items, input())
+
+  // The owner ticks two boxes by hand, one with a date and one without.
+  const before = await readFile(roadmapPath(), 'utf8')
+  await writeFile(
+    roadmapPath(),
+    before
+      .replace(
+        '- [ ] UM-001 Authenticate a user against stored credentials',
+        '- [x] UM-001 <!-- done:2026-08-12 --> Authenticate a user against stored credentials',
+      )
+      .replace('- [ ] BI-001 ', '- [x] BI-001 '),
+  )
+
+  // A new requirement lands and handoff runs again.
+  const grown = [...REQS, req('UM-003', 'user-management', 'Expire a session after idle time')]
+  await markdown.apply(buildWorkItems(CAPS, grown), input(CAPS, grown))
+
+  const after = await readFile(roadmapPath(), 'utf8')
+  expect(after).toContain(
+    '- [x] UM-001 <!-- done:2026-08-12 --> Authenticate a user against stored credentials',
+  )
+  expect(after).toContain('- [x] BI-001 Raise an invoice for a completed booking')
+  expect(after).toContain('- [ ] UM-003 Expire a session after idle time')
+})
+
+test('throughput reads ticked boxes, with a null date for an undated tick', async () => {
+  const items = buildWorkItems(CAPS, REQS)
+  await markdown.apply(items, input())
+  const before = await readFile(roadmapPath(), 'utf8')
+  await writeFile(
+    roadmapPath(),
+    before
+      .replace('- [ ] UM-001 ', '- [x] UM-001 <!-- done:2026-08-12 --> ')
+      .replace('- [ ] BI-001 ', '- [x] BI-001 '),
+  )
+
+  const t = await markdown.throughput?.(input())
+  expect(t?.completions).toEqual([
+    { fr: 'BI-001', doneAt: null },
+    { fr: 'UM-001', doneAt: '2026-08-12' },
+  ])
+  expect(t?.basis).toContain('roadmap')
+})
+
+test('throughput on a roadmap that was never written reports nothing built', async () => {
+  const t = await markdown.throughput?.(input())
+  expect(t?.completions).toEqual([])
+})
+
+test('a second apply over an unchanged store reports every item unchanged', async () => {
+  const items = buildWorkItems(CAPS, REQS)
+  await markdown.apply(items, input())
+  const second = await markdown.apply(items, input())
+  expect(second.created).toEqual([])
+  expect(second.updated).toEqual([])
+  expect(second.unchanged.sort()).toEqual(['billing', 'user-management'])
+})
+
+test('plan is apply-free: it writes nothing', async () => {
+  const items = await markdown.plan(input())
+  expect(items.map((i) => i.key)).toEqual(['billing', 'user-management'])
+  expect(await Bun.file(roadmapPath()).exists()).toBe(false)
+})
+
+test('a requirement whose text opens with a parenthesised date is not read as dated', () => {
+  // The date lives in an HTML comment precisely so ordinary requirement prose
+  // cannot fabricate one. Parenthesised, this parsed as a completion date and
+  // fed a number nobody recorded into the measured velocity.
+  const roadmap = '- [x] BI-001 (2026-08-12) Raise an invoice\n'
+  const state = parseRoadmap(roadmap)
+  expect(state.get('BI-001')).toEqual({ checked: true, date: null })
+})