@grainulation/mill 1.0.0 → 1.0.1

package/lib/formats/executive-summary.js

@@ -3,13 +3,15 @@
  *
  * Single-page HTML showing only active risks, top recommendations,
  * and confidence-weighted findings. Filters out resolved/low-confidence noise.
+ * Accessible: semantic landmarks, table captions/scope, skip link.
  * Zero dependencies — node built-in only.
  */
 
-export const name = 'executive-summary';
-export const extension = '.html';
-export const mimeType = 'text/html; charset=utf-8';
-export const description = 'Compact executive summary: active risks, recommendations, evidence coverage';
+export const name = "executive-summary";
+export const extension = ".html";
+export const mimeType = "text/html; charset=utf-8";
+export const description =
+  "Compact executive summary: active risks, recommendations, evidence coverage";
 
 /**
  * Convert a compilation object to an executive summary HTML page.
@@ -21,48 +23,65 @@ export function convert(compilation) {
   const claims = compilation.claims || [];
   const certificate = compilation.certificate || {};
 
-  const title = meta.sprint || meta.question || 'Executive Summary';
+  const title = meta.sprint || meta.question || "Executive Summary";
 
   // Active risks sorted by confidence desc
   const risks = claims
-    .filter(c => c.type === 'risk' && c.status === 'active')
+    .filter((c) => c.type === "risk" && c.status === "active")
     .sort((a, b) => (b.confidence || 0) - (a.confidence || 0));
 
   // Active recommendations sorted by confidence desc
   const recs = claims
-    .filter(c => c.type === 'recommendation' && c.status === 'active')
+    .filter((c) => c.type === "recommendation" && c.status === "active")
     .sort((a, b) => (b.confidence || 0) - (a.confidence || 0));
 
   // Evidence coverage — count by tier
-  const tierOrder = ['production', 'tested', 'documented', 'web', 'stated'];
+  const tierOrder = ["production", "tested", "documented", "web", "stated"];
   const tierCounts = {};
   for (const c of claims) {
-    if (c.status === 'reverted') continue;
-    const tier = typeof c.evidence === 'string' ? c.evidence : (c.evidence?.tier || c.evidence_tier || 'unknown');
+    if (c.status === "reverted") continue;
+    const tier =
+      typeof c.evidence === "string"
+        ? c.evidence
+        : c.evidence?.tier || c.evidence_tier || "unknown";
     tierCounts[tier] = (tierCounts[tier] || 0) + 1;
   }
 
-  const riskRows = risks.map(c => {
-    const conf = c.confidence != null ? Math.round(c.confidence * 100) + '%' : '--';
-    const tier = typeof c.evidence === 'string' ? c.evidence : (c.evidence?.tier || '');
-    return `<tr><td class="mono">${esc(c.id)}</td><td>${esc(c.content || c.text || '')}</td><td class="center">${esc(tier)}</td><td class="center">${conf}</td></tr>`;
-  }).join('\n');
-
-  const recRows = recs.map(c => {
-    const conf = c.confidence != null ? Math.round(c.confidence * 100) + '%' : '--';
-    const tier = typeof c.evidence === 'string' ? c.evidence : (c.evidence?.tier || '');
-    return `<tr><td class="mono">${esc(c.id)}</td><td>${esc(c.content || c.text || '')}</td><td class="center">${esc(tier)}</td><td class="center">${conf}</td></tr>`;
-  }).join('\n');
+  const riskRows = risks
+    .map((c) => {
+      const conf =
+        c.confidence != null ? Math.round(c.confidence * 100) + "%" : "--";
+      const tier =
+        typeof c.evidence === "string" ? c.evidence : c.evidence?.tier || "";
+      return `<tr><td class="mono">${esc(c.id)}</td><td>${esc(c.content || c.text || "")}</td><td class="center">${esc(tier)}</td><td class="center">${conf}</td></tr>`;
+    })
+    .join("\n");
+
+  const recRows = recs
+    .map((c) => {
+      const conf =
+        c.confidence != null ? Math.round(c.confidence * 100) + "%" : "--";
+      const tier =
+        typeof c.evidence === "string" ? c.evidence : c.evidence?.tier || "";
+      return `<tr><td class="mono">${esc(c.id)}</td><td>${esc(c.content || c.text || "")}</td><td class="center">${esc(tier)}</td><td class="center">${conf}</td></tr>`;
+    })
+    .join("\n");
 
   const evidenceRows = tierOrder
-    .filter(t => tierCounts[t])
-    .map(t => `<tr><td>${capitalize(t)}</td><td class="center">${tierCounts[t]}</td></tr>`)
-    .join('\n');
+    .filter((t) => tierCounts[t])
+    .map(
+      (t) =>
+        `<tr><td>${capitalize(t)}</td><td class="center">${tierCounts[t]}</td></tr>`,
+    )
+    .join("\n");
   // Include unknown tiers
   const extraTiers = Object.keys(tierCounts)
-    .filter(t => !tierOrder.includes(t))
-    .map(t => `<tr><td>${capitalize(t)}</td><td class="center">${tierCounts[t]}</td></tr>`)
-    .join('\n');
+    .filter((t) => !tierOrder.includes(t))
+    .map(
+      (t) =>
+        `<tr><td>${capitalize(t)}</td><td class="center">${tierCounts[t]}</td></tr>`,
+    )
+    .join("\n");
 
   return `<!DOCTYPE html>
 <html lang="en">
@@ -74,11 +93,14 @@ export function convert(compilation) {
   :root { --bg:#0a0e1a; --surface:#111827; --border:#1e293b; --text:#e2e8f0; --muted:#94a3b8; }
   * { margin:0; padding:0; box-sizing:border-box; }
   body { background:var(--bg); color:var(--text); font-family:-apple-system,BlinkMacSystemFont,'Segoe UI',Roboto,sans-serif; line-height:1.6; padding:2rem; max-width:900px; margin:0 auto; }
+  a.skip-link { position:absolute; top:-40px; left:0; background:var(--surface); color:var(--text); padding:0.5rem 1rem; z-index:100; border-radius:0 0 4px 0; }
+  a.skip-link:focus { top:0; }
   h1 { font-size:1.6rem; margin-bottom:0.25rem; }
   .subtitle { color:var(--muted); font-size:0.9rem; margin-bottom:2rem; }
   h2 { font-size:1.1rem; margin:1.5rem 0 0.75rem; padding-bottom:0.4rem; border-bottom:1px solid var(--border); }
   h2 .count { color:var(--muted); font-weight:400; }
   table { width:100%; border-collapse:collapse; margin-bottom:1rem; }
+  caption { text-align:left; font-size:0.75rem; color:var(--muted); padding-bottom:0.25rem; caption-side:top; }
   th { text-align:left; font-size:0.75rem; text-transform:uppercase; color:var(--muted); padding:0.5rem; border-bottom:1px solid var(--border); }
   td { padding:0.5rem; border-bottom:1px solid var(--border); font-size:0.88rem; vertical-align:top; }
   .center { text-align:center; }
@@ -90,39 +112,65 @@ export function convert(compilation) {
 </style>
 </head>
 <body>
-  <h1>${esc(title)}</h1>
-  <p class="subtitle">${meta.question ? esc(meta.question) : ''}${meta.question && certificate.compiled_at ? ' | ' : ''}${certificate.compiled_at ? 'Compiled: ' + esc(certificate.compiled_at) : ''}</p>
-
+  <a class="skip-link" href="#main-content">Skip to content</a>
+  <header role="banner">
+    <h1>${esc(title)}</h1>
+    <p class="subtitle">${meta.question ? esc(meta.question) : ""}${meta.question && certificate.compiled_at ? " | " : ""}${certificate.compiled_at ? "Compiled: " + esc(certificate.compiled_at) : ""}</p>
+  </header>
+
+  <main id="main-content">
+  <section aria-label="Key risks">
   <h2>Key Risks <span class="count">(${risks.length})</span></h2>
-  ${risks.length > 0 ? `
+  ${
+    risks.length > 0
+      ? `
   <table class="risk-table">
-    <thead><tr><th>ID</th><th>Description</th><th>Evidence</th><th>Confidence</th></tr></thead>
+    <caption>Active risks sorted by confidence</caption>
+    <thead><tr><th scope="col">ID</th><th scope="col">Description</th><th scope="col">Evidence</th><th scope="col">Confidence</th></tr></thead>
     <tbody>${riskRows}</tbody>
-  </table>` : '<p class="empty">No active risks.</p>'}
+  </table>`
+      : '<p class="empty">No active risks.</p>'
+  }
+  </section>
 
+  <section aria-label="Recommendations">
   <h2>Recommendations <span class="count">(${recs.length})</span></h2>
-  ${recs.length > 0 ? `
+  ${
+    recs.length > 0
+      ? `
   <table class="rec-table">
-    <thead><tr><th>ID</th><th>Description</th><th>Evidence</th><th>Confidence</th></tr></thead>
+    <caption>Active recommendations sorted by confidence</caption>
+    <thead><tr><th scope="col">ID</th><th scope="col">Description</th><th scope="col">Evidence</th><th scope="col">Confidence</th></tr></thead>
     <tbody>${recRows}</tbody>
-  </table>` : '<p class="empty">No active recommendations.</p>'}
+  </table>`
+      : '<p class="empty">No active recommendations.</p>'
+  }
+  </section>
 
+  <section aria-label="Evidence coverage">
   <h2>Evidence Coverage</h2>
   <table>
-    <thead><tr><th>Tier</th><th>Claims</th></tr></thead>
+    <caption>Claims count per evidence tier</caption>
+    <thead><tr><th scope="col">Tier</th><th scope="col">Claims</th></tr></thead>
     <tbody>${evidenceRows}${extraTiers}</tbody>
   </table>
+  </section>
+  </main>
 
-  <footer>
-    Certificate: ${certificate.claim_count || claims.length} claims | sha256:${(certificate.sha256 || 'unknown').slice(0, 16)}
+  <footer role="contentinfo">
+    Certificate: ${certificate.claim_count || claims.length} claims | sha256:${(certificate.sha256 || "unknown").slice(0, 16)}
   </footer>
 </body>
 </html>`;
 }
 
 function esc(str) {
-  if (str == null) return '';
-  return String(str).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+  if (str == null) return "";
+  return String(str)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
 }
 
 function capitalize(str) {

package/lib/formats/github-issues.js

@@ -6,10 +6,11 @@
  * Zero dependencies — node built-in only.
  */
 
-export const name = 'github-issues';
-export const extension = '.md';
-export const mimeType = 'text/markdown; charset=utf-8';
-export const description = 'Claims as GitHub issue templates (one markdown file, horizontal-rule separated)';
+export const name = "github-issues";
+export const extension = ".md";
+export const mimeType = "text/markdown; charset=utf-8";
+export const description =
+  "Claims as GitHub issue templates (one markdown file, horizontal-rule separated)";
 
 /**
  * Convert a compilation object to GitHub issue markdown.
@@ -19,71 +20,77 @@ export const description = 'Claims as GitHub issue templates (one markdown file,
 export function convert(compilation) {
   const meta = compilation.meta || {};
   const claims = compilation.claims || [];
-  const sprint = meta.sprint || 'unknown';
+  const sprint = meta.sprint || "unknown";
 
   const lines = [];
 
   lines.push(`# GitHub Issues: ${sprint}`);
-  lines.push('');
-  lines.push('> Bulk-create with the `gh` CLI:');
-  lines.push('> ```');
-  lines.push('> # Split this file by "---" and create each section as an issue:');
-  lines.push(`> # gh issue create --title "TITLE" --body "BODY" --label "TYPE"`);
-  lines.push('> ```');
-  lines.push('');
+  lines.push("");
+  lines.push("> Bulk-create with the `gh` CLI:");
+  lines.push("> ```");
+  lines.push(
+    '> # Split this file by "---" and create each section as an issue:',
+  );
+  lines.push(
+    `> # gh issue create --title "TITLE" --body "BODY" --label "TYPE"`,
+  );
+  lines.push("> ```");
+  lines.push("");
 
   if (claims.length === 0) {
-    lines.push('_No claims to export._');
-    return lines.join('\n') + '\n';
+    lines.push("_No claims to export._");
+    return lines.join("\n") + "\n";
   }
 
   for (let i = 0; i < claims.length; i++) {
     if (i > 0) {
-      lines.push('');
+      lines.push("");
     }
-    lines.push('---');
-    lines.push('');
+    lines.push("---");
+    lines.push("");
     lines.push(...formatClaim(claims[i]));
   }
 
-  lines.push('');
-  return lines.join('\n') + '\n';
+  lines.push("");
+  return lines.join("\n") + "\n";
 }
 
 function formatClaim(claim) {
-  const id = claim.id || '???';
-  const content = claim.content || claim.text || '';
-  const type = claim.type || 'unknown';
+  const id = claim.id || "???";
+  const content = claim.content || claim.text || "";
+  const type = claim.type || "unknown";
   const evidence = getEvidence(claim);
-  const status = claim.status || 'unknown';
+  const status = claim.status || "unknown";
   const tags = Array.isArray(claim.tags) ? claim.tags : [];
   const summary = truncate(content, 80);
 
   const lines = [];
 
   lines.push(`## ${id}: ${summary}`);
-  lines.push('');
-  lines.push(`**Type:** ${type} | **Evidence:** ${evidence} | **Status:** ${status}`);
-  lines.push('');
+  lines.push("");
+  lines.push(
+    `**Type:** ${type} | **Evidence:** ${evidence} | **Status:** ${status}`,
+  );
+  lines.push("");
   lines.push(content);
 
   if (tags.length > 0) {
-    lines.push('');
-    lines.push(`**Tags:** ${tags.join(', ')}`);
+    lines.push("");
+    lines.push(`**Tags:** ${tags.join(", ")}`);
   }
 
   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';
+  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';
+  return claim.evidence_tier || "stated";
 }
 
 function truncate(str, max) {
   if (str.length <= max) return str;
-  return str.slice(0, max - 3) + '...';
+  return str.slice(0, max - 3) + "...";
 }

package/lib/formats/graphml.js

@@ -6,10 +6,11 @@
  * Zero dependencies — node built-in only.
  */
 
-export const name = 'graphml';
-export const extension = '.graphml';
-export const mimeType = 'application/graphml+xml; charset=utf-8';
-export const description = 'Claims as GraphML graph (nodes per claim, edges for shared tags)';
+export const name = "graphml";
+export const extension = ".graphml";
+export const mimeType = "application/graphml+xml; charset=utf-8";
+export const description =
+  "Claims as GraphML graph (nodes per claim, edges for shared tags)";
 
 /**
  * Convert a compilation object to GraphML XML.
@@ -22,32 +23,42 @@ export function convert(compilation) {
   const lines = [];
   lines.push('<?xml version="1.0" encoding="utf-8"?>');
   lines.push('<graphml xmlns="http://graphml.graphstruct.org/graphml">');
-  lines.push('  <key id="type" for="node" attr.name="type" attr.type="string"/>');
-  lines.push('  <key id="evidence" for="node" attr.name="evidence" attr.type="string"/>');
-  lines.push('  <key id="content" for="node" attr.name="content" attr.type="string"/>');
-  lines.push('  <key id="status" for="node" attr.name="status" attr.type="string"/>');
-  lines.push('  <key id="confidence" for="node" attr.name="confidence" attr.type="double"/>');
+  lines.push(
+    '  <key id="type" for="node" attr.name="type" attr.type="string"/>',
+  );
+  lines.push(
+    '  <key id="evidence" for="node" attr.name="evidence" attr.type="string"/>',
+  );
+  lines.push(
+    '  <key id="content" for="node" attr.name="content" attr.type="string"/>',
+  );
+  lines.push(
+    '  <key id="status" for="node" attr.name="status" attr.type="string"/>',
+  );
+  lines.push(
+    '  <key id="confidence" for="node" attr.name="confidence" attr.type="double"/>',
+  );
   lines.push('  <key id="tag" for="edge" attr.name="tag" attr.type="string"/>');
   lines.push('  <graph id="G" edgedefault="undirected">');
 
   // Nodes
   for (const claim of claims) {
-    const id = esc(claim.id || '');
-    const type = esc(claim.type || '');
+    const id = esc(claim.id || "");
+    const type = esc(claim.type || "");
     const evidence = esc(getEvidence(claim));
-    const content = esc(claim.content || claim.text || '');
-    const status = esc(claim.status || '');
-    const confidence = claim.confidence != null ? claim.confidence : '';
+    const content = esc(claim.content || claim.text || "");
+    const status = esc(claim.status || "");
+    const confidence = claim.confidence != null ? claim.confidence : "";
 
     lines.push(`    <node id="${id}">`);
     lines.push(`      <data key="type">${type}</data>`);
     lines.push(`      <data key="evidence">${evidence}</data>`);
     lines.push(`      <data key="content">${content}</data>`);
     lines.push(`      <data key="status">${status}</data>`);
-    if (confidence !== '') {
+    if (confidence !== "") {
       lines.push(`      <data key="confidence">${confidence}</data>`);
     }
-    lines.push('    </node>');
+    lines.push("    </node>");
   }
 
   // Edges: connect claims that share at least one tag
@@ -55,15 +66,17 @@ export function convert(compilation) {
   let edgeId = 0;
   for (const edge of edges) {
     edgeId++;
-    lines.push(`    <edge id="e${edgeId}" source="${esc(edge.source)}" target="${esc(edge.target)}">`);
+    lines.push(
+      `    <edge id="e${edgeId}" source="${esc(edge.source)}" target="${esc(edge.target)}">`,
+    );
     lines.push(`      <data key="tag">${esc(edge.tag)}</data>`);
-    lines.push('    </edge>');
+    lines.push("    </edge>");
   }
 
-  lines.push('  </graph>');
-  lines.push('</graphml>');
+  lines.push("  </graph>");
+  lines.push("</graphml>");
 
-  return lines.join('\n') + '\n';
+  return lines.join("\n") + "\n";
 }
 
 /**
@@ -77,7 +90,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 || "");
     }
   }
 
@@ -100,19 +113,19 @@ function buildTagEdges(claims) {
 }
 
 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 || '';
+  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 || '';
+  return claim.evidence_tier || "";
 }
 
 function esc(str) {
-  if (str == null) return '';
+  if (str == null) return "";
   return String(str)
-    .replace(/&/g, '&amp;')
-    .replace(/</g, '&lt;')
-    .replace(/>/g, '&gt;')
-    .replace(/"/g, '&quot;')
-    .replace(/'/g, '&apos;');
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;")
+    .replace(/'/g, "&apos;");
 }