@grainulation/mill 1.0.0 → 1.0.2

package/lib/formats/confluence-adf.mjs

@@ -0,0 +1,312 @@
+/**
+ * mill format: confluence-adf
+ *
+ * Converts compilation.json to Atlassian Document Format (ADF) JSON.
+ * ADF is the native document format for Confluence Cloud REST API.
+ * Output can be POST'd directly to /wiki/api/v2/pages.
+ * Zero dependencies — node built-in only.
+ */
+
+export const name = "confluence-adf";
+export const extension = ".adf.json";
+export const mimeType = "application/json; charset=utf-8";
+export const description =
+  "Confluence ADF (Atlassian Document Format) for direct API upload";
+
+/**
+ * Convert a compilation object to Confluence ADF JSON.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} ADF JSON output
+ */
+export function convert(compilation) {
+  const meta = compilation.meta || {};
+  const claims = compilation.claims || [];
+  const conflicts = compilation.conflicts || [];
+  const certificate = compilation.certificate || {};
+
+  const title = meta.sprint || meta.question || "Sprint Report";
+  const compiled = certificate.compiled_at || new Date().toISOString();
+  const active = claims.filter((c) => c.status === "active").length;
+
+  const content = [];
+
+  // Title heading
+  content.push(heading(1, title));
+
+  // Question as blockquote
+  if (meta.question) {
+    content.push(blockquote(meta.question));
+  }
+
+  // Meta paragraph
+  const metaParts = [`Compiled: ${compiled}`];
+  if (meta.audience) metaParts.push(`Audience: ${meta.audience}`);
+  content.push(paragraph([text(metaParts.join(" | "), [mark("em")])]));
+
+  // Summary panel
+  content.push(heading(2, "Summary"));
+  content.push(
+    table(
+      [tableRow([tableHeader("Metric"), tableHeader("Count")])],
+      [
+        tableRow([tableCell("Total claims"), tableCell(String(claims.length))]),
+        tableRow([tableCell("Active"), tableCell(String(active))]),
+        ...(conflicts.length > 0
+          ? [
+              tableRow([
+                tableCell("Conflicts"),
+                tableCell(String(conflicts.length)),
+              ]),
+            ]
+          : []),
+      ],
+    ),
+  );
+
+  // Group claims by type (skip reverted)
+  const byType = {};
+  for (const c of claims) {
+    if (c.status === "reverted") continue;
+    const t = c.type || "unknown";
+    if (!byType[t]) byType[t] = [];
+    byType[t].push(c);
+  }
+
+  const typeOrder = [
+    "constraint",
+    "factual",
+    "recommendation",
+    "risk",
+    "estimate",
+    "feedback",
+  ];
+  const sortedTypes = typeOrder.filter((t) => byType[t]);
+  for (const t of Object.keys(byType)) {
+    if (!sortedTypes.includes(t)) sortedTypes.push(t);
+  }
+
+  // Status macro mapping for claim types
+  const statusColors = {
+    risk: "red",
+    constraint: "red",
+    recommendation: "green",
+    factual: "blue",
+    estimate: "purple",
+    feedback: "yellow",
+  };
+
+  // Per-type sections
+  for (const t of sortedTypes) {
+    const group = byType[t];
+    content.push(heading(2, `${capitalize(t)}s (${group.length})`));
+
+    // Add info/warning panels for risks and constraints
+    if (t === "risk" && group.length > 0) {
+      content.push(
+        panel(
+          "warning",
+          group.length + " risk(s) identified -- review before proceeding",
+        ),
+      );
+    } else if (t === "constraint" && group.length > 0) {
+      content.push(
+        panel(
+          "error",
+          group.length + " hard constraint(s) -- these are non-negotiable",
+        ),
+      );
+    }
+
+    // Claims table
+    content.push(
+      table(
+        [
+          tableRow([
+            tableHeader("ID"),
+            tableHeader("Content"),
+            tableHeader("Evidence"),
+            tableHeader("Confidence"),
+            tableHeader("Status"),
+          ]),
+        ],
+        group.map((c) => {
+          const body = c.content || c.text || "";
+          const tier =
+            typeof c.evidence === "string"
+              ? c.evidence
+              : c.evidence?.tier || c.evidence_tier || "";
+          const conf =
+            c.confidence != null ? Math.round(c.confidence * 100) + "%" : "--";
+          const status = c.status || "active";
+          return tableRow([
+            tableCell(c.id || ""),
+            tableCell(body),
+            tableCell(tier),
+            tableCell(conf),
+            tableCellWithStatus(status, statusColors[t] || "neutral"),
+          ]);
+        }),
+      ),
+    );
+
+    // Tags as labels
+    const allTags = new Set();
+    for (const c of group) {
+      if (Array.isArray(c.tags)) c.tags.forEach((tag) => allTags.add(tag));
+    }
+    if (allTags.size > 0) {
+      content.push(
+        paragraph([
+          text("Tags: ", [mark("strong")]),
+          text([...allTags].join(", ")),
+        ]),
+      );
+    }
+
+    // Wrap large sections in expand macro
+    if (group.length > 10) {
+      content.push(
+        paragraph([
+          text(
+            `Showing all ${group.length} ${t} claims. Consider using Confluence page filtering for large datasets.`,
+            [mark("em")],
+          ),
+        ]),
+      );
+    }
+  }
+
+  // Conflicts section
+  if (conflicts.length > 0) {
+    content.push(heading(2, `Conflicts (${conflicts.length})`));
+    const items = conflicts.map((c) => {
+      const ids = Array.isArray(c.ids)
+        ? c.ids.join(" vs ")
+        : c.between || "unknown";
+      const desc = c.description || c.reason || "";
+      const resolved = c.resolution ? ` [resolved: ${c.resolution}]` : "";
+      return bulletItem(`${ids}: ${desc}${resolved}`);
+    });
+    content.push(bulletList(items));
+  }
+
+  // Certificate footer
+  content.push(rule());
+  content.push(
+    paragraph([
+      text(
+        `Certificate: ${certificate.claim_count || claims.length} claims | sha256:${(certificate.sha256 || "unknown").slice(0, 16)}`,
+        [mark("code")],
+      ),
+    ]),
+  );
+
+  const doc = {
+    version: 1,
+    type: "doc",
+    content,
+  };
+
+  return JSON.stringify(doc, null, 2) + "\n";
+}
+
+// --- ADF node builders ---
+
+function heading(level, text_) {
+  return {
+    type: "heading",
+    attrs: { level },
+    content: [{ type: "text", text: text_ }],
+  };
+}
+
+function paragraph(inlines) {
+  return { type: "paragraph", content: inlines };
+}
+
+function text(value, marks_) {
+  const node = { type: "text", text: value };
+  if (marks_ && marks_.length > 0) node.marks = marks_;
+  return node;
+}
+
+function mark(type) {
+  return { type };
+}
+
+function blockquote(text_) {
+  return {
+    type: "blockquote",
+    content: [paragraph([text(text_)])],
+  };
+}
+
+function bulletList(items) {
+  return { type: "bulletList", content: items };
+}
+
+function bulletItem(text_) {
+  return {
+    type: "listItem",
+    content: [paragraph([text(text_)])],
+  };
+}
+
+function panel(panelType, text_) {
+  return {
+    type: "panel",
+    attrs: { panelType },
+    content: [paragraph([text(text_)])],
+  };
+}
+
+function rule() {
+  return { type: "rule" };
+}
+
+function table(headerRows, bodyRows) {
+  return {
+    type: "table",
+    attrs: { isNumberColumnEnabled: false, layout: "default" },
+    content: [...headerRows, ...bodyRows],
+  };
+}
+
+function tableRow(cells) {
+  return { type: "tableRow", content: cells };
+}
+
+function tableHeader(text_) {
+  return {
+    type: "tableHeader",
+    attrs: {},
+    content: [paragraph([text(text_, [mark("strong")])])],
+  };
+}
+
+function tableCell(text_) {
+  return {
+    type: "tableCell",
+    attrs: {},
+    content: [paragraph([text(text_)])],
+  };
+}
+
+function tableCellWithStatus(statusText, color) {
+  return {
+    type: "tableCell",
+    attrs: {},
+    content: [
+      paragraph([
+        {
+          type: "status",
+          attrs: { text: statusText, color, localId: "", style: "" },
+        },
+      ]),
+    ],
+  };
+}
+
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/lib/formats/{csv.js → csv.mjs}

@@ -6,22 +6,23 @@
  * Zero dependencies — node built-in only.
  */
 
-export const name = 'csv';
-export const extension = '.csv';
-export const mimeType = 'text/csv; charset=utf-8';
-export const description = 'Claims as CSV spreadsheet (id, type, topic, content, evidence, status)';
+export const name = "csv";
+export const extension = ".csv";
+export const mimeType = "text/csv; charset=utf-8";
+export const description =
+  "Claims as CSV spreadsheet (id, type, topic, content, evidence, status)";
 
 const COLUMNS = [
-  'id',
-  'type',
-  'topic',
-  'content',
-  'evidence_tier',
-  'evidence_source',
-  'confidence',
-  'status',
-  'tags',
-  'created',
+  "id",
+  "type",
+  "topic",
+  "content",
+  "evidence_tier",
+  "evidence_source",
+  "confidence",
+  "status",
+  "tags",
+  "created",
 ];
 
 /**
@@ -33,59 +34,62 @@ export function convert(compilation) {
   const claims = compilation.claims || [];
 
   if (claims.length === 0) {
-    return COLUMNS.join(',') + '\n';
+    return COLUMNS.join(",") + "\n";
   }
 
-  const header = COLUMNS.join(',');
+  const header = COLUMNS.join(",");
   const rows = claims.map(claimToRow);
 
-  return [header, ...rows].join('\n') + '\n';
+  return [header, ...rows].join("\n") + "\n";
 }
 
 function claimToRow(claim) {
-  return COLUMNS.map(col => {
+  return COLUMNS.map((col) => {
     switch (col) {
-      case 'content':
+      case "content":
         // Claims may use 'text' or 'content' for the main body
-        return escapeField(claim.content || claim.text || '');
-      case 'topic':
+        return escapeField(claim.content || claim.text || "");
+      case "topic":
         // Use claim.topic directly, or fall back to first tag
         return escapeField(
-          claim.topic || (Array.isArray(claim.tags) ? claim.tags[0] || '' : '')
+          claim.topic || (Array.isArray(claim.tags) ? claim.tags[0] || "" : ""),
         );
-      case 'evidence_tier':
+      case "evidence_tier":
         // evidence may be a string (tier directly) or object { tier, source }
-        if (typeof claim.evidence === 'string') return escapeField(claim.evidence);
-        return escapeField(claim.evidence?.tier ?? claim.evidence_tier ?? '');
-      case 'evidence_source':
+        if (typeof claim.evidence === "string")
+          return escapeField(claim.evidence);
+        return escapeField(claim.evidence?.tier ?? claim.evidence_tier ?? "");
+      case "evidence_source":
         // source may be an object { origin, artifact } or a string
-        if (typeof claim.source === 'object' && claim.source !== null) {
-          return escapeField(claim.source.origin || claim.source.artifact || '');
+        if (typeof claim.source === "object" && claim.source !== null) {
+          return escapeField(
+            claim.source.origin || claim.source.artifact || "",
+          );
         }
-        if (typeof claim.evidence === 'object' && claim.evidence?.source) {
+        if (typeof claim.evidence === "object" && claim.evidence?.source) {
           return escapeField(claim.evidence.source);
         }
-        return escapeField(claim.source ?? '');
-      case 'tags':
+        return escapeField(claim.source ?? "");
+      case "tags":
         return escapeField(
-          Array.isArray(claim.tags) ? claim.tags.join('; ') : ''
+          Array.isArray(claim.tags) ? claim.tags.join("; ") : "",
         );
-      case 'confidence':
-        return claim.confidence != null ? String(claim.confidence) : '';
+      case "confidence":
+        return claim.confidence != null ? String(claim.confidence) : "";
       default:
         return escapeField(claim[col]);
     }
-  }).join(',');
+  }).join(",");
 }
 
 function escapeField(value) {
-  if (value == null) return '';
+  if (value == null) return "";
   let str = String(value);
   // CWE-1236: Prevent CSV injection by prefixing formula-triggering characters
   if (/^[=+\-@\t\r]/.test(str)) {
     str = "'" + str;
   }
-  if (str.includes(',') || str.includes('"') || str.includes('\n')) {
+  if (str.includes(",") || str.includes('"') || str.includes("\n")) {
     return `"${str.replace(/"/g, '""')}"`;
   }
   return str;

package/lib/formats/{dot.js → dot.mjs}

@@ -6,21 +6,26 @@
  * Zero dependencies — node built-in only.
  */
 
-export const name = 'dot';
-export const extension = '.dot';
-export const mimeType = 'text/vnd.graphviz; charset=utf-8';
-export const description = 'Claims as Graphviz DOT graph (type clusters, tag edges)';
+export const name = "dot";
+export const extension = ".dot";
+export const mimeType = "text/vnd.graphviz; charset=utf-8";
+export const description =
+  "Claims as Graphviz DOT graph (type clusters, tag edges)";
 
 const TYPE_COLORS = {
-  constraint:     { border: '#f87171', fill: '#2d1f1f', label: 'Constraints' },
-  factual:        { border: '#60a5fa', fill: '#1f2937', label: 'Factual' },
-  estimate:       { border: '#a78bfa', fill: '#1f1f2d', label: 'Estimates' },
-  risk:           { border: '#fb923c', fill: '#2d2517', label: 'Risks' },
-  recommendation: { border: '#34d399', fill: '#172d1f', label: 'Recommendations' },
-  feedback:       { border: '#fbbf24', fill: '#2d2a17', label: 'Feedback' },
+  constraint: { border: "#f87171", fill: "#2d1f1f", label: "Constraints" },
+  factual: { border: "#60a5fa", fill: "#1f2937", label: "Factual" },
+  estimate: { border: "#a78bfa", fill: "#1f1f2d", label: "Estimates" },
+  risk: { border: "#fb923c", fill: "#2d2517", label: "Risks" },
+  recommendation: {
+    border: "#34d399",
+    fill: "#172d1f",
+    label: "Recommendations",
+  },
+  feedback: { border: "#fbbf24", fill: "#2d2a17", label: "Feedback" },
 };
 
-const DEFAULT_COLOR = { border: '#9ca3af', fill: '#1f1f1f', label: 'Other' };
+const DEFAULT_COLOR = { border: "#9ca3af", fill: "#1f1f1f", label: "Other" };
 
 /**
  * Convert a compilation object to DOT format.
@@ -29,19 +34,21 @@ const DEFAULT_COLOR = { border: '#9ca3af', fill: '#1f1f1f', label: 'Other' };
  */
 export function convert(compilation) {
   const claims = compilation.claims || [];
-  const sprintName = compilation.meta?.sprint || 'sprint';
+  const sprintName = compilation.meta?.sprint || "sprint";
 
   const lines = [];
   lines.push(`digraph ${escId(sprintName)} {`);
-  lines.push('  rankdir=LR;');
-  lines.push('  node [shape=box, style=filled, fontname="monospace", fontsize=10];');
+  lines.push("  rankdir=LR;");
+  lines.push(
+    '  node [shape=box, style=filled, fontname="monospace", fontsize=10];',
+  );
   lines.push('  edge [fontname="monospace", fontsize=8];');
-  lines.push('');
+  lines.push("");
 
   // Group claims by type
   const groups = {};
   for (const claim of claims) {
-    const t = claim.type || 'other';
+    const t = claim.type || "other";
     if (!groups[t]) groups[t] = [];
     groups[t].push(claim);
   }
@@ -53,32 +60,36 @@ export function convert(compilation) {
     lines.push(`    label="${escDot(colors.label || type)}";`);
     lines.push(`    color="${colors.border}";`);
     lines.push(`    style=dashed;`);
-    lines.push('');
+    lines.push("");
 
     for (const claim of group) {
-      const id = escId(claim.id || '');
-      const content = claim.content || claim.text || '';
+      const id = escId(claim.id || "");
+      const content = claim.content || claim.text || "";
       const label = truncate(content, 40);
-      lines.push(`    ${id} [label="${escDot(claim.id + '\\n' + label)}" fillcolor="${colors.fill}"];`);
+      lines.push(
+        `    ${id} [label="${escDot(claim.id + "\\n" + label)}" fillcolor="${colors.fill}"];`,
+      );
     }
 
-    lines.push('  }');
-    lines.push('');
+    lines.push("  }");
+    lines.push("");
   }
 
   // Tag edges
   const edges = buildTagEdges(claims);
   if (edges.length > 0) {
-    lines.push('  // Tag edges');
+    lines.push("  // Tag edges");
     for (const edge of edges) {
-      lines.push(`  ${escId(edge.source)} -> ${escId(edge.target)} [label="${escDot('tag: ' + edge.tag)}" style=dashed];`);
+      lines.push(
+        `  ${escId(edge.source)} -> ${escId(edge.target)} [label="${escDot("tag: " + edge.tag)}" style=dashed];`,
+      );
     }
-    lines.push('');
+    lines.push("");
   }
 
-  lines.push('}');
+  lines.push("}");
 
-  return lines.join('\n') + '\n';
+  return lines.join("\n") + "\n";
 }
 
 function buildTagEdges(claims) {
@@ -88,7 +99,7 @@ function buildTagEdges(claims) {
     const tags = Array.isArray(claim.tags) ? claim.tags : [];
     for (const tag of tags) {
       if (!tagMap[tag]) tagMap[tag] = [];
-      tagMap[tag].push(claim.id || '');
+      tagMap[tag].push(claim.id || "");
     }
   }
 
@@ -111,19 +122,19 @@ function buildTagEdges(claims) {
 }
 
 function truncate(str, max) {
-  if (!str) return '';
-  return str.length > max ? str.slice(0, max - 3) + '...' : str;
+  if (!str) return "";
+  return str.length > max ? str.slice(0, max - 3) + "..." : str;
 }
 
 function escId(str) {
   // DOT identifiers: replace non-alphanumeric with underscores
-  return String(str).replace(/[^a-zA-Z0-9_]/g, '_');
+  return String(str).replace(/[^a-zA-Z0-9_]/g, "_");
 }
 
 function escDot(str) {
-  if (str == null) return '';
+  if (str == null) return "";
   return String(str)
-    .replace(/\\/g, '\\\\')
+    .replace(/\\/g, "\\\\")
     .replace(/"/g, '\\"')
-    .replace(/\n/g, '\\n');
+    .replace(/\n/g, "\\n");
 }

package/lib/formats/{evidence-matrix.js → evidence-matrix.mjs}

@@ -6,12 +6,13 @@
  * Zero dependencies — node built-in only.
  */
 
-export const name = 'evidence-matrix';
-export const extension = '.csv';
-export const mimeType = 'text/csv; charset=utf-8';
-export const description = 'Pivot table CSV: claim types vs evidence tiers with counts';
+export const name = "evidence-matrix";
+export const extension = ".csv";
+export const mimeType = "text/csv; charset=utf-8";
+export const description =
+  "Pivot table CSV: claim types vs evidence tiers with counts";
 
-const TIER_ORDER = ['stated', 'web', 'documented', 'tested', 'production'];
+const TIER_ORDER = ["stated", "web", "documented", "tested", "production"];
 
 /**
  * Convert a compilation object to an evidence matrix CSV.
@@ -27,10 +28,10 @@ export function convert(compilation) {
   const allTiers = new Set();
 
   for (const claim of claims) {
-    if (claim.status === 'reverted') continue;
+    if (claim.status === "reverted") continue;
 
-    const type = claim.type || 'unknown';
-    const tier = extractTier(claim) || 'unknown';
+    const type = claim.type || "unknown";
+    const tier = extractTier(claim) || "unknown";
 
     allTypes.add(type);
     allTiers.add(tier);
@@ -55,17 +56,17 @@ export function convert(compilation) {
   const lines = [];
 
   // Header
-  lines.push(['type', ...tierColumns, 'total'].join(','));
+  lines.push(["type", ...tierColumns, "total"].join(","));
 
   // Data rows
   for (const type of typeRows) {
-    const counts = tierColumns.map(tier => pivot[type]?.[tier] || 0);
+    const counts = tierColumns.map((tier) => pivot[type]?.[tier] || 0);
     const total = counts.reduce((sum, n) => sum + n, 0);
-    lines.push([type, ...counts, total].join(','));
+    lines.push([type, ...counts, total].join(","));
   }
 
   // Totals row
-  const colTotals = tierColumns.map(tier => {
+  const colTotals = tierColumns.map((tier) => {
     let sum = 0;
     for (const type of typeRows) {
       sum += pivot[type]?.[tier] || 0;
@@ -73,14 +74,14 @@ export function convert(compilation) {
     return sum;
   });
   const grandTotal = colTotals.reduce((sum, n) => sum + n, 0);
-  lines.push(['total', ...colTotals, grandTotal].join(','));
+  lines.push(["total", ...colTotals, grandTotal].join(","));
 
-  return lines.join('\n') + '\n';
+  return lines.join("\n") + "\n";
 }
 
 function extractTier(claim) {
-  if (typeof claim.evidence === 'string') return claim.evidence;
-  if (typeof claim.evidence === 'object' && claim.evidence !== null) {
+  if (typeof claim.evidence === "string") return claim.evidence;
+  if (typeof claim.evidence === "object" && claim.evidence !== null) {
     return claim.evidence.tier || null;
   }
   return claim.evidence_tier || null;