certainty-units 0.2.0

package/src/cli.js

@@ -0,0 +1,224 @@
+#!/usr/bin/env node
+import { program } from 'commander'
+import { writeFileSync } from 'fs'
+import chalk from 'chalk'
+import { loadConfig, CONFIG_TEMPLATE } from './config.js'
+import { computeCertaintyScore, computeScoreBreakdown, biggestGaps } from './certainty.js'
+import { generateHTML, generateMarkdown } from './report.js'
+import { loadHistory, appendSnapshot, diffAgainstLast } from './history.js'
+
+// Lazy-load adapters by source name
+async function loadAdapter(source) {
+  const adapters = {
+    linear: './adapters/linear.js',
+    jira:   './adapters/jira.js',
+    notion: './adapters/notion.js',
+    github: './adapters/github.js',
+  }
+  const path = adapters[source]
+  if (!path) throw new Error(`Unknown source: "${source}". Supported: ${Object.keys(adapters).join(', ')}`)
+  return import(path)
+}
+
+program
+  .name('certainty-units')
+  .description('Certainty scoring for project work items')
+  .version('0.1.0')
+
+program
+  .command('init')
+  .description('Create a certainty.config.yaml template in the current directory')
+  .action(() => {
+    writeFileSync('certainty.config.yaml', CONFIG_TEMPLATE)
+    console.log(chalk.green('✓') + ' Created certainty.config.yaml')
+    console.log('  Edit it with your API keys, then run: certainty-units sync')
+  })
+
+program
+  .command('sync')
+  .description('Fetch items from your tool and compute certainty scores')
+  .option('-c, --config <path>', 'path to config file', 'certainty.config.yaml')
+  .option('--source <name>', 'override source from config')
+  .option('--json', 'also write cu-data.json')
+  .option('--fail-below <score>', 'exit with code 1 if average certainty is below this (CI gate)')
+  .option('--slack-webhook <url>', 'post the summary to a Slack incoming webhook')
+  .option('--no-history', 'skip reading/writing the snapshot history file')
+  .action(async (opts) => {
+    let config
+    try {
+      config = loadConfig(opts.config)
+    } catch (e) {
+      console.error(chalk.red('Error: ') + e.message)
+      process.exit(1)
+    }
+
+    const source = opts.source ?? config.source
+    console.log(chalk.dim(`Fetching from ${source}…`))
+
+    let adapter
+    try {
+      adapter = await loadAdapter(source)
+    } catch (e) {
+      console.error(chalk.red('Error: ') + e.message)
+      process.exit(1)
+    }
+
+    let items
+    try {
+      items = await adapter.fetchItems(config[source] ?? config)
+    } catch (e) {
+      console.error(chalk.red(`Failed to fetch from ${source}: `) + e.message)
+      process.exit(1)
+    }
+
+    console.log(chalk.dim(`  ${items.length} items fetched. Computing certainty scores…`))
+
+    for (const item of items) {
+      item.certainty_score = computeCertaintyScore(item, item.citation_count ?? 0)
+      item.certainty_breakdown = computeScoreBreakdown(item, item.citation_count ?? 0)
+    }
+
+    const projectName = config.project ?? 'Project'
+    const out = config.output ?? {}
+
+    // summary numbers (needed before history/slack)
+    const scores = items.map(i => i.certainty_score)
+    const avg = scores.length ? Math.round(scores.reduce((a, b) => a + b, 0) / scores.length) : 0
+
+    // compare against the previous sync, then record this one
+    let diff = null
+    if (opts.history) {
+      const historyPath = out.history ?? '.cu-history.json'
+      const history = loadHistory(historyPath)
+      diff = diffAgainstLast(history, items, avg)
+      appendSnapshot(historyPath, history, items, avg)
+    }
+
+    const htmlPath = out.html ?? 'cu-report.html'
+    writeFileSync(htmlPath, generateHTML(items, projectName))
+    console.log(chalk.green('✓') + ` ${htmlPath}`)
+
+    if (out.markdown) {
+      writeFileSync(out.markdown, generateMarkdown(items, projectName))
+      console.log(chalk.green('✓') + ` ${out.markdown}`)
+    }
+
+    if (opts.json) {
+      writeFileSync('cu-data.json', JSON.stringify(items, null, 2))
+      console.log(chalk.green('✓') + ' cu-data.json')
+    }
+
+    // Print quick summary to terminal
+    const high   = scores.filter(s => s >= 80).length
+    const medium = scores.filter(s => s >= 50 && s < 80).length
+    const low    = scores.filter(s => s >= 20 && s < 50).length
+    const unc    = scores.filter(s => s < 20).length
+
+    console.log()
+    console.log(chalk.bold(`${items.length} items  ·  avg certainty ${avg}%`))
+    console.log(
+      chalk.green(`  high ${high}`) + '  ' +
+      chalk.blue(`medium ${medium}`) + '  ' +
+      chalk.yellow(`low ${low}`) + '  ' +
+      chalk.red(`uncertain ${unc}`)
+    )
+
+    // What moved since the previous sync
+    if (diff) {
+      const arrow = diff.avgDelta > 0 ? chalk.green(`▲ +${diff.avgDelta}`)
+        : diff.avgDelta < 0 ? chalk.red(`▼ ${diff.avgDelta}`)
+        : chalk.dim('unchanged')
+      console.log()
+      console.log(chalk.bold(`Since last sync (${diff.since.slice(0, 10)}):`) +
+        `  avg ${diff.avgBefore}% → ${diff.avgNow}%  ${arrow}` +
+        (diff.newItems ? chalk.dim(`  ·  ${diff.newItems} new item${diff.newItems === 1 ? '' : 's'}`) : ''))
+      for (const m of diff.drops.slice(0, 3)) {
+        console.log(chalk.red(`  ▼ ${m.prev} → ${m.now}`) + `  ${chalk.dim(m.item.external_id)}  ${m.item.title.slice(0, 55)}`)
+      }
+      for (const m of diff.rises.slice(0, 3)) {
+        console.log(chalk.green(`  ▲ ${m.prev} → ${m.now}`) + `  ${chalk.dim(m.item.external_id)}  ${m.item.title.slice(0, 55)}`)
+      }
+    }
+
+    // Instant insight: the least certain open items, and what would fix them
+    const risky = items
+      .filter(i => i.workflow_status !== 'done' && (i.certainty_score ?? 0) < 50)
+      .sort((a, b) => (a.certainty_score ?? 0) - (b.certainty_score ?? 0))
+      .slice(0, 5)
+
+    if (risky.length) {
+      console.log()
+      console.log(chalk.bold('Least certain open items:'))
+      for (const item of risky) {
+        const gaps = biggestGaps(item, item.citation_count ?? 0)
+          .map(g => `${g.signal} +${g.gap}`)
+          .join(', ')
+        console.log(
+          `  ${chalk.red(String(item.certainty_score).padStart(3) + '%')} ` +
+          `${chalk.dim(item.external_id)}  ${item.title.slice(0, 60)}`
+        )
+        console.log(chalk.dim(`        missing: ${gaps}`))
+      }
+    }
+
+    // Post summary to Slack
+    const webhook = opts.slackWebhook ?? out.slackWebhook
+    if (webhook) {
+      const deltaText = diff
+        ? ` (${diff.avgDelta > 0 ? '+' : ''}${diff.avgDelta} since ${diff.since.slice(0, 10)})`
+        : ''
+      const lines = [
+        `*Certainty Units — ${projectName}*`,
+        `${items.length} items · avg certainty ${avg}%${deltaText}`,
+        `high ${high} · medium ${medium} · low ${low} · uncertain ${unc}`,
+      ]
+      if (risky.length) {
+        lines.push('', '*Least certain open items:*')
+        for (const item of risky) {
+          const gaps = biggestGaps(item, item.citation_count ?? 0).map(g => `${g.signal} +${g.gap}`).join(', ')
+          lines.push(`• <${item.url}|${item.external_id}> ${item.certainty_score}% — ${item.title.slice(0, 60)} _(missing: ${gaps})_`)
+        }
+      }
+      try {
+        const res = await fetch(webhook, {
+          method: 'POST',
+          headers: { 'Content-Type': 'application/json' },
+          body: JSON.stringify({ text: lines.join('\n') }),
+        })
+        if (!res.ok) throw new Error(`${res.status} ${await res.text()}`)
+        console.log(chalk.green('✓') + ' posted summary to Slack')
+      } catch (e) {
+        console.error(chalk.red('Slack webhook failed: ') + e.message)
+      }
+    }
+
+    // CI gate
+    if (opts.failBelow !== undefined) {
+      const threshold = Number(opts.failBelow)
+      if (Number.isNaN(threshold)) {
+        console.error(chalk.red('Error: ') + '--fail-below must be a number')
+        process.exit(1)
+      }
+      if (avg < threshold) {
+        console.error(chalk.red(`\n✗ average certainty ${avg}% is below the ${threshold}% gate`))
+        process.exit(1)
+      }
+      console.log(chalk.green(`\n✓ average certainty ${avg}% meets the ${threshold}% gate`))
+    }
+  })
+
+program
+  .command('validate')
+  .description('Check config file for required fields without making API calls')
+  .option('-c, --config <path>', 'path to config file', 'certainty.config.yaml')
+  .action((opts) => {
+    try {
+      const config = loadConfig(opts.config)
+      console.log(chalk.green('✓') + ` Config is valid (source: ${config.source})`)
+    } catch (e) {
+      console.error(chalk.red('Invalid config: ') + e.message)
+      process.exit(1)
+    }
+  })
+
+program.parse()

package/src/config.js

@@ -0,0 +1,75 @@
+import { readFileSync, existsSync } from 'fs'
+import { resolve } from 'path'
+import yaml from 'js-yaml'
+
+const CONFIG_FILE = 'certainty.config.yaml'
+
+export function loadConfig(filePath) {
+  const path = resolve(filePath ?? CONFIG_FILE)
+  if (!existsSync(path)) {
+    throw new Error(`Config file not found: ${path}\nRun: certainty-units init`)
+  }
+  const raw = readFileSync(path, 'utf8')
+  const config = yaml.load(raw)
+
+  // Expand env vars like ${MY_VAR}
+  const json = JSON.stringify(config)
+  const expanded = json.replace(/\$\{([^}]+)\}/g, (_, key) => {
+    const val = process.env[key]
+    if (!val) throw new Error(`Missing env var: ${key}`)
+    return val
+  })
+  return JSON.parse(expanded)
+}
+
+export const CONFIG_TEMPLATE = `# certainty-units configuration
+# Docs: https://github.com/2ngnhan/certainty-units
+
+project: My Project
+
+# Choose one source: linear | jira | notion | github
+source: linear
+
+linear:
+  apiKey: \${LINEAR_API_KEY}
+  teamId: your-team-id   # from Linear team URL
+
+  # Optional: override field mappings
+  # fieldMap:
+  #   validation_status:
+  #     field: state.type
+  #     map:
+  #       completed: validated
+  #       started: assumed
+  #   cu_tier:
+  #     field: estimate
+  #     map:
+  #       1: basic
+  #       3: intermediate
+  #       8: advanced
+
+# jira:
+#   host: yourteam.atlassian.net
+#   email: you@example.com
+#   apiToken: \${JIRA_API_TOKEN}
+#   projectKey: MYPROJECT
+
+# github:
+#   repo: owner/name
+#   token: \${GITHUB_TOKEN}   # optional for public repos
+
+# notion:
+#   apiKey: \${NOTION_API_KEY}
+#   databaseId: your-database-id
+#   fieldMap:
+#     title_field: { field: Name }
+#     validation_status:
+#       field: Status
+#       map:
+#         Done: validated
+#         "In Progress": assumed
+
+output:
+  html: cu-report.html
+  markdown: cu-report.md   # optional — remove to skip
+`

package/src/history.js

@@ -0,0 +1,55 @@
+// Snapshot history — persists per-item scores across syncs so a run can
+// report what moved, not just where things stand.
+
+import { readFileSync, writeFileSync, existsSync } from 'fs'
+
+const MAX_SNAPSHOTS = 104 // two years of weekly syncs
+
+export function loadHistory(path) {
+  if (!existsSync(path)) return []
+  try {
+    const parsed = JSON.parse(readFileSync(path, 'utf8'))
+    return Array.isArray(parsed) ? parsed : []
+  } catch {
+    return [] // corrupt history should never block a sync
+  }
+}
+
+export function appendSnapshot(path, history, items, avg) {
+  const scores = {}
+  for (const item of items) scores[item.external_id] = item.certainty_score ?? 0
+  const snapshot = {
+    date: new Date().toISOString(),
+    avg,
+    count: items.length,
+    scores,
+  }
+  const next = [...history, snapshot].slice(-MAX_SNAPSHOTS)
+  writeFileSync(path, JSON.stringify(next, null, 2))
+  return snapshot
+}
+
+// Compare current items against the most recent snapshot.
+// Returns null when there is no previous snapshot to compare against.
+export function diffAgainstLast(history, items, avg) {
+  const last = history[history.length - 1]
+  if (!last) return null
+
+  const moved = []
+  for (const item of items) {
+    const prev = last.scores[item.external_id]
+    if (prev === undefined) continue
+    const delta = (item.certainty_score ?? 0) - prev
+    if (delta !== 0) moved.push({ item, prev, now: item.certainty_score ?? 0, delta })
+  }
+
+  return {
+    since: last.date,
+    avgBefore: last.avg,
+    avgNow: avg,
+    avgDelta: avg - last.avg,
+    drops: moved.filter(m => m.delta < 0).sort((a, b) => a.delta - b.delta),
+    rises: moved.filter(m => m.delta > 0).sort((a, b) => b.delta - a.delta),
+    newItems: items.filter(i => last.scores[i.external_id] === undefined).length,
+  }
+}

package/src/report.js

@@ -0,0 +1,200 @@
+import { certaintyLevel, computeCUMetrics, biggestGaps } from './certainty.js'
+
+function esc(str) {
+  return String(str ?? '')
+    .replaceAll('&', '&')
+    .replaceAll('<', '&lt;')
+    .replaceAll('>', '&gt;')
+    .replaceAll('"', '&quot;')
+}
+
+function levelColor(score) {
+  if (score >= 80) return '#24a148'
+  if (score >= 50) return '#0f62fe'
+  if (score >= 20) return '#f1c21b'
+  return '#da1e28'
+}
+
+function bar(score, breakdown) {
+  const color = levelColor(score)
+  const tooltip = breakdown
+    ? esc(breakdown.map(s => `${s.signal}: ${s.points}/${s.max} (${s.reason})`).join('\n'))
+    : ''
+  return `<div style="display:flex;align-items:center;gap:8px"${tooltip ? ` title="${tooltip}"` : ''}>
+    <div style="flex:1;background:#e0e0e0;border-radius:2px;height:6px">
+      <div style="width:${score}%;background:${color};height:6px;border-radius:2px"></div>
+    </div>
+    <span style="font-size:12px;min-width:32px;text-align:right;color:${color};font-weight:600">${score}</span>
+  </div>`
+}
+
+function metricBox(label, value, sub = '') {
+  return `<div style="background:#f4f4f4;border-radius:4px;padding:16px 20px;min-width:130px">
+    <div style="font-size:28px;font-weight:700;color:#161616">${value}</div>
+    <div style="font-size:12px;color:#525252;margin-top:2px">${label}</div>
+    ${sub ? `<div style="font-size:11px;color:#8d8d8d;margin-top:2px">${sub}</div>` : ''}
+  </div>`
+}
+
+function itemRow(item) {
+  const score = item.certainty_score ?? 0
+  const level = certaintyLevel(score)
+  const tierBadge = item.cu_tier
+    ? `<span style="font-size:10px;background:#e0e0e0;padding:2px 6px;border-radius:10px;margin-left:6px">${item.cu_tier}</span>`
+    : ''
+  return `<tr>
+    <td style="padding:10px 12px;border-bottom:1px solid #e0e0e0">
+      <a href="${esc(item.url) || '#'}" target="_blank" style="color:#0f62fe;text-decoration:none;font-size:13px">${esc(item.external_id)}</a>
+    </td>
+    <td style="padding:10px 12px;border-bottom:1px solid #e0e0e0;font-size:13px;max-width:320px">
+      ${esc(item.title)}${tierBadge}
+    </td>
+    <td style="padding:10px 12px;border-bottom:1px solid #e0e0e0;font-size:12px;color:#525252">${esc(item.workflow_status)}</td>
+    <td style="padding:10px 12px;border-bottom:1px solid #e0e0e0;font-size:12px;color:#525252">${esc(item.validation_status)}</td>
+    <td style="padding:10px 12px;border-bottom:1px solid #e0e0e0;width:160px">${bar(score, item.certainty_breakdown)}</td>
+    <td style="padding:10px 12px;border-bottom:1px solid #e0e0e0;font-size:12px;color:#525252;text-align:center">
+      <span style="color:${levelColor(score)};font-weight:600">${level}</span>
+    </td>
+  </tr>`
+}
+
+function needsAttention(items) {
+  const risky = items
+    .filter(i => i.workflow_status !== 'done' && (i.certainty_score ?? 0) < 50)
+    .sort((a, b) => (a.certainty_score ?? 0) - (b.certainty_score ?? 0))
+    .slice(0, 5)
+  if (!risky.length) return ''
+
+  const rows = risky.map(i => {
+    const gaps = biggestGaps(i, i.citation_count ?? 0)
+      .map(g => `<span style="white-space:nowrap">${esc(g.hint)} <b>+${g.gap}</b></span>`)
+      .join(' &middot; ')
+    return `<div style="display:flex;gap:12px;align-items:baseline;padding:8px 0;border-bottom:1px solid #e0e0e0">
+      <span style="color:${levelColor(i.certainty_score ?? 0)};font-weight:700;min-width:40px">${i.certainty_score ?? 0}%</span>
+      <a href="${esc(i.url) || '#'}" target="_blank" style="color:#0f62fe;text-decoration:none;font-size:13px">${esc(i.external_id)}</a>
+      <span style="font-size:13px;flex:1">${esc(i.title)}</span>
+      <span style="font-size:12px;color:#525252">${gaps}</span>
+    </div>`
+  })
+
+  return `<h2>Needs attention &mdash; least certain open items</h2>
+  <div style="background:#fff;border:1px solid #e0e0e0;border-radius:4px;padding:8px 16px;margin-bottom:32px">
+    ${rows.join('\n')}
+  </div>`
+}
+
+export function generateHTML(items, projectName = 'Project') {
+  const metrics = computeCUMetrics(items)
+  const sorted = [...items].sort((a, b) => (b.certainty_score ?? 0) - (a.certainty_score ?? 0))
+  const now = new Date().toLocaleString()
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width,initial-scale=1">
+<title>Certainty Units — ${projectName}</title>
+<style>
+  * { box-sizing: border-box; margin: 0; padding: 0 }
+  body { font-family: 'IBM Plex Sans', system-ui, sans-serif; background: #fff; color: #161616 }
+  header { background: #161616; color: #fff; padding: 24px 32px; display: flex; justify-content: space-between; align-items: center }
+  header h1 { font-size: 20px; font-weight: 400; letter-spacing: 0.16px }
+  header .meta { font-size: 12px; color: #8d8d8d }
+  main { max-width: 1200px; margin: 0 auto; padding: 32px }
+  .metrics { display: flex; gap: 12px; flex-wrap: wrap; margin-bottom: 32px }
+  h2 { font-size: 16px; font-weight: 600; margin-bottom: 16px; color: #161616 }
+  table { width: 100%; border-collapse: collapse }
+  th { text-align: left; padding: 8px 12px; font-size: 12px; color: #525252; font-weight: 600; border-bottom: 2px solid #e0e0e0; background: #f4f4f4 }
+  tr:hover td { background: #f4f4f4 }
+  .hill { display: flex; gap: 4px; align-items: flex-end; height: 48px; margin-bottom: 8px }
+  .hill-bar { flex: 1; background: #0f62fe; border-radius: 2px 2px 0 0; opacity: 0.7 }
+  footer { text-align: center; padding: 24px; font-size: 12px; color: #8d8d8d }
+  footer a { color: #8d8d8d }
+</style>
+</head>
+<body>
+<header>
+  <h1>Certainty Units &mdash; ${projectName}</h1>
+  <span class="meta">Generated ${now}</span>
+</header>
+<main>
+  <div class="metrics">
+    ${metricBox('Total items', metrics.totalItems)}
+    ${metricBox('With CU tier', metrics.cuItems)}
+    ${metricBox('Avg certainty', metrics.avgCertaintyScore + '%')}
+    ${metricBox('Completion rate', metrics.completionRate + '%', `${metrics.completedCUValue} / ${metrics.totalCUValue} CU`)}
+    ${metricBox('Integrity score', metrics.integrityScore + '%', 'validated / completed')}
+    ${metricBox('Uphill', metrics.uphill, 'discovery zone')}
+    ${metricBox('Downhill', metrics.downhill, 'execution zone')}
+  </div>
+
+  ${needsAttention(items)}
+
+  <h2>Items by certainty score</h2>
+  <table>
+    <thead>
+      <tr>
+        <th>ID</th>
+        <th>Title</th>
+        <th>Status</th>
+        <th>Validation</th>
+        <th>Certainty</th>
+        <th>Level</th>
+      </tr>
+    </thead>
+    <tbody>
+      ${sorted.map(itemRow).join('\n')}
+    </tbody>
+  </table>
+</main>
+<footer>
+  Generated by <a href="https://github.com/2ngnhan/certainty-units" target="_blank">certainty-units</a> &mdash; open source
+</footer>
+</body>
+</html>`
+}
+
+export function generateMarkdown(items, projectName = 'Project') {
+  const m = computeCUMetrics(items)
+  const now = new Date().toISOString().slice(0, 10)
+  const sorted = [...items].sort((a, b) => (b.certainty_score ?? 0) - (a.certainty_score ?? 0))
+
+  const rows = sorted.slice(0, 30).map(i => {
+    const score = i.certainty_score ?? 0
+    const level = certaintyLevel(score)
+    return `| ${i.external_id} | ${i.title.slice(0, 50)} | ${i.workflow_status} | ${score} | ${level} |`
+  })
+
+  const risky = items
+    .filter(i => i.workflow_status !== 'done' && (i.certainty_score ?? 0) < 50)
+    .sort((a, b) => (a.certainty_score ?? 0) - (b.certainty_score ?? 0))
+    .slice(0, 5)
+  const attention = risky.map(i => {
+    const gaps = biggestGaps(i, i.citation_count ?? 0).map(g => `${g.hint} (+${g.gap})`).join(' · ')
+    return `- **${i.certainty_score ?? 0}%** [${i.external_id}](${i.url || '#'}) ${i.title.slice(0, 60)}\n  ${gaps}`
+  })
+
+  return `# Certainty Units Report — ${projectName}
+_${now}_
+${attention.length ? `\n## Needs attention\n\n${attention.join('\n')}\n` : ''}
+## Summary
+
+| Metric | Value |
+|--------|-------|
+| Total items | ${m.totalItems} |
+| Avg certainty | ${m.avgCertaintyScore}% |
+| Completion rate | ${m.completionRate}% |
+| Integrity score | ${m.integrityScore}% |
+| Uphill (discovery) | ${m.uphill} |
+| Downhill (execution) | ${m.downhill} |
+
+## Items (top 30)
+
+| ID | Title | Status | Score | Level |
+|----|-------|--------|-------|-------|
+${rows.join('\n')}
+
+---
+Generated by [certainty-units](https://github.com/2ngnhan/certainty-units)
+`
+}