kaloko 0.9.0 → 0.10.0

package/src/lib/manifest-core.mjs

@@ -36,6 +36,23 @@ export function statusOf (verdicts, captured) {
   return 'pass'
 }
 
+// Step states (#46): a step can be captured in several states (default, empty, error, loading); the state is the
+// last part of a capture key (`mobile.state-empty`, `mobile.dark.state-error`). A key without it is the default.
+export const STATE_PREFIX = 'state-'
+/** Fields of a capture record that name its run dimensions (batch E, step states, token modes). */
+export const DIM_FIELDS = ['browser', 'color_scheme', 'reduced_motion', 'forced_colors', 'display_mode', 'token_mode', 'step_state', 'device_preset']
+/** The step state of a capture key: 'default' unless its last part is `state-<name>`. */
+export function stateOfKey (key) {
+  const last = String(key).split('.').slice(1).pop() || ''
+  return last.startsWith(STATE_PREFIX) ? last.slice(STATE_PREFIX.length) : 'default'
+}
+/** States a scenario step is captured in: its `states:` with `default` first (a step without states: ['default']). */
+export const statesOf = (node) => ['default', ...(Array.isArray(node?.states) ? node.states.filter((s) => s !== 'default') : [])]
+/** Does a capture key belong to this step (its state is one of the step's states)? */
+export const keyAppliesTo = (key, node) => statesOf(node).includes(stateOfKey(key))
+/** Does a criterion apply to a capture of this state (`states:` on the criterion; none = every state)? */
+export const appliesToState = (c, state) => !Array.isArray(c?.states) || !c.states.length || c.states.includes(state || 'default')
+
 /** The capture fields a manifest keeps (the full probe record stays with the capture). */
 export function slimCapture (cap) {
   return {
@@ -45,7 +62,7 @@ export function slimCapture (cap) {
     ...(cap.http_status ? { http_status: cap.http_status } : {}), ...(cap.platform ? { platform: cap.platform, device: cap.device || null } : {}),
     ...(cap.design ? { design: cap.design } : {}), ...(cap.capture ? { capture: cap.capture } : {}),
     ...(cap.criteria_hash ? { criteria_hash: cap.criteria_hash } : {}),
-    ...Object.fromEntries(['browser', 'color_scheme', 'reduced_motion', 'forced_colors', 'display_mode', 'device_preset'].filter((k) => cap[k]).map((k) => [k, cap[k]])),
+    ...Object.fromEntries(DIM_FIELDS.filter((k) => cap[k]).map((k) => [k, cap[k]])),
     ...(cap.ignore?.length ? { ignore: cap.ignore } : {}), ...(cap.unstable ? { unstable: cap.unstable } : {}), ...(cap.keyboard ? { keyboard: cap.keyboard } : {})
   }
 }
@@ -58,9 +75,11 @@ export const keyboardOf = (k) => k ? { complete: !!k.complete, total: k.total ??
  * captures: [{ locale, viewport, cap (capture record or slimCapture), ev (valid evaluation or null),
  *              files: { png, html, thumb?, eval? }, live? }]
  */
-export function assembleNode ({ node, pos, locales, viewportNames, captures, attachments = [] }) {
-  const base = { id: node.id, kind: node.kind, title: node.title, path: node.path ?? null, purpose: node.purpose ?? '', col: pos.col, lane: pos.lane }
+export function assembleNode ({ node, pos, locales, viewportNames: allKeys, captures, attachments = [] }) {
+  const base = { id: node.id, kind: node.kind, title: node.title, path: node.path ?? null, purpose: node.purpose ?? '', col: pos.col, lane: pos.lane, ...(node.states?.length ? { states: statesOf(node) } : {}) }
   if (node.kind === 'decision') return { ...base, status: null }
+  // keys of states this step does not have are not missing captures (a step without `states:` has the default only)
+  const viewportNames = allKeys.filter((k) => keyAppliesTo(k, node))
   const applicable = locales.filter((l) => !node.path || typeof node.path === 'string' || (node.path[l] ?? node.path.default))
   const mine = captures.filter((c) => applicable.includes(c.locale) && viewportNames.includes(c.viewport))
   const capturesOut = {}
@@ -73,7 +92,7 @@ export function assembleNode ({ node, pos, locales, viewportNames, captures, att
       png: c.files.png, thumb: c.files.thumb || null, html: c.files.html || null, url: cap.url ?? null,
       ...(cap.platform ? { platform: cap.platform, device: cap.device || null, tree: c.files.tree || null } : {}),
       // run dimensions (batch E): engine, colour scheme, motion, forced colours, display mode, device preset
-      ...Object.fromEntries(['browser', 'color_scheme', 'reduced_motion', 'forced_colors', 'display_mode', 'device_preset'].filter((k) => cap[k]).map((k) => [k, cap[k]])),
+      ...Object.fromEntries(DIM_FIELDS.filter((k) => cap[k]).map((k) => [k, cap[k]])),
       ...(cap.http_status ? { http_status: cap.http_status } : {}),
       ...(cap.capture && (cap.capture.scale !== 1 || cap.capture.format === 'png' || cap.capture.masked || cap.capture.annotations?.length) ? { quality: cap.capture } : {}), size: [cap.size.width, cap.size.height],
       boxes: cap.boxes, captured_at: cap.captured_at, console_errors: (cap.console_errors || []).length, console: (cap.console_errors || []).slice(0, 20), blocked_list: (cap.blocked_requests || []).slice(0, 20),
@@ -111,7 +130,7 @@ export function assembleNode ({ node, pos, locales, viewportNames, captures, att
     // a criterion limited to other environments (environments: [production]) is not applicable on this walk:
     // reported as such, and it does not make the step partial
     const offEnv = entries.some((e) => e.not_applicable) && entries.every((e) => e.not_applicable || e.verdict === 'not_reached')
-    return { ...agg, verdict: aggregate(verdicts), ...(offEnv ? { not_applicable: 'environment' } : {}) }
+    return { ...agg, verdict: aggregate(verdicts), ...(offEnv ? { not_applicable: entries.find((e) => e.not_applicable).not_applicable } : {}) }
   })
   const counting = criteria.filter((c) => !c.not_applicable)
   const byLocale = {}
@@ -150,3 +169,69 @@ export function summarize (nodes, sessions = null) {
   }
   return summary
 }
+
+// ---- stack steps: one step, many pages of one template (or the variants of a design, #61) ----
+
+export const STACK_DEFAULT_FIELDS = [
+  { id: 'title', label: 'Title', from: 'title' },
+  { id: 'h1', label: 'H1', from: 'h1' },
+  { id: 'words', label: 'Words', from: 'words' },
+  { id: 'http', label: 'HTTP', from: 'http' }
+]
+export const STACK_SEMANTIC_SAMPLE = 20
+export const stackFieldsOf = (node) => (node.fields?.length ? node.fields.map((f) => ({ label: f.label || f.id, from: f.from || f.id, ...f })) : STACK_DEFAULT_FIELDS)
+
+/**
+ * A stack step's manifest node and its items index (qawalk.stack.v1), from the captures of its pages. Shared by the CLI
+ * build and the service, which composes design versions with stack steps from a draft.
+ * captures: [{ item, locale, viewport, cap (capture record), ev (valid evaluation or null), files: { png, thumb?, html?, eval } }]
+ * in walk order. Returns { node, index, file } where `file` is the index's path in the run.
+ */
+export function assembleStack ({ node, base, environment = null, captures, attachments = [] }) {
+  const fields = stackFieldsOf(node).map((f) => ({ id: f.id, label: f.label || f.id }))
+  const crit = (node.criteria || []).map((c) => ({ id: c.id, text: c.text, type: c.check.type, pack: c.pack || null, ...(appliesOnEnv(c, environment) ? {} : { not_applicable: 'environment' }) }))
+  // criteria limited to other environments do not decide the status of a page
+  const live = new Set(crit.filter((c) => !c.not_applicable).map((c) => c.id))
+  const byItem = new Map()
+  for (const c of captures) {
+    const { cap, ev } = c
+    let it = byItem.get(c.item)
+    if (!it) { it = { id: c.item, path: cap.item?.path || null, url: cap.url, title: cap.item?.title || cap.fields?.title || cap.metadata?.title || null, fields: cap.fields || {}, captures: {}, results: {}, order: byItem.size }; byItem.set(c.item, it) }
+    ;(it.captures[c.locale] ||= {})[c.viewport] = { png: c.files.png, thumb: c.files.thumb || null, html: c.files.html || null, url: cap.url, size: cap.size ? (Array.isArray(cap.size) ? cap.size : [cap.size.width, cap.size.height]) : null, boxes: cap.boxes, captured_at: cap.captured_at, console_errors: (cap.console_errors || []).length, console: (cap.console_errors || []).slice(0, 10), overflow: (cap.overflow || []).length, meta: cap.meta, ...(cap.http_status ? { http_status: cap.http_status } : {}), ...(cap.capture?.full_page === false ? { first_screen: true } : {}), ...(c.live ? { live: c.live } : {}), ...Object.fromEntries(DIM_FIELDS.filter((k) => cap[k]).map((k) => [k, cap[k]])), eval: ev ? c.files.eval : null }
+    // a criterion limited to other step states (#46) does not decide this capture
+    it.results[`${c.locale}|${c.viewport}`] = ev ? Object.fromEntries((ev.criteria || []).filter((r) => r.not_applicable !== 'state').map((r) => [r.id, [r.verdict, r.evidence ? String(r.evidence).slice(0, 200) : null, r.score ?? null]])) : Object.fromEntries(crit.filter((x) => x.type !== 'semantic').map((x) => [x.id, ['not_evaluated', null, null]]))
+    if (!ev) it.stale = true
+  }
+  const items = [...byItem.values()].sort((a, b) => a.order - b.order).map(({ order, ...it }) => {
+    const per = Object.values(it.results)
+    const verdictOf = (id) => worst(per.map((r) => r[id]?.[0]).filter(Boolean))
+    const verdicts = crit.filter((c) => live.has(c.id)).map((c) => verdictOf(c.id)).filter((v) => v !== 'not_reached')
+    const status = statusOf(verdicts, per.length > 0)
+    const by_locale = Object.fromEntries(Object.keys(it.captures).map((l) => [l, statusOf(Object.entries(it.results).filter(([k]) => k.startsWith(`${l}|`)).flatMap(([, r]) => Object.entries(r).filter(([id]) => live.has(id)).map(([, x]) => x[0])), true)]))
+    return { ...it, status, by_locale, fails: crit.filter((c) => live.has(c.id) && verdictOf(c.id) === 'fail').map((c) => c.id), review: crit.filter((c) => live.has(c.id) && ['needs_review', 'not_evaluated'].includes(verdictOf(c.id))).map((c) => c.id) }
+  })
+  const summary = { pass: 0, partial: 0, fail: 0, skip: 0 }
+  for (const it of items) summary[it.status]++
+  const criteria = crit.map((c) => {
+    const counts = {}
+    for (const it of items) { const v = worst(Object.values(it.results).map((r) => r[c.id]?.[0]).filter(Boolean)); if (v !== 'not_reached') counts[v] = (counts[v] || 0) + 1 }
+    return { ...c, counts, verdict: counts.fail ? 'fail' : counts.needs_review ? 'needs_review' : counts.not_evaluated ? 'not_evaluated' : counts.pass ? 'pass' : 'not_reached', by_locale: {} }
+  })
+  const semanticSample = node.items?.semantic_sample ?? STACK_SEMANTIC_SAMPLE
+  const file = `steps/${node.id}/items.json`
+  const index = { schema: 'qawalk.stack.v1', node: node.id, fields, criteria: crit, semantic_sample: semanticSample, items }
+  const thumbOf = (it) => { const c = Object.values(it.captures)[0]; const v = c && Object.values(c)[0]; return v ? v.thumb || v.png : null }
+  const sample = [...items.filter((it) => it.status === 'fail'), ...items.filter((it) => it.status !== 'fail')].slice(0, 4).map((it) => ({ id: it.id, title: it.title, path: it.path, status: it.status, thumb: thumbOf(it) }))
+  const status = !items.length ? 'skip' : summary.fail ? 'fail' : summary.partial || summary.skip ? 'partial' : 'pass'
+  const locales = [...new Set(items.flatMap((it) => Object.keys(it.by_locale)))]
+  const by_locale = Object.fromEntries(locales.map((l) => { const s = items.map((it) => it.by_locale[l]).filter(Boolean); return [l, s.includes('fail') ? 'fail' : s.some((x) => x !== 'pass') ? 'partial' : 'pass'] }))
+  const src = node.items || {}
+  const out = {
+    ...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 && 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 }
+  }
+  return { node: out, index, file }
+}
+const appliesOnEnv = (c, environment) => !environment || !Array.isArray(c.environments) || !c.environments.length || c.environments.includes(environment)

package/src/lib/spec-cli.mjs

@@ -7,6 +7,7 @@ import { readJson, UserError } from './util.mjs'
 import { readCaptures } from './run.mjs'
 import { latestCaptures } from './evaluate.mjs'
 import { specText, specDrift, driftText } from './devspec.mjs'
+import { stateOfKey } from './manifest-core.mjs'
 
 const enc = encodeURIComponent
 
@@ -27,19 +28,21 @@ export async function specCmd ({ config, client, run, scenario, scenarioId, args
   const step = typeof args._[0] === 'string' ? args._[0] : typeof args.step === 'string' ? args.step : null
   const locale = typeof args.locale === 'string' ? args.locale : null
   const viewport = typeof args.viewport === 'string' ? args.viewport : null
+  // a step state (#46): its captures (keys <viewport>.state-<name>); default otherwise
+  const state = typeof args.state === 'string' ? args.state : null
   const steps = step ? [step] : (scenario?.nodes || []).filter((n) => n.kind !== 'decision' && n.kind !== 'external').map((n) => n.id)
-  if (!steps.length) throw new UserError('Usage: kaloko spec <step> [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--local] [--json]')
+  if (!steps.length) throw new UserError('Usage: kaloko spec <step> [--ref design|draft|vN|<run id>] [--locale l] [--viewport v] [--state s] [--local] [--json]')
   const out = []
   for (const s of steps) {
     if (args.local || !client) {
       if (!run) throw new UserError('--local needs a run: pass --run <id> or start one.')
-      const list = (await localSpecs(run, { step: s, locale, viewport })).filter((x) => locale || x.locale === (run.meta.scope?.locales?.[0] || x.locale))
-      const one = pickOne(list, viewport)
+      const list = (await localSpecs(run, { step: s, locale, viewport: viewport && state ? null : viewport })).filter((x) => (locale || x.locale === (run.meta.scope?.locales?.[0] || x.locale)) && stateOfKey(x.viewport) === (state || (viewport ? stateOfKey(viewport) : 'default')))
+      const one = pickOne(list, viewport && state && stateOfKey(viewport) === 'default' ? `${viewport}.state-${state}` : viewport)
       if (!one) continue
       out.push({ node: s, locale: one.locale, viewport: one.viewport, ref: 'local', spec: one.spec })
     } else {
       const ref = typeof args.ref === 'string' ? args.ref : typeof args.version === 'string' || typeof args.version === 'number' ? `v${args.version}` : 'design'
-      const q = new URLSearchParams(Object.entries({ ref, locale, viewport }).filter(([, v]) => v))
+      const q = new URLSearchParams(Object.entries({ ref, locale, viewport, state }).filter(([, v]) => v))
       try {
         const d = await client.request('GET', `/orgs/${config.org}/scenarios/${enc(scenarioId)}/steps/${enc(s)}/spec?${q}`)
         out.push({ node: s, locale: d.locale, viewport: d.viewport, ref: d.ref, spec: d.spec })

package/src/lib/stack.mjs

@@ -6,16 +6,13 @@ import { resolve, extname } from 'node:path'
 import { pathToFileURL } from 'node:url'
 import { createHash } from 'node:crypto'
 import { UserError } from './util.mjs'
+import { STACK_DEFAULT_FIELDS, STACK_SEMANTIC_SAMPLE, stackFieldsOf } from './manifest-core.mjs'
 
 export const DEFAULT_LIMIT = 500
-export const DEFAULT_SEMANTIC_SAMPLE = 20
-export const DEFAULT_FIELDS = [
-  { id: 'title', label: 'Title', from: 'title' },
-  { id: 'h1', label: 'H1', from: 'h1' },
-  { id: 'words', label: 'Words', from: 'words' },
-  { id: 'http', label: 'HTTP', from: 'http' }
-]
-export const fieldsOf = (node) => (node.fields?.length ? node.fields.map((f) => ({ label: f.label || f.id, from: f.from || f.id, ...f })) : DEFAULT_FIELDS)
+// fields and the semantic sample live with the pure stack assembly (manifest-core.mjs), which the service shares
+export const DEFAULT_SEMANTIC_SAMPLE = STACK_SEMANTIC_SAMPLE
+export const DEFAULT_FIELDS = STACK_DEFAULT_FIELDS
+export const fieldsOf = stackFieldsOf
 
 const slug = (s) => String(s || '').toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '')
 /** Stable, readable id of a page: the path as a slug (≤ 60 chars) plus a short hash when needed. */

package/src/lib/tokens.mjs

@@ -174,6 +174,22 @@ export function cssValue (type, v) {
 }
 
 /** Structural problems of a set or resolver: names, references that point nowhere, unreadable values. */
+/**
+ * A token mode as CSS (#46): every token with a plain value as a custom property on :root, named after its path
+ * (`color.brand.primary` → `--color-brand-primary`), the way live pages reference tokens. Composite values
+ * (typography, shadow) also get one property per part (`--type-body-font-size`). A design step rendered in a mode
+ * gets this sheet after its own styles.
+ */
+export function modeCss (set, mode) {
+  const safe = (v) => String(v).replace(/[;{}<>\\]/g, '')
+  const lines = []
+  const prop = (name, v) => { if (v != null && (typeof v === 'string' || typeof v === 'number') && String(v).length < 400) lines.push(`--${name.replace(/[^A-Za-z0-9_-]+/g, '-')}:${safe(v)}`) }
+  for (const t of flattenTokens(set, mode)) {
+    if (t.value && typeof t.value === 'object' && !Array.isArray(t.value)) { for (const [k, v] of Object.entries(t.value)) prop(`${t.name}-${k.replace(/[A-Z]/g, (c) => '-' + c.toLowerCase())}`, v) } else prop(t.name, t.value)
+  }
+  return lines.length ? `:root{${lines.join(';')}}` : ''
+}
+
 export function validateTokens (set) {
   if (!set || typeof set !== 'object' || Array.isArray(set)) return ['A token set is a JSON object.']
   const problems = []

package/src/lib/walk-dimensions.mjs

@@ -2,19 +2,40 @@
 // capture takes, and the lines the CLI prints. The rules themselves live in dimensions.mjs.
 import { UserError } from './util.mjs'
 import { isApp } from './apps/drivers.mjs'
-import { resolveViewports, expandScope, dimensionsFrom, appDevices, variantOf, pickKeys, DIMENSIONS } from './dimensions.mjs'
+import { resolveViewports, expandScope, dimensionsFrom, appDevices, variantOf, pickKeys, stateOf, FREE_VALUE, DIMENSIONS } from './dimensions.mjs'
 
 const list = (v) => (typeof v === 'string' ? v.split(',').map((s) => s.trim()).filter(Boolean) : Array.isArray(v) ? v : null)
 
+/**
+ * Token modes a design run renders (#46): the modes of the token set (`tokenModes`, from modesOf) whose names fit
+ * a capture key, the environment's tokens_mode first (it is the default, left out of keys). `token_modes:` in the
+ * environment, the scenario or --token-modes picks some (false: none). A set with only light and dark modes leaves
+ * them to the colour scheme (color_schemes: [light, dark]), as before, unless they are picked. Null when fewer than
+ * two modes are left.
+ */
+export function designTokenModes ({ tokenModes = [], chosen = null, env = {} }) {
+  const modes = (tokenModes || []).filter((m) => FREE_VALUE.test(m))
+  if (chosen === false || env.token_modes === false) return null
+  const want = chosen || (Array.isArray(env.token_modes) ? env.token_modes : null)
+  if (want) for (const m of want) if (!modes.includes(m)) throw new UserError(`Token mode "${m}" is not in the token set (its modes: ${modes.join(', ') || 'none'}).`)
+  let out = want ? modes.filter((m) => want.includes(m)) : modes
+  if (!want && out.every((m) => ['light', 'dark'].includes(m))) out = []
+  if (out.length < 2) return null
+  const first = env.tokens_mode && out.includes(env.tokens_mode) ? env.tokens_mode : out[0]
+  return [first, ...out.filter((m) => m !== first)]
+}
+
 /**
  * The scope of a new run: viewports (sizes and device presets), app devices and the dimensions from the CLI,
  * the scenario and the config. Web runs take every dimension; app runs take devices, colour scheme and motion;
- * Design environments render in Chromium with presets at their whole screen.
+ * Design environments render in Chromium with presets at their whole screen, in every mode of the token set
+ * (`tokenModes`). Steps with `states:` add the step state dimension on every platform.
  */
-export function startScope ({ args = {}, scenario, config, env }) {
+export function startScope ({ args = {}, scenario, config, env, tokenModes = [] }) {
   const platform = scenario.platform || 'web'
   const dims = dimensionsFrom({ args, scenario, config })
   const design = env?.kind === 'design'
+  dims.token_modes = design ? designTokenModes({ tokenModes, chosen: dims.token_modes, env }) : null
   if (isApp(platform) || design) {
     for (const k of ['browsers', 'display_modes']) if (dims[k] && (args[k.replace(/_/g, '-')] || scenario[k])) throw new UserError(`${k.replace(/_/g, ' ')} apply to web runs; ${design ? 'design steps render in Chromium' : `a ${platform} app walks on its devices`}.`)
     dims.browsers = null; dims.display_modes = null
@@ -70,7 +91,8 @@ export function appDeviceGroups (scope, only = null) {
   const keys = Object.keys(scope?.viewports || {})
   const bases = baseViewports(scope)
   const devices = bases.filter((b) => scope.devices?.[b]?.app)
-  const keysOf = (base) => keys.filter((k) => variantOf(scope, k).viewport === base)
+  // one walk per state of a step: the keys of the default state; the others follow from them (stateKeys)
+  const keysOf = (base) => keys.filter((k) => variantOf(scope, k).viewport === base && stateOf(k) === 'default')
   if (devices.length) {
     const picked = devices.filter((id) => !only || only.includes(id))
     if (!picked.length) throw new UserError(`This run has no device ${only.join(', ')} (its devices: ${devices.join(', ')}).`)
@@ -79,5 +101,8 @@ export function appDeviceGroups (scope, only = null) {
   return [{ device: null, title: null, keys: bases.length ? keysOf(bases[0]) : [] }]
 }
 
-/** Keys of one engine (a capture on the shared Chromium takes the Chromium keys). */
-export const engineKeys = (scope, engine = 'chromium') => Object.keys(scope?.viewports || {}).filter((k) => variantOf(scope, k).browser === engine)
+/**
+ * Keys of one engine (a capture on the shared Chromium takes the Chromium keys), of the default step state unless
+ * `state` names another one (`*`: every state, a design walk).
+ */
+export const engineKeys = (scope, engine = 'chromium', state = 'default') => Object.keys(scope?.viewports || {}).filter((k) => variantOf(scope, k).browser === engine && (state === '*' || stateOf(k) === state))