kaloko 0.4.9 → 0.4.11

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/anim.mjs

@@ -0,0 +1,125 @@
+// Animated previews in pure Node: an animated WebP assembled from single-frame WebP images (the browser encodes each
+// frame, this only writes the container), and a GIF encoder for browsers that cannot encode WebP. Both stay small:
+// a preview is a few seconds of a step at thumbnail size.
+
+const chunk = (fourcc, payload) => {
+  const pad = payload.length % 2
+  const head = Buffer.alloc(8); head.write(fourcc, 0, 'ascii'); head.writeUInt32LE(payload.length, 4)
+  return Buffer.concat([head, payload, pad ? Buffer.alloc(1) : Buffer.alloc(0)])
+}
+const u24 = (n) => { const b = Buffer.alloc(3); b.writeUIntLE(n, 0, 3); return b }
+
+/** Chunks of a still WebP: { width, height, alpha, frame: Buffer of the ALPH + VP8/VP8L chunks }. */
+export function readWebp (buf) {
+  if (buf.toString('ascii', 0, 4) !== 'RIFF' || buf.toString('ascii', 8, 12) !== 'WEBP') throw new Error('not a WebP image')
+  let p = 12; let width = 0; let height = 0; let alpha = false
+  const keep = []
+  while (p + 8 <= buf.length) {
+    const fourcc = buf.toString('ascii', p, p + 4); const size = buf.readUInt32LE(p + 4)
+    const body = buf.subarray(p + 8, p + 8 + size)
+    if (fourcc === 'VP8X') { width = body.readUIntLE(4, 3) + 1; height = body.readUIntLE(7, 3) + 1 } else if (fourcc === 'ALPH') { alpha = true; keep.push(chunk('ALPH', body)) } else if (fourcc === 'VP8 ') {
+      // key frame header: 3-byte tag, start code 9d 01 2a, then 14-bit width and height
+      if (!width) { width = body.readUInt16LE(6) & 0x3fff; height = body.readUInt16LE(8) & 0x3fff }
+      keep.push(chunk('VP8 ', body))
+    } else if (fourcc === 'VP8L') {
+      if (!width) { const bits = body.readUInt32LE(1); width = (bits & 0x3fff) + 1; height = ((bits >>> 14) & 0x3fff) + 1; alpha = !!((bits >>> 28) & 1) }
+      keep.push(chunk('VP8L', body))
+    }
+    p += 8 + size + (size % 2)
+  }
+  if (!keep.length) throw new Error('WebP without image data')
+  return { width, height, alpha, frame: Buffer.concat(keep) }
+}
+
+/** frames: [{ webp: Buffer, ms }] → animated WebP looping forever. */
+export function animatedWebp (frames, { loop = 0, background = [255, 255, 255, 255] } = {}) {
+  if (!frames.length) throw new Error('no frames')
+  const parsed = frames.map((f) => ({ ...readWebp(f.webp), ms: Math.max(20, Math.round(f.ms)) }))
+  const W = Math.max(...parsed.map((f) => f.width)); const H = Math.max(...parsed.map((f) => f.height))
+  const alpha = parsed.some((f) => f.alpha)
+  const vp8x = Buffer.alloc(10); vp8x[0] = 0x02 | (alpha ? 0x10 : 0); vp8x.writeUIntLE(W - 1, 4, 3); vp8x.writeUIntLE(H - 1, 7, 3)
+  const anim = Buffer.alloc(6); anim[0] = background[2]; anim[1] = background[1]; anim[2] = background[0]; anim[3] = background[3]; anim.writeUInt16LE(loop, 4)
+  // each frame covers the canvas without blending (bit 1) and is kept until the next (no dispose)
+  const anmf = parsed.map((f) => chunk('ANMF', Buffer.concat([u24(0), u24(0), u24(f.width - 1), u24(f.height - 1), u24(Math.min(0xffffff, f.ms)), Buffer.from([0x02]), f.frame])))
+  const body = Buffer.concat([Buffer.from('WEBP'), chunk('VP8X', vp8x), chunk('ANIM', anim), ...anmf])
+  const head = Buffer.alloc(8); head.write('RIFF', 0, 'ascii'); head.writeUInt32LE(body.length, 4)
+  return Buffer.concat([head, body])
+}
+
+/** Frames and loop count of an animated WebP (tests). */
+export function webpFrames (buf) {
+  let p = 12; const out = []; let loop = null
+  while (p + 8 <= buf.length) {
+    const fourcc = buf.toString('ascii', p, p + 4); const size = buf.readUInt32LE(p + 4)
+    if (fourcc === 'ANIM') loop = buf.readUInt16LE(p + 12)
+    if (fourcc === 'ANMF') out.push({ width: buf.readUIntLE(p + 14, 3) + 1, height: buf.readUIntLE(p + 17, 3) + 1, ms: buf.readUIntLE(p + 20, 3) })
+    p += 8 + size + (size % 2)
+  }
+  return { loop, frames: out }
+}
+
+// ---------- GIF ----------
+// A fixed 6×7×6 colour cube (252 colours) plus four greys, with 4×4 ordered dithering: no per-frame palette search,
+// stable colours from frame to frame, and small files for flat UI screens.
+const LEVELS = [6, 7, 6]
+const PALETTE = (() => {
+  const p = []
+  for (let r = 0; r < 6; r++) for (let g = 0; g < 7; g++) for (let b = 0; b < 6; b++) p.push([Math.round(r * 255 / 5), Math.round(g * 255 / 6), Math.round(b * 255 / 5)])
+  for (const v of [32, 96, 160, 224]) p.push([v, v, v])
+  return p
+})()
+const BAYER = [0, 8, 2, 10, 12, 4, 14, 6, 3, 11, 1, 9, 15, 7, 13, 5].map((v) => (v + 0.5) / 16 - 0.5)
+
+/** RGBA pixels → palette indices of the colour cube, dithered. */
+export function quantize (rgba, width, height) {
+  const out = new Uint8Array(width * height)
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const i = y * width + x; const d = BAYER[(y & 3) * 4 + (x & 3)]
+      const q = (v, n) => Math.max(0, Math.min(n - 1, Math.round(v / 255 * (n - 1) + d)))
+      out[i] = q(rgba[i * 4], LEVELS[0]) * 42 + q(rgba[i * 4 + 1], LEVELS[1]) * 6 + q(rgba[i * 4 + 2], LEVELS[2])
+    }
+  }
+  return out
+}
+
+/** GIF LZW with 8-bit codes, packed into 255-byte sub-blocks. */
+export function lzw (indices, minCode = 8) {
+  const clear = 1 << minCode; const eoi = clear + 1
+  const bytes = []; let cur = 0; let nbits = 0
+  let size = minCode + 1; let next = eoi + 1
+  let dict = new Map()
+  const emit = (code) => { cur |= code << nbits; nbits += size; while (nbits >= 8) { bytes.push(cur & 0xff); cur >>>= 8; nbits -= 8 } }
+  emit(clear)
+  let prefix = indices[0]
+  for (let i = 1; i < indices.length; i++) {
+    const k = indices[i]; const key = prefix * 256 + k
+    const hit = dict.get(key)
+    if (hit !== undefined) { prefix = hit; continue }
+    emit(prefix)
+    if (next < 4096) { dict.set(key, next++); if (next > (1 << size) && size < 12) size++ } else { emit(clear); dict = new Map(); size = minCode + 1; next = eoi + 1 }
+    prefix = k
+  }
+  emit(prefix); emit(eoi)
+  if (nbits > 0) bytes.push(cur & 0xff)
+  const out = [minCode]
+  for (let i = 0; i < bytes.length; i += 255) { const n = Math.min(255, bytes.length - i); out.push(n, ...bytes.slice(i, i + n)) }
+  out.push(0)
+  return Buffer.from(out)
+}
+
+/** frames: [{ rgba, ms }] of one size → looping GIF. */
+export function encodeGif (frames, { width, height, loop = 0 }) {
+  const parts = [Buffer.from('GIF89a')]
+  const lsd = Buffer.alloc(7); lsd.writeUInt16LE(width, 0); lsd.writeUInt16LE(height, 2); lsd[4] = 0xf7; parts.push(lsd) // global table of 256
+  const table = Buffer.alloc(256 * 3); PALETTE.forEach(([r, g, b], i) => { table[i * 3] = r; table[i * 3 + 1] = g; table[i * 3 + 2] = b }); parts.push(table)
+  parts.push(Buffer.from([0x21, 0xff, 0x0b, ...Buffer.from('NETSCAPE2.0'), 0x03, 0x01, loop & 0xff, loop >> 8, 0x00]))
+  for (const f of frames) {
+    const delay = Math.max(2, Math.round(f.ms / 10))
+    parts.push(Buffer.from([0x21, 0xf9, 0x04, 0x04, delay & 0xff, delay >> 8, 0x00, 0x00]))
+    const desc = Buffer.alloc(10); desc[0] = 0x2c; desc.writeUInt16LE(width, 5); desc.writeUInt16LE(height, 7); parts.push(desc)
+    parts.push(lzw(quantize(f.rgba, width, height)))
+  }
+  parts.push(Buffer.from([0x3b]))
+  return Buffer.concat(parts)
+}