buildanything 1.8.0 → 2.1.1

package/src/graph/parser/screenshot.ts

@@ -0,0 +1,342 @@
+/**
+ * Screenshot extractor — STUB for hypothetical environment.
+ *
+ * Slice 5 production mode will:
+ *   - Replace stub captions/tags with multimodal subagent dispatches
+ *   - Add real image decoding (Sharp / @napi-rs/image) for dimensions + palette
+ *   - Cache extractions by SHA256 of image bytes to avoid redundant API calls
+ *
+ * The basename--class ID convention ensures the same image bytes posted under
+ * different image classes (e.g. "reference" vs "brand_drift") produce distinct
+ * node IDs, preventing ID collisions in the graph.
+ *
+ * Source of truth: docs/graph/11-slice5-schema.md
+ *
+ * @module
+ */
+
+import { createHash } from "node:crypto";
+import { ids, kebab } from "../ids.js";
+import type {
+  BrandDriftObservationNode,
+  Confidence,
+  DogfoodFindingNode,
+  GraphEdge,
+  GraphNode,
+  ImageComponentDetectionNode,
+  Relation,
+  ScreenshotNode,
+} from "../types.js";
+import { dhash } from "../util/dhash.js";
+
+// ---------------------------------------------------------------------------
+// Constants
+// ---------------------------------------------------------------------------
+
+const PRODUCED_BY_AGENT = "screenshot-extractor-stub";
+const PRODUCED_AT_STEP = "varies";
+
+/**
+ * Stub nodes are INFERRED: caption/dna_axis_tags/palette are LLM-derived even in production.
+ */
+const SCREENSHOT_STUB_CONFIDENCE: Confidence = "INFERRED";
+
+/** Schema tag for Slice 5 fragments — referenced in doc comment above. */
+const SCHEMA_TAG = "buildanything-slice-5";
+
+const VALID_IMAGE_CLASSES = new Set(["reference", "brand_drift", "dogfood"] as const);
+
+const DNA_AXIS_KEYWORDS = [
+  "scope",
+  "density",
+  "character",
+  "material",
+  "motion",
+  "type",
+  "copy",
+] as const;
+
+// ---------------------------------------------------------------------------
+// Public types
+// ---------------------------------------------------------------------------
+
+export interface ScreenshotInput {
+  imagePath: string;
+  imageClass: "reference" | "brand_drift" | "dogfood";
+  imageBytes: Uint8Array;
+  linkedScreenId?: string | null;
+  linkedFindingId?: string | null;
+  findingSeverity?: "critical" | "major" | "minor";
+  findingDescription?: string;
+}
+
+export interface ScreenshotExtractResult {
+  ok: boolean;
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  errors: { message: string }[];
+}
+
+export interface BrandDriftObservationInput {
+  prodScreenshotId: string;
+  referenceScreenshotId: string;
+  axis: "scope" | "density" | "character" | "material" | "motion" | "type" | "copy";
+  score: number;
+  verdict: "drift" | "ok" | "needs-review";
+  observationId: string;
+}
+
+export interface BrandDriftObservationResult {
+  ok: boolean;
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+  errors: { message: string }[];
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeEdge(
+  source: string,
+  target: string,
+  relation: Relation,
+  sourceFile: string,
+): GraphEdge {
+  return {
+    source,
+    target,
+    relation,
+    confidence: "EXTRACTED",
+    source_file: sourceFile,
+    source_location: "L0",
+    produced_by_agent: PRODUCED_BY_AGENT,
+    produced_at_step: PRODUCED_AT_STEP,
+  };
+}
+
+function basenameNoExt(filePath: string): string {
+  const last = filePath.split("/").pop() ?? filePath;
+  const dotIdx = last.lastIndexOf(".");
+  return dotIdx > 0 ? last.slice(0, dotIdx) : last;
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+export function extractScreenshot(input: ScreenshotInput): ScreenshotExtractResult {
+  const errors: { message: string }[] = [];
+  const nodes: GraphNode[] = [];
+  const edges: GraphEdge[] = [];
+
+  // -- Validation -----------------------------------------------------------
+
+  if (!input.imagePath || !input.imagePath.trim()) {
+    errors.push({ message: "imagePath is empty or whitespace" });
+    return { ok: false, nodes, edges, errors };
+  }
+
+  if (!input.imageBytes || input.imageBytes.length === 0) {
+    errors.push({ message: "imageBytes is empty" });
+    return { ok: false, nodes, edges, errors };
+  }
+
+  if (!VALID_IMAGE_CLASSES.has(input.imageClass as any)) {
+    errors.push({
+      message: `imageClass "${input.imageClass}" is not one of: reference, brand_drift, dogfood`,
+    });
+    return { ok: false, nodes, edges, errors };
+  }
+
+  // -- Compute hashes -------------------------------------------------------
+
+  const perceptualHash = dhash(input.imageBytes);
+  const contentSha8 = createHash("sha256")
+    .update(input.imageBytes)
+    .digest("hex")
+    .slice(0, 8);
+
+  const rawBasename = basenameNoExt(input.imagePath);
+
+  // CRITICAL ID-collision fix: include imageClass in the basename used for ID
+  // so that the same bytes sent under different classes produce different IDs.
+  const idBasename = `${rawBasename}--${input.imageClass}`;
+  const screenshotId = ids.screenshot(kebab(idBasename), contentSha8);
+
+  // -- Class-aware stub extraction ------------------------------------------
+
+  let caption: string;
+  let dnaAxisTags: string[];
+  let dominantPalette: string[];
+
+  if (input.imageClass === "reference") {
+    caption = "Stub caption — Slice 5 production mode dispatches a multimodal subagent";
+
+    // Heuristic: scan rawBasename for DNA axis keywords
+    const lower = rawBasename.toLowerCase();
+    dnaAxisTags = DNA_AXIS_KEYWORDS.filter((kw) => lower.includes(kw));
+
+    dominantPalette = ["#000000", "#FFFFFF"];
+  } else {
+    caption = `Stub caption (${input.imageClass}) — Slice 5 production mode derives this from a multimodal subagent dispatch`;
+    dnaAxisTags = [];
+    dominantPalette = [];
+  }
+
+  // -- Dogfood finding node (emitted before screenshot so we can reference its id) --
+
+  const isDogfoodWithFinding =
+    input.imageClass === "dogfood" &&
+    input.linkedFindingId &&
+    input.linkedFindingId.trim();
+
+  const resolvedFindingId = isDogfoodWithFinding
+    ? ids.dogfoodFinding(input.linkedFindingId!)
+    : null;
+
+  if (isDogfoodWithFinding) {
+    const findingNode: DogfoodFindingNode = {
+      id: resolvedFindingId!,
+      label: input.linkedFindingId!,
+      entity_type: "dogfood_finding",
+      source_file: input.imagePath,
+      source_location: "L0",
+      confidence: SCREENSHOT_STUB_CONFIDENCE,
+      finding_id: input.linkedFindingId!,
+      severity: input.findingSeverity ?? "minor",
+      description:
+        input.findingDescription ??
+        "Stub finding — Slice 5 production mode reads evidence/dogfood/findings.json",
+      screenshot_id: screenshotId,
+      affected_screen_id: input.linkedScreenId ?? null,
+    };
+    nodes.push(findingNode);
+  }
+
+  // -- Screenshot node ------------------------------------------------------
+
+  const screenshotNode: ScreenshotNode = {
+    id: screenshotId,
+    label: rawBasename,
+    entity_type: "screenshot",
+    source_file: input.imagePath,
+    source_location: "L0",
+    confidence: SCREENSHOT_STUB_CONFIDENCE,
+    image_path: input.imagePath,
+    image_class: input.imageClass,
+    caption,
+    perceptual_hash: perceptualHash,
+    dominant_palette: dominantPalette,
+    image_dimensions: "0x0",
+    dna_axis_tags: dnaAxisTags,
+    linked_screen_id: input.linkedScreenId ?? null,
+    linked_finding_id: resolvedFindingId,
+  };
+  nodes.push(screenshotNode);
+
+  // -- Component detection (reference class only) ---------------------------
+
+  if (input.imageClass === "reference") {
+    const detectionId = ids.imageComponentDetection(
+      screenshotId,
+      "stub-component",
+      1,
+    );
+    const detectionNode: ImageComponentDetectionNode = {
+      id: detectionId,
+      label: "stub-component",
+      entity_type: "image_component_detection",
+      source_file: input.imagePath,
+      source_location: "L0",
+      confidence: SCREENSHOT_STUB_CONFIDENCE,
+      screenshot_id: screenshotId,
+      component_label: "stub-component",
+      bounding_box: null,
+      detection_confidence: null,
+    };
+    nodes.push(detectionNode);
+    edges.push(
+      makeEdge(screenshotId, detectionId, "image_has_component_detection", input.imagePath),
+    );
+  }
+
+  // -- Linking edges --------------------------------------------------------
+
+  if (input.linkedScreenId && input.linkedScreenId.trim()) {
+    edges.push(
+      makeEdge(screenshotId, input.linkedScreenId, "screenshot_depicts_screen", input.imagePath),
+    );
+  }
+
+  if (isDogfoodWithFinding) {
+    edges.push(
+      makeEdge(screenshotId, resolvedFindingId!, "screenshot_evidences_finding", input.imagePath),
+    );
+  }
+
+  return { ok: true, nodes, edges, errors };
+}
+
+export function extractBrandDriftObservation(
+  input: BrandDriftObservationInput,
+): BrandDriftObservationResult {
+  const errors: { message: string }[] = [];
+  const nodes: GraphNode[] = [];
+  const edges: GraphEdge[] = [];
+
+  if (!input.prodScreenshotId || !input.prodScreenshotId.trim()) {
+    errors.push({ message: "prodScreenshotId is empty" });
+  }
+  if (!input.referenceScreenshotId || !input.referenceScreenshotId.trim()) {
+    errors.push({ message: "referenceScreenshotId is empty" });
+  }
+  if (!input.observationId || !input.observationId.trim()) {
+    errors.push({ message: "observationId is empty" });
+  }
+  if (errors.length > 0) {
+    return { ok: false, nodes, edges, errors };
+  }
+
+  const nodeId = ids.brandDriftObservation(input.observationId);
+
+  const node: BrandDriftObservationNode = {
+    id: nodeId,
+    label: input.observationId,
+    entity_type: "brand_drift_observation",
+    source_file: "<brand-guardian>",
+    source_location: "L0",
+    confidence: "INFERRED",
+    observation_id: input.observationId,
+    prod_screenshot_id: input.prodScreenshotId,
+    reference_screenshot_id: input.referenceScreenshotId,
+    axis: input.axis,
+    score: input.score,
+    verdict: input.verdict,
+  };
+  nodes.push(node);
+
+  const edgeBase = {
+    confidence: "INFERRED" as Confidence,
+    source_file: "<brand-guardian>",
+    source_location: "L0",
+    produced_by_agent: "design-brand-guardian",
+    produced_at_step: "5.1",
+  };
+
+  edges.push({
+    source: nodeId,
+    target: input.prodScreenshotId,
+    relation: "prod_drifts_from_reference_prod",
+    ...edgeBase,
+  });
+
+  edges.push({
+    source: nodeId,
+    target: input.referenceScreenshotId,
+    relation: "prod_drifts_from_reference_ref",
+    ...edgeBase,
+  });
+
+  return { ok: true, nodes, edges, errors };
+}

package/src/graph/parser/sprint-tasks.ts

@@ -0,0 +1,317 @@
+// Deterministic, schema-aware extractor for sprint-tasks.md.
+// Source of truth: docs/graph/09-slice4-schema.md.
+// No LLM, no I/O. Caller passes the markdown content and path.
+
+import { ids, sha256Hex } from "../ids.js";
+import type {
+  ExtractError,
+  ExtractResult,
+  GraphEdge,
+  GraphFragment,
+  GraphNode,
+  Relation,
+  TaskNode,
+} from "../types.js";
+
+const PRODUCED_BY = "planner";
+const PRODUCED_AT_STEP = "2.3.2";
+
+// ---------------------------------------------------------------------------
+// Shared helpers (same pattern as component-manifest.ts / page-spec.ts)
+// ---------------------------------------------------------------------------
+
+interface Line {
+  n: number;
+  text: string;
+}
+
+interface Ctx {
+  mdPath: string;
+  errors: ExtractError[];
+  nodes: GraphNode[];
+  edges: GraphEdge[];
+}
+
+function loc(line: number): string {
+  return `L${line}`;
+}
+
+function pushError(ctx: Ctx, line: number, message: string): void {
+  ctx.errors.push({ line, message });
+}
+
+function splitLines(content: string): Line[] {
+  return content.split(/\r?\n/).map((text, i) => ({ n: i + 1, text }));
+}
+
+function splitRow(text: string): string[] {
+  let s = text.trim();
+  if (s.startsWith("|")) s = s.slice(1);
+  if (s.endsWith("|")) s = s.slice(0, -1);
+  return s.split("|").map((c) => c.trim());
+}
+
+const SEP_RE = /^\s*\|?\s*[-:| ]+\s*\|?\s*$/;
+
+interface TableRow {
+  cells: Record<string, string>;
+  line: number;
+}
+
+interface Table {
+  headerLine: number;
+  headers: string[];
+  rows: TableRow[];
+}
+
+function findTables(lines: Line[]): Table[] {
+  const tables: Table[] = [];
+  let i = 0;
+  while (i < lines.length - 1) {
+    const cur = lines[i];
+    const next = lines[i + 1];
+    if (
+      cur.text.includes("|") &&
+      next.text.includes("|") &&
+      SEP_RE.test(next.text)
+    ) {
+      const headers = splitRow(cur.text).map((h) => h.toLowerCase().trim());
+      const rows: TableRow[] = [];
+      let j = i + 2;
+      while (j < lines.length) {
+        const ln = lines[j];
+        if (!ln.text.includes("|")) break;
+        if (SEP_RE.test(ln.text)) { j++; continue; }
+        const cells = splitRow(ln.text);
+        if (cells.every((c) => c === "")) { j++; continue; }
+        const row: Record<string, string> = {};
+        for (let c = 0; c < headers.length; c++) {
+          row[headers[c]] = (cells[c] ?? "").trim();
+        }
+        rows.push({ cells: row, line: ln.n });
+        j++;
+      }
+      tables.push({ headerLine: cur.n, headers, rows });
+      i = j;
+    } else {
+      i++;
+    }
+  }
+  return tables;
+}
+
+function isEmptyRef(s: string): boolean {
+  const t = s.trim();
+  return t === "" || t === "\u2014" || t === "-" || t === "\u2013";
+}
+
+function sortNodes(nodes: GraphNode[]): GraphNode[] {
+  return [...nodes].sort((a, b) => (a.id < b.id ? -1 : a.id > b.id ? 1 : 0));
+}
+
+function sortEdges(edges: GraphEdge[]): GraphEdge[] {
+  return [...edges].sort((a, b) => {
+    const k = (e: GraphEdge): string => `${e.relation} ${e.source} ${e.target}`;
+    return k(a) < k(b) ? -1 : k(a) > k(b) ? 1 : 0;
+  });
+}
+
+function makeEdge(
+  ctx: Ctx,
+  source: string,
+  target: string,
+  relation: Relation,
+  line: number,
+): GraphEdge {
+  return {
+    source,
+    target,
+    relation,
+    confidence: "EXTRACTED",
+    source_file: ctx.mdPath,
+    source_location: loc(line),
+    produced_by_agent: PRODUCED_BY,
+    produced_at_step: PRODUCED_AT_STEP,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Owns-files parsing
+// ---------------------------------------------------------------------------
+
+function parseOwnsFiles(raw: string): string[] {
+  if (isEmptyRef(raw)) return [];
+  return raw
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0);
+}
+
+// ---------------------------------------------------------------------------
+// Required columns
+// ---------------------------------------------------------------------------
+
+const REQUIRED_COLUMNS = [
+  "task id",
+  "title",
+  "size",
+  "dependencies",
+  "behavioral test",
+  "owns files",
+  "implementing phase",
+  "feature",
+  "screens",
+];
+
+const VALID_SIZES = new Set(["S", "M", "L"]);
+
+// ---------------------------------------------------------------------------
+// Public entrypoint
+// ---------------------------------------------------------------------------
+
+export function extractSprintTasks(input: {
+  mdPath: string;
+  mdContent: string;
+}): ExtractResult {
+  const { mdPath, mdContent } = input;
+  const lines = splitLines(mdContent);
+  const ctx: Ctx = { mdPath, errors: [], nodes: [], edges: [] };
+
+  const tables = findTables(lines);
+  if (tables.length === 0) {
+    return {
+      ok: false,
+      errors: [{ line: 0, message: "No pipe tables found in sprint-tasks.md" }],
+    };
+  }
+
+  // Collect all valid rows across tables
+  const allRows: { row: TableRow; headers: string[]; headerLine: number }[] = [];
+
+  for (const table of tables) {
+    if (table.headers.length < 9) {
+      pushError(
+        ctx,
+        table.headerLine,
+        `Table has fewer than 9 columns (got ${table.headers.length})`,
+      );
+      continue;
+    }
+
+    for (const col of REQUIRED_COLUMNS) {
+      if (!table.headers.includes(col)) {
+        const displayName = col
+          .split(" ")
+          .map((w) => w[0].toUpperCase() + w.slice(1))
+          .join(" ");
+        pushError(ctx, table.headerLine, `Missing required column: '${displayName}'`);
+      }
+    }
+
+    if (ctx.errors.length > 0) continue;
+
+    for (const row of table.rows) {
+      allRows.push({ row, headers: table.headers, headerLine: table.headerLine });
+    }
+  }
+
+  if (ctx.errors.length > 0) {
+    return { ok: false, errors: ctx.errors };
+  }
+
+  // Track task IDs for duplicate detection
+  const taskIdSeen = new Map<string, number>();
+
+  for (const { row } of allRows) {
+    const rawTaskId = row.cells["task id"] ?? "";
+    if (rawTaskId.trim() === "") {
+      pushError(ctx, row.line, `Anonymous task at L${row.line} — Task ID is required`);
+      continue;
+    }
+
+    const taskIdLower = rawTaskId.toLowerCase();
+    const prev = taskIdSeen.get(taskIdLower);
+    if (prev !== undefined) {
+      pushError(
+        ctx,
+        row.line,
+        `Duplicate Task ID '${rawTaskId}' at L${prev} and L${row.line}`,
+      );
+      continue;
+    }
+    taskIdSeen.set(taskIdLower, row.line);
+
+    const size = (row.cells["size"] ?? "").trim().toUpperCase();
+    if (!VALID_SIZES.has(size)) {
+      pushError(
+        ctx,
+        row.line,
+        `Invalid Size '${(row.cells["size"] ?? "").trim()}' at L${row.line} — must be S, M, or L`,
+      );
+      continue;
+    }
+
+    const taskId = rawTaskId.trim();
+    const title = (row.cells["title"] ?? "").trim();
+    const behavioralTest = (row.cells["behavioral test"] ?? "").trim();
+    const implementingPhase = (row.cells["implementing phase"] ?? "").trim();
+    const ownsFiles = parseOwnsFiles(row.cells["owns files"] ?? "");
+    const featureRaw = (row.cells['feature'] ?? '').trim();
+    const featureId = isEmptyRef(featureRaw) ? null : ids.feature(featureRaw);
+    const screensRaw = (row.cells['screens'] ?? '').trim();
+    const screenIds = isEmptyRef(screensRaw) ? [] : screensRaw.split(',').map((s) => s.trim()).filter((s) => s.length > 0).map((s) => ids.screen(s)).sort();
+
+    const node: TaskNode = {
+      id: ids.task(taskId),
+      label: title,
+      entity_type: "task",
+      source_file: mdPath,
+      source_location: loc(row.line),
+      confidence: "EXTRACTED",
+      task_id: taskId,
+      title,
+      size: size as "S" | "M" | "L",
+      behavioral_test: behavioralTest,
+      assigned_phase: implementingPhase,
+      feature_id: featureId,
+      screen_ids: screenIds,
+      owns_files: ownsFiles,
+    };
+    ctx.nodes.push(node);
+
+    // Feature edge
+    if (featureId) {
+      ctx.edges.push(makeEdge(ctx, node.id, featureId, "task_implements_feature", row.line));
+    }
+
+    // Screen edges
+    for (const screenId of screenIds) {
+      ctx.edges.push(makeEdge(ctx, node.id, screenId, "task_touches_screen", row.line));
+    }
+
+    // Dependency edges
+    const depsRaw = (row.cells["dependencies"] ?? "").trim();
+    if (!isEmptyRef(depsRaw)) {
+      const deps = depsRaw.split(",").map((d) => d.trim()).filter((d) => d.length > 0);
+      for (const dep of deps) {
+        ctx.edges.push(makeEdge(ctx, node.id, ids.task(dep), "task_depends_on", row.line));
+      }
+    }
+  }
+
+  if (ctx.errors.length > 0) {
+    return { ok: false, errors: ctx.errors };
+  }
+
+  const fragment: GraphFragment = {
+    version: 1,
+    schema: "buildanything-slice-4",
+    source_file: mdPath,
+    source_sha: sha256Hex(mdContent),
+    produced_at: new Date().toISOString(),
+    nodes: sortNodes(ctx.nodes),
+    edges: sortEdges(ctx.edges),
+  };
+
+  return { ok: true, fragment, errors: [] };
+}