@hegemonart/get-design-done 1.24.2 → 1.26.0

package/scripts/lib/gdd-state/mutator.ts

@@ -29,6 +29,13 @@ import {
   type MustHave,
   type ParsedState,
   type Position,
+  type PrototypingBlock,
+  type QualityGateBlock,
+  type QualityGateRun,
+  type QualityGateStatus,
+  type SketchEntry,
+  type SkippedEntry,
+  type SpikeEntry,
 } from './types.ts';
 
 /**
@@ -250,6 +257,10 @@ function emitBlock(
       return emitDecisions(state.decisions, rawBody);
     case 'must_haves':
       return emitMustHaves(state.must_haves, rawBody);
+    case 'prototyping':
+      return emitPrototyping(state.prototyping, rawBody);
+    case 'quality_gate':
+      return emitQualityGate(state.quality_gate, rawBody);
     case 'connections':
       return emitConnections(state.connections, rawBody);
     case 'blockers':
@@ -340,6 +351,151 @@ function emitBlockers(blockers: Blocker[], rawBody: string | null): string {
   return blockers.map((b) => `[${b.stage}] [${b.date}]: ${b.text}`).join('\n');
 }
 
+/**
+ * Emit the body of a `<prototyping>` block (Phase 25 Plan 25-01).
+ *
+ * Returns `null` when the block should be omitted entirely — i.e. the
+ * parsed state has `prototyping === null` AND no raw body is on file.
+ * That signal short-circuits `emitBlock` so we don't litter the output
+ * with empty `<prototyping></prototyping>` pairs on fresh files.
+ *
+ * Fidelity rule (matches the other blocks): when `rawBody` round-trips
+ * through `tryReparsePrototyping` and matches the current value
+ * structurally, emit the raw body verbatim. Otherwise canonicalize.
+ */
+function emitPrototyping(
+  block: PrototypingBlock | null,
+  rawBody: string | null,
+): string | null {
+  if (block === null && rawBody === null) return null;
+  if (block === null) {
+    // Block was present in source but state set it to null — caller wants
+    // to drop the block. Still return null so emitBlock skips emission.
+    return null;
+  }
+  if (rawBody !== null) {
+    const reparsed = tryReparsePrototyping(rawBody);
+    if (reparsed !== null && prototypingEqual(reparsed, block)) {
+      return rawBody;
+    }
+  }
+  return canonicalPrototyping(block);
+}
+
+function canonicalPrototyping(block: PrototypingBlock): string {
+  const lines: string[] = [];
+  for (const s of block.sketches) {
+    lines.push(canonicalSketch(s));
+  }
+  for (const sp of block.spikes) {
+    lines.push(canonicalSpike(sp));
+  }
+  for (const sk of block.skipped) {
+    lines.push(canonicalSkipped(sk));
+  }
+  return lines.join('\n');
+}
+
+function canonicalSketch(s: SketchEntry): string {
+  const parts: string[] = [
+    `slug=${formatPrototypingAttr(s.slug)}`,
+    `cycle=${formatPrototypingAttr(s.cycle)}`,
+    `decision=${formatPrototypingAttr(s.decision)}`,
+    `status=${formatPrototypingAttr(s.status)}`,
+  ];
+  for (const [k, v] of Object.entries(s.extra_attrs)) {
+    parts.push(`${k}=${formatPrototypingAttr(v)}`);
+  }
+  return `<sketch ${parts.join(' ')}/>`;
+}
+
+function canonicalSpike(s: SpikeEntry): string {
+  const parts: string[] = [
+    `slug=${formatPrototypingAttr(s.slug)}`,
+    `cycle=${formatPrototypingAttr(s.cycle)}`,
+    `decision=${formatPrototypingAttr(s.decision)}`,
+    `verdict=${formatPrototypingAttr(s.verdict)}`,
+    `status=${formatPrototypingAttr(s.status)}`,
+  ];
+  for (const [k, v] of Object.entries(s.extra_attrs)) {
+    parts.push(`${k}=${formatPrototypingAttr(v)}`);
+  }
+  return `<spike ${parts.join(' ')}/>`;
+}
+
+function canonicalSkipped(s: SkippedEntry): string {
+  const parts: string[] = [
+    `at=${formatPrototypingAttr(s.at)}`,
+    `cycle=${formatPrototypingAttr(s.cycle)}`,
+    `reason=${formatPrototypingAttr(s.reason)}`,
+  ];
+  for (const [k, v] of Object.entries(s.extra_attrs)) {
+    parts.push(`${k}=${formatPrototypingAttr(v)}`);
+  }
+  return `<skipped ${parts.join(' ')}/>`;
+}
+
+/**
+ * Format an attribute value for emission. We always quote with double
+ * quotes for canonical output: this avoids ambiguity on values containing
+ * whitespace, equal signs, or solidus. Embedded `"` are escaped to `&quot;`
+ * which is what the parser already strips when re-reading. Empty strings
+ * are emitted as `""` (the parser tolerates them).
+ */
+function formatPrototypingAttr(v: string): string {
+  return `"${v.replace(/"/g, '&quot;')}"`;
+}
+
+/**
+ * Emit the body of a `<quality_gate>` block (Phase 25 Plan 25-03).
+ *
+ * Returns `null` when the block should be omitted entirely — i.e. the
+ * parsed state has `quality_gate === null` AND no raw body is on file.
+ * Mirror of `emitPrototyping`'s short-circuit behavior so fresh STATE.md
+ * files don't carry an empty `<quality_gate></quality_gate>` pair.
+ *
+ * Fidelity rule (matches the other blocks): when `rawBody` round-trips
+ * through `tryReparseQualityGate` and matches the current value
+ * structurally, emit the raw body verbatim. Otherwise canonicalize.
+ */
+function emitQualityGate(
+  block: QualityGateBlock | null,
+  rawBody: string | null,
+): string | null {
+  if (block === null && rawBody === null) return null;
+  if (block === null) {
+    // Block was present in source but state set it to null — caller wants
+    // to drop the block. Still return null so emitBlock skips emission.
+    return null;
+  }
+  if (rawBody !== null) {
+    const reparsed = tryReparseQualityGate(rawBody);
+    if (reparsed !== null && qualityGateEqual(reparsed, block)) {
+      return rawBody;
+    }
+  }
+  return canonicalQualityGate(block);
+}
+
+function canonicalQualityGate(block: QualityGateBlock): string {
+  if (block.run === null) return '';
+  return canonicalQualityGateRun(block.run);
+}
+
+function canonicalQualityGateRun(run: QualityGateRun): string {
+  const parts: string[] = [
+    `started_at=${formatPrototypingAttr(run.started_at)}`,
+    `completed_at=${formatPrototypingAttr(run.completed_at)}`,
+    `status=${formatPrototypingAttr(run.status)}`,
+    `iteration=${formatPrototypingAttr(String(run.iteration))}`,
+    `commands_run=${formatPrototypingAttr(run.commands_run)}`,
+  ];
+  for (const [k, v] of Object.entries(run.extra_attrs)) {
+    parts.push(`${k}=${formatPrototypingAttr(v)}`);
+  }
+  return `<run ${parts.join(' ')}/>`;
+}
+
 function emitTimestamps(
   ts: Record<string, string>,
   rawBody: string | null,
@@ -415,6 +571,90 @@ function blockersEqual(a: Blocker[], b: Blocker[]): boolean {
   return true;
 }
 
+function prototypingEqual(
+  a: PrototypingBlock,
+  b: PrototypingBlock,
+): boolean {
+  if (a.sketches.length !== b.sketches.length) return false;
+  if (a.spikes.length !== b.spikes.length) return false;
+  if (a.skipped.length !== b.skipped.length) return false;
+  for (let i = 0; i < a.sketches.length; i++) {
+    if (!sketchEqual(a.sketches[i]!, b.sketches[i]!)) return false;
+  }
+  for (let i = 0; i < a.spikes.length; i++) {
+    if (!spikeEqual(a.spikes[i]!, b.spikes[i]!)) return false;
+  }
+  for (let i = 0; i < a.skipped.length; i++) {
+    if (!skippedEqual(a.skipped[i]!, b.skipped[i]!)) return false;
+  }
+  return true;
+}
+
+function sketchEqual(a: SketchEntry, b: SketchEntry): boolean {
+  return (
+    a.slug === b.slug &&
+    a.cycle === b.cycle &&
+    a.decision === b.decision &&
+    a.status === b.status &&
+    extraAttrsEqual(a.extra_attrs, b.extra_attrs)
+  );
+}
+
+function spikeEqual(a: SpikeEntry, b: SpikeEntry): boolean {
+  return (
+    a.slug === b.slug &&
+    a.cycle === b.cycle &&
+    a.decision === b.decision &&
+    a.verdict === b.verdict &&
+    a.status === b.status &&
+    extraAttrsEqual(a.extra_attrs, b.extra_attrs)
+  );
+}
+
+function skippedEqual(a: SkippedEntry, b: SkippedEntry): boolean {
+  return (
+    a.at === b.at &&
+    a.cycle === b.cycle &&
+    a.reason === b.reason &&
+    extraAttrsEqual(a.extra_attrs, b.extra_attrs)
+  );
+}
+
+function extraAttrsEqual(
+  a: Record<string, string>,
+  b: Record<string, string>,
+): boolean {
+  const ak = Object.keys(a);
+  const bk = Object.keys(b);
+  if (ak.length !== bk.length) return false;
+  for (let i = 0; i < ak.length; i++) {
+    if (ak[i] !== bk[i]) return false;
+    const key = ak[i]!;
+    if (a[key] !== b[key]) return false;
+  }
+  return true;
+}
+
+function qualityGateEqual(
+  a: QualityGateBlock,
+  b: QualityGateBlock,
+): boolean {
+  if (a.run === null && b.run === null) return true;
+  if (a.run === null || b.run === null) return false;
+  return qualityGateRunEqual(a.run, b.run);
+}
+
+function qualityGateRunEqual(a: QualityGateRun, b: QualityGateRun): boolean {
+  return (
+    a.started_at === b.started_at &&
+    a.completed_at === b.completed_at &&
+    a.status === b.status &&
+    a.iteration === b.iteration &&
+    a.commands_run === b.commands_run &&
+    extraAttrsEqual(a.extra_attrs, b.extra_attrs)
+  );
+}
+
 function recordsEqual(
   a: Record<string, string>,
   b: Record<string, string>,
@@ -553,6 +793,220 @@ function tryReparseBlockers(raw: string): Blocker[] | null {
   }
 }
 
+/**
+ * Reparse a `<prototyping>` body for fidelity comparison. Mirrors the
+ * shape of `parsePrototypingBody` in parser.ts but is intentionally
+ * separate (and tolerant) — returns `null` on any structural surprise so
+ * the caller falls back to canonical emission rather than throwing.
+ *
+ * Unlike the parser, this helper does NOT throw on missing required
+ * attributes. If the source body has been hand-edited into something the
+ * parser would reject, we treat it as "definitely changed" and return
+ * `null` so the canonical writer takes over.
+ */
+function tryReparsePrototyping(raw: string): PrototypingBlock | null {
+  try {
+    const sketches: SketchEntry[] = [];
+    const spikes: SpikeEntry[] = [];
+    const skipped: SkippedEntry[] = [];
+    const selfClose = /^<([a-z_]+)(\s+[^>]*?)?\s*\/>\s*$/;
+    for (const line of raw.split('\n')) {
+      const t = line.trim();
+      if (t === '' || t.startsWith('<!--')) continue;
+      const m = t.match(selfClose);
+      if (!m) {
+        // Anything non-comment that isn't a self-closing tag means the
+        // raw body is no longer a clean match for the parsed value.
+        return null;
+      }
+      const tag = m[1] ?? '';
+      const attrs = parseAttrInline(m[2] ?? '');
+      if (tag === 'sketch') {
+        const slug = attrs['slug'];
+        const cycle = attrs['cycle'];
+        const decision = attrs['decision'];
+        const status = attrs['status'] ?? 'resolved';
+        if (slug === undefined || cycle === undefined || decision === undefined) {
+          return null;
+        }
+        if (status !== 'resolved') return null;
+        sketches.push({
+          slug,
+          cycle,
+          decision,
+          status: 'resolved',
+          extra_attrs: extractExtras(attrs, [
+            'slug',
+            'cycle',
+            'decision',
+            'status',
+          ]),
+        });
+      } else if (tag === 'spike') {
+        const slug = attrs['slug'];
+        const cycle = attrs['cycle'];
+        const decision = attrs['decision'];
+        const verdict = attrs['verdict'];
+        const status = attrs['status'] ?? 'resolved';
+        if (
+          slug === undefined ||
+          cycle === undefined ||
+          decision === undefined ||
+          verdict === undefined
+        ) {
+          return null;
+        }
+        if (verdict !== 'yes' && verdict !== 'no' && verdict !== 'partial') {
+          return null;
+        }
+        if (status !== 'resolved') return null;
+        spikes.push({
+          slug,
+          cycle,
+          decision,
+          verdict,
+          status: 'resolved',
+          extra_attrs: extractExtras(attrs, [
+            'slug',
+            'cycle',
+            'decision',
+            'verdict',
+            'status',
+          ]),
+        });
+      } else if (tag === 'skipped') {
+        const at = attrs['at'];
+        const cycle = attrs['cycle'];
+        const reason = attrs['reason'];
+        if (at === undefined || cycle === undefined || reason === undefined) {
+          return null;
+        }
+        skipped.push({
+          at,
+          cycle,
+          reason,
+          extra_attrs: extractExtras(attrs, ['at', 'cycle', 'reason']),
+        });
+      } else {
+        // Unknown self-closing tag — return null to force canonical path.
+        return null;
+      }
+    }
+    return { sketches, spikes, skipped };
+  } catch {
+    return null;
+  }
+}
+
+/** Mirror of parser's `parsePrototypingAttrs` — kept local to avoid
+ *  cross-file circular reach (mutator must not import parser internals). */
+function parseAttrInline(span: string): Record<string, string> {
+  const out: Record<string, string> = {};
+  const re = /([a-zA-Z_][\w-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s/>]+))/g;
+  let m: RegExpExecArray | null;
+  while ((m = re.exec(span)) !== null) {
+    const key = m[1] ?? '';
+    const value: string =
+      (m[2] !== undefined ? m[2] : undefined) ??
+      (m[3] !== undefined ? m[3] : undefined) ??
+      m[4] ??
+      '';
+    if (key !== '') out[key] = value;
+  }
+  return out;
+}
+
+function extractExtras(
+  all: Record<string, string>,
+  known: readonly string[],
+): Record<string, string> {
+  const out: Record<string, string> = {};
+  for (const [k, v] of Object.entries(all)) {
+    if (!known.includes(k)) out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Reparse a `<quality_gate>` body for fidelity comparison. Mirror of
+ * `tryReparsePrototyping` — returns `null` on any structural surprise so
+ * the caller falls back to canonical emission rather than throwing.
+ *
+ * Tolerant of multiple `<run/>` lines (last-wins, matching the parser),
+ * blank lines, and comments. Strict on attribute presence and enum
+ * validity — a hand-edited body that drops `commands_run` will fail to
+ * round-trip and fall through to canonical form, which is correct.
+ */
+function tryReparseQualityGate(raw: string): QualityGateBlock | null {
+  try {
+    let run: QualityGateRun | null = null;
+    const selfClose = /^<([a-z_]+)(\s+[^>]*?)?\s*\/>\s*$/;
+    for (const line of raw.split('\n')) {
+      const t = line.trim();
+      if (t === '' || t.startsWith('<!--')) continue;
+      const m = t.match(selfClose);
+      if (!m) {
+        // Anything non-comment that isn't a self-closing tag means the
+        // raw body is no longer a clean match for the parsed value.
+        return null;
+      }
+      const tag = m[1] ?? '';
+      if (tag !== 'run') {
+        // Unknown self-closing tag inside <quality_gate> — force canonical.
+        return null;
+      }
+      const attrs = parseAttrInline(m[2] ?? '');
+      const started_at = attrs['started_at'];
+      const completed_at = attrs['completed_at'];
+      const status = attrs['status'];
+      const iterationRaw = attrs['iteration'];
+      const commands_run = attrs['commands_run'];
+      if (
+        started_at === undefined ||
+        completed_at === undefined ||
+        status === undefined ||
+        iterationRaw === undefined ||
+        commands_run === undefined
+      ) {
+        return null;
+      }
+      if (
+        status !== 'pass' &&
+        status !== 'fail' &&
+        status !== 'timeout' &&
+        status !== 'skipped'
+      ) {
+        return null;
+      }
+      const iteration = Number(iterationRaw);
+      if (
+        !Number.isFinite(iteration) ||
+        !Number.isInteger(iteration) ||
+        iteration < 0
+      ) {
+        return null;
+      }
+      run = {
+        started_at,
+        completed_at,
+        status: status as QualityGateStatus,
+        iteration,
+        commands_run,
+        extra_attrs: extractExtras(attrs, [
+          'started_at',
+          'completed_at',
+          'status',
+          'iteration',
+          'commands_run',
+        ]),
+      };
+    }
+    return { run };
+  } catch {
+    return null;
+  }
+}
+
 function tryReparseTimestamps(
   raw: string,
 ): Record<string, string> | null {