@brainwav/diagram 1.0.8 → 1.1.0

package/src/core/analysis-generation-diagrams-core-sequence.js

@@ -0,0 +1,142 @@
+const path = require('path');
+const {
+  escapeMermaid,
+  mapSafeNames,
+  byNameIndex,
+  componentsByRole,
+} = require('./analysis-generation-utils');
+const { limitItems } = require('./analysis-generation-diagrams-limit');
+const { sequenceNote } = require('./analysis-generation-diagrams-empty');
+
+const ROLE_VERB_PRIORITY = [
+  ['auth', 'authenticates via'],
+  ['events', 'emits to'],
+  ['llm', 'calls LLM'],
+  ['tool', 'invokes tool'],
+];
+
+/**
+ * Selects the preferred sequence-message verb for a dependency based on its role tags.
+ * @param {Array<string>} roleTags - Array of role tag identifiers; if not an array it is treated as empty.
+ * @returns {string} The chosen verb (for example `reads from`, `authenticates via`, `emits to`); returns `"calls"` if no role matches.
+ */
+function resolveSequenceVerb(roleTags) {
+  const tags = Array.isArray(roleTags) ? roleTags : [];
+  if (tags.includes('database')) {
+    if (tags.includes('write') || tags.includes('writes')) return 'writes to';
+    return 'queries';
+  }
+  for (const [role, verb] of ROLE_VERB_PRIORITY) {
+    if (tags.includes(role)) return verb;
+  }
+  return 'calls';
+}
+
+/**
+ * Generate a Mermaid sequence diagram for the provided components and their dependencies.
+ *
+ * @param {Object} data - Input model containing components and optional entry points.
+ * @param {Array<Object>} data.components - Array of component objects. Each component is expected to include at least:
+ *   - {string} name - Internal identifier.
+ *   - {string} originalName - Human-visible name.
+ *   - {string} [type] - Component type (e.g. 'service').
+ *   - {Array<string>} [roleTags] - Role tags (e.g. 'user', 'database').
+ *   - {Array<string>} [dependencies] - Names of dependent components.
+ * @param {Array<string>} [data.entryPoints] - Optional list of entry point file paths; basenames are matched against component.originalName to seed the diagram.
+ * @returns {string} The Mermaid sequence diagram text starting with `sequenceDiagram`, or a short note string such as "No data available" or "No services detected". 
+ */
+function generateSequence(data) {
+  if (!data || !Array.isArray(data.components)) {
+    return sequenceNote('No data available');
+  }
+
+  const MAX_PARTICIPANTS = 8;
+  const byName = byNameIndex(data.components);
+  const participantLookup = new Map();
+
+  const entryNames = new Set(
+    (data.entryPoints || []).map((ep) => path.basename(ep, path.extname(ep)))
+  );
+  let roots = data.components.filter((component) => entryNames.has(component.originalName));
+
+  if (roots.length === 0) {
+    roots = limitItems([
+      ...componentsByRole(data.components, 'user'),
+      ...data.components.filter((component) => component.type === 'service'),
+    ], 2);
+  }
+
+  const visited = new Map();
+  const queue = [];
+  for (const root of roots) {
+    if (root && !visited.has(root.name)) {
+      visited.set(root.name, 0);
+      queue.push({ comp: root, depth: 0 });
+    }
+  }
+  let queueIndex = 0;
+  while (queueIndex < queue.length && visited.size < MAX_PARTICIPANTS) {
+    const { comp, depth } = queue[queueIndex++];
+    for (const depName of comp.dependencies || []) {
+      if (visited.has(depName)) continue;
+      if (visited.size >= MAX_PARTICIPANTS) break;
+      const dep = byName.get(depName);
+      if (!dep) continue;
+      visited.set(depName, depth + 1);
+      queue.push({ comp: dep, depth: depth + 1 });
+    }
+  }
+
+  const participants = [...visited.entries()]
+    .sort((a, b) => a[1] - b[1])
+    .map(([name]) => byName.get(name))
+    .filter(Boolean);
+
+  for (const participant of participants) {
+    participantLookup.set(participant.name, participant);
+  }
+
+  if (participants.length === 0) {
+    return sequenceNote('No services detected');
+  }
+
+  const safeMap = mapSafeNames(participants);
+  const lines = ['sequenceDiagram'];
+
+  const participantType = (component) => {
+    const tags = component.roleTags || [];
+    if (tags.includes('user')) return 'actor';
+    if (tags.includes('database') || tags.includes('memory')) return 'database';
+    return 'participant';
+  };
+
+  for (const participant of participants) {
+    const safe = safeMap.get(participant);
+    lines.push(`  ${participantType(participant)} ${safe} as ${escapeMermaid(participant.originalName)}`);
+  }
+
+  lines.push('');
+
+  const emittedEdges = new Set();
+  for (const caller of participants) {
+    const callerSafe = safeMap.get(caller);
+    for (const depName of caller.dependencies || []) {
+      const callee = participantLookup.get(depName);
+      if (!callee) continue;
+      const calleeSafe = safeMap.get(callee);
+      const key = `${callerSafe}->${calleeSafe}`;
+      if (emittedEdges.has(key)) continue;
+      emittedEdges.add(key);
+      const verb = resolveSequenceVerb(callee.roleTags);
+      lines.push(`  ${callerSafe}->>${calleeSafe}: ${verb}`);
+      lines.push(`  ${calleeSafe}-->>${callerSafe}: response`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  generateSequence,
+  resolveSequenceVerb,
+};

package/src/core/analysis-generation-diagrams-core-shapes.js

@@ -0,0 +1,104 @@
+const { escapeMermaid, mapSafeNames } = require('./analysis-generation-utils');
+const { limitItems } = require('./analysis-generation-diagrams-limit');
+const { classNote } = require('./analysis-generation-diagrams-empty');
+
+/**
+ * Build a Mermaid `classDiagram` string from the provided data.
+ *
+ * Filters `data.components` to entries whose `type` is `'class'` or `'component'`, limits the list to 20 items,
+ * emits a class block for each selected component containing its `filePath`, and adds dependency edges for up to
+ * the first 3 dependencies per component only when the dependency name is present among the selected classes.
+ *
+ * @param {Object} data - Input container expected to have a `components` array of component objects.
+ *   Each component should include at least `name`, `type` and `filePath`, and may include `dependencies` (array of names).
+ * @returns {string} A Mermaid `classDiagram` text. If `data` is missing or invalid returns the result of `classNote('No data available')`.
+ *   If no classes are selected the diagram contains a `note "No classes found"`.
+ */
+function generateClass(data) {
+  if (!data || !Array.isArray(data.components)) {
+    return classNote('No data available');
+  }
+
+  const lines = ['classDiagram'];
+  const MAX_CLASSES = 20;
+  const classes = limitItems(
+    data.components.filter((component) => component.type === 'class' || component.type === 'component'),
+    MAX_CLASSES,
+    'Class diagram limited to {limit} classes'
+  );
+  const classNames = new Set(classes.map((component) => component.name));
+  const classByName = new Map(classes.map((component) => [component.name, component]));
+  const classIds = mapSafeNames(classes);
+
+  if (classes.length === 0) {
+    lines.push('  note "No classes found"');
+    return lines.join('\n');
+  }
+
+  for (const component of classes) {
+    const safeId = classIds.get(component);
+    if (!safeId) continue;
+    lines.push(`  class ${safeId} {`);
+    lines.push(`    +${escapeMermaid(component.filePath)}`);
+    lines.push('  }');
+  }
+
+  for (const component of classes) {
+    const deps = (component.dependencies || []).slice(0, 3);
+    for (const depName of deps) {
+      if (classNames.has(depName)) {
+        const from = classIds.get(component);
+        const to = classIds.get(classByName.get(depName));
+        if (!from || !to) continue;
+        lines.push(`  ${from} --> ${to}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build a Mermaid flowchart that chains components sequentially from Start to End.
+ *
+ * If `data` is missing or `data.components` is not an array, a minimal Start → End flow is returned.
+ * The component list is limited to 8 items; if the resulting list is empty the diagram connects Start directly to End.
+ * Each included component becomes a node labelled with its `originalName` and is connected in order, ending with an edge to End.
+ *
+ * @param {Object} data - Object containing a `components` array of component descriptors.
+ * @returns {string} A Mermaid `flowchart TD` diagram as a string.
+ */
+function generateFlow(data) {
+  if (!data || !Array.isArray(data.components)) {
+    return 'flowchart TD\n  Start(["Start"])\n  End(["End"])\n  Start --> End';
+  }
+
+  const lines = ['flowchart TD'];
+  lines.push('  Start(["Start"])');
+  const MAX_COMPONENTS = 8;
+  const comps = limitItems(data.components, MAX_COMPONENTS, 'Flow diagram limited to {limit} components');
+
+  if (comps.length === 0) {
+    lines.push('  End(["End"])');
+    lines.push('  Start --> End');
+    return lines.join('\n');
+  }
+
+  let prev = 'Start';
+  const nodeIds = mapSafeNames(comps);
+  for (const component of comps) {
+    const safeName = nodeIds.get(component);
+    if (!safeName) continue;
+    lines.push(`  ${safeName}["${escapeMermaid(component.originalName)}"]`);
+    lines.push(`  ${prev} --> ${safeName}`);
+    prev = safeName;
+  }
+  lines.push('  End(["End"])');
+  lines.push(`  ${prev} --> End`);
+  return lines.join('\n');
+}
+
+module.exports = {
+  generateClass,
+  generateFlow,
+};

package/src/core/analysis-generation-diagrams-core.js

@@ -0,0 +1,12 @@
+const { generateArchitecture } = require('./analysis-generation-diagrams-core-architecture');
+const { generateSequence } = require('./analysis-generation-diagrams-core-sequence');
+const { generateDependency } = require('./analysis-generation-diagrams-core-dependency');
+const { generateClass, generateFlow } = require('./analysis-generation-diagrams-core-shapes');
+
+module.exports = {
+  generateArchitecture,
+  generateSequence,
+  generateDependency,
+  generateClass,
+  generateFlow,
+};

package/src/core/analysis-generation-diagrams-empty.js

@@ -0,0 +1,68 @@
+const { escapeMermaid } = require('./analysis-generation-utils-core');
+
+/**
+ * Create a Mermaid Note node string containing the given message.
+ * @param {string} message - The text to include inside the note node.
+ * @returns {string} The Mermaid fragment in the form `  Note["<message>"]`.
+ */
+function noteNode(message) {
+  return `  Note["${escapeMermaid(message)}"]`;
+}
+
+/**
+ * Create a Mermaid `graph` fragment containing a single note node.
+ * @param {string} message - Text to place inside the note node.
+ * @param {string} [direction='TD'] - Graph layout direction (for example `'TD'` for top-down or `'LR'` for left-right).
+ * @returns {string} A Mermaid `graph` block containing the note node with the provided message.
+ */
+function graphNote(message, direction = 'TD') {
+  return `graph ${direction}\n${noteNode(message)}`;
+}
+
+/**
+ * Construct a Mermaid flowchart snippet that contains a single note.
+ *
+ * @param {string} message - Text to place inside the note.
+ * @param {string} [direction='TD'] - Flow direction for the chart (commonly 'TD' for top-down, 'LR' for left-right, etc.).
+ * @returns {string} A Mermaid `flowchart` fragment starting with `flowchart <direction>` followed by a note node containing the provided message.
+ */
+function flowNote(message, direction = 'TD') {
+  return `flowchart ${direction}\n${noteNode(message)}`;
+}
+
+/**
+ * Build a Mermaid sequenceDiagram fragment containing a note positioned over User and App.
+ * @param {string} message - Text to place inside the note.
+ * @returns {string} A `sequenceDiagram` snippet with a `Note over User,App` containing the provided message.
+ */
+function sequenceNote(message) {
+  return `sequenceDiagram\n  Note over User,App: ${escapeMermaid(message)}`;
+}
+
+/**
+ * Create a Mermaid classDiagram fragment containing a note with the provided message.
+ * @param {string} message - The note text to include inside the class diagram.
+ * @returns {string} The Mermaid `classDiagram` snippet that contains the note with the provided message.
+ */
+function classNote(message) {
+  return `classDiagram\n  note "${escapeMermaid(message)}"`;
+}
+
+/**
+ * Create a Mermaid `architecture-beta` snippet that attaches a service note to the `server`.
+ *
+ * @param {string} message - The note text to place inside the service note for the `server`.
+ * @returns {string} The Mermaid diagram fragment `architecture-beta\n    service note(server)[<message>]`.
+ */
+function architectureNote(message) {
+  return `architecture-beta\n    service note(server)[${escapeMermaid(message)}]`;
+}
+
+module.exports = {
+  noteNode,
+  graphNote,
+  flowNote,
+  sequenceNote,
+  classNote,
+  architectureNote,
+};

package/src/core/analysis-generation-diagrams-erd.js

@@ -0,0 +1,59 @@
+const { extractErdModel } = require('../schema/erd-extractor');
+const { evaluateErdConfidence } = require('../schema/erd-confidence');
+const { renderErdMermaid } = require('../schema/erd-model');
+
+function commentLine(text) {
+  return `  %% ${String(text || '').replace(/\r?\n/g, ' ').trim()}`;
+}
+
+function insertErdComments(mermaid, comments) {
+  const lines = String(mermaid || 'erDiagram').split(/\r?\n/);
+  const [header, ...rest] = lines;
+  return [
+    header || 'erDiagram',
+    ...comments.filter(Boolean).map(commentLine),
+    ...rest,
+  ].join('\n');
+}
+
+function buildErdMetadata(extraction, confidence) {
+  return {
+    purpose: 'schema_entity_relationships',
+    consumers: ['human', 'agent', 'ci'],
+    source: 'schema_extraction',
+    extractionInvoked: Boolean(extraction?.extractionInvoked),
+    terminalClass: extraction?.terminalClass || 'unknown',
+    schemaSources: Array.isArray(extraction?.sourceFiles) ? extraction.sourceFiles : [],
+    sourcePrecedence: Array.isArray(extraction?.sourcePrecedence) ? extraction.sourcePrecedence : [],
+    compactEligible: !confidence.shouldFail,
+    confidence,
+  };
+}
+
+function generateErdArtifact(data) {
+  const extraction = extractErdModel({
+    rootPath: data?.rootPath,
+    ignore: Array.isArray(data?.exclude) ? data.exclude : [],
+  });
+  const confidence = evaluateErdConfidence(extraction.model);
+  const mermaid = renderErdMermaid(extraction.model, {
+    lowConfidenceMarker: confidence.markerRequired,
+    inferenceShare: confidence.counts?.inferenceShare,
+  });
+  const comments = [
+    `erd extraction: ${extraction.terminalClass}`,
+    extraction.sourceFiles.length > 0
+      ? `schema sources: ${extraction.sourceFiles.join(', ')}`
+      : 'schema sources: none',
+    ...((extraction.diagnostics || []).slice(0, 3)),
+  ];
+
+  return {
+    mermaid: insertErdComments(mermaid, comments),
+    metadata: buildErdMetadata(extraction, confidence),
+  };
+}
+
+module.exports = {
+  generateErdArtifact,
+};

package/src/core/analysis-generation-diagrams-limit.js

@@ -0,0 +1,27 @@
+const chalk = require('chalk');
+
+/**
+ * Limit an input list to the first `limit` elements, optionally emitting a formatted warning when items were truncated.
+ *
+ * @param {*} items - The value to be treated as an array; if not an array it is treated as an empty list.
+ * @param {number} limit - Maximum number of items to keep.
+ * @param {string|null} [warningTemplate=null] - Optional template for a warning message; if a string and the original array length exceeds `limit` the function logs this template with `{limit}` replaced by the limit.
+ * @returns {Array} The original items truncated to at most `limit` elements (or an empty array if `items` was not an array).
+ */
+function limitItems(items, limit, warningTemplate = null) {
+  const list = Array.isArray(items) ? items : [];
+  const parsedLimit = Number(limit);
+  const safeLimit = Number.isFinite(parsedLimit) ? Math.max(0, Math.trunc(parsedLimit)) : list.length;
+  const capped = list.slice(0, safeLimit);
+
+  if (typeof warningTemplate === 'string' && list.length > safeLimit) {
+    const warning = warningTemplate.replace('{limit}', String(safeLimit));
+    console.warn(chalk.yellow(`⚠️  ${warning}`));
+  }
+
+  return capped;
+}
+
+module.exports = {
+  limitItems,
+};

package/src/core/analysis-generation-diagrams-role-ai-agent.js

@@ -0,0 +1,103 @@
+const {
+  escapeMermaid,
+  componentsByRole,
+  mergeRoleComponents,
+  mapSafeNames,
+  byNameIndex,
+  appendDependencyEdges,
+} = require('./analysis-generation-utils');
+const { flowNote, noteNode } = require('./analysis-generation-diagrams-empty');
+const {
+  safeNodeIds,
+  emitRoleClassStyle,
+  emitSubgraphSpecs,
+} = require('./analysis-generation-diagrams-role-helpers');
+
+/**
+ * Build a Mermaid flowchart string visualising agents, tools, memories and LLMs as layered subgraphs with dependency edges and per-role styling.
+ *
+ * @param {Object} data - Input container.
+ * @param {Array} data.components - Array of component descriptors (roles like `agent`, `tool`, `memory`, `llm`, etc.) used to populate layers and edges.
+ * @returns {string} A Mermaid `flowchart TD` diagram string. If `data` is missing or contains no relevant components, the diagram contains a note indicating no data is available.
+ */
+function generateAgent(data) {
+  if (!data || !Array.isArray(data.components)) {
+    return flowNote('No data available');
+  }
+
+  const lines = ['flowchart TD'];
+
+  const agents = componentsByRole(data.components, 'agent');
+  const tools = componentsByRole(data.components, 'tool');
+  const memories = componentsByRole(data.components, 'memory');
+  const llms = componentsByRole(data.components, 'llm');
+
+  const all = mergeRoleComponents(data.components, [
+    'agent',
+    'tool',
+    'memory',
+    'llm',
+    { role: 'user', limit: 2 },
+  ]);
+  if (all.length === 0) {
+    lines.push(noteNode('No agent/LLM components found — add agent, tool, memory, or llm patterns'));
+    return lines.join('\n');
+  }
+
+  const safeNames = mapSafeNames(all);
+  const byName = byNameIndex(all);
+
+  const layerSpecs = [
+    {
+      id: 'Orchestration',
+      title: '🎯 Orchestration Layer',
+      components: agents,
+      renderNode: (component, safe) => `${safe}["🤖 ${escapeMermaid(component.originalName)}"]`,
+    },
+    {
+      id: 'LLMLayer',
+      title: '🧠 LLM / Model Layer',
+      components: llms,
+      renderNode: (component, safe) => `${safe}["💡 ${escapeMermaid(component.originalName)}"]`,
+    },
+    {
+      id: 'ToolLayer',
+      title: '🔧 Tool Layer',
+      components: tools,
+      renderNode: (component, safe) => `${safe}["🔧 ${escapeMermaid(component.originalName)}"]`,
+    },
+    {
+      id: 'MemoryLayer',
+      title: '📚 Memory / Vector Layer',
+      components: memories,
+      renderNode: (component, safe) => `${safe}[("📚 ${escapeMermaid(component.originalName)}")]`,
+    },
+  ];
+  emitSubgraphSpecs(lines, layerSpecs, safeNames);
+
+  const edges = new Set();
+  appendDependencyEdges(lines, all, byName, safeNames, edges, (_caller, callee) => {
+    const tags = callee.roleTags || [];
+    if (tags.includes('tool')) return 'invokes';
+    if (tags.includes('memory')) return 'retrieves from';
+    if (tags.includes('llm')) return 'calls LLM';
+    if (tags.includes('agent')) return 'delegates to';
+    return 'uses';
+  });
+
+  const classSpecs = [
+    { className: 'agentNode', roleKey: 'agent', components: agents },
+    { className: 'llmNode', roleKey: 'llm', components: llms },
+    { className: 'toolNode', roleKey: 'tool', components: tools },
+    { className: 'memNode', roleKey: 'memory', components: memories },
+  ];
+  for (const spec of classSpecs) {
+    emitRoleClassStyle(lines, spec.className, spec.roleKey, safeNodeIds(spec.components, safeNames));
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  generateAgent,
+};