kaloko 0.4.8 → 0.4.10

package/src/lib/affected-core.mjs

@@ -0,0 +1,242 @@
+// Affected steps from changed files (#14): pure functions, no file system or Node APIs, shared by the CLI
+// (`kaloko affected`, `walk --affected`) and the service (MCP get_affected_steps).
+//
+// A changed file reaches a step in one of these ways, and the selection says which:
+//   - the step's `affects:` globs name the file (or `affects: always`);
+//   - the file is a route file of a known framework (Next.js, Nuxt, SvelteKit, Remix, Astro, Rails) and its route
+//     matches a path of the step: its `path` or a URL captured for it in an earlier run;
+//   - the file is a step script or the scenario itself changed for that step (the caller passes those);
+//   - the file is global (layouts, global styles, dependencies, i18n messages): every step, or every step of one locale;
+//   - the file is imported by a route file (the CLI follows imports; the caller passes the route files it found).
+// Files that are none of these are listed as unmapped, never silently dropped.
+
+/** Minimal glob: `*` within a segment, `**` across segments, `?` one character. */
+export function globRe (glob) {
+  let out = ''
+  for (let i = 0; i < glob.length; i++) {
+    const c = glob[i]
+    if (c === '*' && glob[i + 1] === '*') { out += '.*'; i++; if (glob[i + 1] === '/') i++ } else if (c === '*') out += '[^/]*'
+    else if (c === '?') out += '[^/]'
+    else out += c.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+  }
+  return new RegExp('^' + out + '$')
+}
+
+const CODE = /\.(m?[jt]sx?|cjs|vue|svelte|astro|rb|erb|haml|slim|php|py|css|scss|sass|less|html?)$/i
+const IGNORED = [
+  /(^|\/)(test|tests|spec|specs|__tests__|e2e|cypress|playwright|\.storybook|docs?|\.github|\.vscode|\.idea)\//,
+  /\.(test|spec|stories)\.[a-z]+$/i, /(^|\/)(README|CHANGELOG|LICENSE|CONTRIBUTING)[^/]*$/i, /\.md$/i,
+  /(^|\/)\.(gitignore|gitattributes|editorconfig|prettierrc[^/]*|eslintrc[^/]*|nvmrc|tool-versions)$/, /(^|\/)kaloko\.(ci\.)?config\.yml$/
+]
+const GLOBAL = [
+  /^(package\.json|package-lock\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|Gemfile|Gemfile\.lock)$/,
+  /(^|\/)(tailwind|postcss|next|nuxt|svelte|vite|astro|remix)\.config\.[a-z]+$/,
+  /(^|\/)(globals?|app|main|application)\.(css|scss|sass|less)$/, /^(src\/)?styles\//, /^(src\/)?(assets\/)?(css|styles)\/(global|base|reset|variables|tokens)[^/]*$/,
+  /^public\//, /^static\//,
+  /^(src\/)?app\/(layout|template|not-found|error|global-error)\.[jt]sx?$/, /^(src\/)?pages\/_(app|document)\.[jt]sx?$/,
+  /^(app\/)?(app|error)\.vue$/, /^(app\/)?layouts\//, /^src\/app\.(html|d\.ts)$/, /^src\/hooks(\.(server|client))?\.[jt]s$/, /^src\/routes\/\+layout(\.server)?\.(svelte|[jt]s)$/,
+  /^app\/root\.[jt]sx?$/, /^src\/layouts\//,
+  /^app\/views\/(layouts|shared|application)\//, /^app\/controllers\/application_controller\.rb$/, /^app\/helpers\/application_helper\.rb$/, /^config\/routes(\.rb|\/)/, /^app\/assets\/(stylesheets|config)\//
+]
+// i18n messages: every step, but only in the file's locale when the name says which
+const MESSAGES = /(^|\/)(messages|locales?|lang|i18n|translations)\/(?:.*\/)?([a-z]{2}(?:[-_][A-Za-z]{2})?)(?:\.[a-z]+)?\.(json|ya?ml|po|js|ts)$/
+
+/** Route segments: dynamic `[id]`, `$id`, `:id` become `:id`; catch-all `[...slug]` and `$` become `**`. */
+function segment (s, style) {
+  if (style === 'next' || style === 'nuxt' || style === 'svelte' || style === 'astro') {
+    if (/^\(.*\)$/.test(s) || s.startsWith('@')) return null // route groups and parallel slots are not in the URL
+    if (/^\[\[?\.\.\..+\]\]?$/.test(s)) return '**'
+    if (/^\[\[.+\]\]$/.test(s)) return '**' // optional parameter: this path and below
+    const m = s.match(/^\[(.+?)(=[^\]]+)?\]$/); if (m) return `:${m[1]}`
+    return s
+  }
+  if (style === 'remix') {
+    if (s === '_index' || s === 'index') return ''
+    if (s.startsWith('_')) return null // pathless layout
+    if (s === '$') return '**'
+    if (s.startsWith('$')) return `:${s.slice(1)}`
+    return s.replace(/^\((.+)\)$/, '$1').replace(/_$/, '')
+  }
+  return s
+}
+const join = (parts) => '/' + parts.filter((p) => p !== null && p !== '').join('/')
+
+/**
+ * The route a file serves, by framework convention; { route, scope: 'page'|'prefix', framework } or null.
+ * `prefix` means the file shapes every page under the route (layouts, controllers, colocated components).
+ */
+export function routeOf (file) {
+  let m
+  // Next.js app router
+  if ((m = file.match(/^(?:src\/)?app\/(?:(.*)\/)?(page|route|layout|template|loading|error|not-found|default)\.(?:m?[jt]sx?|mdx)$/))) {
+    const parts = (m[1] || '').split('/').filter(Boolean)
+    if (parts.some((p) => p.startsWith('_'))) return null
+    return { route: join(parts.map((p) => segment(p, 'next'))), scope: ['page', 'route'].includes(m[2]) ? 'page' : 'prefix', framework: 'next' }
+  }
+  // Remix / React Router flat routes
+  if ((m = file.match(/^app\/routes\/(.+?)(?:\/route)?\.[jt]sx?$/))) {
+    const parts = m[1].split(/[./]/).map((p) => segment(p, 'remix'))
+    return { route: join(parts), scope: 'page', framework: 'remix' }
+  }
+  // SvelteKit
+  if ((m = file.match(/^src\/routes\/(?:(.*)\/)?\+(page|layout|server|error)(?:\.server)?\.(svelte|[jt]s)$/))) {
+    return { route: join((m[1] || '').split('/').filter(Boolean).map((p) => segment(p, 'svelte'))), scope: ['page', 'server'].includes(m[2]) ? 'page' : 'prefix', framework: 'sveltekit' }
+  }
+  // Nuxt (pages/*.vue, Nuxt 4 app/pages/*.vue)
+  if ((m = file.match(/^(?:app\/)?pages\/(.+)\.vue$/))) {
+    const parts = m[1].split('/').map((p) => (p === 'index' ? '' : segment(p, 'nuxt')))
+    return { route: join(parts), scope: 'page', framework: 'nuxt' }
+  }
+  // Next.js pages router, Astro, Gatsby
+  if ((m = file.match(/^(src\/)?pages\/(.+)\.(m?[jt]sx?|astro|mdx?)$/))) {
+    const style = m[3] === 'astro' || m[1] ? 'astro' : 'next'
+    const parts = m[2].split('/')
+    if (parts.some((p) => p.startsWith('_'))) return null
+    return { route: join(parts.map((p) => (p === 'index' ? '' : segment(p, style)))), scope: 'page', framework: m[3] === 'astro' ? 'astro' : 'next-pages' }
+  }
+  // Rails: views, controllers and helpers of one controller shape its pages (/admin/products/…)
+  if ((m = file.match(/^app\/views\/(.+)\/[^/]+$/))) return { route: '/' + m[1], scope: 'prefix', framework: 'rails' }
+  if ((m = file.match(/^app\/controllers\/(.+)_controller\.rb$/))) return { route: '/' + m[1], scope: 'prefix', framework: 'rails' }
+  if ((m = file.match(/^app\/helpers\/(.+)_helper\.rb$/))) return { route: '/' + m[1], scope: 'prefix', framework: 'rails' }
+  // a component colocated in a route folder shapes that route and everything below it
+  if ((m = file.match(/^(?:src\/)?app\/(.+)\/[^/]+\.(?:m?[jt]sx?|css|scss)$/)) && !/(^|\/)(api|lib|components|utils|hooks|composables|stores|plugins|middleware|styles|types|javascript|assets|models|controllers|views|helpers|jobs|mailers|channels|services|policies|serializers)(\/|$)/.test(m[1]) && !m[1].split('/').some((p) => p.startsWith('_'))) {
+    return { route: join(m[1].split('/').map((p) => segment(p, 'next'))), scope: 'prefix', framework: 'next' }
+  }
+  if ((m = file.match(/^src\/routes\/(.+)\/[^/+][^/]*\.(svelte|[jt]s)$/))) return { route: join(m[1].split('/').map((p) => segment(p, 'svelte'))), scope: 'prefix', framework: 'sveltekit' }
+  return null
+}
+
+/** How one changed file is treated: ignored, global (optionally for one locale), a route, code to follow, or other. */
+export function classify (file) {
+  if (IGNORED.some((re) => re.test(file))) return { kind: 'ignored' }
+  const msg = file.match(MESSAGES)
+  if (msg) return { kind: 'global', locale: msg[3].replace('_', '-').toLowerCase() }
+  if (GLOBAL.some((re) => re.test(file))) return { kind: 'global' }
+  const r = routeOf(file)
+  if (r) return { kind: 'route', ...r }
+  if (CODE.test(file)) return { kind: 'code' }
+  return { kind: 'other' }
+}
+
+/** RegExp for URL paths a route reaches: `:x` one segment, `**` anything below, prefix scope this path and below. */
+export function routeRe (route, scope = 'page') {
+  const body = route.replace(/\/$/, '').split('/').filter(Boolean).map((s) => s === '**' ? '(?:/.*)?' : '/' + (s.startsWith(':') ? '[^/]+' : s.replace(/[.+^${}()|[\]\\*?]/g, '\\$&'))).join('')
+  if (scope === 'prefix') return new RegExp(`^${body}(?:/.*)?$`)
+  return new RegExp(`^${body || '/'}${body ? '/?' : ''}$`)
+}
+
+/** URL path of a step path or captured URL: no origin, query or hash; `{random}` stands for any one segment. */
+export function pathOf (value) {
+  if (!value) return null
+  let p = String(value)
+  try { if (/^[a-z][a-z0-9+.-]*:\/\//i.test(p)) p = new URL(p).pathname } catch { return null }
+  p = p.split(/[?#]/)[0]
+  if (!p.startsWith('/')) p = '/' + p
+  return p.length > 1 ? p.replace(/\/+$/, '') : p
+}
+
+/** Does a route reach this path (with or without a leading locale segment such as /cs/…)? */
+export function routeMatches (route, scope, path, locales = []) {
+  const re = routeRe(route, scope)
+  const p = path.replaceAll('{random}', 'x')
+  if (re.test(p)) return true
+  const [first, ...rest] = p.split('/').filter(Boolean)
+  const loc = first && (locales.includes(first) || /^[a-z]{2}(-[a-zA-Z]{2})?$/.test(first))
+  return !!loc && re.test('/' + rest.join('/'))
+}
+
+/** Paths of a step: its `path` (every locale) plus URLs captured for it earlier ({ [step]: [url…] }). */
+export function stepPaths (node, captured = {}) {
+  const raw = node.path == null ? [] : typeof node.path === 'string' ? [node.path] : Object.values(node.path)
+  return [...new Set([...raw, ...(captured[node.id] || [])].map(pathOf).filter(Boolean))]
+}
+
+/** Steps a step depends on to be reached: predecessors over main edges (not back edges), transitively. */
+export function upstreamOf (scenario, ids) {
+  const order = new Map(scenario.nodes.map((n, i) => [n.id, i]))
+  const into = new Map()
+  for (const e of scenario.edges || []) if ((e.kind || 'main') === 'main' && order.get(e.from) < order.get(e.to)) (into.get(e.to) || into.set(e.to, []).get(e.to)).push(e.from)
+  const out = new Map()
+  const visit = (id, of) => { for (const p of into.get(id) || []) if (!ids.has(p) && !out.has(p)) { out.set(p, of); visit(p, of) } }
+  for (const id of ids) visit(id, id)
+  return out
+}
+
+/**
+ * Selects the steps changed files reach.
+ * changes: [{ file, kind?, via? }] (`via`: the route file an imported module reaches, from the CLI's import graph)
+ * extra:   { [step]: [reason] } reasons the caller found itself (changed step scripts, changed scenario steps)
+ * captured: { [step]: [url] } URLs captured in earlier runs
+ * Returns { steps: [{ id, reasons }], upstream: [{ id, of }], always, unmapped, ignored, global, locales, all }
+ */
+export function selectAffected ({ scenario, changes, captured = {}, extra = {}, upstream = true }) {
+  const walkable = scenario.nodes.filter((n) => n.kind !== 'decision')
+  const reasons = new Map()
+  const add = (id, why) => { const r = reasons.get(id) || []; if (!r.includes(why)) r.push(why); reasons.set(id, r) }
+  const unmapped = []; const ignored = []; const global = []
+  const localeHits = new Set(); let everyLocale = false
+  const locales = scenario.locales || []
+  const always = walkable.filter((n) => n.affects === 'always').map((n) => n.id)
+  const globs = walkable.filter((n) => Array.isArray(n.affects)).map((n) => ({ id: n.id, res: n.affects.map((g) => [g, globRe(g)]) }))
+  const paths = new Map(walkable.map((n) => [n.id, stepPaths(n, captured)]))
+  for (const ch of changes) {
+    const file = ch.file
+    let hit = false
+    for (const g of globs) for (const [glob, re] of g.res) if (re.test(file)) { add(g.id, `${file} matches affects: ${glob}`); hit = true; everyLocale = true }
+    const c = ch.kind ? ch : { ...ch, ...classify(ch.via || file) }
+    if (c.kind === 'ignored' && !hit) { ignored.push(file); continue }
+    if (c.kind === 'global') {
+      global.push(c.locale ? `${file} (${c.locale})` : file)
+      if (c.locale) localeHits.add(c.locale); else everyLocale = true
+      for (const n of walkable) add(n.id, `${ch.via ? `${file} → imported by ${ch.via}` : file} is shared by every page${c.locale ? ` in ${c.locale}` : ''}`)
+      continue
+    }
+    if (c.kind === 'route') {
+      const label = `${ch.via ? `${file} → imported by ${ch.via}` : file} → route ${c.route}${c.scope === 'prefix' ? '/…' : ''}`
+      for (const n of walkable) {
+        const p = (paths.get(n.id) || []).find((x) => routeMatches(c.route, c.scope, x, locales))
+        if (p) { add(n.id, `${label} (${stepPaths(n).includes(p) ? 'step path' : 'captured earlier'} ${p})`); hit = true }
+      }
+      if (!hit) unmapped.push(`${file} (route ${c.route}: no step shows it)`)
+      everyLocale = true
+      continue
+    }
+    if (!hit) unmapped.push(file); else everyLocale = true
+  }
+  for (const [id, list] of Object.entries(extra)) for (const why of list) { add(id, why); everyLocale = true }
+  for (const id of always) if (!reasons.has(id)) add(id, 'always walked (affects: always)')
+  const picked = new Set(reasons.keys())
+  const onlyAlways = (id) => always.includes(id) && reasons.get(id).length === 1 && reasons.get(id)[0].startsWith('always walked')
+  const ups = upstream ? upstreamOf(scenario, new Set([...picked].filter((id) => !onlyAlways(id)))) : new Map()
+  for (const id of picked) ups.delete(id)
+  const order = new Map(scenario.nodes.map((n, i) => [n.id, i]))
+  const steps = [...reasons].map(([id, r]) => ({ id, reasons: r })).sort((a, b) => order.get(a.id) - order.get(b.id))
+  const real = steps.filter((s) => !onlyAlways(s.id))
+  return {
+    steps,
+    upstream: [...ups].map(([id, of]) => ({ id, of })).sort((a, b) => order.get(a.id) - order.get(b.id)),
+    always,
+    unmapped, ignored, global,
+    // only i18n messages of some locales changed: the walk can stay in those locales
+    locales: !everyLocale && localeHits.size ? [...localeHits] : null,
+    all: real.length > 0 && real.length === walkable.length,
+    none: real.length === 0
+  }
+}
+
+/** The ids to walk, in scenario order: selected, always and upstream steps. */
+export const selectedIds = (scenario, sel) => scenario.nodes.map((n) => n.id).filter((id) => sel.steps.some((s) => s.id === id) || sel.upstream.some((u) => u.id === id))
+
+/** Human explanation of a selection, one line per step. */
+export function formatAffected (sel, { scenario, base = null, changed = 0 } = {}) {
+  const lines = [`Affected steps of ${scenario.id}${base ? ` (changes against ${base}` : ' ('}${changed} changed file(s)):`]
+  if (sel.none && !sel.always.length) lines.push('  none: no changed file reaches a step of this scenario')
+  for (const s of sel.steps) lines.push(`  ✓ ${s.id.padEnd(24)} ${s.reasons.slice(0, 3).join('; ')}${s.reasons.length > 3 ? `; +${s.reasons.length - 3} more` : ''}`)
+  for (const u of sel.upstream) lines.push(`  ↑ ${u.id.padEnd(24)} walked first to reach ${u.of} (upstream; --no-upstream skips it)`)
+  const skipped = scenario.nodes.filter((n) => n.kind !== 'decision' && !sel.steps.some((s) => s.id === n.id) && !sel.upstream.some((u) => u.id === n.id)).map((n) => n.id)
+  if (skipped.length) lines.push(`  · not walked: ${skipped.join(', ')}`)
+  if (sel.locales) lines.push(`  locales: ${sel.locales.join(', ')} (only their messages changed)`)
+  if (sel.unmapped.length) lines.push(`  ? unmapped (no route, import or affects: glob reaches a step): ${sel.unmapped.slice(0, 8).join(', ')}${sel.unmapped.length > 8 ? `, +${sel.unmapped.length - 8} more` : ''}\n    add affects: [<glob>] to the steps they shape, or walk everything (--if-unmapped all)`)
+  if (sel.ignored.length) lines.push(`  ignored (tests, docs, CI): ${sel.ignored.length} file(s)`)
+  return lines.join('\n')
+}

package/src/lib/affected.mjs

@@ -0,0 +1,233 @@
+// `kaloko affected` and `walk --affected` (#14): changed files from git, imports followed to route files, URLs
+// captured in earlier runs (local and, with a token, the newest shared run), then the pure selection.
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { readdir, readFile, stat, cp, mkdir } from 'node:fs/promises'
+import { join, relative, resolve, dirname } from 'node:path'
+import yaml from 'js-yaml'
+import { classify, selectAffected, pathOf } from './affected-core.mjs'
+import { readJson, readJsonl, appendJsonl, writeJson } from './util.mjs'
+import { listRuns } from './run.mjs'
+
+const exec = promisify(execFile)
+async function git (cwd, args) {
+  try { return (await exec('git', args, { cwd, timeout: 20000, maxBuffer: 16 * 1024 * 1024 })).stdout.trim() } catch { return null }
+}
+
+/** The ref changes are measured against: --base, then CI variables, then origin/main or main. */
+export async function baseRef (cwd, explicit, vars = process.env) {
+  const candidates = [
+    explicit,
+    vars.KALOKO_BASE,
+    vars.GITHUB_BASE_REF && `origin/${vars.GITHUB_BASE_REF}`,
+    vars.CI_MERGE_REQUEST_DIFF_BASE_SHA,
+    vars.CI_MERGE_REQUEST_TARGET_BRANCH_NAME && `origin/${vars.CI_MERGE_REQUEST_TARGET_BRANCH_NAME}`,
+    'origin/main', 'origin/master', 'main', 'master'
+  ].filter(Boolean)
+  for (const ref of candidates) if (await git(cwd, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`])) return ref
+  return null
+}
+
+/** Files changed since the merge base with `base`, plus uncommitted and untracked ones, relative to `root`. */
+export async function changedFiles (root, base) {
+  const top = await git(root, ['rev-parse', '--show-toplevel'])
+  if (!top) return { base: null, files: [] }
+  const ref = await baseRef(root, base)
+  const mb = ref ? await git(root, ['merge-base', 'HEAD', ref]) : null
+  const lists = await Promise.all([
+    mb ? git(root, ['diff', '--name-only', mb, 'HEAD']) : '',
+    git(root, ['diff', '--name-only', 'HEAD']),
+    git(root, ['ls-files', '--others', '--exclude-standard', '--full-name'])
+  ])
+  // git names files from the top of the repository; the project may be a folder of it (monorepos)
+  const prefix = (await git(root, ['rev-parse', '--show-prefix'])) || ''
+  const files = [...new Set(lists.flatMap((l) => (l || '').split('\n').filter(Boolean)))].filter((f) => f.startsWith(prefix)).map((f) => f.slice(prefix.length)).sort()
+  return { base: ref, mergeBase: mb, files, top }
+}
+
+const SOURCE = /\.(m?[jt]sx?|cjs|vue|svelte|astro)$/
+const SKIP_DIRS = new Set(['node_modules', '.git', '.next', '.nuxt', '.svelte-kit', '.output', 'dist', 'build', 'out', 'coverage', 'tmp', 'vendor', '.turbo', '.cache', 'public'])
+const SPEC = /(?:import|export)\s[^'"`]*?from\s*['"]([^'"]+)['"]|import\s*\(\s*['"]([^'"]+)['"]\s*\)|require\s*\(\s*['"]([^'"]+)['"]\s*\)|import\s+['"]([^'"]+)['"]/g
+
+async function sourceFiles (root, limit = 30000) {
+  const out = []
+  const walk = async (dir) => {
+    if (out.length >= limit) return
+    let entries = []
+    try { entries = await readdir(dir, { withFileTypes: true }) } catch { return }
+    for (const e of entries) {
+      if (e.isDirectory()) { if (!SKIP_DIRS.has(e.name) && !e.name.startsWith('.')) await walk(join(dir, e.name)) } else if (SOURCE.test(e.name)) out.push(join(dir, e.name))
+    }
+  }
+  await walk(root)
+  return out
+}
+
+/** Path aliases: tsconfig/jsconfig `paths` (one level), else @/ and ~/ to src/ or the root. */
+async function aliases (root) {
+  const out = []
+  for (const f of ['tsconfig.json', 'jsconfig.json']) {
+    try {
+      const text = (await readFile(join(root, f), 'utf8')).replace(/^\s*\/\/.*$/gm, '').replace(/,(\s*[}\]])/g, '$1')
+      const o = JSON.parse(text).compilerOptions || {}
+      for (const [k, v] of Object.entries(o.paths || {})) if (k.endsWith('/*') && v?.[0]?.endsWith('/*')) out.push([k.slice(0, -1), resolve(root, o.baseUrl || '.', v[0].slice(0, -1)) + '/'])
+    } catch {}
+  }
+  const src = await stat(join(root, 'src')).then((s) => s.isDirectory(), () => false)
+  for (const a of ['@/', '~/', '$lib/']) if (!out.some(([k]) => k === a)) out.push([a, a === '$lib/' ? join(root, 'src', 'lib') + '/' : (src ? join(root, 'src') : root) + '/'])
+  return out
+}
+
+const EXTS = ['', '.ts', '.tsx', '.js', '.jsx', '.mjs', '.vue', '.svelte', '.astro', '/index.ts', '/index.tsx', '/index.js', '/index.jsx', '/index.vue']
+
+/** Reverse import graph of the project's JS/TS/Vue/Svelte sources: file → files importing it (relative to root). */
+export async function importGraph (root) {
+  const files = await sourceFiles(root)
+  const known = new Set(files)
+  const alias = await aliases(root)
+  const resolveSpec = (from, spec) => {
+    let base = null
+    if (spec.startsWith('.')) base = resolve(dirname(from), spec)
+    else { const a = alias.find(([k]) => spec.startsWith(k)); if (a) base = a[1] + spec.slice(a[0].length) }
+    if (!base) return null
+    const stripped = base.replace(/\.(js|mjs|jsx)$/, '')
+    for (const b of [base, stripped]) for (const e of EXTS) if (known.has(b + e)) return b + e
+    return null
+  }
+  const into = new Map()
+  for (const f of files) {
+    let text
+    try { const s = await stat(f); if (s.size > 1024 * 1024) continue; text = await readFile(f, 'utf8') } catch { continue }
+    for (const m of text.matchAll(SPEC)) {
+      const target = resolveSpec(f, m[1] || m[2] || m[3] || m[4])
+      if (!target || target === f) continue
+      const k = relative(root, target); const v = relative(root, f)
+      ;(into.get(k) || into.set(k, new Set()).get(k)).add(v)
+    }
+  }
+  return into
+}
+
+/** Route or global files that import `file`, directly or through other modules (breadth first, depth ≤ 6). */
+export function importersReaching (graph, file, depth = 6, max = 40) {
+  const found = []; const seen = new Set([file]); let frontier = [file]
+  for (let d = 0; d < depth && frontier.length && found.length < max; d++) {
+    const next = []
+    for (const f of frontier) {
+      for (const imp of graph.get(f) || []) {
+        if (seen.has(imp)) continue
+        seen.add(imp)
+        const c = classify(imp)
+        if (c.kind === 'route' || c.kind === 'global') found.push(imp); else if (c.kind === 'code') next.push(imp)
+      }
+    }
+    frontier = next
+  }
+  return found
+}
+
+/** URLs captured for each step in earlier runs of the scenario: local run folders, then the newest shared run. */
+export async function capturedRoutes ({ root, output, scenarioId, client = null, org = null }) {
+  const out = {}
+  const addRun = (m) => {
+    for (const n of m.nodes || []) for (const vps of Object.values(n.captures || {})) for (const c of Object.values(vps || {})) {
+      const p = pathOf(c?.url); if (p && /^https?:/.test(c.url)) (out[n.id] ||= new Set()).add(p)
+    }
+  }
+  const local = (await listRuns(root, output)).filter((r) => r.scenario?.id === scenarioId).sort((a, b) => b.started_at.localeCompare(a.started_at)).slice(0, 5)
+  for (const m of local) addRun(m)
+  let shared = null
+  if (client && org) {
+    try {
+      const [latest] = await client.request('GET', `/orgs/${org}/runs?scenario=${encodeURIComponent(scenarioId)}&limit=1`)
+      if (latest) { addRun(await client.request('GET', `/orgs/${org}/runs/${latest.id}`)); shared = latest.id }
+    } catch {}
+  }
+  return { routes: Object.fromEntries(Object.entries(out).map(([k, v]) => [k, [...v]])), local: local.length, shared }
+}
+
+/** Steps whose script or definition changed (script files relative to the scenario, the scenario against the base). */
+async function scenarioChanges ({ root, scenario, scenarioFile, files, mergeBase, top }) {
+  const extra = {}
+  const add = (id, why) => (extra[id] ||= []).push(why)
+  const dir = dirname(scenarioFile)
+  for (const n of scenario.nodes) {
+    const s = n.execution?.script && relative(root, resolve(dir, n.execution.script))
+    if (s && files.includes(s)) add(n.id, `step script ${s} changed`)
+  }
+  const rel = relative(root, scenarioFile)
+  if (files.includes(rel)) {
+    let before = null
+    if (mergeBase && top) { const text = await git(root, ['show', `${mergeBase}:./${relative(root, scenarioFile)}`]); try { before = text ? yaml.load(text) : null } catch {} }
+    const old = new Map((before?.nodes || []).map((n) => [n.id, JSON.stringify(n)]))
+    // compared as written (packs unexpanded), so a pack update in the CLI does not mark every step
+    const now = yaml.load(await readFile(scenarioFile, 'utf8'))
+    for (const n of scenario.nodes) {
+      if (n.kind === 'decision') continue
+      const raw = JSON.stringify((now?.nodes || []).find((x) => x.id === n.id) ?? n)
+      if (!old.has(n.id)) add(n.id, before ? 'new step in the scenario' : 'the scenario is new')
+      else if (old.get(n.id) !== raw) add(n.id, 'step changed in the scenario')
+    }
+  }
+  return extra
+}
+
+/**
+ * The full selection for one scenario. `files` overrides git (agents and CI may pass the list they know).
+ * Returns { sel, base, files, routes }.
+ */
+export async function affectedFor ({ root, config, scenario, scenarioFile, base, files = null, client = null, upstream = true }) {
+  const diff = files ? { base: base || null, files, mergeBase: null, top: null } : await changedFiles(root, base)
+  const scenarioRel = relative(root, scenarioFile)
+  const graphNeeded = diff.files.some((f) => classify(f).kind === 'code' && SOURCE.test(f))
+  const graph = graphNeeded ? await importGraph(root) : new Map()
+  const changes = []
+  for (const file of diff.files) {
+    if (file === scenarioRel) continue
+    const c = classify(file)
+    if (c.kind === 'code' && SOURCE.test(file)) {
+      const via = importersReaching(graph, file)
+      if (via.length) { for (const v of via) changes.push({ file, via: v }); continue }
+    }
+    changes.push({ file })
+  }
+  // the scenario's own steps folder is mechanics of the walk, never a page of the app
+  const stepsDir = relative(root, dirname(scenarioFile)) + '/'
+  const appChanges = changes.filter((c) => !c.file.startsWith(stepsDir) || c.via)
+  const extra = await scenarioChanges({ root, scenario, scenarioFile, files: diff.files, mergeBase: diff.mergeBase, top: diff.top })
+  const { routes, local, shared } = await capturedRoutes({ root, output: config.output, scenarioId: scenario.id, client, org: config.org })
+  const sel = selectAffected({ scenario, changes: appChanges, captured: routes, extra, upstream })
+  return { sel, base: diff.base, files: diff.files, runs: { local, shared } }
+}
+
+/**
+ * Copies the newest earlier local run's captures of the steps that are not walked into this run (marked
+ * carried_from), so the canvas shows the whole flow. Returns { from, steps } or null.
+ */
+export async function carryCaptures ({ root, output, run, scenario, walked }) {
+  const base = resolve(root, output)
+  let names = []
+  try { names = (await readdir(base, { withFileTypes: true })).filter((e) => e.isDirectory() && !e.name.startsWith('.') && e.name !== run.meta.id).map((e) => e.name) } catch { return null }
+  const metas = []
+  for (const name of names) { const m = await readJson(join(base, name, 'meta.json'), null); if (m?.scenario?.id === scenario.id && m.environment?.name === run.meta.environment.name) metas.push(m) }
+  metas.sort((a, b) => b.started_at.localeCompare(a.started_at))
+  const already = new Set((await readJsonl(join(run.dir, 'captures.jsonl'))).map((c) => c.node))
+  for (const prev of metas) {
+    const entries = await readJsonl(join(base, prev.id, 'captures.jsonl'))
+    const take = entries.filter((e) => !walked.has(e.node) && !already.has(e.node) && run.meta.scope.locales.includes(e.locale) && (!e.viewport || run.meta.scope.viewports[e.viewport]))
+    if (!take.length) continue
+    const steps = [...new Set(take.map((e) => e.node))]
+    for (const id of steps) {
+      await mkdir(join(run.dir, 'steps'), { recursive: true })
+      await cp(join(base, prev.id, 'steps', id), join(run.dir, 'steps', id), { recursive: true, force: true }).catch(() => {})
+    }
+    for (const e of take) {
+      if (e.type === 'attachment') await cp(join(base, prev.id, e.file), join(run.dir, e.file), { force: true }).catch(() => {})
+      if (e.type === 'capture') { const cap = await readJson(join(run.dir, e.file), null); if (cap) await writeJson(join(run.dir, e.file), { ...cap, carried_from: prev.id }) }
+      await appendJsonl(join(run.dir, 'captures.jsonl'), { ...e, carried_from: prev.id })
+    }
+    return { from: prev.id, steps }
+  }
+  return null
+}
+

package/src/lib/build.mjs

@@ -29,9 +29,14 @@ export async function buildManifest ({ run, scenario, config, root, catalog = []
       const cap = await readJson(join(run.dir, c.file))
       const stored = await readJson(runPaths(run.dir).step(c.node, c.locale, c.viewport, 'eval.json'), null)
       const ev = stored?.source === evaluationSource(node, cap) ? stored : null
-      caps.push({ locale: c.locale, viewport: c.viewport, cap, ev, files: { png: cap.files.png, thumb: cap.files.thumb || null, html: cap.files.html || null, tree: cap.files.tree || null, eval: `steps/${c.node}/${c.locale}/${c.viewport}.eval.json` }, ...(cap.live ? { live: cap.live } : {}) })
+      // the step spec travels as its own file (Dev mode on screenshots, `kaloko spec`, drift on the service)
+      const spec = cap.spec ? `steps/${c.node}/${c.locale}/${c.viewport}.spec.json` : null
+      if (spec) await writeJson(join(run.dir, spec), cap.spec)
+      caps.push({ locale: c.locale, viewport: c.viewport, cap, ev, files: { png: cap.files.png, thumb: cap.files.thumb || null, html: cap.files.html || null, tree: cap.files.tree || null, eval: `steps/${c.node}/${c.locale}/${c.viewport}.eval.json`, spec }, ...(cap.live ? { live: cap.live } : {}) })
     }
-    nodes.push(assembleNode({ node, pos: pos.get(node.id), locales, viewportNames, captures: caps, attachments: attachments.filter((a) => a.node === node.id) }))
+    // focus screenshots of the keyboard walk (#19): only those of the current captures, not of earlier walks
+    const shots = new Set(caps.flatMap((c) => (c.cap.keyboard?.shots || []).map((s) => s.file)))
+    nodes.push(assembleNode({ node, pos: pos.get(node.id), locales, viewportNames, captures: caps, attachments: attachments.filter((a) => a.node === node.id && (a.kind !== 'focus' || shots.has(a.file))) }))
   }
   const summary = summarize(nodes, scenario.sessions)
 
@@ -126,19 +131,39 @@ async function buildStack ({ run, node, base, captures, attachments }) {
   return {
     ...base, status, by_locale, captures: {}, criteria, semantic: {}, metadata: {}, session: node.session || null,
     execution: node.execution ? { strategy: node.execution.strategy, instructions: node.execution.instructions } : { strategy: 'playwright', instructions: 'Open every page of the stack and capture it.' },
-    attachments: attachments.filter((a) => a.node === node.id).map((a) => ({ type: a.kind, title: a.title, file: a.file, locale: a.locale })),
+    attachments: attachments.filter((a) => a.node === node.id && a.kind !== 'focus').map((a) => ({ type: a.kind, title: a.title, file: a.file, locale: a.locale })),
     stack: { count: items.length, items: file, summary, fields, sample, semantic_sample: semanticSample, source: ['urls', 'file', 'sitemap', 'crawl', 'script'].find((k) => src[k]) || null, stale: items.filter((it) => it.stale).length }
   }
 }
 
+/**
+ * Lines for `kaloko build`: semantic criteria that failed or need a person, per step, locale and viewport, with the
+ * score and the one-sentence reason (#17). At most `max` lines.
+ */
+export function attentionLines (manifest, max = 20) {
+  const out = []
+  for (const n of manifest.nodes || []) {
+    for (const c of n.criteria || []) {
+      if (c.type !== 'semantic' || !['fail', 'needs_review'].includes(c.verdict)) continue
+      for (const [l, vps] of Object.entries(c.by_locale || {})) {
+        for (const [vp, r] of Object.entries(vps)) {
+          if (!['fail', 'needs_review'].includes(r.verdict)) continue
+          out.push(`  ${r.verdict === 'fail' ? '✕' : '?'} ${n.id} ${l}/${vp} ${c.id}${r.score != null ? ` ${Math.round(r.score * 100)} %${r.vision ? ' (with screenshot)' : ''}` : ''}${r.reason ? `: ${r.reason}` : r.note ? `: ${r.note}` : ''}`)
+        }
+      }
+    }
+  }
+  return out.length > max ? [...out.slice(0, max), `  … ${out.length - max} more on the canvas`] : out
+}
+
 export async function writePreview ({ run, manifest }) {
   const template = await readFile(join(packageRoot, 'viewer', 'index.html'), 'utf8')
   // the local preview opens from file://, where fetch cannot read files: stack indexes go inline
   // file:// cannot fetch: stack indexes and app UI trees travel inside the preview
   const withTrees = async (n) => {
-    if (!Object.values(n.captures || {}).some((vps) => Object.values(vps).some((c) => c?.tree))) return n
+    if (!Object.values(n.captures || {}).some((vps) => Object.values(vps).some((c) => c?.tree || c?.spec))) return n
     const captures = {}
-    for (const [l, vps] of Object.entries(n.captures)) { captures[l] = {}; for (const [vp, c] of Object.entries(vps)) captures[l][vp] = c?.tree ? { ...c, tree_inline: await readJson(join(run.dir, c.tree), null) } : c }
+    for (const [l, vps] of Object.entries(n.captures)) { captures[l] = {}; for (const [vp, c] of Object.entries(vps)) captures[l][vp] = c?.tree || c?.spec ? { ...c, ...(c.tree ? { tree_inline: await readJson(join(run.dir, c.tree), null) } : {}), ...(c.spec ? { spec_inline: await readJson(join(run.dir, c.spec), null) } : {}) } : c }
     return { ...n, captures }
   }
   // design runs: live steps open from the merged tree, where links between steps resolve (design.mjs copyLive)

package/src/lib/capture.mjs

@@ -2,6 +2,7 @@ import { writeFile, mkdir, rm } from 'node:fs/promises'
 import { dirname, relative, join } from 'node:path'
 import { buildHtmlView } from './htmlview.mjs'
 import { probe } from './probe.mjs'
+import { pageSpecScript } from './devspec.mjs'
 import { writeJson, readJsonl } from './util.mjs'
 import { addCapture, runPaths } from './run.mjs'
 
@@ -37,6 +38,15 @@ export const toWebp = (page, png, opts = {}) => encodeImage(page, png, { ...opts
  * Capture options: scenario-wide `capture:` merged with the node's. Documentation runs use
  * { format: png, scale: 2, mask: [selectors], annotate: true }; daily acceptance keeps the WebP default.
  */
+/** The page spec (src/lib/devspec.mjs), kept under ~250 kB so it fits a design revision's capture record. */
+export async function stepSpec (page, tokens = null) {
+  try {
+    const spec = await page.evaluate(pageSpecScript(tokens))
+    while (spec.elements.length > 20 && JSON.stringify(spec).length > 250000) spec.elements = spec.elements.slice(0, Math.floor(spec.elements.length * 0.8))
+    return spec
+  } catch { return null }
+}
+
 export function captureOptions (scenario, node) {
   const o = { ...(scenario?.capture || {}), ...(node?.capture || {}) }
   const q = Number(o.quality)
@@ -56,6 +66,8 @@ import { consoleEntriesFor } from './console.mjs'
 import { redact, redactDeep } from './secrets.mjs'
 import { readFields } from './stack.mjs'
 import { checkLinks, checkHreflang, requester, walkCache, NETWORK_ASSERTS, isolatedRequest, cacheScope } from './linkcheck.mjs'
+import { keyboardChecks, needsKeyboard, KEYBOARD_ASSERTS } from './keyboard.mjs'
+import { repeatRegions, resolveIgnore } from './stability.mjs'
 
 /** Probe arguments derived from the node's criteria. */
 export function probeArgs (node, maxChars, design = false) {
@@ -74,6 +86,9 @@ export function probeArgs (node, maxChars, design = false) {
 // md-menu, listboxes, tooltips). A step that leaves one open wants it on the capture.
 const OVERLAY = '[role=menu], [role=listbox], [role=tooltip], .MuiPopover-root, .MuiPopper-root, .MuiMenu-root, md-menu-content, .md-open-menu-container.md-active, .md-panel-outer-wrapper.md-panel-is-showing'
 
+const STACK_KEYBOARD = new Map()
+const STACK_KEYBOARD_PAGES = 5
+
 export async function settle (page) {
   try { await page.waitForLoadState('networkidle', { timeout: 5000 }) } catch {}
   try { await page.evaluate(() => document.fonts?.ready) } catch {}
@@ -95,7 +110,7 @@ export async function settle (page) {
  * Captures the current state of `page` for one step and locale in every
  * requested viewport: full-page PNG, rendered HTML, probe results.
  */
-export async function captureStep ({ page, node, locale, viewports, run, consoleFile, maxChars = 90000, since, extra = {}, format = null, options = null, designSummary = false, htmlView = null, item = null, fields = null }) {
+export async function captureStep ({ page, node, locale, viewports, run, consoleFile, maxChars = 90000, since, extra = {}, format = null, options = null, designSummary = false, htmlView = null, item = null, fields = null, tokens = null, stability = 0 }) {
   const opts = { ...(options || captureOptions(null, node)), ...(format ? { format } : {}) }
   // a page of a stack step lives under steps/<node>/items/<item>/…; its capture record names node and item
   const stepId = item ? `${node.id}/items/${item.id}` : node.id
@@ -132,6 +147,12 @@ export async function captureStep ({ page, node, locale, viewports, run, console
         throw error
       }
     }
+    // the step spec (Dev mode, `kaloko spec`, drift): elements with roles, names and styles mapped to the tokens
+    if (probeArgs(node, maxChars, designSummary).design && !item) result.spec = await stepSpec(page, tokens)
+    // regions the scenario ignores in pixel comparisons (#20), as page rectangles of this capture
+    const ignore = await resolveIgnore(page, node, locale, viewport)
+    // what moves while the page sits still (walk --stability N): repeated screenshots, compared here
+    const unstable = stability > 1 ? await repeatRegions(page, { n: Math.min(6, stability), fullPage: opts.fullPage }).catch((error) => ({ error: String(error.message).slice(0, 200) })) : null
     // numbered marks on the highlighted elements, in criteria order (first box of each)
     const annotations = opts.annotate ? Object.entries(result.boxes || {}).filter(([, list]) => list?.length).map(([criterion, list], i) => ({ n: i + 1, criterion, x: list[0].x, y: list[0].y })) : []
     let image = paths.step(stepId, locale, viewport, opts.format)
@@ -168,6 +189,24 @@ export async function captureStep ({ page, node, locale, viewports, run, console
           : { ok: errors.length === 0, evidence: errors.length ? errors.slice(0, 3).join(' | ') : 'no console errors' }
       }
     }
+    // keyboard and screen-reader checks (#19): a Tab walk and the accessibility tree, after the screenshot and after
+    // the console was read (focus handlers of the page must not count as its errors)
+    let keyboard = null
+    // stack steps walk the keyboard on their first few pages only (one template, hundreds of pages)
+    const kbKey = `${run.dir}|${node.id}|${viewport}`
+    const kbSampled = !item || (STACK_KEYBOARD.set(kbKey, (STACK_KEYBOARD.get(kbKey) || 0) + 1).get(kbKey) <= STACK_KEYBOARD_PAGES)
+    if (needsKeyboard(node) && !kbSampled) {
+      for (const c of node.criteria) if (KEYBOARD_ASSERTS.has(c.check.assert)) result.checks[c.id] = { ok: null, evidence: `keyboard walk runs on the first ${STACK_KEYBOARD_PAGES} pages of a stack step` }
+    }
+    if (needsKeyboard(node) && kbSampled) {
+      const kb = await keyboardChecks(page, node.criteria, {
+        saveShot: async (n, png) => { const f = paths.step(stepId, locale, viewport, `focus-${n}.png`); await writeFile(f, png); return relative(run.dir, f) }
+      })
+      Object.assign(result.checks, kb.checks)
+      result.boxes = { ...result.boxes, ...kb.boxes }
+      keyboard = kb.keyboard
+      for (const s of keyboard?.shots || []) await addCapture(run.dir, { type: 'attachment', kind: 'focus', node: node.id, ...(item ? { item: item.id } : {}), locale, viewport, title: `Focus ${s.n}: ${s.name}`, file: s.file, at: new Date().toISOString() })
+    }
     // experimental HTML view (#42): a scrubbed, script-free static copy with rehosted assets
     let view = null
     if (htmlView) {
@@ -189,6 +228,9 @@ export async function captureStep ({ page, node, locale, viewports, run, console
       ...extra,
       http_status: extra.http_status ?? result.http_status ?? null,
       capture: { format: String(image).split('.').pop(), scale: opts.scale, masked: opts.mask.length, annotations, ...(opts.fullPage ? {} : { full_page: false }) },
+      ...(ignore.length ? { ignore } : {}),
+      ...(unstable ? { unstable } : {}),
+      ...(keyboard ? { keyboard } : {}),
       ...(item ? { item: { id: item.id, path: item.path, ...(item.title ? { title: item.title } : {}), ...(item.purpose ? { purpose: item.purpose } : {}) } } : {}),
       ...(fields ? { fields: { ...(await page.evaluate(readFields, fields).catch(() => ({}))), ...(fields.some((f) => (f.from || f.id) === 'http') ? Object.fromEntries(fields.filter((f) => (f.from || f.id) === 'http').map((f) => [f.id, extra.http_status ?? result.http_status ?? null])) : {}) } } : {}),
       files: { png: relative(run.dir, image), image: relative(run.dir, image), thumb: thumbWritten ? relative(run.dir, thumb) : null, html: relative(run.dir, html) }