@stcrft/statecraft-core 1.1.2

package/src/parser.ts

@@ -0,0 +1,207 @@
+import fs from "node:fs";
+import path from "node:path";
+import { parse } from "yaml";
+import type { Board, Column, Task } from "./ast.js";
+
+/** Thrown when YAML is invalid or required fields are missing/wrong. */
+export class ParseError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = "ParseError";
+  }
+}
+
+function assertObject(value: unknown, path: string): asserts value is Record<string, unknown> {
+  if (value === null || typeof value !== "object" || Array.isArray(value)) {
+    throw new ParseError(`${path}: expected an object`);
+  }
+}
+
+function assertArray(value: unknown, path: string): asserts value is unknown[] {
+  if (!Array.isArray(value)) {
+    throw new ParseError(`${path}: expected an array`);
+  }
+}
+
+function assertString(value: unknown, path: string): asserts value is string {
+  if (typeof value !== "string") {
+    throw new ParseError(`${path}: expected a string`);
+  }
+}
+
+/**
+ * Parse YAML board content into a typed Board AST.
+ * @param content - Raw YAML string (board file content).
+ * @returns Board AST.
+ * @throws ParseError when YAML is invalid or required fields are missing/wrong.
+ */
+export function parseBoardFromString(content: string): Board {
+  let raw: unknown;
+  try {
+    raw = parse(content);
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new ParseError(`Invalid YAML: ${message}`);
+  }
+
+  assertObject(raw, "root");
+  const root = raw as Record<string, unknown>;
+
+  // board (required, non-empty string)
+  if (!("board" in root)) {
+    throw new ParseError("Missing required field: board");
+  }
+  assertString(root.board, "board");
+  if (root.board.trim() === "") {
+    throw new ParseError("board must be a non-empty string");
+  }
+
+  // columns (required, non-empty array)
+  if (!("columns" in root)) {
+    throw new ParseError("Missing required field: columns");
+  }
+  assertArray(root.columns, "columns");
+  if (root.columns.length === 0) {
+    throw new ParseError("columns must be a non-empty array");
+  }
+
+  const columns: Column[] = root.columns.map((item: unknown, i: number) => {
+    const path = `columns[${i}]`;
+    if (typeof item === "string") {
+      if (item.trim() === "") {
+        throw new ParseError(`${path}: column name must be non-empty`);
+      }
+      return { name: item };
+    }
+    if (item !== null && typeof item === "object" && !Array.isArray(item)) {
+      const obj = item as Record<string, unknown>;
+      if (!("name" in obj)) {
+        throw new ParseError(`${path}: column object must have "name"`);
+      }
+      assertString(obj.name, `${path}.name`);
+      if ((obj.name as string).trim() === "") {
+        throw new ParseError(`${path}.name: must be non-empty`);
+      }
+      const col: Column = { name: obj.name as string };
+      if ("limit" in obj && obj.limit !== undefined) {
+        if (typeof obj.limit !== "number" || !Number.isInteger(obj.limit) || obj.limit < 1) {
+          throw new ParseError(`${path}.limit: must be a positive integer`);
+        }
+        col.limit = obj.limit;
+      }
+      return col;
+    }
+    throw new ParseError(`${path}: expected a string or object with "name" (and optional "limit")`);
+  });
+
+  // tasks (required, object; may be empty)
+  if (!("tasks" in root)) {
+    throw new ParseError("Missing required field: tasks");
+  }
+  if (root.tasks === null || typeof root.tasks !== "object" || Array.isArray(root.tasks)) {
+    throw new ParseError("tasks must be an object (map of task id to task)");
+  }
+  const tasksRaw = root.tasks as Record<string, unknown>;
+  const tasks: Record<string, Task> = {};
+
+  for (const [id, rawTask] of Object.entries(tasksRaw)) {
+    const path = `tasks.${id}`;
+    assertObject(rawTask, path);
+    const t = rawTask as Record<string, unknown>;
+
+    if (!("title" in t)) {
+      throw new ParseError(`${path}: missing required field "title"`);
+    }
+    assertString(t.title, `${path}.title`);
+
+    if (!("status" in t)) {
+      throw new ParseError(`${path}: missing required field "status"`);
+    }
+    assertString(t.status, `${path}.status`);
+
+    const task: Task = {
+      title: t.title as string,
+      status: t.status as string,
+    };
+
+    if ("description" in t && t.description !== undefined) {
+      assertString(t.description, `${path}.description`);
+      task.description = t.description as string;
+    }
+    if ("spec" in t && t.spec !== undefined) {
+      assertString(t.spec, `${path}.spec`);
+      task.spec = t.spec as string;
+    }
+    if ("owner" in t && t.owner !== undefined) {
+      assertString(t.owner, `${path}.owner`);
+      task.owner = t.owner as string;
+    }
+    if ("priority" in t && t.priority !== undefined) {
+      assertString(t.priority, `${path}.priority`);
+      task.priority = t.priority as string;
+    }
+    if ("depends_on" in t && t.depends_on !== undefined) {
+      if (typeof t.depends_on === "string") {
+        task.depends_on = [t.depends_on];
+      } else if (Array.isArray(t.depends_on)) {
+        const arr = t.depends_on as unknown[];
+        for (let i = 0; i < arr.length; i++) {
+          assertString(arr[i], `${path}.depends_on[${i}]`);
+        }
+        task.depends_on = arr as string[];
+      } else {
+        throw new ParseError(`${path}.depends_on: expected a string or array of strings`);
+      }
+    }
+
+    tasks[id] = task;
+  }
+
+  return {
+    board: root.board as string,
+    columns,
+    tasks,
+  };
+}
+
+/**
+ * Heuristic: treat as file path if no newline and (ends with .yaml/.yml or contains path sep).
+ * Otherwise treat as raw YAML content.
+ */
+function looksLikePath(input: string): boolean {
+  if (input.includes("\n")) return false;
+  const trimmed = input.trim();
+  if (trimmed.length === 0) return false;
+  return (
+    trimmed.endsWith(".yaml") ||
+    trimmed.endsWith(".yml") ||
+    trimmed.includes("/") ||
+    trimmed.includes(path.sep)
+  );
+}
+
+/**
+ * Parse a board from a file path or raw YAML string.
+ * - If `input` looks like a path (no newline, ends with .yaml/.yml or contains path separator),
+ *   the file is read from disk (relative to cwd) and parsed.
+ * - Otherwise `input` is parsed as raw YAML content.
+ *
+ * @param input - File path (absolute or relative to cwd) or raw YAML string.
+ * @returns Board AST.
+ * @throws ParseError when YAML is invalid or required fields are missing/wrong.
+ * @throws ParseError when input is a path and the file cannot be read (e.g. not found).
+ */
+export function parseBoard(input: string): Board {
+  if (looksLikePath(input)) {
+    const resolved = path.resolve(input.trim());
+    let content: string;
+    try {
+      content = fs.readFileSync(resolved, "utf-8");
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw new ParseError(`Cannot read file "${resolved}": ${message}`);
+    }
+    return parseBoardFromString(content);
+  }
+  return parseBoardFromString(input);
+}

package/src/summarize.ts

@@ -0,0 +1,91 @@
+import type { Board, Column } from "./ast.js";
+
+/**
+ * Returns a plain-text summary of the board for terminal output or paste into chat/docs.
+ * Format: board name, per-column counts, optional WIP limit lines, task list, optional blocked section.
+ * @param board - Parsed board AST.
+ * @returns Summary string ending with a single newline.
+ */
+export function summarize(board: Board): string {
+  const columnNames = board.columns.map((c: Column) => c.name);
+  const lastColumnName = columnNames.length > 0 ? columnNames[columnNames.length - 1] : "";
+
+  // Per-column task counts
+  const countByColumn: Record<string, number> = {};
+  for (const name of columnNames) {
+    countByColumn[name] = 0;
+  }
+  for (const task of Object.values(board.tasks)) {
+    if (task.status in countByColumn) {
+      countByColumn[task.status]++;
+    }
+  }
+
+  const lines: string[] = [];
+
+  // Board name
+  lines.push(`Board: ${board.board}`);
+  lines.push("");
+
+  // Columns: name (count), ...
+  const columnPart = columnNames.map((name) => `${name} (${countByColumn[name] ?? 0})`).join(", ");
+  lines.push(`Columns: ${columnPart}`);
+
+  // WIP limit: for each column with limit and count >= limit
+  for (const col of board.columns) {
+    if (col.limit != null && col.limit >= 1) {
+      const count = countByColumn[col.name] ?? 0;
+      if (count >= col.limit) {
+        lines.push(`  ${col.name} at WIP limit (${count}/${col.limit})`);
+      }
+    }
+  }
+
+  lines.push("");
+
+  // Tasks: ordered by column order, then by task id within column
+  lines.push("Tasks:");
+  const taskIds = Object.keys(board.tasks);
+  const statusToIndex: Record<string, number> = {};
+  columnNames.forEach((name, i) => {
+    statusToIndex[name] = i;
+  });
+  const sortedIds = taskIds.slice().sort((a, b) => {
+    const taskA = board.tasks[a];
+    const taskB = board.tasks[b];
+    const idxA = statusToIndex[taskA.status] ?? 999;
+    const idxB = statusToIndex[taskB.status] ?? 999;
+    if (idxA !== idxB) return idxA - idxB;
+    return a.localeCompare(b);
+  });
+  if (sortedIds.length === 0) {
+    lines.push("  (none)");
+  } else {
+    for (const id of sortedIds) {
+      const task = board.tasks[id];
+      lines.push(`  ${id} [${task.status}] ${task.title}`);
+    }
+  }
+
+  // Blocked: task has depends_on and at least one dependency is not in last column
+  const blocked: { id: string; deps: string[] }[] = [];
+  for (const id of taskIds) {
+    const task = board.tasks[id];
+    const deps = task.depends_on ?? [];
+    const unmet = deps.filter((depId) => {
+      const dep = board.tasks[depId];
+      return dep && dep.status !== lastColumnName;
+    });
+    if (unmet.length > 0) {
+      blocked.push({ id, deps: unmet });
+    }
+  }
+  if (blocked.length > 0) {
+    lines.push("");
+    for (const { id, deps } of blocked) {
+      lines.push(`Blocked: ${id} (depends on ${deps.join(", ")})`);
+    }
+  }
+
+  return lines.join("\n") + "\n";
+}

package/src/validation.ts

@@ -0,0 +1,132 @@
+import type { Board, Column, Task } from "./ast.js";
+
+/** Canonical column set per spec: exact names and order. */
+export const CANONICAL_COLUMNS = ["Backlog", "Ready", "In Progress", "Done"] as const;
+
+/** A single validation error (or warning). */
+export interface ValidationError {
+  /** Human-readable message. */
+  message: string;
+  /** Optional path (e.g. "tasks.AUTH-12.status") for tooling. */
+  path?: string;
+  /** Optional code (e.g. "STATUS_INVALID") for programmatic handling. */
+  code?: string;
+}
+
+/** Result of validating a board. Does not throw; caller decides what to do with errors. */
+export interface ValidationResult {
+  /** True if there are no errors. */
+  valid: boolean;
+  /** List of validation errors (empty if valid). */
+  errors: ValidationError[];
+  /** Optional warnings (e.g. spec file missing). Empty if none. */
+  warnings?: ValidationError[];
+}
+
+/**
+ * Run all validation rules on a parsed board. Does not throw; returns a list of errors.
+ * @param board - Parsed board AST.
+ * @returns List of validation errors (empty if valid).
+ */
+export function validateBoard(board: Board): ValidationError[] {
+  const errors: ValidationError[] = [];
+  const columnNames = board.columns.map((c) => c.name);
+
+  // Canonical columns: must be Backlog, Ready, In Progress, Done in that order
+  if (board.columns.length !== CANONICAL_COLUMNS.length) {
+    errors.push({
+      path: "columns",
+      message: `Board must have exactly ${CANONICAL_COLUMNS.length} columns: ${CANONICAL_COLUMNS.join(", ")}. Got ${board.columns.length}.`,
+      code: "COLUMNS_NOT_CANONICAL",
+    });
+  } else {
+    for (let i = 0; i < CANONICAL_COLUMNS.length; i++) {
+      const expected = CANONICAL_COLUMNS[i];
+      const actual = board.columns[i]?.name;
+      if (actual !== expected) {
+        errors.push({
+          path: `columns[${i}]`,
+          message: `Column at index ${i} must be "${expected}". Got "${actual}". Canonical order: ${CANONICAL_COLUMNS.join(", ")}.`,
+          code: "COLUMNS_NOT_CANONICAL",
+        });
+      }
+    }
+  }
+
+  // Column names unique (redundant if canonical check passed, but keeps other checks consistent)
+  const seen = new Set<string>();
+  for (let i = 0; i < board.columns.length; i++) {
+    const name = board.columns[i].name;
+    if (seen.has(name)) {
+      errors.push({
+        path: `columns[${i}]`,
+        message: `Duplicate column name: "${name}"`,
+        code: "DUPLICATE_COLUMN",
+      });
+    }
+    seen.add(name);
+  }
+
+  // Task status matches column; depends_on refs exist
+  const taskIds = new Set(Object.keys(board.tasks));
+  for (const [id, task] of Object.entries(board.tasks)) {
+    const taskPath = `tasks.${id}`;
+
+    if (!columnNames.includes(task.status)) {
+      errors.push({
+        path: `${taskPath}.status`,
+        message: `Task status "${task.status}" does not match any column. Valid columns: ${columnNames.join(", ")}`,
+        code: "STATUS_INVALID",
+      });
+    }
+
+    if (task.depends_on) {
+      for (const refId of task.depends_on) {
+        if (!taskIds.has(refId)) {
+          errors.push({
+            path: `${taskPath}.depends_on`,
+            message: `Task "${id}" depends on "${refId}", which does not exist`,
+            code: "DEPENDS_ON_INVALID",
+          });
+        }
+      }
+    }
+  }
+
+  // WIP limit per column
+  const countByStatus = new Map<string, number>();
+  for (const task of Object.values(board.tasks)) {
+    countByStatus.set(task.status, (countByStatus.get(task.status) ?? 0) + 1);
+  }
+
+  for (let i = 0; i < board.columns.length; i++) {
+    const col = board.columns[i];
+    if (col.limit == null) continue;
+    const count = countByStatus.get(col.name) ?? 0;
+    if (count > col.limit) {
+      errors.push({
+        path: `columns[${i}]`,
+        message: `Column "${col.name}" has limit ${col.limit} but ${count} task(s) in that status`,
+        code: "WIP_LIMIT_EXCEEDED",
+      });
+    }
+  }
+
+  return errors;
+}
+
+/**
+ * Validate a parsed board. Returns a result with `valid` and `errors`; does not throw.
+ * Use this as the public API; use `validateBoard` if you only need the error list.
+ *
+ * @param board - Parsed board AST.
+ * @returns ValidationResult with `valid: true` and empty `errors` when valid, otherwise `valid: false` and non-empty `errors`.
+ */
+export function validate(board: Board): ValidationResult {
+  const errors = validateBoard(board);
+  return {
+    valid: errors.length === 0,
+    errors,
+    warnings: [],
+  };
+}

package/test/fixtures/board.yaml

@@ -0,0 +1,10 @@
+board: "Fixture Board"
+columns:
+  - Backlog
+  - Ready
+  - In Progress
+  - Done
+tasks:
+  f1:
+    title: "Fixture task"
+    status: Backlog

package/test/parser.test.ts

@@ -0,0 +1,250 @@
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, it, expect } from "vitest";
+import { parseBoard, parseBoardFromString, ParseError } from "../src/parser.js";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const validBoardYaml = `
+board: "Auth Service"
+columns:
+  - Backlog
+  - Ready
+  - name: In Progress
+    limit: 3
+  - Done
+tasks:
+  AUTH-7:
+    title: "Audit existing JWT usage"
+    status: Done
+    owner: kristijan
+    priority: high
+    description: "List all endpoints and call sites using JWT."
+  AUTH-12:
+    title: "Replace JWT with PASETO"
+    status: In Progress
+    owner: kristijan
+    priority: high
+    depends_on: AUTH-7
+    spec: tasks/AUTH-12.md
+  AUTH-13:
+    title: "Add rate limiting to auth endpoints"
+    status: Ready
+    priority: medium
+    description: "Per-IP and per-user limits; configurable thresholds."
+`;
+
+describe("parseBoardFromString", () => {
+  it("parses valid YAML and returns typed Board", () => {
+    const board = parseBoardFromString(validBoardYaml);
+
+    expect(board.board).toBe("Auth Service");
+    expect(board.columns).toHaveLength(4);
+    expect(board.columns[0]).toEqual({ name: "Backlog" });
+    expect(board.columns[1]).toEqual({ name: "Ready" });
+    expect(board.columns[2]).toEqual({ name: "In Progress", limit: 3 });
+    expect(board.columns[3]).toEqual({ name: "Done" });
+
+    expect(Object.keys(board.tasks)).toEqual(["AUTH-7", "AUTH-12", "AUTH-13"]);
+    expect(board.tasks["AUTH-7"].title).toBe("Audit existing JWT usage");
+    expect(board.tasks["AUTH-7"].status).toBe("Done");
+    expect(board.tasks["AUTH-7"].description).toBe("List all endpoints and call sites using JWT.");
+
+    expect(board.tasks["AUTH-12"].title).toBe("Replace JWT with PASETO");
+    expect(board.tasks["AUTH-12"].status).toBe("In Progress");
+    expect(board.tasks["AUTH-12"].depends_on).toEqual(["AUTH-7"]);
+    expect(board.tasks["AUTH-12"].spec).toBe("tasks/AUTH-12.md");
+
+    expect(board.tasks["AUTH-13"].title).toBe("Add rate limiting to auth endpoints");
+    expect(board.tasks["AUTH-13"].status).toBe("Ready");
+    expect(board.tasks["AUTH-13"].priority).toBe("medium");
+  });
+
+  it("normalizes depends_on single string to array", () => {
+    const yaml = `
+board: "Test"
+columns: [A, B]
+tasks:
+  t1:
+    title: "One"
+    status: A
+  t2:
+    title: "Two"
+    status: B
+    depends_on: t1
+`;
+    const board = parseBoardFromString(yaml);
+    expect(board.tasks["t2"].depends_on).toEqual(["t1"]);
+  });
+
+  it("normalizes depends_on array as-is", () => {
+    const yaml = `
+board: "Test"
+columns: [A, B, C]
+tasks:
+  t1: { title: "One", status: A }
+  t2: { title: "Two", status: B }
+  t3:
+    title: "Three"
+    status: C
+    depends_on: [t1, t2]
+`;
+    const board = parseBoardFromString(yaml);
+    expect(board.tasks["t3"].depends_on).toEqual(["t1", "t2"]);
+  });
+
+  it("parses minimal board (empty tasks)", () => {
+    const yaml = `
+board: "Minimal"
+columns: [Backlog, Ready, In Progress, Done]
+tasks: {}
+`;
+    const board = parseBoardFromString(yaml);
+    expect(board.board).toBe("Minimal");
+    expect(board.columns).toHaveLength(4);
+    expect(board.tasks).toEqual({});
+  });
+
+  it("throws ParseError on invalid YAML", () => {
+    expect(() => parseBoardFromString("not: valid: yaml:")).toThrow(ParseError);
+    expect(() => parseBoardFromString("not: valid: yaml:")).toThrow(/Invalid YAML/);
+
+    expect(() => parseBoardFromString("[")).toThrow(ParseError);
+    expect(() => parseBoardFromString("[")).toThrow(/Invalid YAML/);
+  });
+
+  it("throws ParseError when board is missing", () => {
+    const yaml = `
+columns: [A]
+tasks: {}
+`;
+    expect(() => parseBoardFromString(yaml)).toThrow(ParseError);
+    expect(() => parseBoardFromString(yaml)).toThrow(/Missing required field: board/);
+  });
+
+  it("throws ParseError when columns is missing", () => {
+    const yaml = `
+board: "Test"
+tasks: {}
+`;
+    expect(() => parseBoardFromString(yaml)).toThrow(ParseError);
+    expect(() => parseBoardFromString(yaml)).toThrow(/Missing required field: columns/);
+  });
+
+  it("throws ParseError when tasks is missing", () => {
+    const yaml = `
+board: "Test"
+columns: [A]
+`;
+    expect(() => parseBoardFromString(yaml)).toThrow(ParseError);
+    expect(() => parseBoardFromString(yaml)).toThrow(/Missing required field: tasks/);
+  });
+
+  it("throws ParseError when board is empty string", () => {
+    const yaml = `
+board: ""
+columns: [A]
+tasks: {}
+`;
+    expect(() => parseBoardFromString(yaml)).toThrow(ParseError);
+    expect(() => parseBoardFromString(yaml)).toThrow(/non-empty/);
+  });
+
+  it("throws ParseError when columns is not an array", () => {
+    const yaml = `
+board: "Test"
+columns: "not an array"
+tasks: {}
+`;
+    expect(() => parseBoardFromString(yaml)).toThrow(ParseError);
+    expect(() => parseBoardFromString(yaml)).toThrow(/expected an array/);
+  });
+
+  it("throws ParseError when columns is empty", () => {
+    const yaml = `
+board: "Test"
+columns: []
+tasks: {}
+`;
+    expect(() => parseBoardFromString(yaml)).toThrow(ParseError);
+    expect(() => parseBoardFromString(yaml)).toThrow(/non-empty array/);
+  });
+
+  it("throws ParseError when task is missing title", () => {
+    const yaml = `
+board: "Test"
+columns: [A]
+tasks:
+  t1:
+    status: A
+`;
+    expect(() => parseBoardFromString(yaml)).toThrow(ParseError);
+    expect(() => parseBoardFromString(yaml)).toThrow(/title/);
+  });
+
+  it("throws ParseError when task is missing status", () => {
+    const yaml = `
+board: "Test"
+columns: [A]
+tasks:
+  t1:
+    title: "Task"
+`;
+    expect(() => parseBoardFromString(yaml)).toThrow(ParseError);
+    expect(() => parseBoardFromString(yaml)).toThrow(/status/);
+  });
+
+  it("throws ParseError when column limit is not a positive integer", () => {
+    const yaml = `
+board: "Test"
+columns:
+  - name: In Progress
+    limit: "three"
+tasks: {}
+`;
+    expect(() => parseBoardFromString(yaml)).toThrow(ParseError);
+    expect(() => parseBoardFromString(yaml)).toThrow(/limit/);
+  });
+
+  it("throws ParseError when tasks is not an object", () => {
+    const yaml = `
+board: "Test"
+columns: [A]
+tasks: []
+`;
+    expect(() => parseBoardFromString(yaml)).toThrow(ParseError);
+    expect(() => parseBoardFromString(yaml)).toThrow(/tasks must be an object/);
+  });
+});
+
+describe("parseBoard (path or content)", () => {
+  it("parses raw YAML content when input contains newline", () => {
+    const yaml = `
+board: "From Content"
+columns: [A]
+tasks: {}
+`;
+    const board = parseBoard(yaml);
+    expect(board.board).toBe("From Content");
+  });
+
+  it("parses from file path when input looks like path", () => {
+    const fixturePath = path.join(__dirname, "fixtures", "board.yaml");
+    const board = parseBoard(fixturePath);
+    expect(board.board).toBe("Fixture Board");
+    expect(board.columns).toHaveLength(4);
+    expect(board.columns.map((c) => (typeof c === "string" ? c : c.name))).toEqual([
+      "Backlog",
+      "Ready",
+      "In Progress",
+      "Done",
+    ]);
+    expect(board.tasks["f1"].title).toBe("Fixture task");
+    expect(board.tasks["f1"].status).toBe("Backlog");
+  });
+
+  it("throws ParseError when path does not exist", () => {
+    expect(() => parseBoard("/nonexistent/board.yaml")).toThrow(ParseError);
+    expect(() => parseBoard("/nonexistent/board.yaml")).toThrow(/Cannot read file/);
+  });
+});