@haiyangbg/buildbeat 1.21.0 → 2.0.0-beta.2

package/src/v2/engine/yaml-subset.js

@@ -0,0 +1,194 @@
+// Fail-closed strict YAML subset parser for BuildBeat v2 config files.
+// Supports exactly what the official presets need: nested maps, block lists,
+// and plain/quoted scalars with space indentation. Everything else — tabs,
+// anchors, aliases, tags, block/flow scalars, multi-document streams,
+// duplicate keys — is rejected with a line number, never guessed at.
+
+export class YamlSubsetError extends Error {
+  constructor(message, lineNo) {
+    super(lineNo ? `line ${lineNo}: ${message}` : message);
+    this.name = "YamlSubsetError";
+    this.lineNo = lineNo ?? null;
+  }
+}
+
+const KEY_PATTERN = /^[A-Za-z0-9_.-]+$/;
+const FORBIDDEN_SCALAR_START = ["&", "*", "!", "|", ">", "{", "[", "%", "@", "`"];
+
+function parseScalar(raw, lineNo) {
+  const text = raw.trim();
+  if (text.startsWith('"')) {
+    if (!text.endsWith('"') || text.length < 2) {
+      throw new YamlSubsetError(`unterminated double-quoted string: ${text}`, lineNo);
+    }
+    try {
+      return JSON.parse(text);
+    } catch {
+      throw new YamlSubsetError(`invalid double-quoted string: ${text}`, lineNo);
+    }
+  }
+  if (text.startsWith("'")) {
+    if (!text.endsWith("'") || text.length < 2) {
+      throw new YamlSubsetError(`unterminated single-quoted string: ${text}`, lineNo);
+    }
+    const inner = text.slice(1, -1);
+    if (inner.includes("'")) {
+      throw new YamlSubsetError("single-quoted escapes are not supported", lineNo);
+    }
+    return inner;
+  }
+  if (FORBIDDEN_SCALAR_START.includes(text[0])) {
+    throw new YamlSubsetError(`unsupported YAML syntax at: ${text}`, lineNo);
+  }
+  if (text.includes(" #")) {
+    throw new YamlSubsetError("trailing comments are not supported; move the comment to its own line", lineNo);
+  }
+  if (text === "true") return true;
+  if (text === "false") return false;
+  if (text === "null" || text === "~") return null;
+  if (/^-?\d+$/.test(text)) return Number.parseInt(text, 10);
+  if (/^-?\d+\.\d+$/.test(text)) return Number.parseFloat(text);
+  return text;
+}
+
+function splitKeyValue(content, lineNo) {
+  const colon = content.indexOf(":");
+  if (colon === -1) {
+    throw new YamlSubsetError(`expected "key: value", got: ${content}`, lineNo);
+  }
+  const key = content.slice(0, colon);
+  if (!KEY_PATTERN.test(key)) {
+    throw new YamlSubsetError(`unsupported map key: ${key}`, lineNo);
+  }
+  const rest = content.slice(colon + 1);
+  if (rest === "") {
+    return { key, value: null };
+  }
+  if (!rest.startsWith(" ")) {
+    throw new YamlSubsetError(`expected a space after "${key}:"`, lineNo);
+  }
+  return { key, value: rest.slice(1) };
+}
+
+function toLines(text) {
+  const lines = [];
+  const rawLines = text.split("\n");
+  for (const [index, raw] of rawLines.entries()) {
+    const lineNo = index + 1;
+    if (raw.includes("\t")) {
+      throw new YamlSubsetError("tabs are not allowed", lineNo);
+    }
+    const withoutCr = raw.endsWith("\r") ? raw.slice(0, -1) : raw;
+    const trimmed = withoutCr.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) {
+      continue;
+    }
+    if (trimmed === "---" || trimmed === "...") {
+      throw new YamlSubsetError("multi-document YAML is not supported", lineNo);
+    }
+    const indent = withoutCr.length - withoutCr.trimStart().length;
+    lines.push({ indent, content: trimmed, lineNo });
+  }
+  return lines;
+}
+
+function parseNode(lines, start, indent) {
+  const first = lines[start];
+  if (first.content === "-" || first.content.startsWith("- ")) {
+    return parseList(lines, start, indent);
+  }
+  return parseMap(lines, start, indent);
+}
+
+function parseList(lines, start, indent) {
+  const result = [];
+  let index = start;
+  while (index < lines.length && lines[index].indent >= indent) {
+    const line = lines[index];
+    if (line.indent !== indent) {
+      throw new YamlSubsetError(`bad indentation in list (expected ${indent} spaces)`, line.lineNo);
+    }
+    if (line.content !== "-" && !line.content.startsWith("- ")) {
+      break;
+    }
+    const itemIndent = indent + 2;
+    const inline = line.content === "-" ? "" : line.content.slice(2).trim();
+    const childLines = [];
+    if (inline !== "") {
+      childLines.push({ indent: itemIndent, content: inline, lineNo: line.lineNo });
+    }
+    let cursor = index + 1;
+    while (cursor < lines.length && lines[cursor].indent >= itemIndent) {
+      childLines.push(lines[cursor]);
+      cursor += 1;
+    }
+    if (childLines.length === 0) {
+      throw new YamlSubsetError("empty list item", line.lineNo);
+    }
+    const first = childLines[0].content;
+    const quotedScalar = first.startsWith('"') || first.startsWith("'");
+    if (childLines.length === 1 && (quotedScalar || !first.includes(":"))) {
+      result.push(parseScalar(first, childLines[0].lineNo));
+    } else if (!quotedScalar && first.includes(":")) {
+      result.push(parseMapFromLines(childLines, itemIndent));
+    } else {
+      throw new YamlSubsetError("unsupported list item shape", line.lineNo);
+    }
+    index = cursor;
+  }
+  return { value: result, next: index };
+}
+
+function parseMapFromLines(childLines, indent) {
+  const { value, next } = parseMap(childLines, 0, indent);
+  if (next !== childLines.length) {
+    throw new YamlSubsetError("unexpected trailing content in map", childLines[next].lineNo);
+  }
+  return value;
+}
+
+function parseMap(lines, start, indent) {
+  const result = {};
+  let index = start;
+  while (index < lines.length && lines[index].indent >= indent) {
+    const line = lines[index];
+    if (line.indent !== indent) {
+      throw new YamlSubsetError(`bad indentation in map (expected ${indent} spaces)`, line.lineNo);
+    }
+    if (line.content === "-" || line.content.startsWith("- ")) {
+      break;
+    }
+    const { key, value } = splitKeyValue(line.content, line.lineNo);
+    if (Object.hasOwn(result, key)) {
+      throw new YamlSubsetError(`duplicate map key: ${key}`, line.lineNo);
+    }
+    if (value !== null) {
+      result[key] = parseScalar(value, line.lineNo);
+      index += 1;
+      continue;
+    }
+    const childStart = index + 1;
+    if (childStart >= lines.length || lines[childStart].indent <= indent) {
+      throw new YamlSubsetError(`key "${key}" has no value`, line.lineNo);
+    }
+    const parsed = parseNode(lines, childStart, lines[childStart].indent);
+    result[key] = parsed.value;
+    index = parsed.next;
+  }
+  return { value: result, next: index };
+}
+
+export function parseYamlSubset(text) {
+  const lines = toLines(text);
+  if (lines.length === 0) {
+    throw new YamlSubsetError("empty document");
+  }
+  if (lines[0].indent !== 0) {
+    throw new YamlSubsetError("document must start at column 0", lines[0].lineNo);
+  }
+  const { value, next } = parseNode(lines, 0, 0);
+  if (next !== lines.length) {
+    throw new YamlSubsetError("unexpected trailing content", lines[next].lineNo);
+  }
+  return value;
+}

package/src/v2/evidence/collector.js

@@ -0,0 +1,63 @@
+// Evidence Collector v0 per docs/v2/RFC-0002-domain-model.md §4: evidence is
+// what the runner read back (exit codes, logs, git state), never what a
+// worker said. Raw logs stay in the runtime plane; the returned record is the
+// contract-shaped fact the ledger and manifests reference.
+
+import { createHash } from "node:crypto";
+import { mkdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+export function collectCommandEvidence({
+  runtimeDir,
+  runId,
+  step,
+  attempt,
+  execResult,
+  subject,
+  kind = "command",
+  grade = "L2",
+  coverage = null,
+}) {
+  const logsDir = join(runtimeDir, "runs", runId, "logs");
+  mkdirSync(logsDir, { recursive: true });
+  const logName = `${step}-${attempt}.log`;
+  const logPath = join(logsDir, logName);
+  const logBody = [
+    `command: ${execResult.command}`,
+    `exitCode: ${execResult.exitCode}`,
+    `signal: ${execResult.signal}`,
+    `timedOut: ${execResult.timedOut}`,
+    `spawnError: ${execResult.spawnError}`,
+    "--- stdout ---",
+    execResult.stdout,
+    "--- stderr ---",
+    execResult.stderr,
+  ].join("\n");
+  writeFileSync(logPath, logBody, "utf8");
+  const digest = `sha256:${createHash("sha256").update(logBody, "utf8").digest("hex")}`;
+
+  let status;
+  if (execResult.spawnError) {
+    status = "unverified";
+  } else if (execResult.exitCode === 0 && !execResult.timedOut && !execResult.signal) {
+    status = "passed";
+  } else {
+    status = "failed";
+  }
+
+  return {
+    kind,
+    subject,
+    producer: "runner",
+    command: execResult.command,
+    exitCode: execResult.exitCode,
+    startedAt: execResult.startedAt,
+    finishedAt: execResult.finishedAt,
+    digest,
+    location: logPath,
+    coverage,
+    status,
+    adapter: execResult.adapter,
+    grade,
+  };
+}

package/src/v2/observe/observe-config.js

@@ -0,0 +1,194 @@
+// observe.yaml loader per docs/v2/RFC-0003-workflow-policy.md §8 (frozen
+// shape, block form — the strict YAML subset rejects inline {}/[]). Fail
+// closed: any shape violation is an error, never a default.
+
+import { createHash } from "node:crypto";
+import { readFileSync } from "node:fs";
+import { basename, dirname, resolve } from "node:path";
+
+import {
+  OBSERVE_BAND_LEVELS,
+  OBSERVE_SEVERITIES,
+  TRIAGE_ACTIONS,
+} from "../domain/model.js";
+import { parseYamlSubset } from "../engine/yaml-subset.js";
+
+export class ObserveConfigError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ObserveConfigError";
+  }
+}
+
+const WHEN_PATTERN = /^severity\s*>=\s*(info|warn|error|critical)$/;
+
+export function severityRank(severity) {
+  const rank = OBSERVE_SEVERITIES.indexOf(severity);
+  if (rank === -1) {
+    throw new ObserveConfigError(`unknown severity: ${severity}`);
+  }
+  return rank;
+}
+
+function requireString(value, label) {
+  if (typeof value !== "string" || value.length === 0) {
+    throw new ObserveConfigError(`${label} must be a non-empty string`);
+  }
+  return value;
+}
+
+function parseSeverityMap(raw, providerId) {
+  const map = { failed: "error", unverified: "warn" };
+  if (raw === undefined) {
+    return map;
+  }
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new ObserveConfigError(`provider ${providerId}: severity must be a map`);
+  }
+  for (const [key, value] of Object.entries(raw)) {
+    if (key !== "failed" && key !== "unverified") {
+      throw new ObserveConfigError(`provider ${providerId}: severity.${key} is not a known key`);
+    }
+    if (!OBSERVE_SEVERITIES.includes(value)) {
+      throw new ObserveConfigError(
+        `provider ${providerId}: severity.${key} must be one of ${OBSERVE_SEVERITIES.join("|")}`,
+      );
+    }
+    map[key] = value;
+  }
+  return map;
+}
+
+function parseProvider(raw, index) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new ObserveConfigError(`providers[${index}] must be a map`);
+  }
+  const id = requireString(raw.id, `providers[${index}].id`);
+  const command = requireString(raw.command, `provider ${id}: command`);
+  const args = raw.args ?? [];
+  if (!Array.isArray(args) || args.some((arg) => typeof arg !== "string" && typeof arg !== "number")) {
+    throw new ObserveConfigError(`provider ${id}: args must be a list of scalars`);
+  }
+  if (raw.evidence === null || typeof raw.evidence !== "object" || Array.isArray(raw.evidence)) {
+    throw new ObserveConfigError(`provider ${id}: evidence must be a map with kind and subject`);
+  }
+  const evidence = {
+    kind: requireString(raw.evidence.kind, `provider ${id}: evidence.kind`),
+    subject: requireString(raw.evidence.subject, `provider ${id}: evidence.subject`),
+  };
+  let diagnose = null;
+  if (raw.diagnose !== undefined) {
+    if (raw.diagnose === null || typeof raw.diagnose !== "object" || Array.isArray(raw.diagnose)) {
+      throw new ObserveConfigError(`provider ${id}: diagnose must be a map with command`);
+    }
+    const diagnoseArgs = raw.diagnose.args ?? [];
+    if (!Array.isArray(diagnoseArgs)) {
+      throw new ObserveConfigError(`provider ${id}: diagnose.args must be a list`);
+    }
+    diagnose = {
+      command: requireString(raw.diagnose.command, `provider ${id}: diagnose.command`),
+      args: diagnoseArgs.map((arg) => String(arg)),
+      timeoutMs: raw.diagnose.timeoutMs,
+    };
+  }
+  return {
+    id,
+    command,
+    args: args.map((arg) => String(arg)),
+    schedule: raw.schedule === undefined ? "manual" : String(raw.schedule),
+    evidence,
+    severity: parseSeverityMap(raw.severity, id),
+    diagnose,
+    timeoutMs: raw.timeoutMs,
+  };
+}
+
+function parseBands(raw) {
+  if (!Array.isArray(raw) || raw.length !== OBSERVE_BAND_LEVELS.length) {
+    throw new ObserveConfigError(
+      `bands must list exactly the three levels ${OBSERVE_BAND_LEVELS.join(", ")} in order`,
+    );
+  }
+  return raw.map((band, index) => {
+    const expectedLevel = OBSERVE_BAND_LEVELS[index];
+    if (band === null || typeof band !== "object" || Array.isArray(band)) {
+      throw new ObserveConfigError(`bands[${index}] must be a map`);
+    }
+    if (band.level !== expectedLevel) {
+      throw new ObserveConfigError(
+        `bands[${index}].level must be ${expectedLevel} (levels are fixed), got: ${band.level}`,
+      );
+    }
+    const when = requireString(band.when, `band ${expectedLevel}: when`);
+    const match = WHEN_PATTERN.exec(when.trim());
+    if (!match) {
+      throw new ObserveConfigError(
+        `band ${expectedLevel}: when must match "severity >= <level>", got: ${when}`,
+      );
+    }
+    return { level: expectedLevel, minSeverity: match[1] };
+  });
+}
+
+function parseTriage(raw) {
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new ObserveConfigError("triage must be a map");
+  }
+  const actions = raw.actions;
+  if (
+    !Array.isArray(actions) ||
+    actions.length !== TRIAGE_ACTIONS.length ||
+    TRIAGE_ACTIONS.some((action, index) => actions[index] !== action)
+  ) {
+    throw new ObserveConfigError(
+      `triage.actions must be exactly [${TRIAGE_ACTIONS.join(", ")}] (closed set)`,
+    );
+  }
+  if (raw.dismissFeedback !== "bands") {
+    throw new ObserveConfigError('triage.dismissFeedback must be "bands"');
+  }
+  return { actions: [...TRIAGE_ACTIONS], dismissFeedback: "bands" };
+}
+
+export function loadObserveConfig(configPath) {
+  const absolutePath = resolve(configPath);
+  const text = readFileSync(absolutePath, "utf8");
+  const raw = parseYamlSubset(text);
+  if (raw === null || typeof raw !== "object" || Array.isArray(raw)) {
+    throw new ObserveConfigError("observe config must be a YAML map");
+  }
+  if (raw.kind !== "workflow") {
+    throw new ObserveConfigError(`kind must be workflow, got: ${raw.kind}`);
+  }
+  if (raw.version !== 1) {
+    throw new ObserveConfigError(`unsupported observe config version: ${raw.version}`);
+  }
+  if (raw.name !== "observe") {
+    throw new ObserveConfigError(`name must be observe, got: ${raw.name}`);
+  }
+  if (!Array.isArray(raw.providers) || raw.providers.length === 0) {
+    throw new ObserveConfigError("providers must be a non-empty list");
+  }
+  const providers = raw.providers.map((provider, index) => parseProvider(provider, index));
+  const ids = new Set();
+  for (const provider of providers) {
+    if (ids.has(provider.id)) {
+      throw new ObserveConfigError(`duplicate provider id: ${provider.id}`);
+    }
+    ids.add(provider.id);
+  }
+  const configDir = dirname(absolutePath);
+  const repoRoot = raw.repo
+    ? resolve(configDir, String(raw.repo))
+    : basename(configDir) === ".buildbeat"
+      ? dirname(configDir)
+      : configDir;
+  return {
+    configPath: absolutePath,
+    configDigest: `sha256:${createHash("sha256").update(text, "utf8").digest("hex")}`,
+    repoRoot,
+    providers,
+    bands: parseBands(raw.bands),
+    triage: parseTriage(raw.triage),
+  };
+}

package/src/v2/observe/observe-reducer.js

@@ -0,0 +1,117 @@
+// Deterministic reducer for the observe ledger (RFC-0003 §8, implemented M5).
+// Shares envelope/chain rules with the run ledger via EventLedger's pluggable
+// reducer; state here is a runtime view only — triage terminal state lives in
+// the Git-plane intent draft files (invariant 23: runtime is deletable).
+
+export class IllegalObserveEventError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "IllegalObserveEventError";
+  }
+}
+
+export function observeInitialState() {
+  return {
+    seq: 0,
+    cycles: 0,
+    activeCycle: null,
+    providers: {},
+    evidence: [],
+    bands: [],
+    intents: {},
+    triage: [],
+  };
+}
+
+export function applyObserveEvent(state, event) {
+  if (event.seq !== state.seq + 1) {
+    throw new IllegalObserveEventError(`expected seq ${state.seq + 1}, got ${event.seq}`);
+  }
+  const { type, data } = event;
+  const next = structuredClone(state);
+  next.seq = event.seq;
+
+  switch (type) {
+    case "OBSERVE_CYCLE_STARTED": {
+      if (state.activeCycle !== null) {
+        // A crashed cycle never finished; the new cycle supersedes it. Facts
+        // already appended stand; nothing is repaired.
+        next.activeCycle = null;
+      }
+      if (data.cycle !== state.cycles + 1) {
+        throw new IllegalObserveEventError(
+          `expected cycle ${state.cycles + 1}, got ${data.cycle}`,
+        );
+      }
+      next.activeCycle = { cycle: data.cycle, configDigest: data.configDigest, ts: event.ts };
+      next.cycles = data.cycle;
+      break;
+    }
+    case "OBSERVE_CYCLE_FINISHED": {
+      if (!state.activeCycle || state.activeCycle.cycle !== data.cycle) {
+        throw new IllegalObserveEventError(`no active cycle ${data.cycle} to finish`);
+      }
+      next.activeCycle = null;
+      break;
+    }
+    case "EVIDENCE_RECORDED": {
+      next.evidence.push({
+        ref: data.evidenceRef,
+        kind: data.kind,
+        subject: data.subject,
+        digest: data.digest,
+        status: data.status,
+        grade: data.grade,
+        ...(data.provider ? { provider: data.provider } : {}),
+        ...(data.cycle !== undefined ? { cycle: data.cycle } : {}),
+      });
+      if (data.provider) {
+        next.providers[data.provider] = {
+          lastStatus: data.status,
+          lastKind: data.kind,
+          lastSubject: data.subject,
+          lastEvidenceRef: data.evidenceRef,
+          lastTs: event.ts,
+        };
+      }
+      break;
+    }
+    case "BAND_TRIGGERED": {
+      next.bands.push({
+        provider: data.provider,
+        band: data.band,
+        severity: data.severity,
+        fingerprint: data.fingerprint,
+        ts: event.ts,
+      });
+      break;
+    }
+    case "INTENT_DRAFTED": {
+      next.intents[data.fingerprint] = {
+        intentRef: data.intentRef,
+        provider: data.provider,
+        severity: data.severity,
+        ts: event.ts,
+      };
+      break;
+    }
+    case "TRIAGE_RECORDED": {
+      next.triage.push({
+        intentRef: data.intentRef,
+        action: data.action,
+        fingerprint: data.fingerprint,
+        ts: event.ts,
+      });
+      break;
+    }
+    default:
+      // Unknown type written by a newer version: preserved, skipped.
+      break;
+  }
+  return next;
+}
+
+export const OBSERVE_REDUCER = {
+  initialState: observeInitialState,
+  applyEvent: applyObserveEvent,
+};