@brainwav/diagram 1.0.7 → 1.1.0

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

@@ -0,0 +1,186 @@
+const path = require('path');
+const {
+  escapeMermaid,
+  componentsByRole,
+  mapSafeNames,
+} = require('./analysis-generation-utils');
+const { collectExternalImports } = require('./analysis-generation-role-tags');
+const { graphNote, flowNote } = require('./analysis-generation-diagrams-empty');
+const {
+  emitRoleClassStyle,
+  emitSubgraph,
+} = require('./analysis-generation-diagrams-role-helpers');
+
+const EXTERNAL_CATEGORY_RULES = Object.freeze([
+  { category: 'payment', pattern: /stripe|pay|billing|invoice/ },
+  { category: 'email', pattern: /sendgrid|mail|email|smtp|postmark/ },
+  { category: 'database', pattern: /postgres|pg|mysql|sqlite|mongo|redis|dynamo|prisma|typeorm|sequelize/ },
+  { category: 'ai', pattern: /openai|anthropic|gemini|ollama|hugging/ },
+  { category: 'vcs', pattern: /github|gitlab|bitbucket|octokit/ },
+  { category: 'messaging', pattern: /slack|discord|teams|twilio/ },
+  { category: 'cloud', pattern: /s3|gcs|azure|cloudflare|vercel|supabase/ },
+]);
+
+const CATEGORY_LABELS = Object.freeze({
+  payment: 'Payment Provider',
+  email: 'Email Service',
+  database: 'Database',
+  ai: 'AI / LLM Provider',
+  vcs: 'Version Control',
+  messaging: 'Messaging Service',
+  cloud: 'Cloud Provider',
+  external: 'External Service',
+});
+
+/**
+ * Determine the classification category for an external package identifier.
+ *
+ * @param {string} pkg - Package or import identifier to classify (may be falsy).
+ * @returns {string} The matched category key from EXTERNAL_CATEGORY_RULES, or `'external'` when no rule matches.
+ */
+function classifyExternalPackage(pkg) {
+  const candidate = String(pkg || '').toLowerCase();
+  for (const rule of EXTERNAL_CATEGORY_RULES) {
+    if (rule.pattern.test(candidate)) return rule.category;
+  }
+  return 'external';
+}
+
+/**
+ * Builds a C4 Context Mermaid diagram for the project and its detected external systems.
+ *
+ * Iterates components' imports to classify and group external packages, emits a main
+ * System node with a Developer person and "Uses" relationship, and adds one external
+ * System_Ext node per detected category (listing up to three package names). If no
+ * externals are found a placeholder External Systems node is emitted.
+ *
+ * @param {Object} data - Analysis payload.
+ * @param {string} [data.rootPath] - Project root path used to derive the diagram title.
+ * @param {Array<Object>} data.components - Component descriptors; each may include an `imports` array of package strings.
+ * @returns {string} The Mermaid C4Context diagram markup. If `data` is missing or `components` is not an array, returns a short note indicating no data is available.
+ */
+function generateC4Context(data) {
+  if (!data || !Array.isArray(data.components)) {
+    return graphNote('No data available');
+  }
+
+  const projectName = path.basename(data.rootPath || 'System').replace(/[-_]/g, ' ');
+  const lines = ['C4Context', `  title "System Context — ${escapeMermaid(projectName)}"`];
+
+  lines.push(`  System(mainSystem, "${escapeMermaid(projectName)}", "The system being documented")`);
+  lines.push('  Person(developer, "Developer / User", "Uses the system")');
+  lines.push('  Rel(developer, mainSystem, "Uses")');
+
+  const externalByRole = new Map();
+  for (const component of data.components) {
+    for (const pkg of collectExternalImports(component.imports || [])) {
+      const category = classifyExternalPackage(pkg);
+      if (!externalByRole.has(category)) externalByRole.set(category, new Set());
+      externalByRole.get(category).add(pkg);
+    }
+  }
+
+  let extIdx = 0;
+  for (const [category, packages] of externalByRole) {
+    const label = CATEGORY_LABELS[category] || 'External System';
+    const extId = `ext_${extIdx++}`;
+    const pkgList = [...packages].slice(0, 3).join(', ');
+    lines.push(`  System_Ext(${extId}, "${label}", "${escapeMermaid(pkgList)}")`);
+    lines.push(`  Rel(mainSystem, ${extId}, "uses")`);
+  }
+
+  if (externalByRole.size === 0) {
+    lines.push('  System_Ext(noExt, "External Systems", "None detected")');
+  }
+
+  return lines.join('\n');
+}
+
+/**
+ * Build a Mermaid `flowchart LR` diagram describing a RAG (Retrieval-Augmented Generation) pipeline and any detected memory stores, LLM clients or agentic tools.
+ *
+ * The diagram always includes the canonical RAG nodes (User Query → Embedding → Vector Store → Retriever → LLM/Generator → Response). When components with roles `memory`, `llm` or `tool` are present they are rendered as subgraphs and connected with role-specific edges. If `data` is missing or `data.components` is not an array, a short "No data available" flowchart note is returned.
+ *
+ * @param {object} data - Analysis data containing detected components.
+ * @param {Array<object>} data.components - Array of component descriptors used to detect memories, LLMs and tools; each component may include an `originalName` used for node labels.
+ * @returns {string} Mermaid `flowchart LR` markup representing the RAG pipeline and any detected subgraphs, or a short note diagram when input data is absent or invalid.
+ */
+function generateRag(data) {
+  if (!data || !Array.isArray(data.components)) {
+    return flowNote('No data available', 'LR');
+  }
+
+  const memories = componentsByRole(data.components, 'memory');
+  const llms = componentsByRole(data.components, 'llm');
+  const tools = componentsByRole(data.components, 'tool');
+  const toolNodeIds = [];
+
+  const lines = ['flowchart LR'];
+  lines.push('  UserQ(["👤 User Query"])');
+  lines.push('  Embed["📐 Embedding Model"]');
+  lines.push('  VecDB[("📚 Vector Store")]');
+  lines.push('  Retriever["🔍 Retriever"]');
+  lines.push('  LLMNode["🧠 LLM / Generator"]');
+  lines.push('  Output(["✅ Response"])');
+
+  lines.push('  UserQ -->|query| Embed');
+  lines.push('  Embed -->|vector| VecDB');
+  lines.push('  VecDB -->|top-k chunks| Retriever');
+  lines.push('  Retriever -->|context + query| LLMNode');
+  lines.push('  LLMNode -->|generated answer| Output');
+
+  const detectedSpecs = [
+    {
+      id: 'DetectedMemory',
+      title: 'Detected memory stores',
+      components: memories,
+      renderNode: (memory, safe) => `${safe}[("${escapeMermaid(memory.originalName)}")]`,
+      extraEdges: ['  VecDB -. "implemented by" .-> DetectedMemory'],
+    },
+    {
+      id: 'DetectedLLM',
+      title: 'Detected LLM clients',
+      components: llms,
+      renderNode: (llm, safe) => `${safe}["${escapeMermaid(llm.originalName)}"]`,
+      extraEdges: ['  LLMNode -. "implemented by" .-> DetectedLLM'],
+    },
+    {
+      id: 'DetectedTools',
+      title: 'Agentic tool calls',
+      components: tools,
+      renderNode: (tool, safe) => `${safe}["🔧 ${escapeMermaid(tool.originalName)}"]`,
+      extraEdges: [
+        '  LLMNode -->|tool use| DetectedTools',
+        '  DetectedTools -->|result| LLMNode',
+      ],
+    },
+  ];
+
+  for (const spec of detectedSpecs) {
+    const scopedSafeNames = new Map(
+      [...mapSafeNames(spec.components)].map(([component, safe]) => [component, `det_${spec.id.toLowerCase()}_${safe}`])
+    );
+    if (!emitSubgraph(lines, spec.id, spec.title, spec.components, spec.renderNode, scopedSafeNames)) continue;
+    if (spec.id === 'DetectedTools') {
+      for (const component of spec.components) {
+        const safe = scopedSafeNames.get(component);
+        if (safe) toolNodeIds.push(safe);
+      }
+    }
+    for (const edge of spec.extraEdges) {
+      lines.push(edge);
+    }
+  }
+
+  emitRoleClassStyle(lines, 'memNode', 'memory', ['VecDB', 'Retriever']);
+  emitRoleClassStyle(lines, 'llmNode', 'llm', ['LLMNode', 'Embed']);
+  emitRoleClassStyle(lines, 'toolNode', 'tool', toolNodeIds);
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  generateC4Context,
+  generateRag,
+  classifyExternalPackage,
+};

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

@@ -0,0 +1,11 @@
+const { generateAgent } = require('./analysis-generation-diagrams-role-ai-agent');
+const {
+  generateC4Context,
+  generateRag,
+} = require('./analysis-generation-diagrams-role-ai-context');
+
+module.exports = {
+  generateAgent,
+  generateC4Context,
+  generateRag,
+};

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

@@ -0,0 +1,182 @@
+const {
+  escapeMermaid,
+  componentsByRole,
+  buildRoleDiagramContext,
+  appendDependencyEdges,
+  inferDbIntent,
+} = require('./analysis-generation-utils');
+const { flowNote, noteNode } = require('./analysis-generation-diagrams-empty');
+const {
+  emitClassStyle,
+  emitSeedNodesWithIngress,
+} = require('./analysis-generation-diagrams-role-helpers');
+
+const DATABASE_DEPTH = 2;
+const DATABASE_NODE_LIMIT = 30;
+const USER_DEPTH = 2;
+const USER_NODE_LIMIT = 30;
+const EVENTS_DEPTH = 2;
+const EVENTS_NODE_LIMIT = 30;
+
+/**
+ * Builds a Mermaid flowchart (top-down) representing database-focused components and their implied control flow.
+ *
+ * @param {Object} data - Source object containing a `components` array of component records; components with role `"database"` will be rendered.
+ * @returns {string} The Mermaid `flowchart TD` diagram as a single string. If `data` is missing or `data.components` is not an array, returns a "No data available" note string; if no database components are present, returns a role-specific note string.
+ */
+function generateDatabase(data) {
+  if (!data || !Array.isArray(data.components)) {
+    return flowNote('No data available');
+  }
+
+  const lines = ['flowchart TD'];
+  const seeds = componentsByRole(data.components, 'database');
+  if (seeds.length === 0) {
+    lines.push(noteNode('No database-focused components found'));
+    return lines.join('\n');
+  }
+
+  const { byName, safeNames } = buildRoleDiagramContext(data, seeds, DATABASE_DEPTH, DATABASE_NODE_LIMIT);
+
+  lines.push('  UserRequest["User request"]');
+  lines.push('  Decision{Record exists?}');
+
+  const addedEdges = new Set();
+  const dbNodeIds = [];
+
+  for (const seed of seeds) {
+    const safe = safeNames.get(seed);
+    if (!safe) continue;
+
+    dbNodeIds.push(safe);
+    lines.push(`  ${safe}["${escapeMermaid(seed.originalName)}"]`);
+    lines.push(`  UserRequest --> ${safe}`);
+
+    const intent = inferDbIntent(seed);
+    if (intent.hasLookup) {
+      const lookup = `${safe}_lookup`;
+      const create = `${safe}_create`;
+      const update = `${safe}_update`;
+      lines.push(`  ${safe} --> ${lookup}["lookup query"]`);
+      lines.push(`  ${lookup} --> Decision`);
+      lines.push(`  Decision -->|found| ${update}["update or modify"]`);
+      lines.push(`  Decision -->|not found| ${create}["insert/create"]`);
+      lines.push(`  ${update} --> ${safe}_result["result"]`);
+      lines.push(`  ${create} --> ${safe}_result["result"]`);
+    } else if (intent.hasWrite) {
+      const write = `${safe}_write`;
+      lines.push(`  ${safe} --> ${write}["write/update"]`);
+      lines.push(`  ${write} --> ${safe}_result["result"]`);
+    } else {
+      const result = `${safe}_result`;
+      lines.push(`  ${safe} --> ${result}["result"]`);
+    }
+  }
+
+  appendDependencyEdges(lines, seeds, byName, safeNames, addedEdges);
+
+  emitClassStyle(lines, 'dbNode', '#0ea5e9', '#fff', dbNodeIds);
+  emitClassStyle(lines, 'decisionNode', '#0284c7', '#fff', []);
+  lines.push('  class Decision decisionNode');
+  return lines.join('\n');
+}
+
+/**
+ * Builds a left-to-right Mermaid flowchart representing user-facing components and their dependency connections.
+ *
+ * @param {Object} data - Analysis input containing a `components` array; components are filtered by role `'user'`.
+ * @returns {string} A Mermaid `flowchart LR` diagram as a string (may contain a note node when no data or no user-facing components are present).
+ */
+function generateUserInteractions(data) {
+  if (!data || !Array.isArray(data.components)) {
+    return flowNote('No data available', 'LR');
+  }
+
+  const lines = ['flowchart LR'];
+  const seeds = componentsByRole(data.components, 'user');
+  if (seeds.length === 0) {
+    lines.push(noteNode('No user-facing components found'));
+    return lines.join('\n');
+  }
+
+  const { connected, byName, safeNames } = buildRoleDiagramContext(data, seeds, USER_DEPTH, USER_NODE_LIMIT);
+  const edges = new Set();
+  const userNodeIds = [];
+
+  lines.push('  User(("User"))');
+  emitSeedNodesWithIngress(lines, seeds, safeNames, {
+    nodeIds: userNodeIds,
+    renderNode: (seed, safe) => `${safe}["${escapeMermaid(seed.originalName)}"]`,
+    ingressFrom: 'User',
+    edges,
+  });
+
+  appendDependencyEdges(lines, connected, byName, safeNames, edges);
+
+  emitClassStyle(lines, 'userNode', '#16a34a', '#fff', userNodeIds);
+  return lines.join('\n');
+}
+
+/**
+ * Generate a Mermaid TD flowchart representing event channels/queues and which components emit or consume them.
+ *
+ * Builds a diagram that places event channel components inside a "Channels" subgraph and marks seed components as event sources (emitters) while others are rendered as consumers; also appends dependency edges between components. If `data` is missing or `data.components` is not an array, returns a compact "No data available" flow note; if no event-role components are found, returns a diagram containing a "No event/channels components found" note.
+ *
+ * @param {Object} data - Input model containing a `components` array describing system components.
+ * @returns {string} The complete Mermaid flowchart (TD) as a string.
+ */
+function generateEvents(data) {
+  if (!data || !Array.isArray(data.components)) {
+    return flowNote('No data available');
+  }
+
+  const lines = ['flowchart TD'];
+  const seeds = componentsByRole(data.components, 'events');
+  if (seeds.length === 0) {
+    lines.push(noteNode('No event/channels components found'));
+    return lines.join('\n');
+  }
+
+  const { connected, byName, safeNames } = buildRoleDiagramContext(data, seeds, EVENTS_DEPTH, EVENTS_NODE_LIMIT);
+  const edges = new Set();
+  const eventNodeIds = [];
+  const eventSeedNames = new Set(seeds.map((seed) => seed.name));
+
+  lines.push('  subgraph Channels["Event channels / queues"]');
+  for (const component of connected) {
+    const safe = safeNames.get(component);
+    if (!safe) continue;
+    const isEventSource = eventSeedNames.has(component.name);
+    if (isEventSource) {
+      eventNodeIds.push(safe);
+      lines.push(`    ${safe}{{"${escapeMermaid(component.originalName)}"}}`);
+    } else {
+      lines.push(`    ${safe}["${escapeMermaid(component.originalName)}"]`);
+    }
+  }
+  lines.push('  end');
+
+  appendDependencyEdges(
+    lines,
+    connected,
+    byName,
+    safeNames,
+    edges,
+    (component, dep) => {
+      const from = safeNames.get(component);
+      const to = safeNames.get(dep);
+      if (!from || !to) return '';
+      const label = eventSeedNames.has(component.name) ? 'emit' : 'consume';
+      return `${from} -->|${label}| ${to}`;
+    }
+  );
+
+  emitClassStyle(lines, 'eventNode', '#db2777', '#fff', eventNodeIds);
+  return lines.join('\n');
+}
+
+module.exports = {
+  generateDatabase,
+  generateUserInteractions,
+  generateEvents,
+};

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

@@ -0,0 +1,129 @@
+const {
+  mapSafeNames,
+  appendClassAssignment,
+} = require('./analysis-generation-utils');
+
+/**
+ * Convert a list of components into their corresponding safe node identifiers.
+ *
+ * @param {Array} components - Array of component keys to map; non-array inputs are treated as empty.
+ * @param {Map} safeNames - Map from component key to safe node identifier.
+ * @returns {Array<string>} An array of safe node IDs corresponding to entries in `components`; entries without a mapping are omitted.
+ */
+function safeNodeIds(components, safeNames) {
+  if (!Array.isArray(components)) return [];
+  return components.map((component) => safeNames.get(component)).filter(Boolean);
+}
+
+/**
+ * Emit a Mermaid class definition and assign that class to the given nodes.
+ * @param {string[]} lines - Mutable array of diagram lines to append to.
+ * @param {string} className - Identifier for the class to define and assign.
+ * @param {string} fill - Fill colour for the class (e.g. `#ffffff` or `transparent`).
+ * @param {string} color - Text/stroke colour for the class.
+ * @param {string[]|undefined} nodeIds - Optional list of safe node identifiers to assign to the class.
+ */
+function emitClassStyle(lines, className, fill, color, nodeIds) {
+  lines.push(`  classDef ${className} fill:${fill},color:${color}`);
+  appendClassAssignment(lines, nodeIds, className);
+}
+
+/**
+ * Emit a Mermaid class definition for role-specific styling and assign that class to the given nodes.
+ * @param {string[]} lines - Mutable array of diagram lines to append to.
+ * @param {string} className - Identifier for the class to define and assign.
+ * @param {string} roleKey - Role key to look up in the palette.
+ * @param {string[]|undefined} nodeIds - Optional list of safe node identifiers to assign to the class.
+ * @param {Object} palette - Object mapping role keys to {fill, color} objects; falls back to 'general' if roleKey is not found.
+ */
+function emitRoleClassStyle(lines, className, roleKey, nodeIds, palette) {
+  const style = (palette && palette[roleKey]) || (palette && palette.general) || { fill: '#555', color: '#fff' };
+  lines.push(`  classDef ${className} fill:${style.fill},color:${style.color}`);
+  appendClassAssignment(lines, nodeIds, className);
+}
+
+/**
+ * Appends rendered seed nodes to the output lines and, optionally, records their safe IDs and emits unique ingress edges from a specified source.
+ * @param {string[]} lines - Array of output lines to append to.
+ * @param {Array} seeds - Seed identifiers to process.
+ * @param {Map} safeNames - Map from seed identifier to its safe node id.
+ * @param {Object} [options] - Optional behaviours.
+ * @param {string[]} [options.nodeIds] - Array that will receive safe node ids for processed seeds.
+ * @param {Function} [options.renderNode] - Function(seed, safeId) that returns a node markup string to append to lines.
+ * @param {string} [options.ingressFrom] - Source node id for ingress edges; when falsy no ingress edges are emitted.
+ * @param {Set} [options.edges] - Set used to deduplicate emitted ingress edges; a key `${ingressFrom}->${safe}` is added for each emitted edge.
+ */
+function emitSeedNodesWithIngress(lines, seeds, safeNames, options = {}) {
+  const {
+    nodeIds,
+    renderNode,
+    ingressFrom,
+    edges,
+  } = options;
+
+  if (!Array.isArray(seeds)) return;
+  for (const seed of seeds) {
+    const safe = safeNames.get(seed);
+    if (!safe) continue;
+
+    if (Array.isArray(nodeIds)) nodeIds.push(safe);
+    if (typeof renderNode === 'function') {
+      lines.push(`  ${renderNode(seed, safe)}`);
+    }
+
+    if (!ingressFrom || !(edges instanceof Set)) continue;
+    const key = `${ingressFrom}->${safe}`;
+    if (edges.has(key)) continue;
+    edges.add(key);
+    lines.push(`  ${ingressFrom} --> ${safe}`);
+  }
+}
+
+/**
+ * Emit a Mermaid `subgraph` block into `lines` for the provided components.
+ *
+ * Adds a subgraph header with the given `id` and `title`, emits a line for each
+ * component that has a corresponding safe name, and closes the subgraph.
+ *
+ * @param {string[]} lines - Array to which Mermaid lines are appended.
+ * @param {string|number} id - Identifier for the subgraph.
+ * @param {string} title - Display title for the subgraph.
+ * @param {Array} components - List of components to include in the subgraph.
+ * @param {function(any, string): string} renderNode - Function that returns the line for a component given the original component and its safe name.
+ * @param {Map<any,string>} [safeNames] - Optional map of component -> safe node id; if omitted, safe names are derived from `components`.
+ * @returns {boolean} `true` if a subgraph was emitted, `false` otherwise.
+ */
+function emitSubgraph(lines, id, title, components, renderNode, safeNames) {
+  if (!Array.isArray(components) || components.length === 0) return false;
+
+  const names = safeNames || mapSafeNames(components);
+  lines.push(`  subgraph ${id}["${title}"]`);
+  for (const component of components) {
+    const safe = names.get(component);
+    if (!safe) continue;
+    lines.push(`    ${renderNode(component, safe)}`);
+  }
+  lines.push('  end');
+  return true;
+}
+
+function emitSubgraphSpecs(lines, specs, safeNames) {
+  if (!Array.isArray(specs)) return [];
+
+  const emitted = [];
+  for (const spec of specs) {
+    if (!spec) continue;
+    const didEmit = emitSubgraph(lines, spec.id, spec.title, spec.components, spec.renderNode, safeNames);
+    if (didEmit) emitted.push(spec);
+  }
+  return emitted;
+}
+
+module.exports = {
+  safeNodeIds,
+  emitClassStyle,
+  emitRoleClassStyle,
+  emitSeedNodesWithIngress,
+  emitSubgraph,
+  emitSubgraphSpecs,
+};

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

@@ -0,0 +1,129 @@
+const {
+  escapeMermaid,
+  sanitize,
+  componentsByRole,
+  mergeRoleComponents,
+  buildRoleDiagramContext,
+  appendDependencyEdges,
+} = require('./analysis-generation-utils');
+const { collectExternalImports } = require('./analysis-generation-role-tags');
+const { flowNote, noteNode } = require('./analysis-generation-diagrams-empty');
+const {
+  emitClassStyle,
+  emitSeedNodesWithIngress,
+} = require('./analysis-generation-diagrams-role-helpers');
+
+/**
+ * Build a Mermaid flowchart showing authentication-related components and their dependencies.
+ *
+ * @param {Object} data - Analysis data containing a `components` array; each component may include role, imports and identifying fields used to render nodes.
+ * @returns {string} The Mermaid `flowchart TD` source representing authentication components, their ingress boundary, dependency edges and external provider nodes; when input is missing or contains no components this returns a small note diagram indicating no data or no authentication components.
+ */
+function generateAuth(data) {
+  if (!data || !Array.isArray(data.components)) {
+    return flowNote('No data available');
+  }
+
+  const lines = ['flowchart TD'];
+  const seeds = componentsByRole(data.components, 'auth');
+  if (seeds.length === 0) {
+    lines.push(noteNode('No authentication components found'));
+    return lines.join('\n');
+  }
+
+  const { connected, byName, safeNames } = buildRoleDiagramContext(data, seeds, 2, 24);
+  const edges = new Set();
+  const authNodeIds = [];
+
+  lines.push('  Request["Authentication request"]');
+  lines.push('  Boundary{"Auth Boundary"}');
+  lines.push('  Request --> Boundary');
+
+  emitSeedNodesWithIngress(lines, seeds, safeNames, {
+    nodeIds: authNodeIds,
+    renderNode: (seed, safe) => `${safe}["${escapeMermaid(seed.originalName)}"]`,
+    ingressFrom: 'Boundary',
+    edges,
+  });
+
+  appendDependencyEdges(lines, connected, byName, safeNames, edges);
+
+  const providerNodeByPackage = new Map();
+  const providerEdges = new Set();
+  const externalImportsBySeed = new Map();
+  for (const seed of seeds) {
+    const externalImports = collectExternalImports(seed.imports || []);
+    externalImportsBySeed.set(seed, externalImports);
+    for (const pkg of externalImports) {
+      if (!providerNodeByPackage.has(pkg)) {
+        providerNodeByPackage.set(pkg, `ext_${sanitize(pkg)}`);
+      }
+    }
+  }
+  for (const [provider, providerNode] of providerNodeByPackage) {
+    lines.push(`  ${providerNode}[("${escapeMermaid(provider)}")]`);
+  }
+  for (const seed of seeds) {
+    const seedNode = safeNames.get(seed);
+    if (!seedNode) continue;
+    for (const pkg of externalImportsBySeed.get(seed) || []) {
+      const providerNode = providerNodeByPackage.get(pkg);
+      if (!providerNode) continue;
+      const edgeKey = `${seedNode}->${providerNode}`;
+      if (providerEdges.has(edgeKey)) continue;
+      providerEdges.add(edgeKey);
+      lines.push(`  ${seedNode} --> ${providerNode}`);
+    }
+  }
+
+  emitClassStyle(lines, 'authNode', '#7c3aed', '#fff', authNodeIds);
+  return lines.join('\n');
+}
+
+/**
+ * Generate a Mermaid flowchart showing security-related components and their dependencies.
+ *
+ * Builds a `flowchart TD` diagram with an "Untrusted input" ingress node, nodes for components
+ * with roles `security`, `auth` and `integrations`, dependency edges between them, and class
+ * styling for security nodes.
+ *
+ * @param {Object} data - Analysis input containing a `components` array of component objects.
+ * @returns {string} The Mermaid `flowchart TD` source. If `data` is missing or malformed, the
+ * returned diagram contains a "No data available" note; if no matching components are found,
+ * the diagram contains a "No security-focused components found" note.
+ */
+function generateSecurity(data) {
+  if (!data || !Array.isArray(data.components)) {
+    return flowNote('No data available');
+  }
+
+  const lines = ['flowchart TD'];
+  const seeds = mergeRoleComponents(data.components, ['security', 'auth', 'integrations']);
+
+  if (seeds.length === 0) {
+    lines.push(noteNode('No security-focused components found'));
+    return lines.join('\n');
+  }
+
+  const { connected, byName, safeNames } = buildRoleDiagramContext(data, seeds, 2, 40);
+  const edges = new Set();
+  const securityNodeIds = [];
+
+  lines.push('  Untrusted["Untrusted input"]');
+  emitSeedNodesWithIngress(lines, seeds, safeNames, {
+    nodeIds: securityNodeIds,
+    renderNode: (seed, safe) => `${safe}["${escapeMermaid(seed.originalName)}"]`,
+    ingressFrom: 'Untrusted',
+    edges,
+  });
+
+  appendDependencyEdges(lines, connected, byName, safeNames, edges);
+
+  emitClassStyle(lines, 'securityNode', '#dc2626', '#fff', securityNodeIds);
+  return lines.join('\n');
+}
+
+module.exports = {
+  generateAuth,
+  generateSecurity,
+};

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

@@ -0,0 +1,25 @@
+const {
+  generateDatabase,
+  generateUserInteractions,
+  generateEvents,
+} = require('./analysis-generation-diagrams-role-data');
+const {
+  generateAuth,
+  generateSecurity,
+} = require('./analysis-generation-diagrams-role-security');
+const {
+  generateAgent,
+  generateC4Context,
+  generateRag,
+} = require('./analysis-generation-diagrams-role-ai');
+
+module.exports = {
+  generateDatabase,
+  generateUserInteractions,
+  generateEvents,
+  generateAuth,
+  generateSecurity,
+  generateAgent,
+  generateC4Context,
+  generateRag,
+};