@grainulation/mill 1.0.0

package/lib/exporters/pdf.js

@@ -0,0 +1,104 @@
+'use strict';
+
+// NOTE: PDF is the one export format that requires external tools (md-to-pdf
+// for Markdown, puppeteer for HTML). These are fetched via npx on first run,
+// which needs network access. All other mill export formats are zero-dep.
+
+const path = require('node:path');
+const { execFile } = require('node:child_process');
+
+/**
+ * Export HTML or Markdown files to PDF.
+ * Uses npx md-to-pdf for Markdown, npx puppeteer for HTML.
+ * Zero installed deps -- delegates to npx at runtime.
+ */
+
+function deriveOutputPath(inputPath, explicit) {
+  if (explicit) return explicit;
+  const dir = path.dirname(inputPath);
+  const base = path.basename(inputPath, path.extname(inputPath));
+  return path.join(dir, `${base}.pdf`);
+}
+
+function exec(cmd, args) {
+  return new Promise((resolve, reject) => {
+    execFile(cmd, args, { timeout: 120_000 }, (err, stdout, stderr) => {
+      if (err) {
+        reject(new Error(`${cmd} failed: ${stderr || err.message}`));
+      } else {
+        resolve(stdout);
+      }
+    });
+  });
+}
+
+function npxToolError(toolName, originalError) {
+  const msg = originalError.message || String(originalError);
+  const isNotFound = /not found|ENOENT|ERR_MODULE_NOT_FOUND|Cannot find module/i.test(msg);
+  const isNetwork = /ENETUNREACH|ENOTFOUND|fetch failed|EAI_AGAIN/i.test(msg);
+  const isTimeout = /timed out|ETIMEDOUT/i.test(msg);
+
+  let hint;
+  if (isNotFound || isNetwork || isTimeout) {
+    hint =
+      `PDF export requires "${toolName}" which is fetched via npx on first run.\n` +
+      `  To pre-install: npx ${toolName} --version\n` +
+      `  If you are offline or npx is unavailable, use: mill export --format markdown`;
+  } else {
+    hint =
+      `"${toolName}" exited with an error.\n` +
+      `  Verify it works standalone: npx ${toolName} --version\n` +
+      `  Or fall back to: mill export --format markdown`;
+  }
+
+  return new Error(`PDF export failed -- ${toolName} unavailable or broken.\n\n${hint}\n\nOriginal error: ${msg}`);
+}
+
+async function exportFromMarkdown(inputPath, outputPath) {
+  const out = deriveOutputPath(inputPath, outputPath);
+  // md-to-pdf reads from file, writes pdf alongside or to --dest
+  try {
+    await exec('npx', [
+      '--yes', 'md-to-pdf', inputPath,
+      '--dest', out,
+    ]);
+  } catch (err) {
+    throw npxToolError('md-to-pdf', err);
+  }
+  return { outputPath: out, message: `PDF written to ${out}` };
+}
+
+async function exportFromHtml(inputPath, outputPath) {
+  const out = deriveOutputPath(inputPath, outputPath);
+  // Use a small inline puppeteer script via npx
+  const script = `
+    const puppeteer = require('puppeteer');
+    (async () => {
+      const browser = await puppeteer.launch({ headless: 'new' });
+      const page = await browser.newPage();
+      await page.goto('file://${inputPath.replace(/'/g, "\\'")}', { waitUntil: 'networkidle0' });
+      await page.pdf({ path: '${out.replace(/'/g, "\\'")}', format: 'A4', printBackground: true });
+      await browser.close();
+    })();
+  `;
+  try {
+    await exec('node', ['-e', script]);
+  } catch (err) {
+    throw npxToolError('puppeteer', err);
+  }
+  return { outputPath: out, message: `PDF written to ${out}` };
+}
+
+async function exportPdf(inputPath, outputPath) {
+  const ext = path.extname(inputPath).toLowerCase();
+  if (ext === '.md' || ext === '.markdown') {
+    return exportFromMarkdown(inputPath, outputPath);
+  }
+  return exportFromHtml(inputPath, outputPath);
+}
+
+module.exports = {
+  name: 'pdf',
+  description: 'Export HTML or Markdown to PDF',
+  export: exportPdf,
+};

package/lib/formats/bibtex.js

@@ -0,0 +1,76 @@
+/**
+ * mill format: bibtex
+ *
+ * Converts compilation.json claims to BibTeX .bib entries.
+ * Each claim becomes an @misc entry with metadata in note/keywords fields.
+ * Zero dependencies — node built-in only.
+ */
+
+export const name = 'bibtex';
+export const extension = '.bib';
+export const mimeType = 'application/x-bibtex; charset=utf-8';
+export const description = 'Claims as BibTeX bibliography entries (@misc per claim)';
+
+/**
+ * Convert a compilation object to BibTeX.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} BibTeX output
+ */
+export function convert(compilation) {
+  const claims = compilation.claims || [];
+  const meta = compilation.meta || {};
+  const year = new Date().getFullYear().toString();
+  const author = meta.sprint ? `wheat sprint: ${meta.sprint}` : 'wheat sprint';
+
+  if (claims.length === 0) {
+    return `% No claims in compilation\n`;
+  }
+
+  const entries = claims.map(claim => claimToEntry(claim, author, year));
+  return entries.join('\n\n') + '\n';
+}
+
+function claimToEntry(claim, author, year) {
+  const id = String(claim.id || 'unknown').replace(/[^a-zA-Z0-9_-]/g, '_');
+  const title = escapeBibtex(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 keywordsLine = tags.length > 0
+    ? `\n  keywords = {${tags.map(escapeBibtex).join(', ')}},`
+    : '';
+
+  return [
+    `@misc{claim_${id},`,
+    `  title = {${title}},`,
+    `  author = {${escapeBibtex(author)}},`,
+    `  year = {${year}},`,
+    `  note = {${escapeBibtex(noteParts)}},` + keywordsLine,
+    `}`,
+  ].join('\n');
+}
+
+function escapeBibtex(value) {
+  if (value == null) return '';
+  return String(value)
+    .replace(/\\/g, '\\textbackslash{}')
+    .replace(/&/g, '\\&')
+    .replace(/%/g, '\\%')
+    .replace(/#/g, '\\#')
+    .replace(/_/g, '\\_')
+    .replace(/\{/g, '\\{')
+    .replace(/\}/g, '\\}')
+    .replace(/~/g, '\\textasciitilde{}')
+    .replace(/\^/g, '\\textasciicircum{}');
+}

package/lib/formats/changelog.js

@@ -0,0 +1,102 @@
+/**
+ * mill format: changelog
+ *
+ * Converts compilation.json claims to a diff/changelog grouped by status.
+ * Shows active, resolved, and conflict sections with counts.
+ * Zero dependencies — node built-in only.
+ */
+
+export const name = 'changelog';
+export const extension = '.md';
+export const mimeType = 'text/markdown; charset=utf-8';
+export const description = 'Claims changelog grouped by status (active, resolved, conflicts)';
+
+/**
+ * Convert a compilation object to changelog markdown.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} Markdown changelog output
+ */
+export function convert(compilation) {
+  const claims = compilation.claims || [];
+  const conflicts = compilation.conflicts || [];
+  const meta = compilation.meta || {};
+  const sprintName = meta.sprint || 'unnamed';
+
+  const groups = {};
+  for (const claim of claims) {
+    const status = claim.status || 'unknown';
+    if (!groups[status]) groups[status] = [];
+    groups[status].push(claim);
+  }
+
+  const lines = [];
+  lines.push(`# Changelog — ${sprintName}`);
+  lines.push('');
+
+  // Active claims first
+  if (groups.active) {
+    lines.push(`## Active (${groups.active.length} claims)`);
+    lines.push('');
+    for (const claim of groups.active) {
+      lines.push(`- ${claim.id}: ${claimText(claim)}`);
+    }
+    lines.push('');
+  }
+
+  // Resolved claims
+  if (groups.resolved) {
+    lines.push(`## Resolved (${groups.resolved.length} claims)`);
+    lines.push('');
+    for (const claim of groups.resolved) {
+      lines.push(`- ${claim.id}: ${claimText(claim)}`);
+    }
+    lines.push('');
+  }
+
+  // All other statuses
+  const shown = new Set(['active', 'resolved']);
+  const otherStatuses = Object.keys(groups)
+    .filter(s => !shown.has(s))
+    .sort();
+
+  for (const status of otherStatuses) {
+    const group = groups[status];
+    const label = status.charAt(0).toUpperCase() + status.slice(1);
+    lines.push(`## ${label} (${group.length} claims)`);
+    lines.push('');
+    for (const claim of group) {
+      lines.push(`- ${claim.id}: ${claimText(claim)}`);
+    }
+    lines.push('');
+  }
+
+  // Conflicts section
+  if (conflicts.length > 0) {
+    lines.push(`## Conflicts (${conflicts.length})`);
+    lines.push('');
+    for (const conflict of conflicts) {
+      const ids = Array.isArray(conflict.claim_ids)
+        ? conflict.claim_ids.join(' vs ')
+        : (conflict.between || 'unknown');
+      const desc = conflict.description || conflict.reason || '';
+      lines.push(`- ${ids}: ${desc}`);
+    }
+    lines.push('');
+  } else {
+    lines.push(`## Conflicts (0)`);
+    lines.push('');
+    lines.push('No conflicts.');
+    lines.push('');
+  }
+
+  return lines.join('\n');
+}
+
+function claimText(claim) {
+  const text = claim.content || claim.text || '';
+  // Truncate long claims for readability
+  if (text.length > 120) {
+    return text.slice(0, 117) + '...';
+  }
+  return text;
+}

package/lib/formats/csv.js

@@ -0,0 +1,92 @@
+/**
+ * mill format: csv
+ *
+ * Converts compilation.json claims to CSV.
+ * Columns: id, type, topic, content, evidence_tier, evidence_source, confidence, status
+ * 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)';
+
+const COLUMNS = [
+  'id',
+  'type',
+  'topic',
+  'content',
+  'evidence_tier',
+  'evidence_source',
+  'confidence',
+  'status',
+  'tags',
+  'created',
+];
+
+/**
+ * Convert a compilation object to CSV.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} CSV output
+ */
+export function convert(compilation) {
+  const claims = compilation.claims || [];
+
+  if (claims.length === 0) {
+    return COLUMNS.join(',') + '\n';
+  }
+
+  const header = COLUMNS.join(',');
+  const rows = claims.map(claimToRow);
+
+  return [header, ...rows].join('\n') + '\n';
+}
+
+function claimToRow(claim) {
+  return COLUMNS.map(col => {
+    switch (col) {
+      case 'content':
+        // Claims may use 'text' or 'content' for the main body
+        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] || '' : '')
+        );
+      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':
+        // 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.evidence === 'object' && claim.evidence?.source) {
+          return escapeField(claim.evidence.source);
+        }
+        return escapeField(claim.source ?? '');
+      case 'tags':
+        return escapeField(
+          Array.isArray(claim.tags) ? claim.tags.join('; ') : ''
+        );
+      case 'confidence':
+        return claim.confidence != null ? String(claim.confidence) : '';
+      default:
+        return escapeField(claim[col]);
+    }
+  }).join(',');
+}
+
+function escapeField(value) {
+  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')) {
+    return `"${str.replace(/"/g, '""')}"`;
+  }
+  return str;
+}

package/lib/formats/dot.js

@@ -0,0 +1,129 @@
+/**
+ * mill format: dot
+ *
+ * Converts compilation.json claims to Graphviz DOT format.
+ * Claims grouped into type-based subgraph clusters, tag edges as dashed lines.
+ * 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)';
+
+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' },
+};
+
+const DEFAULT_COLOR = { border: '#9ca3af', fill: '#1f1f1f', label: 'Other' };
+
+/**
+ * Convert a compilation object to DOT format.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} DOT output
+ */
+export function convert(compilation) {
+  const claims = compilation.claims || [];
+  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('  edge [fontname="monospace", fontsize=8];');
+  lines.push('');
+
+  // Group claims by type
+  const groups = {};
+  for (const claim of claims) {
+    const t = claim.type || 'other';
+    if (!groups[t]) groups[t] = [];
+    groups[t].push(claim);
+  }
+
+  // Type clusters
+  for (const [type, group] of Object.entries(groups)) {
+    const colors = TYPE_COLORS[type] || DEFAULT_COLOR;
+    lines.push(`  subgraph cluster_${escId(type)} {`);
+    lines.push(`    label="${escDot(colors.label || type)}";`);
+    lines.push(`    color="${colors.border}";`);
+    lines.push(`    style=dashed;`);
+    lines.push('');
+
+    for (const claim of group) {
+      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('  }');
+    lines.push('');
+  }
+
+  // Tag edges
+  const edges = buildTagEdges(claims);
+  if (edges.length > 0) {
+    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('');
+  }
+
+  lines.push('}');
+
+  return lines.join('\n') + '\n';
+}
+
+function buildTagEdges(claims) {
+  const tagMap = {};
+
+  for (const claim of claims) {
+    const tags = Array.isArray(claim.tags) ? claim.tags : [];
+    for (const tag of tags) {
+      if (!tagMap[tag]) tagMap[tag] = [];
+      tagMap[tag].push(claim.id || '');
+    }
+  }
+
+  const edges = [];
+  const seen = new Set();
+
+  for (const [tag, ids] of Object.entries(tagMap)) {
+    for (let i = 0; i < ids.length; i++) {
+      for (let j = i + 1; j < ids.length; j++) {
+        const key = `${ids[i]}--${ids[j]}--${tag}`;
+        if (!seen.has(key)) {
+          seen.add(key);
+          edges.push({ source: ids[i], target: ids[j], tag });
+        }
+      }
+    }
+  }
+
+  return edges;
+}
+
+function truncate(str, max) {
+  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, '_');
+}
+
+function escDot(str) {
+  if (str == null) return '';
+  return String(str)
+    .replace(/\\/g, '\\\\')
+    .replace(/"/g, '\\"')
+    .replace(/\n/g, '\\n');
+}

package/lib/formats/evidence-matrix.js

@@ -0,0 +1,87 @@
+/**
+ * mill format: evidence-matrix
+ *
+ * Generates a pivot CSV with rows=claim types, columns=evidence tiers, cells=counts.
+ * Useful for visualizing evidence coverage across claim categories.
+ * 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';
+
+const TIER_ORDER = ['stated', 'web', 'documented', 'tested', 'production'];
+
+/**
+ * Convert a compilation object to an evidence matrix CSV.
+ * @param {object} compilation - The compilation.json content
+ * @returns {string} CSV pivot table output
+ */
+export function convert(compilation) {
+  const claims = compilation.claims || [];
+
+  // Build the pivot: type -> tier -> count
+  const pivot = {};
+  const allTypes = new Set();
+  const allTiers = new Set();
+
+  for (const claim of claims) {
+    if (claim.status === 'reverted') continue;
+
+    const type = claim.type || 'unknown';
+    const tier = extractTier(claim) || 'unknown';
+
+    allTypes.add(type);
+    allTiers.add(tier);
+
+    if (!pivot[type]) pivot[type] = {};
+    pivot[type][tier] = (pivot[type][tier] || 0) + 1;
+  }
+
+  // Build column order: known tiers first (in canonical order), then any extras
+  const tierColumns = [];
+  for (const t of TIER_ORDER) {
+    if (allTiers.has(t)) tierColumns.push(t);
+  }
+  for (const t of [...allTiers].sort()) {
+    if (!tierColumns.includes(t)) tierColumns.push(t);
+  }
+
+  // Build row order: sort types alphabetically
+  const typeRows = [...allTypes].sort();
+
+  // Generate CSV
+  const lines = [];
+
+  // Header
+  lines.push(['type', ...tierColumns, 'total'].join(','));
+
+  // Data rows
+  for (const type of typeRows) {
+    const counts = tierColumns.map(tier => pivot[type]?.[tier] || 0);
+    const total = counts.reduce((sum, n) => sum + n, 0);
+    lines.push([type, ...counts, total].join(','));
+  }
+
+  // Totals row
+  const colTotals = tierColumns.map(tier => {
+    let sum = 0;
+    for (const type of typeRows) {
+      sum += pivot[type]?.[tier] || 0;
+    }
+    return sum;
+  });
+  const grandTotal = colTotals.reduce((sum, n) => sum + n, 0);
+  lines.push(['total', ...colTotals, grandTotal].join(','));
+
+  return lines.join('\n') + '\n';
+}
+
+function extractTier(claim) {
+  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;
+}