@grainulation/mill 1.0.0

package/lib/formats/markdown.js

@@ -0,0 +1,118 @@
+/**
+ * mill format: markdown
+ *
+ * Converts compilation.json (wheat compiler output) to clean Markdown.
+ * Used by the mill server for live preview and export.
+ * Zero dependencies — node built-in only.
+ */
+
+export const name = 'markdown';
+export const extension = '.md';
+export const mimeType = 'text/markdown; charset=utf-8';
+export const description = 'Clean Markdown document from compilation data';
+
+/**
+ * Convert a compilation object to Markdown.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} Markdown output
+ */
+export function convert(compilation) {
+  const lines = [];
+  const meta = compilation.meta || {};
+  const claims = compilation.claims || [];
+  const conflicts = compilation.conflicts || [];
+  const certificate = compilation.certificate || {};
+
+  // Title
+  const title = meta.sprint || meta.question || 'Sprint Export';
+  lines.push(`# ${title}`);
+  lines.push('');
+
+  // Meta block
+  if (meta.question) {
+    lines.push(`> **Question:** ${meta.question}`);
+    lines.push('');
+  }
+  if (meta.audience) {
+    lines.push(`**Audience:** ${meta.audience}`);
+    lines.push('');
+  }
+  if (certificate.compiled_at) {
+    lines.push(`*Compiled: ${certificate.compiled_at}*`);
+    lines.push('');
+  }
+
+  // Summary stats
+  const active = claims.filter(c => c.status === 'active').length;
+  const superseded = claims.filter(c => c.status === 'superseded').length;
+  const reverted = claims.filter(c => c.status === 'reverted').length;
+  lines.push('## Summary');
+  lines.push('');
+  lines.push(`- **Total claims:** ${claims.length}`);
+  lines.push(`- **Active:** ${active}`);
+  if (superseded) lines.push(`- **Superseded:** ${superseded}`);
+  if (reverted) lines.push(`- **Reverted:** ${reverted}`);
+  if (conflicts.length) lines.push(`- **Conflicts:** ${conflicts.length}`);
+  lines.push('');
+
+  // Group claims by type
+  const byType = {};
+  for (const claim of claims) {
+    if (claim.status === 'reverted') continue;
+    const type = claim.type || 'unknown';
+    if (!byType[type]) byType[type] = [];
+    byType[type].push(claim);
+  }
+
+  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);
+  }
+
+  for (const type of sortedTypes) {
+    const group = byType[type];
+    if (!group || group.length === 0) continue;
+
+    lines.push(`## ${capitalize(type)}s (${group.length})`);
+    lines.push('');
+
+    for (const claim of group) {
+      const conf = claim.confidence != null ? ` [${Math.round(claim.confidence * 100)}%]` : '';
+      const evidenceStr = typeof claim.evidence === 'string' ? claim.evidence : claim.evidence?.tier;
+      const tier = evidenceStr ? ` (${evidenceStr})` : '';
+      const status = claim.status === 'superseded' ? ' ~~superseded~~' : '';
+      const body = claim.content || claim.text || '';
+      lines.push(`- **${claim.id}**${conf}${tier}${status}: ${body}`);
+    }
+    lines.push('');
+  }
+
+  // Conflicts
+  if (conflicts.length > 0) {
+    lines.push('## Conflicts');
+    lines.push('');
+    for (const conflict of conflicts) {
+      const resolved = conflict.resolution ? ' (resolved)' : '';
+      lines.push(`- **${conflict.ids?.join(' vs ') || 'unknown'}**${resolved}: ${conflict.description || conflict.reason || 'No description'}`);
+      if (conflict.resolution) {
+        lines.push(`  - *Resolution:* ${conflict.resolution}`);
+      }
+    }
+    lines.push('');
+  }
+
+  // Certificate
+  if (certificate.sha256 || certificate.claim_count) {
+    lines.push('---');
+    lines.push('');
+    lines.push(`*Certificate: ${certificate.claim_count || claims.length} claims, sha256:${(certificate.sha256 || 'unknown').slice(0, 12)}*`);
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/lib/formats/ndjson.js

@@ -0,0 +1,25 @@
+/**
+ * mill format: ndjson
+ *
+ * One JSON object per line (Newline Delimited JSON).
+ * Each line is a claim with all fields preserved.
+ * Zero dependencies — node built-in only.
+ */
+
+export const name = 'ndjson';
+export const extension = '.ndjson';
+export const mimeType = 'application/x-ndjson';
+export const description = 'Newline-delimited JSON — one claim object per line';
+
+/**
+ * Convert a compilation object to NDJSON.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} NDJSON output
+ */
+export function convert(compilation) {
+  const claims = compilation.claims || [];
+
+  if (claims.length === 0) return '';
+
+  return claims.map(c => JSON.stringify(c)).join('\n') + '\n';
+}

package/lib/formats/obsidian.js

@@ -0,0 +1,136 @@
+/**
+ * mill format: obsidian
+ *
+ * Converts compilation.json claims to Obsidian-flavored markdown
+ * with YAML front matter, wikilinks, and backlinks.
+ * Zero dependencies — node built-in only.
+ */
+
+export const name = 'obsidian';
+export const extension = '.md';
+export const mimeType = 'text/markdown; charset=utf-8';
+export const description = 'Claims as Obsidian vault page (YAML front matter, wikilinks, backlinks)';
+
+/**
+ * Convert a compilation object to Obsidian markdown.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} Markdown output
+ */
+export function convert(compilation) {
+  const meta = compilation.meta || {};
+  const claims = compilation.claims || [];
+  const sprint = meta.sprint || 'unknown';
+  const question = meta.question || '';
+  const audience = meta.audience || '';
+
+  const grouped = groupByType(claims);
+  const lines = [];
+
+  // YAML front matter
+  lines.push('---');
+  lines.push(`sprint: ${sprint}`);
+  if (question) lines.push(`question: "${escapeFrontMatter(question)}"`);
+  if (audience) lines.push(`audience: "${escapeFrontMatter(audience)}"`);
+  lines.push(`claim_count: ${claims.length}`);
+  lines.push('tags: [wheat, sprint, export]');
+  lines.push('---');
+  lines.push('');
+
+  // Title
+  lines.push(`# Sprint: ${sprint}`);
+  lines.push('');
+
+  if (question) {
+    lines.push(`> ${question}`);
+    lines.push('');
+  }
+
+  // Claims grouped by type
+  lines.push('## Claims');
+  lines.push('');
+
+  const typeOrder = ['constraint', 'factual', 'estimate', 'risk', 'recommendation', 'feedback'];
+  const seen = new Set();
+
+  for (const type of typeOrder) {
+    if (grouped[type]) {
+      lines.push(...renderGroup(type, grouped[type]));
+      seen.add(type);
+    }
+  }
+
+  for (const type of Object.keys(grouped)) {
+    if (!seen.has(type)) {
+      lines.push(...renderGroup(type, grouped[type]));
+    }
+  }
+
+  // Connections section
+  lines.push('## Connections');
+  lines.push('');
+  lines.push('- Related: [[compilation]] [[claims]]');
+
+  if (compilation.certificate) {
+    lines.push('- Certificate: [[certificate]]');
+  }
+
+  lines.push('');
+  return lines.join('\n') + '\n';
+}
+
+function groupByType(claims) {
+  const groups = {};
+  for (const claim of claims) {
+    const type = claim.type || 'other';
+    if (!groups[type]) groups[type] = [];
+    groups[type].push(claim);
+  }
+  return groups;
+}
+
+function renderGroup(type, claims) {
+  const label = capitalize(type) + 's';
+  const lines = [];
+
+  lines.push(`### ${label}`);
+
+  for (const claim of claims) {
+    const id = claim.id || '???';
+    const content = claim.content || claim.text || '';
+    const summary = truncate(content, 120);
+    const evidence = getEvidence(claim);
+    const tags = formatTags(claim);
+
+    lines.push(`- [[${id}]] ${summary} #${type} #${evidence}${tags}`);
+  }
+
+  lines.push('');
+  return lines;
+}
+
+function getEvidence(claim) {
+  if (typeof claim.evidence === 'string') return claim.evidence;
+  if (typeof claim.evidence === 'object' && claim.evidence !== null) {
+    return claim.evidence.tier || claim.evidence_tier || 'stated';
+  }
+  return claim.evidence_tier || 'stated';
+}
+
+function formatTags(claim) {
+  const tags = Array.isArray(claim.tags) ? claim.tags : [];
+  if (tags.length === 0) return '';
+  return ' ' + tags.map(t => `#${t.replace(/\s+/g, '-')}`).join(' ');
+}
+
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+function truncate(str, max) {
+  if (str.length <= max) return str;
+  return str.slice(0, max - 3) + '...';
+}
+
+function escapeFrontMatter(str) {
+  return String(str).replace(/"/g, '\\"');
+}

package/lib/formats/opml.js

@@ -0,0 +1,108 @@
+/**
+ * mill format: opml
+ *
+ * Converts compilation.json claims to OPML 2.0 outline,
+ * grouped by claim type.
+ * Zero dependencies — node built-in only.
+ */
+
+export const name = 'opml';
+export const extension = '.opml';
+export const mimeType = 'text/x-opml; charset=utf-8';
+export const description = 'Claims as OPML 2.0 outline grouped by type (for RSS readers and outliners)';
+
+/**
+ * Convert a compilation object to OPML XML.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} OPML XML output
+ */
+export function convert(compilation) {
+  const meta = compilation.meta || {};
+  const claims = compilation.claims || [];
+  const sprint = meta.sprint || 'unknown';
+
+  const grouped = groupByType(claims);
+  const lines = [];
+
+  lines.push('<?xml version="1.0" encoding="utf-8"?>');
+  lines.push('<opml version="2.0">');
+  lines.push(`  <head><title>${esc(sprint)}</title></head>`);
+  lines.push('  <body>');
+
+  const typeOrder = ['constraint', 'factual', 'estimate', 'risk', 'recommendation', 'feedback'];
+  const seen = new Set();
+
+  for (const type of typeOrder) {
+    if (grouped[type]) {
+      lines.push(...renderGroup(type, grouped[type]));
+      seen.add(type);
+    }
+  }
+
+  // Remaining types not in the predefined order
+  for (const type of Object.keys(grouped)) {
+    if (!seen.has(type)) {
+      lines.push(...renderGroup(type, grouped[type]));
+    }
+  }
+
+  lines.push('  </body>');
+  lines.push('</opml>');
+
+  return lines.join('\n') + '\n';
+}
+
+function groupByType(claims) {
+  const groups = {};
+  for (const claim of claims) {
+    const type = claim.type || 'other';
+    if (!groups[type]) groups[type] = [];
+    groups[type].push(claim);
+  }
+  return groups;
+}
+
+function renderGroup(type, claims) {
+  const label = capitalize(type) + 's';
+  const lines = [];
+
+  lines.push(`    <outline text="${esc(label)} (${claims.length})">`);
+
+  for (const claim of claims) {
+    const id = claim.id || '???';
+    const content = claim.content || claim.text || '';
+    const summary = truncate(content, 100);
+    const evidence = getEvidence(claim);
+    lines.push(`      <outline text="${esc(id)}: ${esc(summary)}" _note="evidence: ${esc(evidence)}"/>`);
+  }
+
+  lines.push('    </outline>');
+  return lines;
+}
+
+function getEvidence(claim) {
+  if (typeof claim.evidence === 'string') return claim.evidence;
+  if (typeof claim.evidence === 'object' && claim.evidence !== null) {
+    return claim.evidence.tier || claim.evidence_tier || 'stated';
+  }
+  return claim.evidence_tier || 'stated';
+}
+
+function capitalize(str) {
+  return str.charAt(0).toUpperCase() + str.slice(1);
+}
+
+function truncate(str, max) {
+  if (str.length <= max) return str;
+  return str.slice(0, max - 3) + '...';
+}
+
+function esc(str) {
+  if (str == null) return '';
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}

package/lib/formats/ris.js

@@ -0,0 +1,70 @@
+/**
+ * mill format: ris
+ *
+ * Converts compilation.json claims to RIS tagged citation format.
+ * Each claim becomes a TY-ER record block.
+ * Zero dependencies — node built-in only.
+ */
+
+export const name = 'ris';
+export const extension = '.ris';
+export const mimeType = 'application/x-research-info-systems; charset=utf-8';
+export const description = 'Claims as RIS citation records (one TY-ER block per claim)';
+
+/**
+ * Convert a compilation object to RIS.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} RIS output
+ */
+export function convert(compilation) {
+  const claims = compilation.claims || [];
+  const meta = compilation.meta || {};
+  const author = meta.sprint ? `wheat sprint: ${meta.sprint}` : 'wheat sprint';
+  const year = new Date().getFullYear().toString();
+
+  if (claims.length === 0) {
+    return '';
+  }
+
+  const records = claims.map(claim => claimToRecord(claim, author, year));
+  return records.join('\n') + '\n';
+}
+
+function claimToRecord(claim, author, year) {
+  const id = String(claim.id || 'unknown');
+  const title = claim.content || claim.text || '';
+  const type = claim.type || '';
+  const evidence = typeof claim.evidence === 'string'
+    ? claim.evidence
+    : (claim.evidence?.tier ?? claim.evidence_tier ?? '');
+  const status = claim.status || '';
+  const tags = Array.isArray(claim.tags) ? claim.tags : [];
+  const confidence = claim.confidence != null ? `, confidence: ${claim.confidence}` : '';
+
+  const noteParts = [
+    type ? `type: ${type}` : '',
+    evidence ? `evidence: ${evidence}` : '',
+    status ? `status: ${status}` : '',
+  ].filter(Boolean).join(', ') + confidence;
+
+  const lines = [
+    `TY  - GEN`,
+    `ID  - ${id}`,
+    `TI  - ${title}`,
+    `AU  - ${author}`,
+    `PY  - ${year}`,
+  ];
+
+  for (const tag of tags) {
+    lines.push(`KW  - ${tag}`);
+  }
+
+  if (noteParts) {
+    lines.push(`N1  - ${noteParts}`);
+  }
+
+  lines.push(`ER  - `);
+  lines.push('');
+
+  return lines.join('\n');
+}

package/lib/formats/rss.js

@@ -0,0 +1,100 @@
+/**
+ * mill format: rss
+ *
+ * Converts compilation.json claims to an Atom XML feed.
+ * Each claim becomes a feed entry with category and content.
+ * Zero dependencies — node built-in only.
+ */
+
+export const name = 'rss';
+export const extension = '.xml';
+export const mimeType = 'application/atom+xml; charset=utf-8';
+export const description = 'Claims as Atom XML feed (one entry per claim)';
+
+/**
+ * Convert a compilation object to Atom XML.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} Atom XML output
+ */
+export function convert(compilation) {
+  const claims = compilation.claims || [];
+  const meta = compilation.meta || {};
+  const sprintName = meta.sprint || 'unnamed';
+  const updated = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+  const lines = [];
+  lines.push(`<?xml version="1.0" encoding="utf-8"?>`);
+  lines.push(`<feed xmlns="http://www.w3.org/2005/Atom">`);
+  lines.push(`  <title>${escapeXml(`Sprint: ${sprintName}`)}</title>`);
+  lines.push(`  <id>urn:wheat:sprint:${escapeXml(sprintName)}</id>`);
+  lines.push(`  <updated>${updated}</updated>`);
+
+  if (meta.question) {
+    lines.push(`  <subtitle>${escapeXml(meta.question)}</subtitle>`);
+  }
+
+  for (const claim of claims) {
+    lines.push(claimToEntry(claim));
+  }
+
+  lines.push(`</feed>`);
+  lines.push('');
+
+  return lines.join('\n');
+}
+
+function claimToEntry(claim) {
+  const id = String(claim.id || 'unknown');
+  const text = claim.content || claim.text || '';
+  const type = claim.type || '';
+  const status = claim.status || '';
+  const evidence = typeof claim.evidence === 'string'
+    ? claim.evidence
+    : (claim.evidence?.tier ?? claim.evidence_tier ?? '');
+  const tags = Array.isArray(claim.tags) ? claim.tags : [];
+  const updated = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
+
+  const summaryParts = [
+    type ? `type: ${type}` : '',
+    evidence ? `evidence: ${evidence}` : '',
+    status ? `status: ${status}` : '',
+  ].filter(Boolean).join(', ');
+
+  const lines = [];
+  lines.push(`  <entry>`);
+  lines.push(`    <title>${escapeXml(`${id}: ${truncate(text, 80)}`)}</title>`);
+  lines.push(`    <id>urn:wheat:${escapeXml(id)}</id>`);
+  lines.push(`    <updated>${updated}</updated>`);
+  lines.push(`    <content type="text">${escapeXml(text)}</content>`);
+
+  if (summaryParts) {
+    lines.push(`    <summary>${escapeXml(summaryParts)}</summary>`);
+  }
+
+  if (type) {
+    lines.push(`    <category term="${escapeXml(type)}"/>`);
+  }
+
+  for (const tag of tags) {
+    lines.push(`    <category term="${escapeXml(tag)}"/>`);
+  }
+
+  lines.push(`  </entry>`);
+
+  return lines.join('\n');
+}
+
+function escapeXml(value) {
+  if (value == null) return '';
+  return String(value)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function truncate(str, max) {
+  if (str.length <= max) return str;
+  return str.slice(0, max - 3) + '...';
+}

package/lib/formats/sankey.js

@@ -0,0 +1,72 @@
+/**
+ * mill format: sankey
+ *
+ * Converts compilation.json claims to Sankey JSON for D3-sankey.
+ * Three-column flow: type -> evidence_tier -> status.
+ * Zero dependencies — node built-in only.
+ */
+
+export const name = 'sankey';
+export const extension = '.json';
+export const mimeType = 'application/json; charset=utf-8';
+export const description = 'Claims as Sankey flow JSON (type -> evidence tier -> status)';
+
+/**
+ * Convert a compilation object to Sankey JSON.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} JSON output
+ */
+export function convert(compilation) {
+  const claims = compilation.claims || [];
+
+  // Count flows: type -> evidence, evidence -> status
+  const typeToEvidence = {};
+  const evidenceToStatus = {};
+  const nodeSet = new Set();
+
+  for (const claim of claims) {
+    const type = 'type:' + (claim.type || 'other');
+    const evidence = 'evidence:' + getEvidence(claim) || 'evidence:unknown';
+    const status = 'status:' + (claim.status || 'unknown');
+
+    nodeSet.add(type);
+    nodeSet.add(evidence);
+    nodeSet.add(status);
+
+    // type -> evidence link
+    const teKey = `${type}|||${evidence}`;
+    typeToEvidence[teKey] = (typeToEvidence[teKey] || 0) + 1;
+
+    // evidence -> status link
+    const esKey = `${evidence}|||${status}`;
+    evidenceToStatus[esKey] = (evidenceToStatus[esKey] || 0) + 1;
+  }
+
+  const nodes = Array.from(nodeSet)
+    .sort()
+    .map(id => ({ id }));
+
+  const links = [];
+
+  for (const [key, value] of Object.entries(typeToEvidence)) {
+    const [source, target] = key.split('|||');
+    links.push({ source, target, value });
+  }
+
+  for (const [key, value] of Object.entries(evidenceToStatus)) {
+    const [source, target] = key.split('|||');
+    links.push({ source, target, value });
+  }
+
+  const result = { nodes, links };
+
+  return JSON.stringify(result, null, 2) + '\n';
+}
+
+function getEvidence(claim) {
+  if (typeof claim.evidence === 'string') return claim.evidence;
+  if (typeof claim.evidence === 'object' && claim.evidence !== null) {
+    return claim.evidence.tier || claim.evidence_tier || '';
+  }
+  return claim.evidence_tier || '';
+}