@rarusoft/dendrite-wiki 0.1.0-alpha.0

package/dist/chart-insert.js

@@ -0,0 +1,377 @@
+/**
+ * Chart insertion + validation module — M2 of the AI-mermaid-charts roadmap.
+ *
+ * Single source of truth for adding/updating Mermaid diagrams in wiki pages.
+ * Both insertion paths converge here:
+ *   - Operator-side: the editor's Insert Chart wizard (M5) calls
+ *     `insertChartIntoPage` via the embedded review-bridge endpoint.
+ *   - Agent-side: the `wiki_insert_chart` MCP tool (M3) calls the same
+ *     function directly. Same validation, same anchoring, same write path.
+ *
+ * Design contracts:
+ *   - VALIDATE first. Both paths parse `mermaidSource` with `mermaid.parse`
+ *     before any disk write. If the source is malformed, the call fails with
+ *     a structured error. Never silently corrupt a page.
+ *   - ANCHOR by heading, not by line number. Line numbers shift with any
+ *     edit; headings are stable identifiers. `after-heading` / `before-heading`
+ *     find the matching `## ...` line, then anchor relative to its section
+ *     boundary (next sibling heading at the same or higher level).
+ *   - IDEMPOTENT via stable chart-id markers. Each inserted chart is
+ *     prefixed by `<!-- chart:<kind>-<hash7> -->` where hash7 is sha256 of
+ *     the mermaid source truncated to 7 hex chars. Calling `insertChartIntoPage`
+ *     twice with identical (slug, source, anchor) is a no-op on the second
+ *     call.
+ *   - WRITE via writeWikiPage so the same lint, cache invalidation,
+ *     project-log entry, and benchmark event side-effects fire as any other
+ *     wiki edit. The benchmark trigger is `wiki_insert_chart` (added to the
+ *     DendriteBenchmarkEventTrigger union when M3 wires the MCP tool).
+ */
+import { createHash } from 'node:crypto';
+import { appendProjectLog, readWikiPage, writeWikiPage } from './store.js';
+const MARKER_PREFIX = 'chart:';
+// Matches the marker comment line we insert before each chart. Captures the
+// chart ID. Single-line; the marker always sits on its own line.
+const MARKER_RE = /^<!--\s*chart:([a-z0-9][a-z0-9-]*)\s*-->\s*$/m;
+// The full chart block: marker line + ```mermaid fence + body + closing fence
+// + optional caption. Captures groups for replacement.
+const CHART_BLOCK_RE = /<!--\s*chart:([a-z0-9][a-z0-9-]*)\s*-->\r?\n```mermaid\r?\n([\s\S]*?)\r?\n```\r?\n?(?:\r?\n\*Figure:\s*([^\n]+)\*\r?\n)?/g;
+// Diagram-type keywords Mermaid recognizes. Match is case-insensitive on the
+// first non-empty line. List kept in sync with current Mermaid docs as of
+// the package version pinned in package.json.
+const DIAGRAM_KEYWORDS = [
+    'flowchart', 'graph',
+    'sequenceDiagram',
+    'stateDiagram-v2', 'stateDiagram',
+    'classDiagram',
+    'erDiagram',
+    'gantt', 'pie', 'journey',
+    'gitGraph',
+    'mindmap', 'timeline',
+    'quadrantChart',
+    'xychart-beta', 'sankey-beta',
+    'c4Context', 'c4Container', 'c4Component', 'c4Dynamic', 'c4',
+    'requirementDiagram',
+    'block-beta',
+    'packet-beta'
+];
+// Arrow-like operators across the diagram types. The check just needs ANY of
+// them present — a chart with zero connections is almost always a truncated
+// LLM output ("flowchart TD" with no body) rather than a deliberate empty
+// diagram. We accept false-negatives on edge cases (e.g., a single-node
+// flowchart) — the cost of a false-negative is the operator regenerating;
+// the cost of accepting truncation is a useless chart in the wiki.
+const CONNECTION_OPERATORS = /-->|---|-\.->|==>|->>|-->>|<<--|--?>|->|<->|~~~|\.\.>|::|<-/;
+export async function validateMermaidSource(source) {
+    const trimmed = source.trim();
+    if (!trimmed) {
+        return { ok: false, error: { message: 'Mermaid source is empty.', source } };
+    }
+    // 1. Defense-in-depth on top of mermaid's `securityLevel: 'strict'`. If
+    // somehow `<script>` or `<iframe>` survives the LLM and our prompt, refuse
+    // to write it to a wiki page. The browser renderer would strip them at
+    // display time but the source would still be on disk.
+    if (/<\s*(script|iframe|object|embed)\b/i.test(trimmed)) {
+        return {
+            ok: false,
+            error: {
+                message: 'Mermaid source contains a forbidden HTML tag (<script>, <iframe>, <object>, <embed>).',
+                source
+            }
+        };
+    }
+    // 2. First-line diagram-type keyword. Catches "LLM returned a prose
+    // paragraph instead of mermaid" — by far the most common failure mode.
+    const firstNonEmpty = trimmed.split(/\r?\n/).find((line) => line.trim().length > 0) ?? '';
+    const matchedKeyword = DIAGRAM_KEYWORDS.find((k) => new RegExp(`^${k.replace('-', '\\-')}\\b`, 'i').test(firstNonEmpty));
+    if (!matchedKeyword) {
+        return {
+            ok: false,
+            error: {
+                message: `Mermaid source must start with a diagram-type keyword (flowchart, sequenceDiagram, stateDiagram, classDiagram, erDiagram, gantt, etc.). Got: ${firstNonEmpty.slice(0, 60)}`,
+                source
+            }
+        };
+    }
+    // 3. Bracket balance — catches truncated output. Counts `[`, `]`, `{`, `}`,
+    // `(`, `)` and requires each opener to match its closer. Strings and code
+    // blocks INSIDE Mermaid source are rare enough that we don't try to skip
+    // their contents — if a legitimate diagram fails this check it's because
+    // it contains a literal unbalanced bracket, which is itself a Mermaid
+    // syntax error.
+    const balance = countBracketBalance(trimmed);
+    if (balance.square !== 0 || balance.curly !== 0 || balance.paren !== 0) {
+        return {
+            ok: false,
+            error: {
+                message: `Mermaid source has unbalanced brackets (square: ${balance.square}, curly: ${balance.curly}, paren: ${balance.paren}). Likely truncated.`,
+                source
+            }
+        };
+    }
+    // 4. Connection check — must have at least one arrow operator UNLESS the
+    // diagram type is one that legitimately has no connections (gantt, pie,
+    // journey, timeline, quadrantChart, xychart, sankey, mindmap, gitGraph).
+    // For flowchart / sequence / state / class / er, no connections almost
+    // certainly means truncated output.
+    const NEEDS_CONNECTIONS = ['flowchart', 'graph', 'sequenceDiagram', 'stateDiagram-v2', 'stateDiagram', 'classDiagram', 'erDiagram'];
+    if (NEEDS_CONNECTIONS.includes(matchedKeyword) && !CONNECTION_OPERATORS.test(trimmed)) {
+        return {
+            ok: false,
+            error: {
+                message: `Mermaid ${matchedKeyword} has no arrow connections. Likely truncated output.`,
+                source
+            }
+        };
+    }
+    return { ok: true, diagramType: keywordToDiagramType(matchedKeyword) };
+}
+function countBracketBalance(source) {
+    let square = 0;
+    let curly = 0;
+    let paren = 0;
+    for (const ch of source) {
+        if (ch === '[')
+            square++;
+        else if (ch === ']')
+            square--;
+        else if (ch === '{')
+            curly++;
+        else if (ch === '}')
+            curly--;
+        else if (ch === '(')
+            paren++;
+        else if (ch === ')')
+            paren--;
+    }
+    return { square, curly, paren };
+}
+function keywordToDiagramType(keyword) {
+    // Normalize the keyword to a stable diagram-type label for downstream
+    // consumers (matches the names mermaid.parse() returns where possible).
+    if (keyword === 'flowchart' || keyword === 'graph')
+        return 'flowchart-v2';
+    if (keyword === 'stateDiagram' || keyword === 'stateDiagram-v2')
+        return 'stateDiagram-v2';
+    return keyword;
+}
+/**
+ * Pure string-transformation core: given the existing page content and the
+ * insertion request, returns the new content + chart ID + noop flag. No
+ * file IO, no logging, no benchmark events. Used by both the file-system
+ * wrapper below AND directly by tests (skips the fixture-cwd dance).
+ */
+export async function computeChartInsertion(existingContent, input) {
+    const validation = await validateMermaidSource(input.mermaidSource);
+    if (!validation.ok) {
+        throw new ChartValidationError(validation.error.message, validation.error.source);
+    }
+    const chartKind = input.chartKind ?? inferChartKindFromDiagramType(validation.diagramType);
+    const chartId = computeChartId(chartKind, input.mermaidSource);
+    // Idempotency: if the same chartId is already in the page, no-op.
+    const existingIdMatch = new RegExp(`<!--\\s*chart:${chartId}\\s*-->`).test(existingContent);
+    if (existingIdMatch) {
+        return { chartId, chartKind, content: existingContent, insertedAt: existingContent.indexOf(`<!-- chart:${chartId}`), noop: true };
+    }
+    const block = renderChartBlock(chartId, input.mermaidSource, input.caption);
+    const { content, insertedAt } = applyAnchor(existingContent, block, input.anchor);
+    return { chartId, chartKind, content, insertedAt, noop: false };
+}
+/**
+ * Pure replacement core. Same shape as computeChartInsertion.
+ */
+export async function computeChartReplacement(existingContent, input) {
+    const validation = await validateMermaidSource(input.newSource);
+    if (!validation.ok) {
+        throw new ChartValidationError(validation.error.message, validation.error.source);
+    }
+    const found = findChartBlockById(existingContent, input.chartId);
+    if (!found) {
+        throw new ChartNotFoundError(`No chart with id "${input.chartId}" in page.`);
+    }
+    const originalKind = parseKindFromChartId(input.chartId);
+    const newChartId = computeChartId(originalKind, input.newSource);
+    if (newChartId === input.chartId) {
+        return { chartId: input.chartId, content: existingContent, insertedAt: found.start, noop: true };
+    }
+    const block = renderChartBlock(newChartId, input.newSource, input.caption);
+    const content = existingContent.slice(0, found.start) + block + existingContent.slice(found.end);
+    return { chartId: newChartId, content, insertedAt: found.start, noop: false };
+}
+/**
+ * File-system wrapper around computeChartInsertion. Reads the page, computes
+ * the new content, writes it back (unless dryRun), and appends a project-log
+ * entry. The MCP tool (M3) and the editor wizard (M5) both call this.
+ */
+export async function insertChartIntoPage(input) {
+    const existing = await readWikiPage(input.slug);
+    const result = await computeChartInsertion(existing, input);
+    if (!result.noop && !input.dryRun) {
+        await writeWikiPage(input.slug, result.content);
+        const author = input.authorTag === 'operator' ? 'in-browser editor' : 'agent';
+        await appendProjectLog(`Inserted ${result.chartKind} chart \`${result.chartId}\` into \`${input.slug}\` via ${author} (chart-insert).`);
+    }
+    return { ok: true, chartId: result.chartId, noop: result.noop, content: result.content, insertedAt: result.insertedAt };
+}
+export async function replaceChartInPage(input) {
+    const existing = await readWikiPage(input.slug);
+    const result = await computeChartReplacement(existing, input);
+    if (!result.noop && !input.dryRun) {
+        await writeWikiPage(input.slug, result.content);
+        const author = input.authorTag === 'operator' ? 'in-browser editor' : 'agent';
+        await appendProjectLog(`Replaced chart \`${input.chartId}\` → \`${result.chartId}\` in \`${input.slug}\` via ${author} (chart-insert).`);
+    }
+    return { ok: true, chartId: result.chartId, noop: result.noop, content: result.content, insertedAt: result.insertedAt };
+}
+// -------------------------- helpers --------------------------------------
+export function computeChartId(kind, source) {
+    const hash = createHash('sha256').update(source.trim()).digest('hex').slice(0, 7);
+    return `auto-${kind}-${hash}`;
+}
+function parseKindFromChartId(chartId) {
+    // chartId is `auto-<kind>-<hash>` — pull the kind from the middle segment.
+    const match = chartId.match(/^auto-([a-z]+)-[0-9a-f]+$/i);
+    const candidate = match?.[1];
+    const valid = ['flowchart', 'sequence', 'state', 'class', 'er', 'gantt', 'diagram'];
+    return candidate && valid.includes(candidate) ? candidate : 'diagram';
+}
+function inferChartKindFromDiagramType(diagramType) {
+    // Mermaid's parse() returns names like 'flowchart-v2', 'sequence', 'stateDiagram', etc.
+    if (/^flowchart/i.test(diagramType) || /^graph/i.test(diagramType))
+        return 'flowchart';
+    if (/^sequence/i.test(diagramType))
+        return 'sequence';
+    if (/^state/i.test(diagramType))
+        return 'state';
+    if (/^class/i.test(diagramType))
+        return 'class';
+    if (/^er/i.test(diagramType))
+        return 'er';
+    if (/^gantt/i.test(diagramType))
+        return 'gantt';
+    return 'diagram';
+}
+function renderChartBlock(chartId, source, caption) {
+    const trimmed = source.trim();
+    const captionLine = caption?.trim() ? `\n*Figure: ${caption.trim()}*\n` : '';
+    return `<!-- chart:${chartId} -->\n\`\`\`mermaid\n${trimmed}\n\`\`\`\n${captionLine}`;
+}
+function findChartBlockById(content, chartId) {
+    CHART_BLOCK_RE.lastIndex = 0;
+    let match;
+    while ((match = CHART_BLOCK_RE.exec(content)) !== null) {
+        if (match[1] === chartId) {
+            return {
+                chartId: match[1],
+                start: match.index,
+                end: match.index + match[0].length,
+                source: match[2],
+                caption: match[3]
+            };
+        }
+    }
+    return null;
+}
+function applyAnchor(content, block, anchor) {
+    const lines = content.split(/\r?\n/);
+    const eol = content.includes('\r\n') ? '\r\n' : '\n';
+    switch (anchor.kind) {
+        case 'after-heading': {
+            const idx = findHeadingLine(lines, anchor.heading);
+            if (idx === -1) {
+                throw new AnchorNotFoundError(`Heading "${anchor.heading}" not found in page.`);
+            }
+            const sectionEnd = findSectionEnd(lines, idx);
+            const insertLineIdx = sectionEnd;
+            return spliceAtLine(lines, insertLineIdx, block, eol);
+        }
+        case 'before-heading': {
+            const idx = findHeadingLine(lines, anchor.heading);
+            if (idx === -1) {
+                throw new AnchorNotFoundError(`Heading "${anchor.heading}" not found in page.`);
+            }
+            return spliceAtLine(lines, idx, block, eol);
+        }
+        case 'end-of-page': {
+            return spliceAtLine(lines, lines.length, block, eol);
+        }
+        case 'after-line': {
+            if (anchor.line < 1 || anchor.line > lines.length) {
+                throw new AnchorNotFoundError(`Line ${anchor.line} is out of range (page has ${lines.length} lines).`);
+            }
+            return spliceAtLine(lines, anchor.line, block, eol);
+        }
+    }
+}
+function findHeadingLine(lines, heading) {
+    const target = heading.trim().toLowerCase();
+    // Match `^#{1,6}\s+<heading>\s*$` case-insensitively. Anchored to the whole
+    // line so we don't false-match a heading mention inside a code block — that
+    // would be a bug worth catching, but for now we accept it as a known
+    // limitation and call it out in the roadmap's open questions.
+    for (let i = 0; i < lines.length; i++) {
+        const match = lines[i].match(/^(#{1,6})\s+(.+?)\s*$/);
+        if (match && match[2].trim().toLowerCase() === target) {
+            return i;
+        }
+    }
+    return -1;
+}
+function headingLevel(line) {
+    const match = line.match(/^(#{1,6})\s/);
+    return match ? match[1].length : 0;
+}
+function findSectionEnd(lines, headingIdx) {
+    // A section ends just before the next heading at the SAME OR HIGHER level
+    // (lower number = higher level). H2's section ends before the next H1 or H2.
+    // Returns the line index where to insert (== first line AFTER the section).
+    const startLevel = headingLevel(lines[headingIdx]);
+    if (startLevel === 0)
+        return lines.length;
+    for (let i = headingIdx + 1; i < lines.length; i++) {
+        const lvl = headingLevel(lines[i]);
+        if (lvl > 0 && lvl <= startLevel) {
+            return i;
+        }
+    }
+    return lines.length;
+}
+function spliceAtLine(lines, lineIdx, block, eol) {
+    const before = lines.slice(0, lineIdx).join(eol);
+    const after = lines.slice(lineIdx).join(eol);
+    // Always sandwich the block with blank lines so it doesn't fuse into
+    // surrounding content (especially next to a heading).
+    const parts = [];
+    if (before.length > 0)
+        parts.push(before);
+    parts.push(''); // blank line separator
+    parts.push(block.trimEnd());
+    parts.push(''); // blank line separator
+    if (after.length > 0)
+        parts.push(after);
+    const content = parts.join(eol);
+    // The block starts just after the leading separator(s). Compute by finding
+    // the marker comment in the new content.
+    const insertedAt = content.indexOf(`<!-- chart:`);
+    return { content, insertedAt };
+}
+// -------------------------- typed errors ---------------------------------
+export class ChartValidationError extends Error {
+    source;
+    constructor(message, source) {
+        super(message);
+        this.name = 'ChartValidationError';
+        this.source = source;
+    }
+}
+export class AnchorNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'AnchorNotFoundError';
+    }
+}
+export class ChartNotFoundError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'ChartNotFoundError';
+    }
+}