@vladpazych/dexter 0.1.0

package/src/output/output.test.ts

@@ -0,0 +1,374 @@
+import { describe, expect, test } from "bun:test"
+import { block, field, heading, list, render, text, toValue } from "./index.ts"
+import { setColorEnabled } from "../terminal/colors.ts"
+
+// Disable colors for deterministic CLI output in tests
+setColorEnabled(false)
+
+// ---------------------------------------------------------------------------
+// Fixtures
+// ---------------------------------------------------------------------------
+
+const commitDoc = block(
+  "commit",
+  field("hash", "abc123"),
+  field("intent", "impl: add feature"),
+  field("files", list("file", text("src/a.ts"), text("src/b.ts"))),
+)
+
+const scopeDoc = block(
+  "scope",
+  { path: "meta/src" },
+  heading("meta/src"),
+  field("status", "clean"),
+  field("changes", 0),
+)
+
+const mixedDoc = block("result", field("count", 3), text("some note"))
+
+const simpleList = list(text("alpha"), text("beta"), text("gamma"))
+
+const nestedDoc = block(
+  "report",
+  heading("Quality Report"),
+  block("lint", field("errors", 0), field("warnings", 2)),
+  block("typecheck", field("errors", 0)),
+)
+
+// ---------------------------------------------------------------------------
+// Builders
+// ---------------------------------------------------------------------------
+
+describe("builders", () => {
+  test("text creates a text node", () => {
+    const n = text("hello")
+    expect(n).toEqual({ kind: "text", value: "hello" })
+  })
+
+  test("text with style", () => {
+    const n = text("error", "red")
+    expect(n).toEqual({ kind: "text", value: "error", style: "red" })
+  })
+
+  test("field with primitive", () => {
+    const n = field("count", 42)
+    expect(n).toEqual({ kind: "field", label: "count", value: 42 })
+  })
+
+  test("field with node value", () => {
+    const n = field("items", list(text("a")))
+    expect(n.kind).toBe("field")
+    expect(typeof n.value).toBe("object")
+  })
+
+  test("block without attrs", () => {
+    const n = block("commit", field("hash", "abc"))
+    expect(n.kind).toBe("block")
+    expect(n.tag).toBe("commit")
+    expect(n.attrs).toBeUndefined()
+    expect(n.children).toHaveLength(1)
+  })
+
+  test("block with attrs", () => {
+    const n = block("scope", { path: "meta" }, field("status", "ok"))
+    expect(n.attrs).toEqual({ path: "meta" })
+    expect(n.children).toHaveLength(1)
+  })
+
+  test("list without tag", () => {
+    const n = list(text("a"), text("b"))
+    expect(n.kind).toBe("list")
+    expect(n.tag).toBeUndefined()
+    expect(n.items).toHaveLength(2)
+  })
+
+  test("list with tag", () => {
+    const n = list("file", text("a"), text("b"))
+    expect(n.tag).toBe("file")
+    expect(n.items).toHaveLength(2)
+  })
+
+  test("heading", () => {
+    const n = heading("Title")
+    expect(n).toEqual({ kind: "heading", text: "Title" })
+  })
+})
+
+// ---------------------------------------------------------------------------
+// JSON renderer
+// ---------------------------------------------------------------------------
+
+describe("json", () => {
+  test("text → string", () => {
+    expect(toValue(text("hello"))).toBe("hello")
+  })
+
+  test("field preserves number type", () => {
+    expect(toValue(field("count", 42))).toEqual({ count: 42 })
+  })
+
+  test("field preserves boolean type", () => {
+    expect(toValue(field("ok", true))).toEqual({ ok: true })
+  })
+
+  test("field preserves string type", () => {
+    expect(toValue(field("name", "alice"))).toEqual({ name: "alice" })
+  })
+
+  test("block with fields → object", () => {
+    const value = toValue(commitDoc) as Record<string, unknown>
+    expect(value.hash).toBe("abc123")
+    expect(value.intent).toBe("impl: add feature")
+    expect(value.files).toEqual(["src/a.ts", "src/b.ts"])
+  })
+
+  test("block with attrs merges into object", () => {
+    const value = toValue(scopeDoc) as Record<string, unknown>
+    expect(value.path).toBe("meta/src")
+    expect(value.status).toBe("clean")
+    expect(value.changes).toBe(0)
+  })
+
+  test("heading omitted from JSON", () => {
+    const value = toValue(scopeDoc) as Record<string, unknown>
+    expect("text" in value).toBe(false)
+  })
+
+  test("list → array", () => {
+    expect(toValue(simpleList)).toEqual(["alpha", "beta", "gamma"])
+  })
+
+  test("block with non-field children → array", () => {
+    const doc = block("items", text("one"), text("two"))
+    expect(toValue(doc)).toEqual(["one", "two"])
+  })
+
+  test("single non-field child unwraps", () => {
+    const doc = block("wrapper", text("only"))
+    expect(toValue(doc)).toBe("only")
+  })
+
+  test("mixed block → object with content", () => {
+    const value = toValue(mixedDoc) as Record<string, unknown>
+    expect(value.count).toBe(3)
+    expect(value.content).toEqual(["some note"])
+  })
+
+  test("nested blocks", () => {
+    const value = toValue(nestedDoc) as Record<string, unknown>
+    expect(value).toEqual({
+      lint: { errors: 0, warnings: 2 },
+      typecheck: { errors: 0 },
+    })
+  })
+
+  test("render json produces valid JSON string", () => {
+    const str = render(commitDoc, "json")
+    const parsed = JSON.parse(str)
+    expect(parsed.hash).toBe("abc123")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// XML renderer
+// ---------------------------------------------------------------------------
+
+describe("xml", () => {
+  test("text → escaped content", () => {
+    expect(render(text("a < b & c"), "xml")).toBe("a &lt; b &amp; c")
+  })
+
+  test("text style ignored", () => {
+    expect(render(text("bold", "bold"), "xml")).toBe("bold")
+  })
+
+  test("field → element", () => {
+    expect(render(field("hash", "abc"), "xml")).toBe("<hash>abc</hash>")
+  })
+
+  test("field with number", () => {
+    expect(render(field("count", 42), "xml")).toBe("<count>42</count>")
+  })
+
+  test("block → tag wrapping", () => {
+    const xml = render(block("commit", field("hash", "abc")), "xml")
+    expect(xml).toBe("<commit>\n<hash>abc</hash>\n</commit>")
+  })
+
+  test("block with attrs", () => {
+    const xml = render(block("scope", { path: "meta/src" }, field("status", "ok")), "xml")
+    expect(xml).toContain('<scope path="meta/src">')
+    expect(xml).toContain("<status>ok</status>")
+  })
+
+  test("attrs escaped", () => {
+    const xml = render(block("scope", { path: 'a "b" c' }), "xml")
+    expect(xml).toContain('path="a &quot;b&quot; c"')
+  })
+
+  test("empty block → self-closing", () => {
+    expect(render(block("empty"), "xml")).toBe("<empty />")
+  })
+
+  test("heading omitted", () => {
+    const xml = render(block("sec", heading("Title"), field("x", 1)), "xml")
+    expect(xml).not.toContain("Title")
+    expect(xml).toContain("<x>1</x>")
+  })
+
+  test("list without tag → concatenated", () => {
+    const xml = render(list(text("a"), text("b")), "xml")
+    expect(xml).toBe("a\nb")
+  })
+
+  test("list with tag → wrapped items", () => {
+    const xml = render(list("file", text("a.ts"), text("b.ts")), "xml")
+    expect(xml).toBe("<file>a.ts</file>\n<file>b.ts</file>")
+  })
+
+  test("nested structure", () => {
+    const xml = render(commitDoc, "xml")
+    expect(xml).toContain("<commit>")
+    expect(xml).toContain("<hash>abc123</hash>")
+    expect(xml).toContain("<file>src/a.ts</file>")
+    expect(xml).toContain("</commit>")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// CLI renderer
+// ---------------------------------------------------------------------------
+
+describe("cli", () => {
+  test("text without style", () => {
+    expect(render(text("hello"), "cli")).toBe("hello")
+  })
+
+  test("text style applied (colors disabled → plain)", () => {
+    // Colors disabled via setColorEnabled(false) at top
+    expect(render(text("error", "red"), "cli")).toBe("error")
+  })
+
+  test("field renders label: value", () => {
+    const out = render(field("hash", "abc"), "cli")
+    expect(out).toContain("hash:")
+    expect(out).toContain("abc")
+  })
+
+  test("field with number", () => {
+    const out = render(field("count", 42), "cli")
+    expect(out).toContain("42")
+  })
+
+  test("block joins children with newlines", () => {
+    const out = render(block("test", field("a", 1), field("b", 2)), "cli")
+    expect(out).toContain("\n")
+    expect(out).toContain("a:")
+    expect(out).toContain("b:")
+  })
+
+  test("heading renders with newline prefix", () => {
+    const out = render(heading("Title"), "cli")
+    expect(out).toContain("Title")
+    expect(out.startsWith("\n")).toBe(true)
+  })
+
+  test("list one per line", () => {
+    const out = render(simpleList, "cli")
+    const lines = out.split("\n")
+    expect(lines).toHaveLength(3)
+    expect(lines[0]).toBe("alpha")
+    expect(lines[1]).toBe("beta")
+    expect(lines[2]).toBe("gamma")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Markdown renderer
+// ---------------------------------------------------------------------------
+
+describe("md", () => {
+  test("text plain", () => {
+    expect(render(text("hello"), "md")).toBe("hello")
+  })
+
+  test("text bold", () => {
+    expect(render(text("important", "bold"), "md")).toBe("**important**")
+  })
+
+  test("text dim → italic", () => {
+    expect(render(text("subtle", "dim"), "md")).toBe("*subtle*")
+  })
+
+  test("text color style → plain", () => {
+    expect(render(text("red text", "red"), "md")).toBe("red text")
+  })
+
+  test("field → bold label", () => {
+    expect(render(field("hash", "abc"), "md")).toBe("**hash:** abc")
+  })
+
+  test("heading → markdown heading", () => {
+    expect(render(heading("Title"), "md")).toBe("## Title")
+  })
+
+  test("list → bullet items", () => {
+    const out = render(simpleList, "md")
+    expect(out).toBe("- alpha\n- beta\n- gamma")
+  })
+
+  test("block separates children with blank lines", () => {
+    const out = render(block("sec", field("a", 1), field("b", 2)), "md")
+    expect(out).toContain("\n\n")
+    expect(out).toContain("**a:** 1")
+    expect(out).toContain("**b:** 2")
+  })
+
+  test("full document", () => {
+    const doc = block(
+      "report",
+      heading("Quality Report"),
+      field("errors", 0),
+      list(text("lint passed"), text("types passed")),
+    )
+    const out = render(doc, "md")
+    expect(out).toContain("## Quality Report")
+    expect(out).toContain("**errors:** 0")
+    expect(out).toContain("- lint passed")
+    expect(out).toContain("- types passed")
+  })
+})
+
+// ---------------------------------------------------------------------------
+// Cross-mode: same tree, four outputs
+// ---------------------------------------------------------------------------
+
+describe("polymorphic render", () => {
+  test("same tree produces valid output in all modes", () => {
+    const doc = block(
+      "result",
+      heading("Commit"),
+      field("hash", "abc123"),
+      field("ok", true),
+      field("files", list(text("a.ts"))),
+    )
+
+    const json = render(doc, "json")
+    const parsed = JSON.parse(json)
+    expect(parsed.hash).toBe("abc123")
+    expect(parsed.ok).toBe(true)
+    expect(parsed.files).toEqual(["a.ts"])
+
+    const xml = render(doc, "xml")
+    expect(xml).toContain("<hash>abc123</hash>")
+    expect(xml).toContain("<ok>true</ok>")
+
+    const cli = render(doc, "cli")
+    expect(cli).toContain("abc123")
+    expect(cli).toContain("Commit")
+
+    const md = render(doc, "md")
+    expect(md).toContain("## Commit")
+    expect(md).toContain("**hash:** abc123")
+  })
+})

package/src/output/render-cli.ts

@@ -0,0 +1,55 @@
+/**
+ * CLI renderer — colored terminal output respecting NO_COLOR/FORCE_COLOR.
+ *
+ * Uses the existing `c` convenience object from terminal/colors.
+ */
+
+import type { Node, Style } from "./types.ts"
+import { c } from "../terminal/colors.ts"
+
+const styleFn: Record<Style, (text: string) => string> = {
+  bold: c.bolded,
+  dim: c.dimmed,
+  red: c.red,
+  green: c.green,
+  yellow: c.yellow,
+  blue: c.blue,
+  cyan: c.cyan,
+  magenta: c.magenta,
+  gray: c.gray,
+}
+
+function renderValue(value: string | number | boolean | Node): string {
+  if (typeof value !== "object") return String(value)
+  return renderCli(value)
+}
+
+/** Render a node tree as colored CLI output. */
+export function renderCli(node: Node): string {
+  switch (node.kind) {
+    case "text":
+      return node.style ? styleFn[node.style](node.value) : node.value
+
+    case "field": {
+      const label = c.dimmed(`${node.label}:`)
+      const rendered = renderValue(node.value)
+      if (rendered.includes("\n")) return `${label}\n${rendered}`
+      return `${label} ${rendered}`
+    }
+
+    case "block": {
+      const parts: string[] = []
+      for (const child of node.children) {
+        const rendered = renderCli(child)
+        if (rendered) parts.push(rendered)
+      }
+      return parts.join("\n")
+    }
+
+    case "list":
+      return node.items.map(renderCli).join("\n")
+
+    case "heading":
+      return `\n${c.bolded(node.text)}`
+  }
+}

package/src/output/render-json.ts

@@ -0,0 +1,80 @@
+/**
+ * JSON renderer — converts document tree to structured JavaScript values.
+ *
+ * `toValue` produces a JS value (object/array/string/number/boolean).
+ * `renderJson` stringifies it.
+ */
+
+import type { Node } from "./types.ts"
+
+/** Convert a node tree to a JSON-compatible JavaScript value. */
+export function toValue(node: Node): unknown {
+  switch (node.kind) {
+    case "text":
+      return node.value
+
+    case "field":
+      // Standalone field → single-entry object
+      return { [node.label]: fieldValue(node.value) }
+
+    case "block":
+      return blockValue(node)
+
+    case "list":
+      return node.items.map(toValue)
+
+    case "heading":
+      return undefined
+  }
+}
+
+function fieldValue(value: string | number | boolean | Node): unknown {
+  if (typeof value !== "object") return value
+  return toValue(value)
+}
+
+function blockValue(node: Extract<Node, { kind: "block" }>): unknown {
+  const fields: [string, unknown][] = []
+  const content: unknown[] = []
+
+  // Attrs become top-level properties
+  if (node.attrs) {
+    for (const [k, v] of Object.entries(node.attrs)) {
+      fields.push([k, v])
+    }
+  }
+
+  for (const child of node.children) {
+    if (child.kind === "field") {
+      fields.push([child.label, fieldValue(child.value)])
+    } else if (child.kind === "heading") {
+      // Omitted in JSON
+    } else if (child.kind === "block") {
+      fields.push([child.tag, blockValue(child)])
+    } else {
+      content.push(toValue(child))
+    }
+  }
+
+  // All fields → object
+  if (fields.length > 0 && content.length === 0) {
+    return Object.fromEntries(fields)
+  }
+
+  // All non-fields → array (or single value)
+  if (fields.length === 0) {
+    if (content.length === 1) return content[0]
+    return content
+  }
+
+  // Mixed → object with content key
+  const obj = Object.fromEntries(fields)
+  obj.content = content
+  return obj
+}
+
+/** Render a node tree as a compact JSON string. */
+export function renderJson(node: Node): string {
+  const value = toValue(node)
+  return JSON.stringify(value)
+}

package/src/output/render-md.ts

@@ -0,0 +1,43 @@
+/**
+ * Markdown renderer — structured output as GitHub-flavored markdown.
+ *
+ * Useful for PR descriptions, documentation, and GitHub comments.
+ */
+
+import type { Node } from "./types.ts"
+
+function renderValue(value: string | number | boolean | Node): string {
+  if (typeof value !== "object") return String(value)
+  return renderMd(value)
+}
+
+/** Render a node tree as markdown. */
+export function renderMd(node: Node): string {
+  switch (node.kind) {
+    case "text":
+      if (node.style === "bold") return `**${node.value}**`
+      if (node.style === "dim") return `*${node.value}*`
+      return node.value
+
+    case "field": {
+      const rendered = renderValue(node.value)
+      if (rendered.includes("\n")) return `**${node.label}:**\n${rendered}`
+      return `**${node.label}:** ${rendered}`
+    }
+
+    case "block": {
+      const parts: string[] = []
+      for (const child of node.children) {
+        const rendered = renderMd(child)
+        if (rendered) parts.push(rendered)
+      }
+      return parts.join("\n\n")
+    }
+
+    case "list":
+      return node.items.map((item) => `- ${renderMd(item)}`).join("\n")
+
+    case "heading":
+      return `## ${node.text}`
+  }
+}

package/src/output/render-xml.ts

@@ -0,0 +1,55 @@
+/**
+ * XML renderer — semantic tags for hooks and skill preprocessing.
+ *
+ * Flat output (no indentation) to keep content compact for LLM consumption.
+ */
+
+import type { Node } from "./types.ts"
+
+export function escapeXml(str: string): string {
+  return str.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;")
+}
+
+function renderValue(value: string | number | boolean | Node): string {
+  if (typeof value !== "object") return escapeXml(String(value))
+  return renderXml(value)
+}
+
+function attrs(record: Readonly<Record<string, string>>): string {
+  const pairs = Object.entries(record).map(([k, v]) => `${k}="${escapeXml(v)}"`)
+  return pairs.length > 0 ? " " + pairs.join(" ") : ""
+}
+
+/** Render a node tree as XML. */
+export function renderXml(node: Node): string {
+  switch (node.kind) {
+    case "text":
+      return escapeXml(node.value)
+
+    case "field": {
+      const inner = renderValue(node.value)
+      if (inner.includes("\n")) {
+        return `<${node.label}>\n${inner}\n</${node.label}>`
+      }
+      return `<${node.label}>${inner}</${node.label}>`
+    }
+
+    case "block": {
+      const attrStr = node.attrs ? attrs(node.attrs) : ""
+      const children = node.children.filter((c) => c.kind !== "heading").map(renderXml)
+      const inner = children.join("\n")
+      if (!inner) return `<${node.tag}${attrStr} />`
+      return `<${node.tag}${attrStr}>\n${inner}\n</${node.tag}>`
+    }
+
+    case "list": {
+      if (node.tag) {
+        return node.items.map((item) => `<${node.tag}>${renderXml(item)}</${node.tag}>`).join("\n")
+      }
+      return node.items.map(renderXml).join("\n")
+    }
+
+    case "heading":
+      return ""
+  }
+}

package/src/output/render.ts

@@ -0,0 +1,23 @@
+/**
+ * Polymorphic render dispatcher.
+ */
+
+import type { Node, OutputMode } from "./types.ts"
+import { renderCli } from "./render-cli.ts"
+import { renderJson } from "./render-json.ts"
+import { renderXml } from "./render-xml.ts"
+import { renderMd } from "./render-md.ts"
+
+/** Render a document tree to a string in the given output mode. */
+export function render(node: Node, mode: OutputMode): string {
+  switch (mode) {
+    case "cli":
+      return renderCli(node)
+    case "json":
+      return renderJson(node)
+    case "xml":
+      return renderXml(node)
+    case "md":
+      return renderMd(node)
+  }
+}

package/src/output/types.ts

@@ -0,0 +1,44 @@
+/**
+ * Polymorphic output — build once, render to any format.
+ *
+ * Five node kinds form a document tree.
+ * Four output modes produce strings for different consumers.
+ */
+
+export type Style = "bold" | "dim" | "red" | "green" | "yellow" | "blue" | "cyan" | "magenta" | "gray"
+
+export type Primitive = string | number | boolean
+
+export type TextNode = {
+  readonly kind: "text"
+  readonly value: string
+  readonly style?: Style
+}
+
+export type FieldNode = {
+  readonly kind: "field"
+  readonly label: string
+  readonly value: Primitive | Node
+}
+
+export type BlockNode = {
+  readonly kind: "block"
+  readonly tag: string
+  readonly attrs?: Readonly<Record<string, string>>
+  readonly children: readonly Node[]
+}
+
+export type ListNode = {
+  readonly kind: "list"
+  readonly tag?: string
+  readonly items: readonly Node[]
+}
+
+export type HeadingNode = {
+  readonly kind: "heading"
+  readonly text: string
+}
+
+export type Node = TextNode | FieldNode | BlockNode | ListNode | HeadingNode
+
+export type OutputMode = "cli" | "json" | "xml" | "md"