@iceinvein/agent-skills 0.2.0 → 0.4.0

package/skills/migrate/scripts/__tests__/handoff-cmd.test.ts

@@ -0,0 +1,308 @@
+import { afterEach, beforeEach, expect, test } from 'bun:test'
+import { mkdir, mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { blockedRequirements } from '../handoff.ts'
+import { runHandoff } from '../handoff-cmd.ts'
+import type { Requirement } from '../types.ts'
+
+let root: string
+let source: string
+
+function req(id: string, over: Partial<Requirement> = {}): Requirement {
+  return {
+    id,
+    cap: 'user-management',
+    requirement: `requirement ${id}`,
+    actors: 'User',
+    objects: 'Thing',
+    rules: 'none',
+    origin: 'intended',
+    confidence: { kind: 'confirmed' },
+    citations: [{ kind: 'src', path: 'app.js', lines: [1, 1] }],
+    parity: { kind: 'rubric', level: 'high' },
+    batch: 'b-extract-1',
+    ...over,
+  }
+}
+
+const PHASES = ['probe', 'enumerate', 'seam', 'extract', 'parity', 'queue', 'adjudicate', 'handoff']
+
+async function jsonl(name: string, rows: unknown[]): Promise<void> {
+  await writeFile(join(root, '.migrate', name), rows.map((r) => `${JSON.stringify(r)}\n`).join(''))
+}
+
+// A complete, gate-clean store with one declared surface and no closers, so a
+// handoff test does not have to satisfy eight lens censuses to reach the thing
+// it is actually asserting.
+async function store(over: { requirements?: Requirement[]; queueStatus?: string } = {}) {
+  await mkdir(join(root, '.migrate', 'queue'), { recursive: true })
+  await writeFile(
+    join(root, '.migrate', 'config.toml'),
+    [
+      '[source]',
+      `path = "${source}"`,
+      'scope = "handoff fixture"',
+      'stack = "unknown"',
+      'vcs = "none"',
+      'basis = "source-only"',
+      '',
+      '[target]',
+      'name = "target"',
+      'stack = "unknown"',
+      'parity_test_path = "tests/parity/{capability}/{fr_slug}.test.ts"',
+      '',
+      '[surfaces]',
+      'types = ["routes"]',
+      '',
+      '[closers]',
+      'set = []',
+      '',
+      '[handoff]',
+      'adapter = "markdown"',
+      '',
+    ].join('\n'),
+  )
+
+  const requirements = over.requirements ?? [req('UM-001'), req('UM-002')]
+  await jsonl('elements.jsonl', [
+    {
+      id: 'route-get-users',
+      surface: 'routes',
+      element: 'GET /users',
+      found_by: ['code'],
+      disposition: { kind: 'mapped', fr: 'UM-001' },
+      refs: [],
+      lens: 'code',
+      batch: 'b-routes-1',
+      notes: '',
+    },
+  ])
+  await jsonl('requirements.jsonl', requirements)
+  await jsonl('capabilities.jsonl', [
+    {
+      slug: 'user-management',
+      title: 'User management',
+      ns: 'UM',
+      elements: ['route-get-users'],
+    },
+  ])
+  await jsonl('census.jsonl', [
+    {
+      kind: 'lens',
+      surface: 'routes',
+      phase: 'enumerate',
+      directions: {
+        code: { count: 1, evidence: 'grep app.get' },
+        nav: { count: 1, evidence: 'walked the router' },
+      },
+      total: 1,
+      in_ledger: 0,
+      added: 1,
+      skipped: [],
+      queued: [],
+      batch: 'b-routes-1',
+    },
+  ])
+
+  await writeFile(
+    join(root, '.migrate', 'queue', 'q-open-question.md'),
+    [
+      '---',
+      'id: q-open-question',
+      'severity: moderate',
+      `status: ${over.queueStatus ?? 'adjudicated'}`,
+      ...(over.queueStatus === 'open' ? [] : ['ruling: settled in favour of billing']),
+      '---',
+      '',
+      '## Evidence',
+      '',
+      'e',
+      '',
+      '## Options',
+      '',
+      'o',
+      '',
+      '## Recommendation',
+      '',
+      'r',
+      '',
+    ].join('\n'),
+  )
+
+  const phases: Record<string, unknown> = {}
+  for (const p of PHASES) {
+    phases[p] = {
+      status: 'done',
+      batches:
+        p === 'enumerate'
+          ? [{ id: 'b-routes-1', count: 1 }]
+          : p === 'extract'
+            ? [{ id: 'b-extract-1', count: requirements.length }]
+            : [],
+      pending: [],
+    }
+  }
+  // handoff has not run yet: this is the command under test.
+  phases.handoff = { status: 'pending', batches: [], pending: [] }
+  await writeFile(
+    join(root, '.migrate', 'phases.json'),
+    JSON.stringify({ version: 1, phases }, null, 2),
+  )
+}
+
+beforeEach(async () => {
+  root = await mkdtemp(join(tmpdir(), 'migrate-handoff-'))
+  source = join(root, 'legacy')
+  await Bun.write(join(source, 'app.js'), '// legacy\n')
+})
+
+afterEach(async () => {
+  await rm(root, { recursive: true, force: true })
+})
+
+// --- blockedRequirements, pure ---
+
+test('a queued confidence blocks only while its queue item is open', () => {
+  const queued = req('UM-001', { confidence: { kind: 'queued', queue: 'q-x' } })
+
+  expect(blockedRequirements([queued], new Set(['q-x']))).toEqual([{ fr: 'UM-001', queue: 'q-x' }])
+  // The correction this milestone exists to make. Once the item is
+  // adjudicated it is no longer open, the decision is settled, and the
+  // requirement must stop blocking handoff even though its confidence still
+  // reads `queued`. Treating any queued confidence as a blocker would refuse
+  // handoff forever unless every such requirement were re-imported first.
+  expect(blockedRequirements([queued], new Set())).toEqual([])
+})
+
+test('a sub-high rubric parity blocks on its own queue item', () => {
+  const moderate = req('UM-002', {
+    parity: { kind: 'rubric', level: 'moderate', queue: 'q-y' },
+  })
+  expect(blockedRequirements([moderate], new Set(['q-y']))).toEqual([
+    { fr: 'UM-002', queue: 'q-y' },
+  ])
+  expect(blockedRequirements([moderate], new Set())).toEqual([])
+})
+
+test('a high rubric and a differential parity never block', () => {
+  const high = req('UM-003')
+  const differential = req('UM-004', { parity: { kind: 'differential', ref: 't.test.ts' } })
+  expect(blockedRequirements([high, differential], new Set(['q-x']))).toEqual([])
+})
+
+test('one requirement blocked from both directions is reported once per path', () => {
+  const both = req('UM-005', {
+    confidence: { kind: 'queued', queue: 'q-a' },
+    parity: { kind: 'rubric', level: 'low', queue: 'q-b' },
+  })
+  expect(blockedRequirements([both], new Set(['q-a', 'q-b']))).toEqual([
+    { fr: 'UM-005', queue: 'q-a' },
+    { fr: 'UM-005', queue: 'q-b' },
+  ])
+})
+
+// --- the verb ---
+
+test('handoff writes handoff.json and records the phase batch', async () => {
+  await store()
+  const code = await runHandoff({ root })
+  expect(code).toBe(0)
+
+  const file = JSON.parse(await readFile(join(root, '.migrate', 'handoff.json'), 'utf8'))
+  expect(file.adapter).toBe('markdown')
+  expect(file.items).toHaveLength(1)
+  expect(file.items[0].frs).toEqual(['UM-001', 'UM-002'])
+  expect(file.basis).toEqual({ confirmed: 2, emitted: 2, order: ['user-management'] })
+  // The stored item drops the rendered body, which is regenerated on every
+  // plan() and would otherwise churn the file on wording alone.
+  expect(file.items[0].body).toBeUndefined()
+
+  const phases = JSON.parse(await readFile(join(root, '.migrate', 'phases.json'), 'utf8'))
+  expect(phases.phases.handoff.batches).toHaveLength(1)
+})
+
+test('handoff.json is byte-identical across two runs over one store', async () => {
+  await store()
+  await runHandoff({ root })
+  const first = await readFile(join(root, '.migrate', 'handoff.json'), 'utf8')
+  await runHandoff({ root })
+  const second = await readFile(join(root, '.migrate', 'handoff.json'), 'utf8')
+  expect(second).toBe(first)
+})
+
+test('handoff refuses while a queue item is open, naming it', async () => {
+  await store({ queueStatus: 'open' })
+  const code = await runHandoff({ root })
+  expect(code).toBe(1)
+  expect(await Bun.file(join(root, '.migrate', 'handoff.json')).exists()).toBe(false)
+})
+
+test('handoff refuses a requirement blocked by an open item, naming both', async () => {
+  await store({
+    requirements: [
+      req('UM-001'),
+      req('UM-002', { confidence: { kind: 'queued', queue: 'q-open-question' } }),
+    ],
+    queueStatus: 'open',
+  })
+  // Asserting the message, not just the exit code. Gate 11 already fails an
+  // open queue item, so a test that only checked `code === 1` passed even with
+  // blockedRequirements stubbed out to return nothing, and the "naming both"
+  // in this test's own name went unverified.
+  const written: string[] = []
+  const original = process.stderr.write.bind(process.stderr)
+  process.stderr.write = ((chunk: string) => {
+    written.push(String(chunk))
+    return true
+  }) as typeof process.stderr.write
+  let code: number
+  try {
+    code = await runHandoff({ root })
+  } finally {
+    process.stderr.write = original
+  }
+  expect(code).toBe(1)
+  expect(written.join('')).toContain('UM-002 blocked by q-open-question')
+})
+
+test('a corrupt handoff.json is a violation, not a crash', async () => {
+  await store()
+  await writeFile(join(root, '.migrate', 'handoff.json'), '{"items": "not an array"}')
+  const { runCheck } = await import('../check.ts')
+  // Bounded checks must still work: the file is read only for the gate that
+  // needs it, so a corrupt one cannot break `check --phase probe`, `status` or
+  // `report`.
+  const early = await runCheck({ root, phase: 'probe' })
+  expect(early.violations.filter((v) => v.gate === 'handoff')).toEqual([])
+  const full = await runCheck({ root })
+  const named = full.violations.filter((v) => v.gate === 'handoff')
+  expect(named.length).toBeGreaterThan(0)
+  expect(named[0]?.message).toContain('handoff.json')
+})
+
+test('--dry-run runs the preflight and writes nothing', async () => {
+  await store()
+  const code = await runHandoff({ root, dryRun: true })
+  expect(code).toBe(0)
+  expect(await Bun.file(join(root, '.migrate', 'handoff.json')).exists()).toBe(false)
+  expect(await Bun.file(join(root, 'docs', 'migrate', 'roadmap.md')).exists()).toBe(false)
+})
+
+test('--dry-run still refuses on an open queue item', async () => {
+  await store({ queueStatus: 'open' })
+  expect(await runHandoff({ root, dryRun: true })).toBe(1)
+})
+
+test('an unknown adapter is a usage error naming the three that exist', async () => {
+  await store()
+  const code = await runHandoff({ root, adapter: 'jira' })
+  expect(code).toBe(2)
+})
+
+test('the preflight is bounded at adjudicate, so gate 12 cannot block the run that satisfies it', async () => {
+  // handoff.json does not exist yet, and gate 12 requires it. An unbounded
+  // preflight would therefore refuse every first handoff, forever.
+  await store()
+  expect(await runHandoff({ root })).toBe(0)
+})

package/skills/migrate/scripts/__tests__/handoff-order.test.ts

@@ -0,0 +1,156 @@
+import { expect, test } from 'bun:test'
+import { buildWorkItems, dependencyOrder } from '../handoff.ts'
+import type { Capability, Requirement } from '../types.ts'
+
+function cap(slug: string, elements: string[]): Capability {
+  return { slug, title: slug.replace(/-/g, ' '), ns: slug.slice(0, 2).toUpperCase(), elements }
+}
+
+// A requirement in `capSlug` citing each of `cites` as a ledger element. The
+// edge under test is directional: the capability that owns the cited element
+// is the dependency, and the capability doing the citing is the dependent.
+function req(id: string, capSlug: string, cites: string[]): Requirement {
+  return {
+    id,
+    cap: capSlug,
+    requirement: `requirement ${id}`,
+    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 slugs = (caps: Capability[]): string[] => caps.map((c) => c.slug)
+
+test('a chain emits its dependencies first', () => {
+  // alpha cites an element owned by beta; beta cites one owned by gamma.
+  const caps = [cap('alpha', ['el-a']), cap('beta', ['el-b']), cap('gamma', ['el-c'])]
+  const reqs = [
+    req('AL-001', 'alpha', ['el-b']),
+    req('BE-001', 'beta', ['el-c']),
+    req('GA-001', 'gamma', []),
+  ]
+  const { ordered, cycle } = dependencyOrder(caps, reqs)
+  expect(slugs(ordered)).toEqual(['gamma', 'beta', 'alpha'])
+  expect(cycle).toEqual([])
+})
+
+test('a diamond emits a valid order, deterministically', () => {
+  // top depends on left and right; both depend on base.
+  const caps = [
+    cap('top', ['el-t']),
+    cap('left', ['el-l']),
+    cap('right', ['el-r']),
+    cap('base', ['el-b']),
+  ]
+  const reqs = [
+    req('TO-001', 'top', ['el-l', 'el-r']),
+    req('LE-001', 'left', ['el-b']),
+    req('RI-001', 'right', ['el-b']),
+    req('BA-001', 'base', []),
+  ]
+  const first = dependencyOrder(caps, reqs)
+  expect(slugs(first.ordered)).toEqual(['base', 'left', 'right', 'top'])
+  // Re-running over the same input, and over a shuffled input, gives the same
+  // answer: the tie between left and right is broken by slug, not by position.
+  const shuffled = dependencyOrder([...caps].reverse(), [...reqs].reverse())
+  expect(slugs(shuffled.ordered)).toEqual(slugs(first.ordered))
+})
+
+test('a cycle emits its members in slug order and reports them', () => {
+  const caps = [cap('yin', ['el-y']), cap('yang', ['el-z']), cap('solo', ['el-s'])]
+  const reqs = [
+    req('YI-001', 'yin', ['el-z']),
+    req('YA-001', 'yang', ['el-y']),
+    req('SO-001', 'solo', []),
+  ]
+  const { ordered, cycle } = dependencyOrder(caps, reqs)
+  // solo is unblocked and goes first; the two-cycle follows in slug order.
+  expect(slugs(ordered)).toEqual(['solo', 'yang', 'yin'])
+  expect(cycle).toEqual(['yang', 'yin'])
+})
+
+test('a capability whose requirements cite no ledger elements is unblocked', () => {
+  const caps = [cap('alpha', ['el-a']), cap('beta', ['el-b'])]
+  const reqs = [
+    // A src citation is not a ledger citation and creates no edge.
+    {
+      ...req('AL-001', 'alpha', []),
+      citations: [{ kind: 'src' as const, path: 'app.js', lines: [1, 2] as [number, number] }],
+    },
+    req('BE-001', 'beta', []),
+  ]
+  const { ordered, cycle } = dependencyOrder(caps, reqs)
+  expect(slugs(ordered)).toEqual(['alpha', 'beta'])
+  expect(cycle).toEqual([])
+})
+
+test('a capability citing an element it owns itself does not depend on itself', () => {
+  const caps = [cap('alpha', ['el-a', 'el-a2'])]
+  const reqs = [req('AL-001', 'alpha', ['el-a2'])]
+  const { ordered, cycle } = dependencyOrder(caps, reqs)
+  expect(slugs(ordered)).toEqual(['alpha'])
+  expect(cycle).toEqual([])
+})
+
+test('buildWorkItems carries frs, weight and dependsOn per capability', () => {
+  const caps = [cap('alpha', ['el-a']), cap('beta', ['el-b'])]
+  const reqs = [
+    req('AL-001', 'alpha', ['el-b']),
+    req('AL-002', 'alpha', []),
+    req('BE-001', 'beta', []),
+  ]
+  const items = buildWorkItems(caps, reqs)
+  expect(items.map((i) => i.key)).toEqual(['beta', 'alpha'])
+
+  const alpha = items.find((i) => i.key === 'alpha')
+  expect(alpha?.frs).toEqual(['AL-001', 'AL-002'])
+  expect(alpha?.weight).toBe(2)
+  expect(alpha?.dependsOn).toEqual(['beta'])
+  expect(alpha?.body).toContain('AL-001')
+  expect(alpha?.body).toContain('AL-002')
+
+  const beta = items.find((i) => i.key === 'beta')
+  expect(beta?.dependsOn).toEqual([])
+  expect(beta?.weight).toBe(1)
+})
+
+test('buildWorkItems emits a capability with no requirements at weight zero', () => {
+  // An empty capability is still a real partition entry, and dropping it would
+  // silently narrow what handoff emitted relative to what the seam decided.
+  const items = buildWorkItems([cap('empty', ['el-e'])], [])
+  expect(items).toHaveLength(1)
+  expect(items[0]?.weight).toBe(0)
+  expect(items[0]?.frs).toEqual([])
+})
+
+test('only genuine cycle members are reported, and what follows a cycle still sorts', () => {
+  // "Everything left is in a cycle" was false: anything transitively blocked
+  // by one was reported as a member too, and its satisfiable placement was
+  // thrown away. Here yin and yang cycle; alpha depends on yin and zulu on
+  // alpha, so both have a valid position after the cycle is broken.
+  const caps = [
+    cap('yin', ['el-y']),
+    cap('yang', ['el-z']),
+    cap('alpha', ['el-a']),
+    cap('zulu', ['el-u']),
+  ]
+  const reqs = [
+    req('YI-001', 'yin', ['el-z']),
+    req('YA-001', 'yang', ['el-y']),
+    req('AL-001', 'alpha', ['el-y']),
+    req('ZU-001', 'zulu', ['el-a']),
+  ]
+  const { ordered, cycle } = dependencyOrder(caps, reqs)
+  expect(cycle).toEqual(['yang', 'yin'])
+  // alpha comes after the cycle it depends on, and zulu after alpha.
+  const at = (slug: string): number => slugs(ordered).indexOf(slug)
+  expect(at('alpha')).toBeGreaterThan(at('yin'))
+  expect(at('zulu')).toBeGreaterThan(at('alpha'))
+  expect(slugs(ordered).sort()).toEqual(['alpha', 'yang', 'yin', 'zulu'])
+})