@brainwav/diagram 1.0.7 → 1.1.0

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

@@ -0,0 +1,182 @@
+const chalk = require('chalk');
+const crypto = require('crypto');
+const path = require('path');
+const { estimateTokensFromBytes } = require('../artifacts/artifact-budget');
+const { findClosestMatch, formatSuggestion } = require('../utils/suggestions');
+const { SUPPORTED_DIAGRAM_TYPES } = require('./analysis-generation-constants');
+const { generateErdArtifact } = require('./analysis-generation-diagrams-erd');
+const {
+  generateArchitecture,
+  generateSequence,
+  generateDependency,
+  generateClass,
+  generateFlow,
+} = require('./analysis-generation-diagrams-core');
+const {
+  generateDatabase,
+  generateUserInteractions,
+  generateEvents,
+  generateAuth,
+  generateSecurity,
+  generateAgent,
+  generateC4Context,
+  generateRag,
+} = require('./analysis-generation-diagrams-role');
+
+const DIAGRAM_PURPOSES = Object.freeze({
+  architecture: 'component_hierarchy',
+  sequence: 'service_interaction_flow',
+  dependency: 'import_dependency_graph',
+  class: 'class_relationships',
+  flow: 'process_data_flow',
+  database: 'persistence_code_paths',
+  erd: 'schema_entity_relationships',
+  user: 'user_entrypaths',
+  events: 'event_architecture_paths',
+  auth: 'authentication_authorization_flow',
+  security: 'security_boundary_trust_paths',
+  agent: 'multi_agent_orchestration_paths',
+  c4context: 'system_context_map',
+  rag: 'retrieval_augmented_generation_flow',
+});
+
+function defaultDiagramMetadata(type) {
+  return {
+    purpose: DIAGRAM_PURPOSES[type] || 'architecture_diagram',
+    consumers: ['human', 'agent'],
+    source: type === 'erd' ? 'schema_extraction' : 'static_analysis',
+  };
+}
+
+function buildDiagramArtifact(type, mermaid, metadata = {}) {
+  return {
+    mermaid,
+    metadata: {
+      ...defaultDiagramMetadata(type),
+      ...metadata,
+    },
+  };
+}
+
+/**
+ * Selects and executes the appropriate diagram generator for the requested diagram type.
+ *
+ * If `type` is not recognised, logs a warning (including a nearest-match suggestion when available)
+ * and falls back to generating an architecture diagram.
+ *
+ * @param {any} data - Input data used by the selected generator to produce the diagram.
+ * @param {string} type - Diagram type identifier (e.g. "architecture", "sequence", "database").
+ * @param {string|undefined} [focus] - Optional focus/context passed to generators that support it.
+ * @returns {{mermaid: string, metadata: Object}} Generated Mermaid diagram source and artifact metadata.
+ */
+function generateDiagramArtifact(data, type, focus) {
+  switch (type) {
+    case 'architecture': return buildDiagramArtifact(type, generateArchitecture(data, focus));
+    case 'sequence': return buildDiagramArtifact(type, generateSequence(data));
+    case 'dependency': return buildDiagramArtifact(type, generateDependency(data, focus));
+    case 'class': return buildDiagramArtifact(type, generateClass(data));
+    case 'flow': return buildDiagramArtifact(type, generateFlow(data));
+    case 'database': return buildDiagramArtifact(type, generateDatabase(data));
+    case 'erd': return generateErdArtifact(data);
+    case 'user': return buildDiagramArtifact(type, generateUserInteractions(data));
+    case 'events': return buildDiagramArtifact(type, generateEvents(data));
+    case 'auth': return buildDiagramArtifact(type, generateAuth(data));
+    case 'security': return buildDiagramArtifact(type, generateSecurity(data));
+    case 'agent': return buildDiagramArtifact(type, generateAgent(data));
+    case 'c4context': return buildDiagramArtifact(type, generateC4Context(data));
+    case 'rag': return buildDiagramArtifact(type, generateRag(data));
+    default: {
+      const validTypes = [...SUPPORTED_DIAGRAM_TYPES];
+      const suggestion = findClosestMatch(type, validTypes);
+      console.warn(chalk.yellow(`⚠️  Unknown diagram type "${type}", using architecture`));
+      if (suggestion) {
+        console.warn(formatSuggestion(suggestion));
+      }
+      return buildDiagramArtifact('architecture', generateArchitecture(data, focus));
+    }
+  }
+}
+
+function generate(data, type, focus) {
+  return generateDiagramArtifact(data, type, focus).mermaid;
+}
+
+/**
+ * Common placeholder note texts used to detect empty diagrams.
+ */
+const PLACEHOLDER_NOTE_TEXTS = [
+  'note["no data available"]',
+  'note["no components found',
+  'no services detected',
+  'note "no data available"',
+  'note "no classes found"',
+  'note["no database-focused components found"]',
+  'no supported schema sources found',
+  'schema sources: none',
+  'note["no user-facing components found"]',
+  'note["no event/channels components found"]',
+  'note["no authentication components found"]',
+  'note["no security-focused components found"]',
+  'no agent/llm components found',
+  'no data available',
+];
+
+/**
+ * Detects whether Mermaid diagram content represents a placeholder or empty diagram.
+ *
+ * @param {string|null|undefined} mermaidCode - Mermaid diagram source to inspect; non-string or falsy values are treated as placeholder content.
+ * @returns {boolean} `true` if the provided content is empty, not a string, or contains common placeholder notes (e.g. "no data available", "no components found"); `false` otherwise.
+ */
+function isPlaceholderDiagram(mermaidCode) {
+  if (!mermaidCode || typeof mermaidCode !== 'string') return true;
+  const compact = mermaidCode.toLowerCase();
+  return PLACEHOLDER_NOTE_TEXTS.some(noteText => compact.includes(noteText));
+}
+
+/**
+ * Create a manifest entry describing a generated Mermaid diagram file.
+ *
+ * @param {string} type - Diagram type identifier.
+ * @param {string} filePath - Absolute or relative path to the generated file.
+ * @param {string|any} mermaidCode - Mermaid source for the diagram; may be non-string.
+ * @param {string} [rootPath] - Optional root path used to compute a relative outputPath.
+ * @returns {{type: string, file: string, outputPath: string, lines: number, bytes: number, approxTokens: number, isPlaceholder: boolean}} An object containing:
+ *  - `type`: the diagram type,
+ *  - `file`: basename of `filePath`,
+ *  - `outputPath`: `filePath` relative to `rootPath` when provided, otherwise `filePath` as given,
+ *  - `lines`: number of lines in `mermaidCode`,
+ *  - `bytes`: UTF-8 byte size of `mermaidCode`,
+ *  - `approxTokens`: token estimate derived from `bytes`,
+ *  - `isPlaceholder`: `true` if `mermaidCode` is considered a placeholder/empty diagram, `false` otherwise.
+ */
+function toManifestEntry(type, filePath, mermaidCode, rootPath, metadata = {}) {
+  const lines = typeof mermaidCode === 'string' ? mermaidCode.split('\n') : [];
+  const bytes = Buffer.byteLength(mermaidCode || '', 'utf8');
+  const defaults = defaultDiagramMetadata(type);
+  const sourceHash = crypto
+    .createHash('sha256')
+    .update(String(mermaidCode || ''))
+    .digest('hex');
+  return {
+    type,
+    file: path.basename(filePath),
+    outputPath: rootPath ? path.relative(rootPath, filePath) : filePath,
+    purpose: metadata.purpose || defaults.purpose,
+    consumers: Array.isArray(metadata.consumers) ? metadata.consumers : defaults.consumers,
+    source: metadata.source || defaults.source,
+    commitPolicy: 'generated_artifact',
+    sourceHash,
+    lines: lines.length,
+    bytes,
+    approxTokens: estimateTokensFromBytes(bytes),
+    isPlaceholder: isPlaceholderDiagram(mermaidCode),
+    ...(metadata && Object.keys(metadata).length > 0 ? { metadata } : {}),
+  };
+}
+
+module.exports = {
+  generate,
+  generateDiagramArtifact,
+  isPlaceholderDiagram,
+  toManifestEntry,
+};

package/src/core/analysis-generation-role-tags-constants.js

@@ -0,0 +1,55 @@
+const ROLE_PATTERNS = {
+  user: [
+    'route', 'routes', 'controller', 'controllers', 'handler', 'handlers',
+    'api', 'middleware', 'page', 'pages', 'ui', 'frontend', 'web', 'client', 'request'
+  ],
+  auth: [
+    'auth', 'authentication', 'authorization', 'session', 'signin', 'login',
+    'signup', 'token', 'jwt', 'oauth', 'sso', 'passport', 'identity', 'acl',
+    'guard', 'permission', 'password', 'mfa', 'security'
+  ],
+  database: [
+    'db', 'database', 'data', 'datastore', 'repository', 'repo', 'model',
+    'schema', 'migration', 'query', 'querybuilder', 'prisma', 'typeorm',
+    'sequelize', 'mongoose', 'knex', 'drizzle', 'redis', 'postgres', 'mysql',
+    'sqlite', 'mongo', 'dynamodb', 'd1'
+  ],
+  events: [
+    'event', 'events', 'queue', 'worker', 'cron', 'scheduler', 'webhook',
+    'pubsub', 'bus', 'publish', 'subscriber', 'consumer', 'producer',
+    'listener', 'trigger'
+  ],
+  integrations: [
+    'integration', 'webhook', 'gateway', 'stripe', 'pay', 'sendgrid', 'twilio',
+    'sentry', 'github', 'slack', 'analytics', 'mail', 'smtp', 'storage'
+  ],
+  security: [
+    'security', 'threat', 'attack', 'rate', 'encrypt', 'decrypt', 'signature',
+    'hash', 'verify', 'csrf', 'xss', 'audit', 'compliance', 'policy', 'vault',
+    'kms', 'secret', 'key'
+  ],
+  agent: [
+    'agent', 'supervisor', 'orchestrator', 'planner', 'executor', 'swarm',
+    'crew', 'runner', 'coordinator', 'assistant', 'brain'
+  ],
+  tool: [
+    'tool', 'tools', 'plugin', 'plugins', 'action', 'actions',
+    'function_calling', 'functioncalling', 'capability', 'skill'
+  ],
+  memory: [
+    'memory', 'vector', 'vectorstore', 'embedding', 'embeddings',
+    'retrieval', 'rag', 'chroma', 'pinecone', 'weaviate', 'faiss',
+    'context', 'recall', 'longterm', 'shortterm'
+  ],
+  llm: [
+    'llm', 'openai', 'anthropic', 'gemini', 'claude', 'ollama', 'gpt',
+    'completion', 'inference', 'model', 'prompt', 'chat', 'generation'
+  ],
+};
+
+const SENSITIVE_RISK_TAGS = new Set(['auth', 'database', 'security']);
+
+module.exports = {
+  ROLE_PATTERNS,
+  SENSITIVE_RISK_TAGS,
+};

package/src/core/analysis-generation-role-tags-imports.js

@@ -0,0 +1,32 @@
+const {
+  getImportPath,
+  getExternalPackageName,
+} = require('./analysis-generation-utils');
+
+/**
+ * Collects unique external package names referenced by an array of import entries.
+ *
+ * @param {Array} importEntries - Array of import entry objects or descriptors; entries that produce no import path or a relative path (starting with ".") are ignored.
+ * @returns {string[]} Unique external package names found in importEntries.
+ */
+function collectExternalImports(importEntries) {
+  const packages = new Set();
+  if (!Array.isArray(importEntries)) return [];
+
+  for (const entry of importEntries) {
+    const importPath = getImportPath(entry);
+    if (!importPath || importPath.startsWith('.')) {
+      continue;
+    }
+    const externalPackage = getExternalPackageName(importPath);
+    if (externalPackage) {
+      packages.add(externalPackage);
+    }
+  }
+
+  return [...packages];
+}
+
+module.exports = {
+  collectExternalImports,
+};

package/src/core/analysis-generation-role-tags-infer.js

@@ -0,0 +1,49 @@
+const { normalizePath } = require('./analysis-generation-utils');
+const { ROLE_PATTERNS, SENSITIVE_RISK_TAGS } = require('./analysis-generation-role-tags-constants');
+const { textHasToken } = require('./analysis-generation-role-tags-match');
+const { collectExternalImports } = require('./analysis-generation-role-tags-imports');
+
+/**
+ * Infer role and risk tags for a file from its path, original name, content and external imports.
+ *
+ * @param {string} filePath - File path used for structural matching.
+ * @param {string} originalName - Original file name used for structural matching.
+ * @param {string} fileContent - Full file content used for token matching.
+ * @param {Array} importEntries - Import records used to collect external import identifiers.
+ * @param {string} type - If equal to `'service'`, the `'service'` tag will be added.
+ * @returns {string[]} Array of inferred tags. Includes `'service'` when `type === 'service'`; if no tags match, returns `['general']`.
+ */
+function inferRoleTags(filePath, originalName, fileContent, importEntries, type) {
+  const content = (fileContent || '').toLowerCase();
+  const pathText = normalizePath(filePath || '').toLowerCase();
+  const nameText = (originalName || '').toLowerCase();
+  const externalImports = collectExternalImports(importEntries).join(' ').toLowerCase();
+  const structuralCombined = `${pathText} ${nameText} ${externalImports}`;
+  const fullCombined = `${structuralCombined} ${content}`;
+
+  const tags = new Set();
+
+  for (const [tag, tokens] of Object.entries(ROLE_PATTERNS)) {
+    const searchTarget = SENSITIVE_RISK_TAGS.has(tag) ? structuralCombined : fullCombined;
+    for (const token of tokens) {
+      if (textHasToken(searchTarget, token)) {
+        tags.add(tag);
+        break;
+      }
+    }
+  }
+
+  if (type === 'service') {
+    tags.add('service');
+  }
+
+  if (tags.size === 0 || (type === 'service' && tags.size === 1 && tags.has('service'))) {
+    tags.add('general');
+  }
+
+  return [...tags];
+}
+
+module.exports = {
+  inferRoleTags,
+};

package/src/core/analysis-generation-role-tags-match.js

@@ -0,0 +1,19 @@
+/**
+ * Determines whether the given text contains the specified token as a whole token-like substring.
+ *
+ * Matching is case-insensitive and requires the token to be bounded by the start or end of the string
+ * or by one-character separators: '/', '\', '.', '_' or '-'.
+ *
+ * @param {string} text - The text to search within.
+ * @param {string} token - The token to search for; all characters in this token are matched literally.
+ * @returns {boolean} `true` if the token is present as a whole token-like substring, `false` otherwise.
+ */
+function textHasToken(text, token) {
+  const escaped = token.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  const re = new RegExp(`(^|[\\\\/._-])${escaped}([\\\\/._-]|$)`, 'i');
+  return re.test(text);
+}
+
+module.exports = {
+  textHasToken,
+};

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

@@ -0,0 +1,7 @@
+const { collectExternalImports } = require('./analysis-generation-role-tags-imports');
+const { inferRoleTags } = require('./analysis-generation-role-tags-infer');
+
+module.exports = {
+  collectExternalImports,
+  inferRoleTags,
+};

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

@@ -0,0 +1,308 @@
+const crypto = require('crypto');
+const path = require('path');
+
+/**
+ * Identify the programming language from a file path's extension.
+ * @param {string} filePath - The file path whose extension will be inspected.
+ * @returns {string} The language label (for example `'typescript'`, `'javascript'`, `'python'`) or `'unknown'` if the extension is not recognised.
+ */
+function detectLanguage(filePath) {
+  if (typeof filePath !== 'string') return 'unknown';
+  const ext = path.extname(filePath).toLowerCase();
+  const map = {
+    '.ts': 'typescript', '.tsx': 'typescript',
+    '.mts': 'typescript', '.cts': 'typescript',
+    '.js': 'javascript', '.jsx': 'javascript',
+    '.mjs': 'javascript', '.cjs': 'javascript',
+    '.py': 'python', '.go': 'go', '.rs': 'rust',
+    '.java': 'java', '.rb': 'ruby', '.php': 'php',
+  };
+  return map[ext] || 'unknown';
+}
+
+/**
+ * Infer a coarse file type from the file name and file content using simple heuristics.
+ *
+ * Uses the file basename to prioritise `service` and `component` classifications, and
+ * inspects `content` for indicative tokens to identify `class`, `function` or `module`.
+ * Falls back to `file` when no heuristic matches.
+ *
+ * @param {string} filePath - File path used for basename-based heuristics.
+ * @param {string} content - File content used for token-based heuristics.
+ * @returns {string} One of: `'service'`, `'component'`, `'class'`, `'function'`, `'module'`, or `'file'`.
+ */
+function inferType(filePath, content) {
+  const base = typeof filePath === 'string' ? path.basename(filePath).toLowerCase() : '';
+  const text = typeof content === 'string' ? content : '';
+  if (base.includes('service')) return 'service';
+  if (base.includes('component') || base.endsWith('.tsx') || base.endsWith('.jsx')) return 'component';
+  if (text.includes('class ') && text.includes('extends')) return 'class';
+  if (text.includes('export default function') || text.includes('export function')) return 'function';
+  if (text.includes('module.exports') || text.includes('export ')) return 'module';
+  return 'file';
+}
+
+const IMPORT_PATTERNS = Object.freeze({
+  javascript: [
+    /import\s+(?:(?:\{[^}]*?\}|\*\s+as\s+\w+|\w+)\s+from\s+)?["']([^"']+)["']/g,
+    /require\s*\(\s*["']([^"']+)["']\s*\)/g,
+    /import\s*\(\s*["']([^"']+)["']\s*\)/g,
+  ],
+  python: [
+    /^\s*from\s+([\w.]+)/gm,
+    /^\s*import\s+([\w.]+)/gm,
+  ],
+});
+
+/**
+ * Return the list of import-matching regular expressions for a given language.
+ * @param {string} lang - Language identifier; supported values: `'typescript'`, `'javascript'`, `'python'`, `'go'`.
+ * @returns {RegExp[]} An array of regular expression patterns used to find import statements for the specified language, or an empty array if the language is not recognised.
+ */
+function resolveImportPatterns(lang) {
+  if (lang === 'typescript' || lang === 'javascript') return IMPORT_PATTERNS.javascript;
+  if (lang === 'python') return IMPORT_PATTERNS.python;
+  return [];
+}
+
+/**
+ * Find import specifiers in source text for a given language.
+ *
+ * @param {string} content - Source file content to scan for import statements.
+ * @param {string} [lang] - Language key used to select import patterns (e.g. "javascript", "python", "go").
+ * @returns {Array<{path: string, index: number, order: number}>} An array of match records for each import specifier.
+ * Each record contains:
+ *   - `path`: the captured import path string,
+ *   - `index`: character index in `content` where the match starts,
+ *   - `order`: traversal order to preserve precedence when multiple patterns match at the same index.
+ */
+function collectImportMatches(content, lang) {
+  if (typeof content !== 'string' || content.length === 0) return [];
+
+  const matches = [];
+  let order = 0;
+  for (const pattern of resolveImportPatterns(lang)) {
+    for (const match of content.matchAll(pattern)) {
+      const importPath = match[1];
+      if (!importPath) continue;
+      matches.push({
+        path: importPath,
+        index: typeof match.index === 'number' ? match.index : 0,
+        order,
+      });
+      order += 1;
+    }
+  }
+
+  matches.sort((a, b) => {
+    if (a.index !== b.index) return a.index - b.index;
+    return a.order - b.order;
+  });
+  return matches;
+}
+
+/**
+ * Build an array of character indices for the start of each line in the given content.
+ * @param {string} content - The text content to analyse.
+ * @returns {number[]} An array of zero-based character indices marking the start of each line; the first element is 0.
+ */
+function buildLineStarts(content) {
+  const starts = [0];
+  for (let i = 0; i < content.length; i++) {
+    if (content[i] === '\n') starts.push(i + 1);
+  }
+  return starts;
+}
+
+/**
+ * Determine the 1-based line number containing the given character index.
+ *
+ * @param {number[]} lineStarts - Sorted array of zero-based character indices for the start of each line (first element should be 0).
+ * @param {number} index - Character index to locate; non-finite or negative values are treated as 0.
+ * @returns {number} The 1-based line number in which `index` falls. Returns `1` if `lineStarts` is not a valid non-empty array.
+ */
+function lineNumberForIndex(lineStarts, index) {
+  if (!Array.isArray(lineStarts) || lineStarts.length === 0) return 1;
+  const boundedIndex = Math.max(0, Number.isFinite(index) ? index : 0);
+
+  let low = 0;
+  let high = lineStarts.length - 1;
+  while (low <= high) {
+    const mid = Math.floor((low + high) / 2);
+    if (lineStarts[mid] <= boundedIndex) {
+      low = mid + 1;
+    } else {
+      high = mid - 1;
+    }
+  }
+  return high + 1;
+}
+
+/**
+ * Extract Go import statements with their positions from source code.
+ *
+ * @param {string} content - Go source code to scan.
+ * @returns {Array<{path: string, line: number}>} Array of import records with path and line number.
+ */
+function extractGoImportsWithPositions(content) {
+  if (typeof content !== 'string' || content.length === 0) return [];
+
+  const imports = [];
+  const lineStarts = buildLineStarts(content);
+
+  // Match single import: import "path"
+  const singleImportPattern = /import\s+"([^"]+)"/g;
+  for (const match of content.matchAll(singleImportPattern)) {
+    const importPath = match[1];
+    if (!importPath) continue;
+    const index = typeof match.index === 'number' ? match.index : 0;
+    imports.push({
+      path: importPath,
+      line: lineNumberForIndex(lineStarts, index),
+    });
+  }
+
+  // Match import blocks: import ( ... )
+  const blockPattern = /import\s*\(\s*([\s\S]*?)\s*\)/g;
+  for (const blockMatch of content.matchAll(blockPattern)) {
+    const block = blockMatch[1];
+    if (!block) continue;
+    const blockStart = typeof blockMatch.index === 'number' ? blockMatch.index : 0;
+    const blockOffsetInMatch = blockMatch[0].indexOf(block);
+
+    // Extract individual imports from the block
+    const pathPattern = /"([^"]+)"/g;
+    for (const pathMatch of block.matchAll(pathPattern)) {
+      const importPath = pathMatch[1];
+      if (!importPath) continue;
+      const pathIndex = blockStart
+        + Math.max(0, blockOffsetInMatch)
+        + (typeof pathMatch.index === 'number' ? pathMatch.index : 0);
+      imports.push({
+        path: importPath,
+        line: lineNumberForIndex(lineStarts, pathIndex),
+      });
+    }
+  }
+
+  return imports;
+}
+
+/**
+ * Extracts import specifiers from source content for a given language.
+ *
+ * @param {string} content - The file contents to scan for import statements.
+ * @param {string} lang - Language identifier (e.g. 'javascript', 'python', 'go') used to select parsing patterns.
+ * @returns {string[]} An array of import paths found in the content; an empty array if none are found or the input is invalid.
+ */
+function extractImports(content, lang) {
+  if (lang === 'go') {
+    return extractGoImportsWithPositions(content).map((match) => match.path);
+  }
+  return collectImportMatches(content, lang).map((match) => match.path);
+}
+
+/**
+ * Parse source text for import statements for the given language and return each import path with its 1-based line number.
+ *
+ * @param {string} content - Source text to search for imports.
+ * @param {string} [lang] - Language hint used to select import patterns (e.g. 'javascript', 'python', 'go').
+ * @returns {{path: string, line: number}[]} An array of objects containing the import `path` and its 1-based `line` number.
+ */
+function extractImportsWithPositions(content, lang) {
+  if (lang === 'go') {
+    return extractGoImportsWithPositions(content);
+  }
+  const lineStarts = buildLineStarts(typeof content === 'string' ? content : '');
+  return collectImportMatches(content, lang).map((match) => ({
+    path: match.path,
+    line: lineNumberForIndex(lineStarts, match.index),
+  }));
+}
+
+/**
+ * Create a filesystem- and identifier-safe name from an arbitrary string.
+ *
+ * Produces a base identifier by replacing non-alphanumeric/underscore characters with `_`
+ * and prefixing an underscore if the name starts with a digit, then appends an
+ * 8-character hexadecimal hash derived from the original input to ensure stability and reduce collisions.
+ *
+ * @param {string} name - The original name to sanitise.
+ * @returns {string} The sanitised identifier with an appended 8-character hex hash.
+ */
+function sanitize(name) {
+  const base = name.replace(/[^a-zA-Z0-9_]/g, '_').replace(/^[0-9]/, '_$&');
+  const hash = crypto.createHash('sha256').update(name).digest('hex').slice(0, 8);
+  return `${base}_${hash}`;
+}
+
+/**
+ * Escape characters that interfere with Mermaid diagrams by prefixing them with backslashes.
+ *
+ * @param {string} str - The input string to escape.
+ * @returns {string} The input with any of the characters \ " [ ] ( ) # < > { } | prefixed by a backslash; returns an empty string for falsy input.
+ */
+function escapeMermaid(str) {
+  if (!str) return '';
+  return str.replace(/[\\"\[\]()#<>{}|]/g, '\\$&');
+}
+
+/**
+ * Normalise path separators by converting Windows backslashes to forward slashes.
+ * @param {string} inputPath - Path string that may contain backslashes.
+ * @returns {string} The path with all backslashes replaced by forward slashes.
+ */
+function normalizePath(inputPath) {
+  return inputPath.replace(/\\/g, '/');
+}
+
+/**
+ * Normalises a file path to a comparable form by converting backslashes to forward slashes and removing a leading "./".
+ * @param {string} filePath - The input path; falsy values are treated as an empty string.
+ * @returns {string} The normalised path using forward slashes with any leading "./" removed.
+ */
+function toComparablePath(filePath) {
+  return normalizePath(String(filePath || '')).replace(/^\.\//, '');
+}
+
+/**
+ * Extracts a module specifier string from an import descriptor.
+ *
+ * @param {string|{path?: string}|null|undefined} importInfo - A module import descriptor: either a string specifier or an object with a `path` string property.
+ * @returns {string|null} The import path when available, or `null` if no valid path is present.
+ */
+function getImportPath(importInfo) {
+  if (typeof importInfo === 'string') return importInfo;
+  if (importInfo && typeof importInfo.path === 'string') return importInfo.path;
+  return null;
+}
+
+/**
+ * Extracts the top-level package name from a module import specifier.
+ *
+ * @param {string} importPath - Module specifier (e.g. "react", "lodash/get", "@scope/pkg/sub").
+ * @returns {string|null} The package name — for scoped packages returns the scope and package (e.g. "@scope/pkg"), for unscoped returns the leading segment before a slash (e.g. "lodash"); `null` if `importPath` is not a non-empty string.
+ */
+function getExternalPackageName(importPath) {
+  if (typeof importPath !== 'string') return null;
+  if (!importPath) return null;
+  if (importPath.startsWith('@')) {
+    const [scope, pkg] = importPath.split('/');
+    return scope && pkg ? `${scope}/${pkg}` : scope || null;
+  }
+  return importPath.split('/')[0] || null;
+}
+
+module.exports = {
+  detectLanguage,
+  inferType,
+  extractImports,
+  extractImportsWithPositions,
+  extractGoImportsWithPositions,
+  sanitize,
+  escapeMermaid,
+  normalizePath,
+  toComparablePath,
+  getImportPath,
+  getExternalPackageName,
+};