@paths.design/caws-cli 10.0.1 → 10.2.0

package/dist/utils/event-renderer.js

@@ -0,0 +1,521 @@
+/**
+ * @fileoverview Event Renderer — pure fold over the event log
+ *
+ * Replays `.caws/events.jsonl` into the same view shape that
+ * `working-state.loadState(specId)` produces today. This module is
+ * a pure function: same events in → same view out, no filesystem
+ * side effects, no writes.
+ *
+ * The fold logic is a verbatim port of the three pure helpers in
+ * `working-state.js` (`computePhase`, `computeBlockers`,
+ * `computeNextActions`) — they already operated on a state object,
+ * so we simply apply them to the rolling fold result after each event.
+ *
+ * Phase 1 reads the event log *in addition to* the state layer, not
+ * instead of it. The parity test in
+ * `tests/integration/event-log-parity.test.js` asserts the two paths
+ * produce equivalent views for the fields iterate/status/sidecar/gates
+ * actually consume.
+ *
+ * @author @darianrosebrook
+ */
+
+const { readEvents } = require('./event-log');
+
+// Must match working-state.js for parity.
+const STATE_SCHEMA_VERSION = 'caws.state.v1';
+const MAX_HISTORY = 20;
+
+// ---------------------------------------------------------------------------
+// Shape: empty state (mirrors working-state.initializeState)
+// ---------------------------------------------------------------------------
+
+/**
+ * Build an empty default view for a spec that has no events yet.
+ * @param {string} specId
+ * @returns {object}
+ */
+function emptyView(specId) {
+  return {
+    schema: STATE_SCHEMA_VERSION,
+    spec_id: specId,
+    updated_at: null,
+    phase: 'not-started',
+    files_touched: [],
+    validation: null,
+    evaluation: null,
+    gates: null,
+    acceptance_criteria: null,
+    blockers: [],
+    next_actions: [],
+    history: [],
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Derived-field computation (verbatim port from working-state.js:334-474)
+//
+// These functions operate on the fold result, not on persisted state.
+// They must stay byte-equivalent to the originals until Phase 3 removes
+// the state layer entirely.
+// ---------------------------------------------------------------------------
+
+/**
+ * Derive the current workflow phase from the folded state.
+ * Identical semantics to `working-state.computePhase`.
+ * @param {object} state
+ * @returns {string}
+ */
+function computePhase(state) {
+  const v = state.validation;
+  const e = state.evaluation;
+  const g = state.gates;
+  const ac = state.acceptance_criteria;
+
+  // Closed specs stay closed regardless of prior artifacts.
+  if (state.phase === 'closed') return 'closed';
+
+  // Nothing has run yet
+  if (!v && !e && !g && !ac) return 'not-started';
+
+  // Validation failed or evaluation below 70% → still authoring the spec
+  if (v && !v.passed) return 'spec-authoring';
+  if (e && e.percentage < 70) return 'spec-authoring';
+
+  // All ACs pass, all gates pass, evaluation >= 90% → complete
+  if (
+    ac && ac.total > 0 && ac.fail === 0 && ac.unchecked === 0 &&
+    g && g.passed &&
+    e && e.percentage >= 90
+  ) {
+    return 'complete';
+  }
+
+  // All ACs pass, gates have been run → verification phase
+  if (ac && ac.total > 0 && ac.fail === 0 && ac.unchecked === 0 && g) {
+    return 'verification';
+  }
+
+  // Otherwise: implementation
+  return 'implementation';
+}
+
+/**
+ * Extract active blockers from the folded state.
+ * Identical semantics to `working-state.computeBlockers`.
+ * @param {object} state
+ * @returns {object[]}
+ */
+function computeBlockers(state) {
+  // Closed specs have no active blockers. This is a Phase 1 divergence
+  // from working-state.computeBlockers, which predates the spec_closed
+  // event. See EVLOG-001 acceptance criterion A5 and design doc §8.2:
+  // closed specs must render with phase=closed and no blockers, without
+  // touching the filesystem.
+  if (state.phase === 'closed') return [];
+
+  const blockers = [];
+  const now = new Date().toISOString();
+
+  if (state.validation && !state.validation.passed) {
+    blockers.push({
+      type: 'validation_failure',
+      message: `Validation failed with ${state.validation.error_count} error(s)`,
+      since: state.validation.last_run || now,
+    });
+  }
+
+  if (state.gates && state.gates.results) {
+    for (const g of state.gates.results) {
+      if (g.status === 'fail' && g.mode === 'block') {
+        blockers.push({
+          type: 'gate_failure',
+          gate: g.name,
+          message: `Gate "${g.name}" is blocking`,
+          since: state.gates.last_run || now,
+        });
+      }
+    }
+  }
+
+  if (state.acceptance_criteria && state.acceptance_criteria.fail > 0) {
+    const failingIds = (state.acceptance_criteria.results || [])
+      .filter((r) => r.status === 'FAIL')
+      .map((r) => r.id);
+    blockers.push({
+      type: 'ac_failure',
+      message: `${state.acceptance_criteria.fail} acceptance criteria failing${failingIds.length ? ': ' + failingIds.join(', ') : ''}`,
+      since: state.acceptance_criteria.last_run || now,
+    });
+  }
+
+  return blockers;
+}
+
+/**
+ * Compute ordered next actions from the folded state.
+ * Identical semantics to `working-state.computeNextActions`.
+ * @param {object} state
+ * @returns {string[]}
+ */
+function computeNextActions(state) {
+  const actions = [];
+
+  // Closed specs have no next actions.
+  if (state.phase === 'closed') return [];
+
+  if (state.validation && !state.validation.passed) {
+    actions.push('Fix validation errors, then run: caws validate');
+  }
+
+  if (state.gates && state.gates.results) {
+    for (const g of state.gates.results) {
+      if (g.status === 'fail' && g.mode === 'block') {
+        actions.push(`Fix gate violation: ${g.name}`);
+      }
+    }
+  }
+
+  if (state.acceptance_criteria) {
+    const failing = (state.acceptance_criteria.results || [])
+      .filter((r) => r.status === 'FAIL')
+      .map((r) => r.id);
+    if (failing.length > 0) {
+      actions.push(`Fix failing acceptance criteria: ${failing.join(', ')}`);
+    }
+
+    const unchecked = state.acceptance_criteria.unchecked || 0;
+    if (unchecked > 0) {
+      actions.push(`Add tests for ${unchecked} unchecked acceptance criteria`);
+    }
+  }
+
+  if (state.evaluation && state.evaluation.percentage < 80) {
+    actions.push(
+      `Improve spec quality (currently ${state.evaluation.percentage}%), run: caws evaluate`
+    );
+  }
+
+  if (!state.validation) {
+    actions.push('Run: caws validate');
+  }
+
+  if (!state.evaluation) {
+    actions.push('Run: caws evaluate');
+  }
+
+  if (!state.acceptance_criteria) {
+    actions.push('Run: caws verify-acs');
+  }
+
+  if (actions.length === 0) {
+    actions.push(
+      'All checks passing. Ready for merge. Run: caws verify-acs --run for final verification.'
+    );
+  }
+
+  return actions;
+}
+
+// ---------------------------------------------------------------------------
+// Fold: apply a single event to a per-spec view
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply one event to the given per-spec view. Mutates and returns the view.
+ * This mirrors the merge semantics of `working-state.updateState`:
+ *   - replace-merge for validation/evaluation/gates/acceptance_criteria
+ *   - set-union merge for files_touched
+ *   - append-then-cap history
+ *
+ * @param {object} view
+ * @param {object} event
+ * @returns {object} The mutated view (returned for chaining)
+ */
+function applyEvent(view, event) {
+  const { event: type, data = {}, ts } = event;
+
+  switch (type) {
+    case 'spec_created': {
+      // No state fields to set here; the spec registry is the source of truth
+      // for type/title/risk_tier/mode. We record it in history so the renderer
+      // can distinguish "never touched" from "created but not yet worked".
+      view.history.push({
+        timestamp: ts,
+        command: 'specs.create',
+        summary: `Created ${data.type || 'spec'}: ${data.title || data.id || view.spec_id}`,
+      });
+      break;
+    }
+
+    case 'spec_closed': {
+      view.phase = 'closed';
+      view.blockers = [];
+      view.next_actions = [];
+      view.history.push({
+        timestamp: ts,
+        command: 'specs.close',
+        summary: `Closed (prior status: ${data.prior_status || 'unknown'})`,
+      });
+      break;
+    }
+
+    case 'spec_deleted': {
+      // A deleted spec shouldn't typically be rendered; if we do see it,
+      // mark the view as terminal but leave a trace in history.
+      view.phase = 'closed';
+      view.history.push({
+        timestamp: ts,
+        command: 'specs.delete',
+        summary: 'Deleted',
+      });
+      break;
+    }
+
+    case 'validation_completed': {
+      view.validation = {
+        last_run: ts,
+        passed: !!data.passed,
+        compliance_score: data.compliance_score ?? null,
+        grade: data.grade ?? null,
+        error_count: data.error_count ?? 0,
+        warning_count: data.warning_count ?? 0,
+      };
+      const summaryText = data.passed
+        ? `Passed (Grade ${view.validation.grade || '?'})`
+        : `Failed — ${view.validation.error_count} error(s)`;
+      view.history.push({
+        timestamp: ts,
+        command: 'validate',
+        summary: summaryText,
+      });
+      break;
+    }
+
+    case 'evaluation_completed': {
+      view.evaluation = {
+        last_run: ts,
+        score: data.score,
+        max_score: data.max_score,
+        percentage: data.percentage,
+        grade: data.grade,
+        checks_passed: data.checks_passed,
+        checks_total: data.checks_total,
+      };
+      view.history.push({
+        timestamp: ts,
+        command: 'evaluate',
+        summary: `${data.score}/${data.max_score} (${data.percentage}%) Grade ${data.grade}`,
+      });
+      break;
+    }
+
+    case 'gates_evaluated': {
+      view.gates = {
+        last_run: ts,
+        context: data.context || 'cli',
+        passed: !!data.passed,
+        summary: data.summary || {},
+        results: (data.gates || []).map((g) => ({
+          name: g.name,
+          status: g.status,
+          mode: g.mode,
+        })),
+      };
+      const { blocked = 0, warned = 0, passed = 0 } = data.summary || {};
+      view.history.push({
+        timestamp: ts,
+        command: 'gates',
+        summary: `${passed} passed, ${blocked} blocked, ${warned} warned`,
+      });
+      break;
+    }
+
+    case 'verify_acs_completed': {
+      view.acceptance_criteria = {
+        last_run: ts,
+        total: data.total,
+        pass: data.pass,
+        fail: data.fail,
+        unchecked: data.unchecked,
+        results: (data.results || []).map((r) => ({
+          id: r.id,
+          status: r.status,
+        })),
+      };
+      view.history.push({
+        timestamp: ts,
+        command: 'verify-acs',
+        summary: `${data.pass}/${data.total} pass, ${data.fail} fail, ${data.unchecked} unchecked`,
+      });
+      break;
+    }
+
+    case 'session_ended': {
+      // A session can touch files without calling any spec-scoped command.
+      // When the session ends, merge its file list into this spec's view.
+      // Only applies if the event carries our spec_id (the caller filters).
+      if (Array.isArray(data.files_touched) && data.files_touched.length > 0) {
+        const merged = new Set([...view.files_touched, ...data.files_touched]);
+        view.files_touched = [...merged];
+        view.history.push({
+          timestamp: ts,
+          command: 'session',
+          summary: `+${data.files_touched.length} file(s) touched`,
+        });
+      }
+      break;
+    }
+
+    default:
+      // Unknown or non-spec-scoped event type — ignore for this fold.
+      break;
+  }
+
+  // Derived fields recomputed on every applicable event.
+  view.blockers = computeBlockers(view);
+  view.next_actions = computeNextActions(view);
+  view.phase = computePhase(view);
+  view.updated_at = ts;
+
+  // Cap history at MAX_HISTORY (matches working-state.updateState).
+  if (view.history.length > MAX_HISTORY) {
+    view.history = view.history.slice(-MAX_HISTORY);
+  }
+
+  return view;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Fold an event stream into the view for a single spec.
+ *
+ * Pure function: the same events + specId always produce the same view.
+ * No filesystem access. No writes.
+ *
+ * Events are filtered to those that are either scoped to this spec via
+ * `spec_id`, or session-level events whose `data.spec_id` matches.
+ *
+ * @param {object[]} events — the full event stream (from readEvents)
+ * @param {string} specId
+ * @returns {object} view matching the shape of working-state.loadState
+ */
+function renderSpecState(events, specId) {
+  if (!specId || typeof specId !== 'string') {
+    throw new Error('event-renderer.renderSpecState: specId is required');
+  }
+  const view = emptyView(specId);
+  for (const event of events) {
+    if (!isEventForSpec(event, specId)) continue;
+    applyEvent(view, event);
+  }
+  return view;
+}
+
+/**
+ * Fold an event stream into a Map of specId → view for every spec that
+ * has at least one event in the stream.
+ *
+ * @param {object[]} events
+ * @returns {Map<string, object>}
+ */
+function renderAllSpecStates(events) {
+  const views = new Map();
+  for (const event of events) {
+    const specId = getEventSpecId(event);
+    if (!specId) continue;
+    if (!views.has(specId)) {
+      views.set(specId, emptyView(specId));
+    }
+    applyEvent(views.get(specId), event);
+  }
+  return views;
+}
+
+/**
+ * Convenience: read the event log and render a single spec's view.
+ * Equivalent to calling `loadState(specId)` but backed by the event log.
+ *
+ * **Contract parity with `working-state.loadState`**: returns `null` when
+ * there are zero events for this spec, matching `loadState`'s behavior of
+ * returning `null` when the state file does not exist. This is load-bearing
+ * for Phase 2 read flips — call sites like `status.js`'s
+ * `loadState(id) || null` coalesce depend on it, and `iterate.js`'s
+ * `if (workingState) { ... }` guard would otherwise always be truthy under
+ * the event-log path even for untouched specs.
+ *
+ * `renderSpecState` itself stays pure and always returns a view object
+ * (possibly empty). The null translation only happens here, at the
+ * `loadState`-compatible boundary.
+ *
+ * @param {string} specId
+ * @param {object} [options]
+ * @param {string} [options.projectRoot]
+ * @returns {object|null}
+ */
+function loadStateFromEvents(specId, options = {}) {
+  const events = readEvents(options);
+  // If no events match this spec, return null to match loadState's contract.
+  let hasMatch = false;
+  for (const event of events) {
+    if (isEventForSpec(event, specId)) {
+      hasMatch = true;
+      break;
+    }
+  }
+  if (!hasMatch) return null;
+  return renderSpecState(events, specId);
+}
+
+/**
+ * Determine whether an event is scoped to a given spec.
+ * @param {object} event
+ * @param {string} specId
+ * @returns {boolean}
+ */
+function isEventForSpec(event, specId) {
+  if (event.spec_id === specId) return true;
+  // Session events may carry their own spec_id inside data.
+  if (event.event === 'session_ended' && event.data && event.data.spec_id === specId) {
+    return true;
+  }
+  return false;
+}
+
+/**
+ * Extract the spec_id an event refers to, if any. Used by
+ * renderAllSpecStates to group events by spec.
+ * @param {object} event
+ * @returns {string|null}
+ */
+function getEventSpecId(event) {
+  if (event.spec_id) return event.spec_id;
+  if (event.data && event.data.spec_id) return event.data.spec_id;
+  return null;
+}
+
+// ---------------------------------------------------------------------------
+// Exports
+// ---------------------------------------------------------------------------
+
+module.exports = {
+  renderSpecState,
+  renderAllSpecStates,
+  loadStateFromEvents,
+  emptyView,
+
+  // Exposed for tests only.
+  _internal: {
+    applyEvent,
+    computePhase,
+    computeBlockers,
+    computeNextActions,
+    isEventForSpec,
+    getEventSpecId,
+    STATE_SCHEMA_VERSION,
+    MAX_HISTORY,
+  },
+};

package/dist/utils/schema-validator.js

@@ -34,8 +34,16 @@ function createValidator(schemaPath) {
 }
 
 function getSchemaPath(schemaName, projectRoot) {
-  const projectPath = path.join(projectRoot, '.caws', 'schemas', schemaName);
-  if (fs.existsSync(projectPath)) return projectPath;
+  // Order: flat repo layout (`.caws/<name>.schema.json`) wins so
+  // repos that tightened a schema in-place (e.g. CAWSFIX-03) are
+  // the authoritative source. Nested `.caws/schemas/<name>.schema.json`
+  // is the legacy layout kept for back-compat. Bundled template is
+  // the last-resort fallback used by globally-installed CLIs and
+  // projects without a local copy.
+  const flatPath = path.join(projectRoot, '.caws', schemaName);
+  if (fs.existsSync(flatPath)) return flatPath;
+  const nestedPath = path.join(projectRoot, '.caws', 'schemas', schemaName);
+  if (fs.existsSync(nestedPath)) return nestedPath;
   return path.join(__dirname, '../../templates/.caws/schemas', schemaName);
 }
 

package/dist/utils/working-state.js

@@ -40,11 +40,36 @@ function findRoot(startDir) {
 
 /**
  * Resolve the absolute path for a spec's state file.
+ *
+ * **Fail-loud contract (CAWSFIX-02)**: throws if `specId` is undefined,
+ * null, empty, non-string, or whitespace-only. This fence prevents the
+ * `.caws/state/undefined.json` bug class — a historical source of
+ * silent data corruption where legacy callers passed `spec.id` without
+ * checking whether `spec` was a valid resolved spec.
+ *
+ * Symmetric with the `REQUIRES_SPEC_ID` fence in `event-log.js` from
+ * EVLOG-001: both state-layer and event-log writes now refuse to
+ * proceed with an undefined spec id. Callers that legitimately lack a
+ * spec id (e.g. legacy working-specs, failed resolveSpec) must guard
+ * their calls with `if (spec && spec.id)` — the pattern `gates.js`
+ * already uses and which `validate.js`/`evaluate.js`/`verify-acs.js`
+ * are updated to use in the same tranche.
+ *
  * @param {string} specId
  * @param {string} [projectRoot]
  * @returns {string}
+ * @throws {Error} if specId is not a non-empty string
  */
 function getStatePath(specId, projectRoot) {
+  if (!specId || typeof specId !== 'string' || specId.trim() === '') {
+    throw new Error(
+      `working-state.getStatePath: specId must be a non-empty string ` +
+        `(got ${JSON.stringify(specId)}). This is the fence that prevents ` +
+        `the .caws/state/undefined.json bug class — callers without a ` +
+        `resolved spec id must guard with \`if (spec && spec.id)\` before ` +
+        `invoking saveState/updateState/recordValidation/etc.`
+    );
+  }
   const root = projectRoot || findRoot();
   return path.join(root, STATE_DIR, `${specId}.json`);
 }