@albinocrabs/feynman 0.2.0

package/hooks/feynman-lint.js

@@ -0,0 +1,96 @@
+#!/usr/bin/env node
+// hooks/feynman-lint.js — feynman Stop-hook variant
+// Reads Claude's response from stdin JSON {response, session_id, ...}
+// If lint fails: emit additionalContext with corrections
+// If lint passes: exit 0 silently
+// ALWAYS exits 0 — never block Claude (best practice)
+// Zero deps. CJS only.
+'use strict';
+
+const { lint } = require('../lib/lint');
+
+// Rule descriptions for actionable feedback
+const RULE_DESCRIPTIONS = {
+  L01: 'Box closure: every ┌─...─┐ opening must have a matching └─...─┘ at the same column',
+  L02: 'Tree chars: last child must use └── not ├──',
+  L03: 'Arrow style: use only one arrow style per diagram (-->, →, ─→, or ──>)',
+  L04: 'Column widths: all table rows must have the same number of columns',
+  L05: 'Flow integrity: two [Box] tokens on the same line must have an arrow between them',
+  L06: 'Priority scale: if ▲ appears, ▼ must also appear (and vice versa)',
+  L07: 'Mermaid+ASCII mix: use either Mermaid or ASCII diagrams, not both in the same response',
+  L08: 'Frame width: all rows inside a ┌─ frame must have the same display width',
+};
+
+/**
+ * Build a concise additionalContext message from lint issues
+ * @param {object[]} issues
+ * @returns {string}
+ */
+function buildCorrectionMessage(issues) {
+  if (!issues || issues.length === 0) return '';
+
+  // Group by rule
+  const byRule = new Map();
+  for (const iss of issues) {
+    if (!byRule.has(iss.rule)) byRule.set(iss.rule, []);
+    byRule.get(iss.rule).push(iss);
+  }
+
+  const lines = [
+    'DIAGRAM LINT CORRECTIONS NEEDED:',
+    '',
+  ];
+
+  for (const [rule, ruleIssues] of byRule) {
+    const desc = RULE_DESCRIPTIONS[rule] || rule;
+    lines.push(`[${rule}] ${desc}`);
+    for (const iss of ruleIssues) {
+      lines.push(`  - Line ${iss.line}: ${iss.message}`);
+      if (iss.suggestion) lines.push(`    Fix: ${iss.suggestion}`);
+    }
+    lines.push('');
+  }
+
+  lines.push('Please correct the ASCII diagram(s) above before responding further.');
+
+  return lines.join('\n');
+}
+
+// Accumulate stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const data = JSON.parse(input);
+    const response = data.response || data.message || '';
+
+    if (!response || typeof response !== 'string') {
+      process.exit(0);
+    }
+
+    const result = lint(response);
+
+    if (result.passed) {
+      // No errors — exit 0 silently
+      process.exit(0);
+    }
+
+    // Build correction message
+    const correctionText = buildCorrectionMessage(result.issues);
+
+    // Emit Stop-hook output
+    process.stdout.write(JSON.stringify({
+      hookSpecificOutput: {
+        hookEventName: 'Stop',
+        additionalContext: correctionText
+      }
+    }));
+
+    // Always exit 0 — never block Claude
+    process.exit(0);
+  } catch (e) {
+    // Silent fail — never surface hook errors
+    process.exit(0);
+  }
+});

package/hooks/hooks.json

@@ -0,0 +1,17 @@
+{
+  "description": "Inject feynman ASCII diagram rules before each Claude Code prompt.",
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "FEYNMAN_HOME=\"$HOME/.claude\" node \"${CLAUDE_PLUGIN_ROOT}/hooks/feynman-activate.js\"",
+            "timeout": 5,
+            "statusMessage": "Injecting diagram rules..."
+          }
+        ]
+      }
+    ]
+  }
+}

package/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "PLUGIN_ROOT=\"${PLUGIN_ROOT:-$CLAUDE_PLUGIN_ROOT}\"; FEYNMAN_HOME=\"$HOME/.codex\" node \"$PLUGIN_ROOT/hooks/feynman-activate.js\"",
+            "timeout": 5,
+            "statusMessage": "Injecting diagram rules..."
+          }
+        ]
+      }
+    ]
+  }
+}

package/install.sh

@@ -0,0 +1,18 @@
+#!/usr/bin/env bash
+# feynman install — thin wrapper around bin/feynman.js
+# Usage: bash install.sh [--force]
+set -e
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# Node >= 18 check
+if ! command -v node >/dev/null 2>&1; then
+  echo "Error: node not found. Install Node.js >=18: https://nodejs.org" >&2
+  exit 1
+fi
+NODE_VER=$(node -v 2>/dev/null | sed 's/v//' | cut -d. -f1)
+if [ -z "$NODE_VER" ] || [ "$NODE_VER" -lt 18 ] 2>/dev/null; then
+  echo "Error: Node.js >=18 required (found $(node -v 2>/dev/null || echo 'unknown'))" >&2
+  exit 1
+fi
+
+exec node "$SCRIPT_DIR/bin/feynman.js" install "$@"

package/lib/lint/index.js

@@ -0,0 +1,100 @@
+// lib/lint/index.js — diagram linter orchestrator
+// lint(markdown, options) => {issues, passed}
+// format(issues, mode) => string
+// Zero deps. CJS only.
+'use strict';
+
+const { parse } = require('./parser');
+const rules = require('./rules');
+
+/**
+ * Lint a markdown string for ASCII diagram issues.
+ * @param {string} markdown
+ * @param {{rules?: string[]}} [options] - optional rule filter
+ * @returns {{issues: object[], passed: boolean}}
+ */
+function lint(markdown, options) {
+  if (typeof markdown !== 'string') {
+    return { issues: [], passed: true };
+  }
+
+  const enabledRules = (options && options.rules) || null;
+
+  function isEnabled(ruleId) {
+    if (!enabledRules) return true;
+    return enabledRules.includes(ruleId);
+  }
+
+  const ast = parse(markdown);
+  const allIssues = [];
+
+  // Per-node rules
+  const perNodeRules = [
+    { id: 'L01', fn: rules.L01_box_closure },
+    { id: 'L02', fn: rules.L02_tree_chars },
+    { id: 'L03', fn: rules.L03_arrow_style },
+    { id: 'L04', fn: rules.L04_column_widths },
+    { id: 'L05', fn: rules.L05_flow_integrity },
+    { id: 'L06', fn: rules.L06_priority_scale },
+    { id: 'L08', fn: rules.L08_frame_width },
+  ];
+
+  for (const node of ast) {
+    for (const { id, fn } of perNodeRules) {
+      if (!isEnabled(id)) continue;
+      try {
+        const nodeIssues = fn(node, markdown);
+        if (Array.isArray(nodeIssues)) allIssues.push(...nodeIssues);
+      } catch (e) {
+        // Rule threw — skip silently (never crash linter)
+      }
+    }
+  }
+
+  // Full-text rules (L07 operates once on full markdown, not per-node)
+  if (isEnabled('L07')) {
+    try {
+      const l07Issues = rules.L07_no_mermaid_mix(null, markdown);
+      if (Array.isArray(l07Issues)) allIssues.push(...l07Issues);
+    } catch (e) {
+      // Skip silently
+    }
+  }
+
+  const errorCount = allIssues.filter(i => i.severity === 'error').length;
+  const passed = errorCount === 0;
+
+  return { issues: allIssues, passed };
+}
+
+/**
+ * Format issues for output.
+ * @param {object[]} issues
+ * @param {'gcc'|'json'} mode
+ * @param {string} [filename] - for gcc mode
+ * @param {boolean} [useColor] - ANSI color for TTY
+ * @returns {string}
+ */
+function format(issues, mode, filename, useColor) {
+  if (mode === 'json') {
+    return JSON.stringify(issues, null, 2);
+  }
+
+  // gcc mode: <file>:<line>:<col>: L0X severity message
+  if (!issues || issues.length === 0) return '';
+
+  const RESET  = useColor ? '\x1b[0m'  : '';
+  const RED    = useColor ? '\x1b[31m' : '';
+  const YELLOW = useColor ? '\x1b[33m' : '';
+  const BOLD   = useColor ? '\x1b[1m'  : '';
+
+  const file = filename || '<input>';
+
+  return issues.map(iss => {
+    const color = iss.severity === 'error' ? RED : YELLOW;
+    const sev = iss.severity === 'error' ? 'error' : 'warn';
+    return `${file}:${iss.line}:${iss.column}: ${color}${BOLD}${iss.rule} ${sev}${RESET} ${iss.message}`;
+  }).join('\n');
+}
+
+module.exports = { lint, format };

package/lib/lint/parser.js

@@ -0,0 +1,229 @@
+#!/usr/bin/env node
+// lib/lint/parser.js — ASCII diagram block parser
+// Returns AST: [{type:'diagram', content, startLine, endLine, indent}]
+// Detection: ``` fences (generic only) OR standalone blocks ≥30% diagram chars, ≥3 lines
+// Zero deps. CJS only.
+'use strict';
+
+// Characters that indicate ASCII diagram content
+// Box-drawing: ┌┐└┘─│├┤┬┴┼ Tree: ├── └── Arrows: →←↑↓▲▼
+// Also count: + - | < > brackets used in ASCII art context
+const DIAGRAM_CHARS = new Set([
+  '┌', '┐', '└', '┘', '─', '│', '├', '┤', '┬', '┴', '┼',
+  '→', '←', '↑', '↓', '▲', '▼',
+  '+', '-', '|'
+]);
+
+// Box-drawing Unicode specifically (high-confidence indicators)
+const BOX_DRAWING_CHARS = new Set([
+  '┌', '┐', '└', '┘', '─', '│', '├', '┤', '┬', '┴', '┼',
+  '→', '←', '↑', '↓', '▲', '▼'
+]);
+
+/**
+ * Count diagram chars in a string (non-space chars only for ratio)
+ * @param {string} text
+ * @returns {{diagramCount: number, nonSpaceCount: number, hasBoxDrawing: boolean}}
+ */
+function countDiagramChars(text) {
+  let diagramCount = 0;
+  let nonSpaceCount = 0;
+  let hasBoxDrawing = false;
+
+  for (const ch of text) {
+    if (ch === ' ' || ch === '\t' || ch === '\n' || ch === '\r') continue;
+    nonSpaceCount++;
+    if (DIAGRAM_CHARS.has(ch)) diagramCount++;
+    if (BOX_DRAWING_CHARS.has(ch)) hasBoxDrawing = true;
+  }
+  return { diagramCount, nonSpaceCount, hasBoxDrawing };
+}
+
+/**
+ * Check if a block of text looks like a diagram.
+ * Heuristic: box-drawing Unicode dominant OR structural pattern (flow/tree/table/priority)
+ * Explicitly excludes prose lines where box-chars appear incidentally in sentences.
+ * @param {string[]} lines
+ * @returns {boolean}
+ */
+function looksLikeDiagram(lines) {
+  const text = lines.join('\n');
+  const { nonSpaceCount, hasBoxDrawing } = countDiagramChars(text);
+
+  // Must have minimum content
+  if (nonSpaceCount < 3) return false;
+
+  // If any line looks like natural prose (has word chars AND box chars but ratio is low)
+  // then exclude it from standalone detection.
+  // Prose check: line has alphabetic words AND box chars but < 20% diagram chars overall
+  const isProse = lines.every(line => {
+    const trimmed = line.trim();
+    if (!trimmed) return true;
+    // If the line has natural language (multiple word chars) and any box chars
+    // but the box chars are embedded in prose (not structural)
+    const wordChars = (trimmed.match(/[a-zA-Z]/g) || []).length;
+    const boxChars = [...trimmed].filter(ch => BOX_DRAWING_CHARS.has(ch)).length;
+    // Prose: more letters than box chars by a significant margin
+    if (wordChars > 5 && boxChars > 0 && wordChars > boxChars * 3) return true;
+    return !trimmed; // blank lines are neutral
+  });
+
+  // For standalone blocks (not fenced), require structural indicators
+  // Box-drawing Unicode dominant (≥40% of non-space chars are box-drawing)
+  const boxDrawingCount = [...text].filter(ch => BOX_DRAWING_CHARS.has(ch)).length;
+  const boxRatio = nonSpaceCount > 0 ? boxDrawingCount / nonSpaceCount : 0;
+
+  if (hasBoxDrawing && boxRatio >= 0.15 && !isProse) return true;
+
+  // Check for structural patterns (these override prose check)
+  // Tree structure: lines starting with ├── or └──
+  if (/^[\s│]*[├└]──/m.test(text)) return true;
+
+  // Flow diagram: [Box] connected with arrows
+  if (/\[[^\]]+\]/.test(text) && /-->|→|─→|──>/.test(text)) return true;
+
+  // Priority scale: ▲ or ▼ on their own
+  if (/^[\s]*[▲▼]/m.test(text)) return true;
+
+  // Table: multiple lines starting with |
+  const tableRows = lines.filter(l => /^\s*\|.*\|/.test(l));
+  if (tableRows.length >= 2) return true;
+
+  return false;
+}
+
+/**
+ * Get leading indent (number of spaces) of a line
+ * @param {string} line
+ * @returns {number}
+ */
+function getIndent(line) {
+  let i = 0;
+  while (i < line.length && line[i] === ' ') i++;
+  return i;
+}
+
+/**
+ * Parse markdown string into AST of diagram nodes.
+ * @param {string} markdown
+ * @returns {Array<{type: 'diagram', content: string, startLine: number, endLine: number, indent: number}>}
+ */
+function parse(markdown) {
+  const lines = markdown.split('\n');
+  const nodes = [];
+
+  let i = 0;
+  while (i < lines.length) {
+    const line = lines[i];
+    const trimmed = line.trim();
+
+    // Check for fenced code block: ```
+    const fenceMatch = trimmed.match(/^```(\w*)$/);
+    if (fenceMatch) {
+      const lang = fenceMatch[1].toLowerCase();
+
+      // Skip named language blocks (js, bash, python, mermaid, etc.)
+      // Only process generic ``` fences (empty lang tag)
+      if (lang !== '') {
+        // Advance to closing fence, skip this block
+        i++;
+        while (i < lines.length && lines[i].trim() !== '```') i++;
+        i++; // skip closing ```
+        continue;
+      }
+
+      // Generic fence — collect content
+      const indent = getIndent(line);
+      const blockLines = [];
+      i++; // move past opening fence
+      const startLine = i + 1; // 1-based line number of first content line
+      while (i < lines.length && lines[i].trim() !== '```') {
+        blockLines.push(lines[i]);
+        i++;
+      }
+      const endLine = i + 1; // 1-based (points to closing ```)
+      i++; // skip closing ```
+
+      // Check if it looks like a diagram
+      // Fenced blocks: also accept multiple [Box] tokens (even without arrows)
+      // since those are clearly intended as flow diagrams (L05 will catch missing arrows)
+      const hasFencedBoxPattern = blockLines.some(line => {
+        const boxes = [...line.matchAll(/\[[^\]]+\]/g)];
+        return boxes.length >= 2;
+      });
+      if (blockLines.length >= 1 && (looksLikeDiagram(blockLines) || hasFencedBoxPattern)) {
+        nodes.push({
+          type: 'diagram',
+          content: blockLines.join('\n'),
+          startLine,
+          endLine,
+          indent
+        });
+      }
+      continue;
+    }
+
+    // Standalone block detection: accumulate consecutive non-empty lines
+    // that collectively look like a diagram
+    if (trimmed.length > 0 && !trimmed.startsWith('#') && !trimmed.startsWith('<!--')) {
+      const startLine = i + 1; // 1-based
+      const indent = getIndent(line);
+      const blockLines = [line];
+      let j = i + 1;
+
+      // Extend block: include lines until we hit blank or markdown heading/fence
+      while (j < lines.length) {
+        const nextLine = lines[j];
+        const nextTrimmed = nextLine.trim();
+
+        // Stop at blank lines, headings, or fences
+        if (nextTrimmed === '' || nextTrimmed.startsWith('#') || nextTrimmed.startsWith('```')) break;
+        blockLines.push(nextLine);
+        j++;
+      }
+
+      // Check for structural diagram indicators (order matters — strongest first)
+      const text = blockLines.join('\n');
+      const { hasBoxDrawing } = countDiagramChars(text);
+      const hasBoxToken = /\[[^\]]+\]/.test(text) && /-->|→|─>|──>/.test(text);
+      // Multiple [Box] tokens on one line without natural language between them
+      // (even without arrows — L05 will catch missing arrows)
+      // "Natural language between" means: word chars NOT in brackets between the boxes
+      const hasMultiBox = blockLines.some(l => {
+        const matches = [...l.matchAll(/\[[^\]]+\]/g)];
+        if (matches.length < 2) return false;
+        // Check what's between the first and last box
+        const firstEnd = matches[0].index + matches[0][0].length;
+        const lastStart = matches[matches.length - 1].index;
+        const between = l.slice(firstEnd, lastStart);
+        // If "between" contains regular English words (sequences of alpha), it's prose
+        // Allow: spaces, arrows, punctuation, special chars
+        if (/[a-zA-Z]{3,}/.test(between)) return false; // prose words between boxes
+        return true;
+      });
+      const hasTree = /[├└]──/.test(text);
+      const hasPriority = /^[\s]*[▲▼]/m.test(text);
+      const hasTable = blockLines.filter(l => /^\s*\|.*\|/.test(l)).length >= 2;
+
+      const isDiagram = hasBoxDrawing || hasBoxToken || hasMultiBox || hasTree || hasPriority || hasTable;
+
+      if (isDiagram && (looksLikeDiagram(blockLines) || hasMultiBox || hasTree || hasPriority || hasTable)) {
+        nodes.push({
+          type: 'diagram',
+          content: text,
+          startLine,
+          endLine: j, // 1-based (last line index + 1)
+          indent
+        });
+        i = j;
+        continue;
+      }
+    }
+
+    i++;
+  }
+
+  return nodes;
+}
+
+module.exports = { parse };