@defrex/autobuild 0.8.0

package/packages/core/src/config/roles.ts

@@ -0,0 +1,438 @@
+/**
+ * Role-key consumability diagnostics (SPEC §9).
+ *
+ * `[roles]` is an open map, so a `[roles.<name>]` entry whose name nothing
+ * consumes is accepted, eagerly resolved, validated — and then never looked up.
+ * The session that was meant to run on it runs on `[roles.default]` instead.
+ * This module is the pure derivation that lets `ab dispatch` say so at startup.
+ * It never throws and never changes which runtime, model, or args run.
+ *
+ * TWO MECHANISMS, DELIBERATELY KEPT APART. No notice, comment, or document may
+ * say a declared key "inherits default":
+ *
+ * - *Declaration.* `createRuntimeResolver` eagerly resolves EVERY declared role
+ *   by merging its own fields over `default` independently per field
+ *   (`src/ports/runner/routing.ts`). `[roles.ghost]` with its own runtime and
+ *   model resolves to exactly that pair, and is validated — an unconsumed role
+ *   naming an unregistered runtime still fails `ab dispatch` loudly. The
+ *   warnings here neither suppress nor compete with that error.
+ * - *Lookup.* `resolve(role, ...aliases)` returns the validated
+ *   `[roles.default]` result when NO candidate key is declared. That wholesale
+ *   fallback is what silently runs a verify step on the default model.
+ *
+ * The harm named here is the pair of the two: a key declared on one side and
+ * never requested on the other.
+ */
+import { CORE_PHASES } from '../ontology'
+import type { Config } from './schema'
+
+// ── Vocabulary ───────────────────────────────────────────────────────────────
+
+/** `ab dispatch`'s pre-build title completion (src/cli/dispatch.ts). */
+export const SLUG_ROLE = 'slug'
+/** `ab upgrade`'s skill-conflict resolver (src/cli/upgrade-agent.ts). */
+export const UPGRADE_ROLE = 'upgrade'
+/** The harvest run's synthesize session (src/processes/harvest-runner.ts). */
+export const HARVEST_ROLE = 'harvest'
+/** The harvest run's review session (src/processes/harvest-runner.ts). */
+export const HARVEST_REVIEW_ROLE = 'harvest-review'
+
+/**
+ * Roles the pipeline requests outside the configured phases and steps. These
+ * are shared constants rather than bare string literals at their call sites so
+ * a consumer and this diagnostic cannot drift apart — a consumable key missing
+ * from here would become a false "unconsumed" warning, which is the same class
+ * of bug this module exists to report.
+ */
+export const INTERNAL_ROLES = [SLUG_ROLE, UPGRADE_ROLE, HARVEST_ROLE, HARVEST_REVIEW_ROLE] as const
+
+/** The reserved `[roles]` inheritance base (§9). Never reported unconsumed. */
+export const RESERVED_ROLE = 'default'
+
+// ── Derivation ───────────────────────────────────────────────────────────────
+
+/** Every consumer a declared key has, of every kind. */
+export interface RoleKeyConsumers {
+  key: string
+  /** The human phrase for this key's own canonical use, when it has one. */
+  canonicalUse?: string
+  /** Agent verify steps this key currently ROUTES through the deprecated
+   * skill-name convention — the step declares no `[roles.<step>]` of its own. */
+  activeAlias: string[]
+  /** Agent verify steps whose configured skill is this key but which declare
+   * their own step-named role, so the key is inert for them. */
+  supersededAlias: string[]
+}
+
+export interface RoleKeyDiagnostics {
+  /** The sorted canonical keys this configuration can consume. Deliberately
+   * excludes deprecated aliases: the message must not teach the dying form. */
+  valid: string[]
+  /** Declared keys with no consumer of any kind, sorted. */
+  unconsumed: string[]
+  /** Declared keys a deprecated skill-name alias reaches, sorted by key —
+   * both the still-routing and the superseded-and-inert cases. */
+  deprecated: RoleKeyConsumers[]
+}
+
+/** The structural shape both `[verify.<step>]` and `[finalize.<step>]` share. */
+type StepTable = { kind: 'check' } | { kind: 'agent'; skill: string }
+
+export interface RuntimeReferenceGroup {
+  runtime: string
+  /** Human-readable routes selecting this runtime, including alternates. */
+  references: string[]
+  /** Explicit configured models selected for readiness probing. */
+  models: string[]
+  /** At least one selected route leaves its model to the runtime registration. */
+  usesRuntimeDefaultModel: boolean
+}
+
+/**
+ * Derive the runtime targets that can actually start sessions. This mirrors the
+ * resolver's per-axis inheritance, role/alias precedence, and alternate overlay
+ * without requiring a runtime registry, so config validation and remote
+ * bootstrap share one source of truth.
+ */
+export function effectiveRuntimeReferences(
+  config: Pick<Config, 'roles' | 'verify' | 'finalize'>,
+): RuntimeReferenceGroup[] {
+  const defaultSpec = config.roles.default ?? {}
+  const routes: Array<{ role: string; aliases?: string[]; label: string }> = [
+    ...CORE_PHASES.map((role) => ({ role, label: `role ${displayName(role)}` })),
+    ...INTERNAL_ROLES.map((role) => ({ role, label: `role ${displayName(role)}` })),
+    ...agentSteps(config.verify.steps, config.verify.stepConfigs).map(({ step, skill }) => ({
+      role: step,
+      aliases: [skill],
+      label: `agent verify role ${displayName(step)}`,
+    })),
+    ...agentSteps(config.finalize.steps, config.finalize.stepConfigs).map(({ step }) => ({
+      role: step,
+      label: `agent finalize role ${displayName(step)}`,
+    })),
+  ]
+
+  const grouped = new Map<
+    string,
+    { references: Set<string>; models: Set<string>; usesRuntimeDefaultModel: boolean }
+  >()
+  const declaredSpec = (role: string, aliases: readonly string[] = []) => {
+    for (const key of [role, ...aliases]) {
+      if (key === RESERVED_ROLE) return defaultSpec
+      if (Object.hasOwn(config.roles, key)) return config.roles[key]!
+    }
+    return defaultSpec
+  }
+  const add = (runtime: string | undefined, model: string | undefined, reference: string) => {
+    if (runtime === undefined || runtime.trim() === '') return
+    const group = grouped.get(runtime) ?? {
+      references: new Set(),
+      models: new Set(),
+      usesRuntimeDefaultModel: false,
+    }
+    group.references.add(reference)
+    if (model !== undefined) group.models.add(model)
+    else group.usesRuntimeDefaultModel = true
+    grouped.set(runtime, group)
+  }
+
+  for (const route of routes) {
+    const spec = declaredSpec(route.role, route.aliases)
+    const runtime = spec.runtime ?? defaultSpec.runtime
+    const model = spec.model ?? defaultSpec.model
+    add(runtime, model, `${route.label} primary`)
+    const alternates = spec.alternates ?? defaultSpec.alternates ?? []
+    alternates.forEach((alternate, index) => {
+      add(
+        alternate.runtime ?? runtime,
+        alternate.model ?? model,
+        `${route.label} alternate[${index}]`,
+      )
+    })
+  }
+
+  return [...grouped.entries()]
+    .sort(([left], [right]) => (left < right ? -1 : left > right ? 1 : 0))
+    .map(([runtime, group]) => ({
+      runtime,
+      references: [...group.references].sort(),
+      models: [...group.models].sort(),
+      usesRuntimeDefaultModel: group.usesRuntimeDefaultModel,
+    }))
+}
+
+/** Declared steps that actually run, in declaration order, agent kind only —
+ * a `kind = "check"` step starts no session and consumes no role. */
+function agentSteps(
+  steps: readonly string[],
+  stepConfigs: Record<string, StepTable>,
+): { step: string; skill: string }[] {
+  const agents: { step: string; skill: string }[] = []
+  const seen = new Set<string>()
+  for (const step of steps) {
+    if (seen.has(step)) continue
+    seen.add(step)
+    // OWN property, for the same reason `declared` below is spelled out: step
+    // names are user-chosen from an open set, so `constructor` and `toString`
+    // are legal, and a bare read would answer an inherited function for a
+    // listed-but-tableless step. Cross-validation rejects that config before it
+    // can reach here, so this is redundant in practice — it keeps the read
+    // sound on its own rather than on a guarantee made in another file.
+    if (!Object.hasOwn(stepConfigs, step)) continue
+    const table = stepConfigs[step]!
+    if (table.kind !== 'agent') continue
+    agents.push({ step, skill: table.skill })
+  }
+  return agents
+}
+
+// ── Rendering a user-chosen name ─────────────────────────────────────────────
+//
+// Role names, verify step names, and finalize step names are ARBITRARY nonempty
+// strings. Every one of them reaches an operator's terminal, so every one is
+// rendered through `displayName`/`tomlKey` below and never hand-quoted or
+// interpolated bare. Two failures follow from getting this wrong, and both have
+// happened: `[roles.ui.visual]` is not the key it looks like (TOML reads the dot
+// as nesting), and a name carrying a newline splits ONE notice into two physical
+// stderr lines, breaking the one-notice-per-line contract every surface
+// downstream assumes.
+
+/** TOML bare keys are letters, digits, `-`, and `_` only. */
+const TOML_BARE_KEY = /^[A-Za-z0-9_-]+$/
+
+/**
+ * The body of a TOML basic string, escaped on an ALLOWLIST: a character is
+ * emitted raw only when it is printable ASCII a basic string accepts unescaped.
+ * Everything else — every C0 control, U+007F, and every non-ASCII code point —
+ * becomes TOML's own `\uXXXX`, or `\UXXXXXXXX` above the BMP.
+ *
+ * The allowlist is the whole design. `JSON.stringify` was the escaper here for
+ * three rounds and is a DENYLIST: it escapes C0 controls, then passes U+007F
+ * through raw, then passes every other non-ASCII code point through raw. Each
+ * gap was found and patched one code point at a time, which is not a process
+ * that terminates. Nothing outside the allowlist can reach a terminal now,
+ * whatever it is, and there is no per-character rule left to get wrong.
+ *
+ * Iterating with `for…of` walks code points, so an astral character is escaped
+ * once as `\U0001F600` rather than as two lone surrogates — which TOML rejects
+ * outright and which therefore would not round-trip.
+ */
+function escapeBasic(name: string): string {
+  let out = ''
+  for (const char of name) {
+    const code = char.codePointAt(0)!
+    if (char === '"' || char === '\\') out += `\\${char}`
+    else if (code >= 0x20 && code <= 0x7e) out += char
+    else if (code > 0xffff) out += `\\U${code.toString(16).toUpperCase().padStart(8, '0')}`
+    else out += `\\u${code.toString(16).toUpperCase().padStart(4, '0')}`
+  }
+  return out
+}
+
+/** A name IN PROSE — always quoted, always escaped. The one place a name is
+ * wrapped in quotes, so a quote cannot break out of the phrase and nothing
+ * unprintable can reach a line-oriented sink raw. */
+export function displayName(name: string): string {
+  return `"${escapeBasic(name)}"`
+}
+
+/**
+ * A name AS THE OPERATOR MUST TYPE IT in a table header: bare when TOML's
+ * bare-key grammar accepts it — which keeps every ordinary notice
+ * byte-identical — and otherwise the quoted prose form, unchanged. The two
+ * renderings differ in exactly that one condition and share the escaper, so
+ * they cannot drift into disagreeing about what is safe.
+ */
+export function tomlKey(name: string): string {
+  return TOML_BARE_KEY.test(name) ? name : displayName(name)
+}
+
+/** The table header to write, quoted when the name needs it. */
+const roleTable = (name: string): string => `[roles.${tomlKey(name)}]`
+
+/**
+ * Classify every declared `[roles.<key>]` against every consumer it has.
+ * Iterates `steps` rather than the `stepConfigs` key sets so only steps that
+ * actually run contribute; cross-validation already guarantees the two agree.
+ */
+export function roleKeyDiagnostics(config: Config): RoleKeyDiagnostics {
+  const verifyAgents = agentSteps(config.verify.steps, config.verify.stepConfigs)
+  const finalizeAgents = agentSteps(config.finalize.steps, config.finalize.stepConfigs)
+
+  // `default` is tested FIRST so the reserved phrase always wins, which is also
+  // what keeps the rename/delete advice structurally unreachable for it.
+  //
+  // Every arm renders through `displayName`, including the two whose names come
+  // from fixed lists. Those two are safe on their own, but a phrase built here
+  // is appended verbatim to a notice by the shared/colliding branch, and one
+  // uniform rule is what stops the next arm added to this list from being the
+  // hand-quoted one.
+  const canonicalUse = (key: string): string | undefined => {
+    if (key === RESERVED_ROLE) return `the reserved ${roleTable(RESERVED_ROLE)} inheritance base`
+    if ((CORE_PHASES as readonly string[]).includes(key)) {
+      return `the ${displayName(key)} core phase role`
+    }
+    if (verifyAgents.some((agent) => agent.step === key)) {
+      return `agent verify step ${displayName(key)}`
+    }
+    if (finalizeAgents.some((agent) => agent.step === key)) {
+      return `agent finalize step ${displayName(key)}`
+    }
+    if ((INTERNAL_ROLES as readonly string[]).includes(key)) {
+      return `the internal ${displayName(key)} role`
+    }
+    return undefined
+  }
+
+  // MUST mirror the resolver's candidate walk (src/ports/runner/routing.ts),
+  // reserved arm included: a step named `default` always has its step-named
+  // role declared, so its skill-name alias really is inert. The `||` arm is
+  // redundant in practice — construction fails without `[roles.default]` — but
+  // it keeps the two implementations of "declared" from drifting apart.
+  const declared = (step: string): boolean =>
+    step === RESERVED_ROLE || Object.hasOwn(config.roles, step)
+
+  const valid = [
+    ...new Set([
+      RESERVED_ROLE,
+      ...CORE_PHASES,
+      ...verifyAgents.map((agent) => agent.step),
+      ...finalizeAgents.map((agent) => agent.step),
+      ...INTERNAL_ROLES,
+    ]),
+  ].sort()
+
+  const unconsumed: string[] = []
+  const deprecated: RoleKeyConsumers[] = []
+
+  for (const key of Object.keys(config.roles).sort()) {
+    const use = canonicalUse(key)
+    // A step whose own name IS the key has no alias at all: the key is
+    // canonical for it, and step-name precedence means it routes that way.
+    const aliasFor = verifyAgents.filter((agent) => agent.skill === key && agent.step !== key)
+    const activeAlias = aliasFor.filter((a) => !declared(a.step)).map((a) => a.step)
+    const supersededAlias = aliasFor.filter((a) => declared(a.step)).map((a) => a.step)
+
+    if (activeAlias.length > 0 || (supersededAlias.length > 0 && use === undefined)) {
+      deprecated.push({
+        key,
+        ...(use !== undefined ? { canonicalUse: use } : {}),
+        activeAlias,
+        supersededAlias,
+      })
+      continue
+    }
+    // Fully consumed. An inert alias on an already-canonical key needs no
+    // advice, and `canonicalUse(RESERVED_ROLE)` is what exempts the reserved
+    // key from the unconsumed bucket — structurally, not by an early skip.
+    if (use !== undefined) continue
+    unconsumed.push(key)
+  }
+
+  return { valid, unconsumed, deprecated }
+}
+
+// ── Notices ──────────────────────────────────────────────────────────────────
+//
+// One string per key, so advice is never blanket, and every branch's advice is
+// safe to follow literally — which means BOTH that following it converges (one
+// edit, then silence) and that what it tells you to type is valid TOML. Two
+// shape constraints: the key and its replacement land in the FIRST CLAUSE, so
+// they are on the first rendered row at any realistic width; and the valid-key
+// list is its own string, so it starts at column 0 of its own row instead of
+// trailing a paragraph. House style is subject-first, `subject: predicate —
+// detail`, with no `warning:` prefix.
+
+function andList(parts: readonly string[]): string {
+  if (parts.length <= 1) return parts[0] ?? ''
+  if (parts.length === 2) return `${parts[0]} and ${parts[1]}`
+  return `${parts.slice(0, -1).join(', ')}, and ${parts[parts.length - 1]}`
+}
+
+/** Step names in prose — each through `displayName`, never hand-quoted. */
+const named = (steps: readonly string[]): string => andList(steps.map(displayName))
+
+const roleTables = (names: readonly string[]): string => andList(names.map(roleTable))
+
+function deprecationNotice(entry: RoleKeyConsumers): string {
+  const { key, canonicalUse, activeAlias, supersededAlias } = entry
+
+  // A SUPERSEDED alias is not a consumer. It is inert by definition — the step
+  // declares its own step-named role, which wins — so it can never be a reason
+  // to keep this key, and it never blocks the rename. Counting it as one made
+  // the advice non-converging: "keep it, it is also the superseded key for
+  // e2e", followed on the next dispatch by "it can be deleted".
+
+  // Inert: the key routes nothing at all.
+  if (activeAlias.length === 0) {
+    const subject =
+      supersededAlias.length === 1
+        ? `agent verify step ${named(supersededAlias)} declares its own step-named role`
+        : `agent verify steps ${named(supersededAlias)} each declare their own step-named role`
+    return (
+      `autobuild.toml: ${roleTable(key)} can be deleted — ${subject}, so this ` +
+      `deprecated skill-name key changes nothing.`
+    )
+  }
+
+  // Safe rename: one step still routed and no OTHER consumer, so the key moves
+  // in one edit. Superseded steps are deliberately not "other consumers".
+  if (canonicalUse === undefined && activeAlias.length === 1) {
+    return (
+      `autobuild.toml: ${roleTable(key)} should be ${roleTable(activeAlias[0]!)} — it is the ` +
+      `deprecated skill-name key for agent verify step ${named(activeAlias)} and stops ` +
+      `working in a future release.`
+    )
+  }
+
+  // Shared or colliding: the key routes several steps, or its name is itself
+  // canonical, so the advice is to declare each step and then keep or delete.
+  const routed =
+    activeAlias.length === 1
+      ? 'it routes that agent verify step through the deprecated skill-name key'
+      : 'it routes those agent verify steps through the deprecated skill-name key'
+  const advice =
+    canonicalUse !== undefined
+      ? `Keep ${roleTable(key)}: it is also ${canonicalUse}.`
+      : `Delete ${roleTable(key)} once those are declared.`
+  return `autobuild.toml: ${roleTable(key)} should be ${roleTables(activeAlias)} — ${routed}. ${advice}`
+}
+
+/**
+ * The rendered notices — THE one message set. Empty for a clean configuration.
+ *
+ * Order: the unconsumed-keys line, then the valid-key line (only when there are
+ * unconsumed keys), then one notice per deprecated key in key order. Every
+ * surface renders these exact strings in full: nothing here or downstream may
+ * cap, summarize, or truncate them, or a surface would report that a class of
+ * problem exists without naming the keys the operator has to change.
+ *
+ * The unconsumed line deliberately stops at the harm and does not explain what
+ * runs instead — that belongs in SPEC §9 and `docs/configuration.md`, and
+ * putting it here pushed the required valid-key list past the right edge.
+ */
+export function roleKeyWarnings(config: Config): string[] {
+  const { valid, unconsumed, deprecated } = roleKeyDiagnostics(config)
+  const lines: string[] = []
+  if (unconsumed.length > 0) {
+    const keys = unconsumed.map(roleTable).join(', ')
+    lines.push(
+      unconsumed.length === 1
+        ? `autobuild.toml: ${keys} is declared but nothing requests it — its runtime, model, and args never reach a session.`
+        : `autobuild.toml: ${keys} are declared but nothing requests them — their runtime, model, and args never reach a session.`,
+    )
+    // Rendered as keys, not as prose names: this list is what the operator
+    // types next, so a name needing quotes must show them here too.
+    lines.push(`Valid role keys: ${valid.map(tomlKey).join(', ')}`)
+  }
+  for (const entry of deprecated) lines.push(deprecationNotice(entry))
+  for (const [role, spec] of Object.entries(config.roles)) {
+    const declared =
+      spec.extensions !== undefined || spec.alternates?.some((alt) => alt.extensions !== undefined)
+    if (!declared) continue
+    lines.push(
+      `autobuild.toml: ${roleTable(role)} declares deprecated extensions — it has no effect; use args for explicit runtime CLI arguments.`,
+    )
+  }
+  return lines
+}