@henryavila/mdprobe 0.1.0

package/src/export.js

@@ -0,0 +1,211 @@
+/**
+ * Export functions for annotation files.
+ *
+ * Each function accepts a duck-typed annotationFile object (or the real
+ * AnnotationFile class) -- anything with `.source`, `.sourceHash`, `.version`,
+ * `.annotations`, `.sections`, and `.toJSON()`.
+ */
+
+// ---------------------------------------------------------------------------
+// SARIF severity mapping
+// ---------------------------------------------------------------------------
+
+const LEVEL_MAP = {
+  bug: 'error',
+  question: 'note',
+  suggestion: 'warning',
+  nitpick: 'note',
+}
+
+// ---------------------------------------------------------------------------
+// exportReport
+// ---------------------------------------------------------------------------
+
+/**
+ * Generates a human-readable markdown review report.
+ *
+ * @param {object} af - AnnotationFile (or duck-typed equivalent)
+ * @param {string} _sourceContent - Original markdown (unused but kept for API symmetry)
+ * @returns {string} Markdown report
+ */
+export function exportReport(af, _sourceContent) {
+  const annotations = af.annotations ?? []
+
+  if (annotations.length === 0) {
+    return `# Review Report: ${af.source}\n\nNo annotations found.\n`
+  }
+
+  const openCount = annotations.filter(a => a.status === 'open').length
+  const resolvedCount = annotations.filter(a => a.status === 'resolved').length
+  const total = annotations.length
+
+  const lines = []
+
+  // Title
+  lines.push(`# Review Report: ${af.source}`)
+  lines.push('')
+
+  // Summary
+  lines.push('## Summary')
+  lines.push('')
+  lines.push(`- **Total annotations:** ${total}`)
+  lines.push(`- **Open:** ${openCount}`)
+  lines.push(`- **Resolved:** ${resolvedCount}`)
+  lines.push('')
+
+  // Sections table
+  const sections = af.sections ?? []
+  if (sections.length > 0) {
+    lines.push('## Sections')
+    lines.push('')
+    lines.push('| Section | Status |')
+    lines.push('|---------|--------|')
+    for (const sec of sections) {
+      lines.push(`| ${sec.heading} | ${sec.status} |`)
+    }
+    lines.push('')
+  }
+
+  // Annotations detail
+  lines.push('## Annotations')
+  lines.push('')
+
+  for (const ann of annotations) {
+    lines.push(`### [${ann.tag}] ${ann.quote?.exact ?? ann.selectors?.quote?.exact ?? ''} (${ann.status})`)
+    lines.push('')
+    lines.push(`> ${ann.selectors?.quote?.exact ?? ''}`)
+    lines.push('')
+    lines.push(`**Comment:** ${ann.comment}`)
+    lines.push(`**Author:** ${ann.author} | **Status:** ${ann.status}`)
+    lines.push('')
+
+    if (ann.replies && ann.replies.length > 0) {
+      lines.push('**Replies:**')
+      for (const reply of ann.replies) {
+        lines.push(`- **${reply.author}:** ${reply.comment}`)
+      }
+      lines.push('')
+    }
+
+    lines.push('---')
+    lines.push('')
+  }
+
+  return lines.join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// exportInline
+// ---------------------------------------------------------------------------
+
+/**
+ * Inserts annotations as HTML comments into the original markdown source.
+ *
+ * @param {object} af - AnnotationFile (or duck-typed equivalent)
+ * @param {string} sourceContent - Original markdown text
+ * @returns {string} Markdown with inline annotation comments
+ */
+export function exportInline(af, sourceContent) {
+  const annotations = af.annotations ?? []
+
+  if (annotations.length === 0) {
+    return sourceContent
+  }
+
+  const sourceLines = sourceContent.split('\n')
+
+  // Sort annotations by startLine descending so that insertions don't shift
+  // line indices of subsequent annotations.
+  const sorted = [...annotations].sort((a, b) => {
+    const lineA = a.selectors?.position?.startLine ?? 0
+    const lineB = b.selectors?.position?.startLine ?? 0
+    return lineB - lineA
+  })
+
+  for (const ann of sorted) {
+    const startLine = ann.selectors?.position?.startLine
+    if (startLine == null) continue
+
+    // Build the comment line
+    const prefix = ann.status === 'resolved' ? '[RESOLVED] ' : ''
+    const comment = `<!-- ${prefix}[${ann.tag}] ${ann.comment} -->`
+
+    // Insert after the annotated line (startLine is 1-based)
+    const insertIdx = startLine // after line at (startLine - 1), which is index startLine
+    sourceLines.splice(insertIdx, 0, comment)
+  }
+
+  return sourceLines.join('\n')
+}
+
+// ---------------------------------------------------------------------------
+// exportJSON
+// ---------------------------------------------------------------------------
+
+/**
+ * Returns the annotationFile's JSON representation.
+ *
+ * @param {object} af - AnnotationFile (or duck-typed equivalent)
+ * @returns {object} Plain JSON-serializable object
+ */
+export function exportJSON(af) {
+  return af.toJSON()
+}
+
+// ---------------------------------------------------------------------------
+// exportSARIF
+// ---------------------------------------------------------------------------
+
+/**
+ * Generates a SARIF 2.1.0 report from annotations.
+ *
+ * Resolved annotations are excluded from results.
+ *
+ * @param {object} af - AnnotationFile (or duck-typed equivalent)
+ * @param {string} sourceFilePath - Path to the source file (used in artifact URIs)
+ * @returns {object} SARIF 2.1.0 object
+ */
+export function exportSARIF(af, sourceFilePath) {
+  const annotations = af.annotations ?? []
+
+  // Only include open annotations; resolved are excluded.
+  const openAnnotations = annotations.filter(a => a.status === 'open')
+
+  return {
+    $schema:
+      'https://raw.githubusercontent.com/oasis-tcs/sarif-spec/main/sarif-2.1/schema/sarif-schema-2.1.0.json',
+    version: '2.1.0',
+    runs: [
+      {
+        tool: {
+          driver: {
+            name: 'mdprobe',
+            version: '0.1.0',
+            informationUri: 'https://github.com/henryavila/mdprobe',
+          },
+        },
+        results: openAnnotations.map(ann => {
+          const pos = ann.selectors?.position ?? {}
+          return {
+            ruleId: ann.tag,
+            level: LEVEL_MAP[ann.tag] ?? 'note',
+            message: { text: ann.comment },
+            locations: [
+              {
+                physicalLocation: {
+                  artifactLocation: { uri: sourceFilePath },
+                  region: {
+                    startLine: pos.startLine,
+                    startColumn: pos.startColumn,
+                    endLine: pos.endLine,
+                    endColumn: pos.endColumn,
+                  },
+                },
+              },
+            ],
+          }
+        }),
+      },
+    ],
+  }
+}

package/src/handler.js

@@ -0,0 +1,229 @@
+import { readFile } from 'node:fs/promises'
+import { render } from './renderer.js'
+
+// ---------------------------------------------------------------------------
+// Embedded CSS for the review UI
+// ---------------------------------------------------------------------------
+const EMBEDDED_CSS = `
+  body { font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif; max-width: 900px; margin: 0 auto; padding: 2rem; line-height: 1.6; color: #24292f; }
+  h1, h2, h3 { border-bottom: 1px solid #d0d7de; padding-bottom: .3em; }
+  pre { background: #f6f8fa; padding: 1rem; border-radius: 6px; overflow-x: auto; }
+  code { font-size: 0.9em; }
+  table { border-collapse: collapse; width: 100%; }
+  th, td { border: 1px solid #d0d7de; padding: .5rem; text-align: left; }
+  a { color: #0969da; text-decoration: none; }
+  a:hover { text-decoration: underline; }
+  ul.file-list { list-style: none; padding: 0; }
+  ul.file-list li { padding: .5rem 0; border-bottom: 1px solid #eee; }
+`
+
+// ---------------------------------------------------------------------------
+// Helper: wrap rendered HTML in a full page shell
+// ---------------------------------------------------------------------------
+function htmlPage(title, bodyHtml) {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
+<title>${escapeHtml(title)}</title>
+<style>${EMBEDDED_CSS}</style>
+</head>
+<body>
+${bodyHtml}
+</body>
+</html>`
+}
+
+function escapeHtml(str) {
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+}
+
+// ---------------------------------------------------------------------------
+// Helper: collect POST body
+// ---------------------------------------------------------------------------
+function collectBody(req) {
+  return new Promise((resolve, reject) => {
+    const chunks = []
+    req.on('data', (chunk) => chunks.push(chunk))
+    req.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')))
+    req.on('error', reject)
+  })
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Creates an HTTP request handler for the mdprobe review UI.
+ *
+ * @param {object} options
+ * @param {function} [options.resolveFile] - (req) => string  Resolves a file path from the request
+ * @param {function} [options.listFiles]   - () => Array<{id, path, label}>  Lists available files
+ * @param {string}   [options.basePath='/'] - URL prefix the handler owns
+ * @param {string}   [options.author]      - Default author name
+ * @param {function} [options.onComplete]  - Callback receiving {file, annotations, open, resolved}
+ * @returns {function(req, res): void}
+ */
+export function createHandler(options = {}) {
+  const {
+    resolveFile,
+    listFiles,
+    basePath = '/',
+    author,
+    onComplete,
+  } = options
+
+  // Normalise basePath: remove trailing slash (unless it IS just '/')
+  const base = basePath === '/' ? '' : basePath.replace(/\/+$/, '')
+
+  return function handler(req, res) {
+    // Parse the URL
+    const url = new URL(req.url, `http://${req.headers.host || 'localhost'}`)
+    const pathname = url.pathname
+
+    // ----- basePath guard -----
+    // If basePath is '/' (base === ''), everything matches.
+    // Otherwise, pathname must equal base or start with base + '/'.
+    if (base !== '') {
+      if (pathname !== base && !pathname.startsWith(base + '/')) {
+        res.writeHead(404, { 'Content-Type': 'text/plain' })
+        res.end('Not Found')
+        return
+      }
+    }
+
+    // Sub-path relative to basePath
+    let subPath
+    if (base === '') {
+      subPath = pathname
+    } else {
+      subPath = pathname.slice(base.length) || '/'
+    }
+
+    // Ensure subPath starts with '/'
+    if (!subPath.startsWith('/')) {
+      subPath = '/' + subPath
+    }
+
+    // ----- Route: static assets -----
+    if (subPath === '/assets/style.css' && req.method === 'GET') {
+      res.writeHead(200, { 'Content-Type': 'text/css' })
+      res.end(EMBEDDED_CSS)
+      return
+    }
+
+    // ----- Route: GET /api/files -----
+    if (subPath === '/api/files' && req.method === 'GET') {
+      if (listFiles) {
+        const files = listFiles()
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify(files))
+      } else {
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end('[]')
+      }
+      return
+    }
+
+    // ----- Route: GET /api/annotations -----
+    if (subPath === '/api/annotations' && req.method === 'GET') {
+      res.writeHead(200, { 'Content-Type': 'application/json' })
+      res.end('[]')
+      return
+    }
+
+    // ----- Route: POST /api/complete -----
+    if (subPath === '/api/complete' && req.method === 'POST') {
+      collectBody(req).then((bodyStr) => {
+        let data
+        try {
+          data = bodyStr ? JSON.parse(bodyStr) : {}
+        } catch {
+          data = {}
+        }
+
+        if (onComplete) {
+          const result = {
+            file: typeof data.file === 'string' ? data.file : '',
+            annotations: typeof data.annotations === 'number' ? data.annotations : 0,
+            open: typeof data.open === 'number' ? data.open : 0,
+            resolved: typeof data.resolved === 'number' ? data.resolved : 0,
+          }
+          onComplete(result)
+        }
+
+        res.writeHead(200, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ ok: true }))
+      }).catch(() => {
+        res.writeHead(400, { 'Content-Type': 'application/json' })
+        res.end(JSON.stringify({ error: 'Bad request' }))
+      })
+      return
+    }
+
+    // ----- Route: GET / (root) -----
+    if (subPath === '/' && req.method === 'GET') {
+      if (listFiles) {
+        // File picker mode
+        const files = listFiles()
+        const listHtml = files.map((f) => {
+          const href = (base || '') + '/' + f.id
+          const label = f.label || f.path || f.id
+          return `<li><a href="${escapeHtml(href)}">${escapeHtml(label)}</a></li>`
+        }).join('\n')
+
+        const body = htmlPage('mdprobe - Files', `<h1>Files</h1>\n<ul class="file-list">\n${listHtml}\n</ul>`)
+        res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+        res.end(body)
+        return
+      }
+
+      // Single-file mode via resolveFile
+      if (resolveFile) {
+        const filePath = resolveFile(req)
+        readFile(filePath, 'utf-8').then((content) => {
+          const { html } = render(content)
+          const body = htmlPage('mdprobe', html)
+          res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+          res.end(body)
+        }).catch(() => {
+          res.writeHead(404, { 'Content-Type': 'text/plain' })
+          res.end('File not found')
+        })
+        return
+      }
+
+      // Nothing configured
+      res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+      res.end(htmlPage('mdprobe', '<p>No files configured.</p>'))
+      return
+    }
+
+    // ----- Route: GET /<anything> ---- resolve file by id/path -----
+    if (req.method === 'GET' && !subPath.startsWith('/api/') && !subPath.startsWith('/assets/')) {
+      if (resolveFile) {
+        const filePath = resolveFile(req)
+        readFile(filePath, 'utf-8').then((content) => {
+          const { html } = render(content)
+          const body = htmlPage('mdprobe', html)
+          res.writeHead(200, { 'Content-Type': 'text/html; charset=utf-8' })
+          res.end(body)
+        }).catch(() => {
+          res.writeHead(404, { 'Content-Type': 'text/plain' })
+          res.end('File not found')
+        })
+        return
+      }
+    }
+
+    // ----- 404 fallback -----
+    res.writeHead(404, { 'Content-Type': 'text/plain' })
+    res.end('Not Found')
+  }
+}

package/src/hash.js

@@ -0,0 +1,51 @@
+import { createHash } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
+import yaml from 'js-yaml'
+
+/**
+ * Compute SHA-256 hex digest of a string.
+ * @param {string} str
+ * @returns {string} 64-char lowercase hex hash
+ */
+export function hashContent(str) {
+  return createHash('sha256').update(str, 'utf8').digest('hex')
+}
+
+/**
+ * Read a file as UTF-8 and return its SHA-256 hex digest.
+ * @param {string} filePath
+ * @returns {Promise<string>}
+ */
+export async function hashFile(filePath) {
+  const content = await readFile(filePath, 'utf8')
+  return hashContent(content)
+}
+
+/**
+ * Detect whether the markdown source has drifted from the hash
+ * stored in its YAML sidecar annotation file.
+ *
+ * @param {string} yamlPath - path to the YAML annotation sidecar
+ * @param {string} mdPath   - path to the markdown source file
+ * @returns {Promise<{drifted: boolean, savedHash: string|null, currentHash: string}>}
+ */
+export async function detectDrift(yamlPath, mdPath) {
+  const [yamlRaw, mdRaw] = await Promise.all([
+    readFile(yamlPath, 'utf8'),
+    readFile(mdPath, 'utf8'),
+  ])
+
+  const doc = yaml.load(yamlRaw)
+  const currentHash = hashContent(mdRaw)
+
+  let savedHash = null
+  if (doc && typeof doc.source_hash === 'string' && doc.source_hash.startsWith('sha256:')) {
+    savedHash = doc.source_hash.slice('sha256:'.length)
+  }
+
+  return {
+    drifted: savedHash !== currentHash,
+    savedHash,
+    currentHash,
+  }
+}