@shipwrights/source-jira 0.1.0 → 0.2.0

package/README.md

@@ -81,7 +81,7 @@ config:
 
 ## Status
 
-v0.1.0 — Phase 1. Implements `healthcheck` + `listAvailable`. Materialise, transitions, and PR-link writes land in later phases.
+v0.2.0 — Phase 2. Implements `healthcheck`, `listAvailable`, `pickNext`, and `materialize` (full ADF→markdown rendering of Jira issue descriptions). Status transitions (`markStatus`) and PR-link writes (`attachPR`) still throw `"lands in Phase N"` errors and arrive in v0.3 / v0.4.
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shipwrights/source-jira",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Jira backlog source adapter for @shipwrights/core. Pulls issues via JQL, materialises them as epic files, writes status transitions and PR links back to Jira.",
   "type": "module",
   "main": "./src/index.mjs",

package/src/adf-to-markdown.mjs

@@ -0,0 +1,192 @@
+// ADF (Atlassian Document Format) → markdown converter.
+//
+// Handles the 80% of ADF nodes that show up in a normal Jira issue
+// description: paragraphs, headings, bullet / ordered lists, code blocks,
+// blockquotes, horizontal rules, links, inline cards, mentions, emoji.
+//
+// Unsupported nodes (tables, panels, status pills, expand/collapse, dates,
+// embeds) emit an HTML comment so the consumer sees what was dropped without
+// the document falling apart silently. Tables are common enough to flag, but
+// implementing them well needs row/header logic that doesn't earn its keep
+// for a v1.
+//
+// Marks (inline text formatting) handled: strong, em, code, strike, link.
+// Underline and subsup render as plain text (no clean markdown equivalent).
+
+const UNSUPPORTED_NODES = new Set([
+  "table",
+  "tableRow",
+  "tableHeader",
+  "tableCell",
+  "panel",
+  "expand",
+  "nestedExpand",
+  "status",
+  "date",
+  "mediaGroup",
+  "mediaSingle",
+  "media",
+  "embedCard",
+  "decisionList",
+  "decisionItem",
+  "taskList",
+  "taskItem",
+]);
+
+/**
+ * Convert an ADF root document to markdown.
+ *
+ * @param {object | null | undefined} adf - the document; usually fields.description from a Jira issue
+ * @returns {string} markdown (empty string for null/undefined)
+ */
+export function adfToMarkdown(adf) {
+  if (!adf) return "";
+  if (typeof adf === "string") return adf; // already plain text
+  if (adf.type !== "doc") {
+    // Some endpoints return a single node — handle gracefully.
+    return renderNode(adf, { listDepth: 0 }).trim();
+  }
+  const out = renderChildren(adf.content ?? [], { listDepth: 0 }, "\n\n").trim();
+  return out;
+}
+
+function renderChildren(nodes, ctx, separator = "") {
+  if (!Array.isArray(nodes)) return "";
+  return nodes
+    .map((n) => renderNode(n, ctx))
+    .filter((s) => s !== "")
+    .join(separator);
+}
+
+function renderNode(node, ctx) {
+  if (!node || typeof node !== "object") return "";
+  const type = node.type;
+  switch (type) {
+    case "text":
+      return renderTextWithMarks(node);
+    case "paragraph":
+      return renderChildren(node.content ?? [], ctx);
+    case "hardBreak":
+      return "  \n"; // markdown line break: two spaces + newline
+    case "heading":
+      return renderHeading(node, ctx);
+    case "bulletList":
+      return renderList(node, ctx, "-");
+    case "orderedList":
+      return renderList(node, ctx, "1.");
+    case "listItem":
+      return renderChildren(node.content ?? [], ctx, "\n");
+    case "codeBlock":
+      return renderCodeBlock(node);
+    case "blockquote":
+      return renderBlockquote(node, ctx);
+    case "rule":
+      return "---";
+    case "inlineCard":
+      return renderInlineCard(node);
+    case "mention":
+      return renderMention(node);
+    case "emoji":
+      return renderEmoji(node);
+    default:
+      if (UNSUPPORTED_NODES.has(type)) {
+        return `<!-- unsupported ADF node: ${type} -->`;
+      }
+      // Unknown node — try to render children, fall back to a comment
+      if (Array.isArray(node.content) && node.content.length > 0) {
+        return renderChildren(node.content, ctx);
+      }
+      return `<!-- unknown ADF node: ${type} -->`;
+  }
+}
+
+function renderTextWithMarks(node) {
+  let text = node.text ?? "";
+  if (!text) return "";
+  const marks = node.marks ?? [];
+  for (const mark of marks) {
+    text = applyMark(text, mark);
+  }
+  return text;
+}
+
+function applyMark(text, mark) {
+  switch (mark.type) {
+    case "strong":
+      return `**${text}**`;
+    case "em":
+      return `*${text}*`;
+    case "code":
+      return `\`${text}\``;
+    case "strike":
+      return `~~${text}~~`;
+    case "link": {
+      const href = mark.attrs?.href ?? "";
+      return `[${text}](${href})`;
+    }
+    case "underline":
+      // No native markdown for underline. Render as text + comment so consumers
+      // can spot if they want to add it back via HTML.
+      return text;
+    case "subsup":
+      return text;
+    default:
+      return text;
+  }
+}
+
+function renderHeading(node, ctx) {
+  const level = Math.min(Math.max(node.attrs?.level ?? 1, 1), 6);
+  const inner = renderChildren(node.content ?? [], ctx);
+  return `${"#".repeat(level)} ${inner}`;
+}
+
+function renderList(node, ctx, marker) {
+  const childCtx = { ...ctx, listDepth: ctx.listDepth + 1 };
+  const indent = "  ".repeat(ctx.listDepth);
+  return (node.content ?? [])
+    .map((item) => {
+      const inner = renderChildren(item.content ?? [], childCtx, "\n");
+      const lines = inner.split("\n");
+      const first = lines.shift() ?? "";
+      // Continuation lines: only add the +2 indent for plain text. Lines
+      // that already start with whitespace are nested-list output that
+      // self-indents at the correct depth.
+      const rest = lines.map((l) => {
+        if (l === "" || /^\s/.test(l)) return l;
+        return `${indent}  ${l}`;
+      });
+      return `${indent}${marker} ${first}${rest.length > 0 ? `\n${rest.join("\n")}` : ""}`;
+    })
+    .join("\n");
+}
+
+function renderCodeBlock(node) {
+  const lang = node.attrs?.language ?? "";
+  const content = (node.content ?? [])
+    .map((c) => c.text ?? "")
+    .join("");
+  return `\`\`\`${lang}\n${content}\n\`\`\``;
+}
+
+function renderBlockquote(node, ctx) {
+  const inner = renderChildren(node.content ?? [], ctx, "\n\n");
+  return inner
+    .split("\n")
+    .map((line) => `> ${line}`)
+    .join("\n");
+}
+
+function renderInlineCard(node) {
+  const url = node.attrs?.url ?? "";
+  return url ? `[${url}](${url})` : "";
+}
+
+function renderMention(node) {
+  const text = node.attrs?.text ?? node.attrs?.id ?? "user";
+  return text.startsWith("@") ? text : `@${text}`;
+}
+
+function renderEmoji(node) {
+  return node.attrs?.text ?? node.attrs?.shortName ?? "";
+}

package/src/client.mjs

@@ -107,6 +107,20 @@ export function createClient({ host, email, token, fetch: fetchImpl = fetch } =
       return out;
     },
 
+    /**
+     * Get a single issue by key or id, including its full description (which
+     * search responses don't return). Used by materialize().
+     *
+     * @param {string} issueKeyOrId
+     * @param {{ fields?: string[], expand?: string }} opts
+     */
+    getIssue(issueKeyOrId, { fields, expand } = {}) {
+      const query = {};
+      if (Array.isArray(fields) && fields.length > 0) query.fields = fields.join(",");
+      if (expand) query.expand = expand;
+      return request("GET", `/issue/${encodeURIComponent(issueKeyOrId)}`, { query });
+    },
+
     /**
      * Low-level escape hatch. Useful for tests and for endpoints not yet
      * added to this client.

package/src/index.mjs

@@ -4,11 +4,17 @@
 //
 //   { healthcheck, listAvailable, pickNext, materialize, markStatus, attachPR }
 //
-// Phase 1 ships healthcheck + listAvailable + pickNext. The remaining three
-// land in Phases 2–4.
+// Phase 1 shipped healthcheck + listAvailable + pickNext.
+// Phase 2 (this file) adds materialize: fetch the full issue, render its ADF
+// description to markdown, write an epic file with frontmatter.
+//
+// markStatus and attachPR still throw "Phase N" errors — they land in 3 and 4.
 
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
 import { createClient } from "./client.mjs";
 import { validateJql, fieldsForSearch } from "./jql.mjs";
+import { adfToMarkdown } from "./adf-to-markdown.mjs";
 
 const PRIORITY_ORDER = { Highest: 0, High: 1, Medium: 2, Low: 3, Lowest: 4 };
 
@@ -84,6 +90,102 @@ function comparePriority(a, b) {
   return (a.id ?? "").localeCompare(b.id ?? "");
 }
 
+/**
+ * Lowercase-hyphen-only slug, truncated to a sensible length.
+ */
+function slugify(title) {
+  return String(title ?? "")
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 60) || "untitled";
+}
+
+/**
+ * Map a Jira priority name to Shipwright's P0..P3 if it matches a known label;
+ * otherwise pass through. Jira's default priorities are Highest, High, Medium,
+ * Low, Lowest — we collapse to the closest P.
+ */
+function priorityCodeFromName(name) {
+  switch (name) {
+    case "Highest":
+      return "P0";
+    case "High":
+      return "P1";
+    case "Medium":
+      return "P2";
+    case "Low":
+    case "Lowest":
+      return "P3";
+    default:
+      return name ?? "P2";
+  }
+}
+
+/**
+ * Pull a list of acceptance criteria from a description's markdown body.
+ * Recognises two common patterns:
+ *   - "## Acceptance" or "## Acceptance Criteria" heading followed by a list
+ *   - a top-level checkbox list (`- [ ] criterion`)
+ * Returns [] when no recognizable section is found.
+ */
+function extractAcceptance(markdown) {
+  if (!markdown) return [];
+  const headingRe = /^##\s+Acceptance(?:\s+Criteria)?\s*$([\s\S]*?)(?=^##\s|\Z)/im;
+  const match = markdown.match(headingRe);
+  const block = match ? match[1] : markdown;
+  const bullets = [];
+  for (const line of block.split(/\r?\n/)) {
+    const m = line.match(/^\s*[-*]\s+(?:\[[\sxX]\]\s+)?(.+?)\s*$/);
+    if (m) bullets.push(m[1]);
+  }
+  return bullets;
+}
+
+/**
+ * Build the epic markdown document from an enriched BacklogItem + rendered
+ * description. Output structure mirrors @shipwrights/core's epic schema.
+ */
+function buildEpicMarkdown(item, descriptionMd) {
+  const acceptance = extractAcceptance(descriptionMd);
+  const priorityCode = priorityCodeFromName(item.priority);
+  const sourceBlock = item.metadata
+    ? `source:\n  kind: jira\n  issue_key: ${item.metadata.issueKey}\n  jira_url: ${item.metadata.jiraUrl ?? ""}`
+    : "";
+  const acceptanceBlock = acceptance.length > 0
+    ? `acceptance:\n${acceptance.map((a) => `  - ${escapeYamlInline(a)}`).join("\n")}`
+    : "acceptance: []";
+
+  return `---
+id: ${item.id}
+title: ${escapeYamlInline(item.title)}
+status: refined
+priority: ${priorityCode}
+domain: ${item.domain ?? "full-stack"}
+owner: claude
+parents: ${formatParents(item.parents)}
+${acceptanceBlock}
+size: ${item.size ?? "medium"}
+${sourceBlock}
+---
+
+## Why
+
+${descriptionMd || "_(no description in Jira)_"}
+`;
+}
+
+function formatParents(parents) {
+  if (!Array.isArray(parents) || parents.length === 0) return "[]";
+  return `[${parents.join(", ")}]`;
+}
+
+function escapeYamlInline(value) {
+  const s = String(value ?? "");
+  if (/^[A-Za-z0-9 _\-.,!?()]+$/.test(s)) return s;
+  return JSON.stringify(s);
+}
+
 /**
  * Factory called by @shipwrights/core's source-loader.
  */
@@ -158,14 +260,51 @@ export function createSource(rawConfig = {}) {
     },
 
     /**
-     * Phases 2–4: not yet implemented. Each throws a clear error rather than
-     * silently no-oping, so consumers know they're on a Phase 1 release.
+     * Phase 2: fetch the Jira issue (full description), render ADF →
+     * markdown, write a refined epic file with frontmatter. Returns
+     * { epicFilePath, created } per the BacklogSource contract.
+     *
+     * The epic file is written with `status: refined` so the orchestrator
+     * skips re-running the PO refinement step. Acceptance criteria are
+     * parsed from the description if a recognizable `## Acceptance` or
+     * checkbox section is found; otherwise left empty for the user/PO to
+     * fill in.
      */
-    async materialize(_item, _targetDir) {
-      throw new Error(
-        "@shipwrights/source-jira: materialize() lands in Phase 2 (next release). Use listAvailable() / pickNext() for now and materialise epic files by hand.",
-      );
+    async materialize(item, targetDir) {
+      if (!item?.id) {
+        throw new Error("@shipwrights/source-jira: materialize() needs a BacklogItem with an id");
+      }
+      if (!targetDir || typeof targetDir !== "string") {
+        throw new Error("@shipwrights/source-jira: materialize() needs a targetDir path");
+      }
+
+      const fullFields = fieldsForSearch({ fieldMapping: field_mapping }).concat(["description"]);
+      const issue = await client.getIssue(item.id, { fields: fullFields });
+      const enriched = toBacklogItem(issue, { idPrefix: id_prefix, fieldMapping: field_mapping });
+
+      const description = adfToMarkdown(issue.fields?.description);
+      const slug = slugify(enriched.title);
+      const filename = `${enriched.id}-${slug}.md`;
+      const path = join(targetDir, filename);
+      const created = !existsSync(path);
+
+      mkdirSync(targetDir, { recursive: true });
+      const body = buildEpicMarkdown(enriched, description);
+      // Be polite: if the file already exists with status > refined, don't
+      // overwrite its body — only refresh the frontmatter title in case it
+      // changed in Jira.
+      if (!created) {
+        const existing = readFileSync(path, "utf8");
+        const status = (existing.match(/^status:\s*(\S+)/m) ?? [])[1];
+        if (status && status !== "idea" && status !== "refined") {
+          // Don't clobber in-flight epics; leave them alone.
+          return { epicFilePath: path, created: false };
+        }
+      }
+      writeFileSync(path, body, "utf8");
+      return { epicFilePath: path, created };
     },
+
     async markStatus(_itemId, _status) {
       throw new Error(
         "@shipwrights/source-jira: markStatus() lands in Phase 3 (next release).",