@brainwav/diagram 1.0.7 → 1.1.0

package/src/core/analysis-generation-analyze-components.js

@@ -0,0 +1,102 @@
+const fs = require('fs');
+const path = require('path');
+const chalk = require('chalk');
+const {
+  detectLanguage,
+  inferType,
+  extractImportsWithPositions,
+  normalizePath,
+} = require('./analysis-generation-utils');
+const { inferRoleTags } = require('./analysis-generation-role-tags');
+
+/**
+ * Extracts component metadata from a set of files beneath a root path.
+ *
+ * Processes each path in `uniqueFiles`, reading file contents (files larger than 10 MB are skipped), detecting language and relative path, identifying entry points, ensuring unique component names, extracting imports and type information, and collecting directory and language statistics.
+ *
+ * @param {string} rootPath - Root directory used to compute relative file paths.
+ * @param {string[]} uniqueFiles - Array of file paths to analyse.
+ * @returns {{components: Array, entryPoints: string[], languages: Object<string, number>, directories: string[]}} An object containing:
+ *   - `components`: array of component descriptors with properties `{ name, originalName, filePath, type, imports, roleTags, directory }`.
+ *   - `entryPoints`: list of relative file paths that match common entry-point filenames.
+ *   - `languages`: mapping of detected language to file count.
+ *   - `directories`: sorted array of unique relative directory names.
+ */
+function extractComponents(rootPath, uniqueFiles) {
+  const components = [];
+  const languages = {};
+  const directories = new Set();
+  const entryPoints = [];
+  const seenNames = new Set();
+
+  for (const filePath of uniqueFiles) {
+    try {
+      const fd = fs.openSync(filePath, 'r');
+      let content;
+      try {
+        const { size } = fs.fstatSync(fd);
+        if (size > 10 * 1024 * 1024) {
+          console.warn(chalk.yellow(`⚠️  Skipping large file: ${path.basename(filePath)} (${(size / 1024 / 1024).toFixed(2)} MB)`));
+          continue;
+        }
+        content = fs.readFileSync(fd, 'utf-8');
+      } finally {
+        // Close fd even if continue is called in the size check above (uniqueFiles loop)
+        fs.closeSync(fd);
+      }
+
+      const lang = detectLanguage(filePath);
+      let rel = normalizePath(path.relative(rootPath, filePath));
+      const dir = path.dirname(rel);
+      if (dir === '.') {
+        rel = `./${rel}`;
+      }
+
+      languages[lang] = (languages[lang] || 0) + 1;
+      if (dir !== '.') directories.add(dir);
+
+      const entryPattern = /\/(index|main|app|server)\.(ts|js|tsx|jsx|mts|mjs|py|go|rs)$/i;
+      if (entryPattern.test(rel)) {
+        entryPoints.push(rel);
+      }
+
+      const baseName = path.basename(filePath, path.extname(filePath));
+      let uniqueName = baseName;
+      let counter = 1;
+      while (seenNames.has(uniqueName)) {
+        uniqueName = `${baseName}_${counter}`;
+        counter++;
+      }
+      seenNames.add(uniqueName);
+
+      const imports = extractImportsWithPositions(content, lang);
+      const type = inferType(filePath, content);
+
+      components.push({
+        name: uniqueName,
+        originalName: baseName,
+        filePath: rel,
+        type,
+        imports,
+        roleTags: inferRoleTags(rel, baseName, content, imports, type),
+        directory: dir,
+      });
+    } catch (error) {
+      if (process.env.DEBUG) {
+        const safePath = path.basename(filePath);
+        console.error(chalk.gray(`Skipped ${safePath}: ${error.message}`));
+      }
+    }
+  }
+
+  return {
+    components,
+    entryPoints,
+    languages,
+    directories: [...directories].sort(),
+  };
+}
+
+module.exports = {
+  extractComponents,
+};

package/src/core/analysis-generation-analyze-dependencies.js

@@ -0,0 +1,33 @@
+const {
+  getImportPath,
+  resolveInternalImport,
+  findComponentByResolvedPath,
+} = require('./analysis-generation-utils');
+
+/**
+ * Populate each component's `dependencies` with the names of internal components it imports.
+ *
+ * Iterates over `components`, resets each component's `dependencies` to an empty array, resolves internal imports relative to `rootPath`, and appends the `name` of any component that matches a resolved import. Unresolved or external imports are ignored.
+ *
+ * @param {Array<Object>} components - Array of component objects; each should have `imports` (array) and `filePath` (string). This function sets `dependencies` on each component.
+ * @param {string} rootPath - Project root path used when resolving internal import paths.
+ */
+function linkDependencies(components, rootPath) {
+  for (const comp of components) {
+    const deps = new Set();
+    const imports = Array.isArray(comp.imports) ? comp.imports : [];
+    for (const imp of imports) {
+      const importPath = getImportPath(imp);
+      if (!importPath) continue;
+      const resolved = resolveInternalImport(comp.filePath, importPath, rootPath);
+      if (!resolved) continue;
+      const dep = findComponentByResolvedPath(components, resolved);
+      if (dep && dep.name) deps.add(dep.name);
+    }
+    comp.dependencies = [...deps];
+  }
+}
+
+module.exports = {
+  linkDependencies,
+};

package/src/core/analysis-generation-analyze-files.js

@@ -0,0 +1,48 @@
+const fs = require('fs');
+const path = require('path');
+const { glob } = require('glob');
+const chalk = require('chalk');
+
+/**
+ * Resolve candidate files either from an explicit list or by expanding glob patterns, returning a de-duplicated list of absolute file paths.
+ *
+ * When `explicitFiles` is a non-empty array it takes precedence: each entry is resolved to an absolute path (relative entries resolved against `rootPath`), discarded if outside `rootPath`, and kept only if it exists and is a file. When `explicitFiles` is not provided or empty, `patterns` are expanded with `glob` using `rootPath` as the current working directory and `exclude` as ignore patterns; invalid glob patterns are skipped with a warning.
+ *
+ * @param {string} rootPath - Base directory used to resolve relative explicit paths and as the `cwd` for globbing.
+ * @param {string[]} patterns - Glob patterns to expand when `explicitFiles` is not provided or empty.
+ * @param {string|string[]} exclude - Patterns to pass to glob's `ignore` option.
+ * @param {string[]} explicitFiles - Optional explicit file paths; if provided and non-empty these are used instead of globbing.
+ * @returns {string[]} An array of absolute, existing file paths with duplicates removed.
+ */
+async function resolveCandidateFiles(rootPath, patterns, exclude, explicitFiles) {
+  if (Array.isArray(explicitFiles) && explicitFiles.length > 0) {
+    return [...new Set(explicitFiles
+      .map((filePath) => {
+        const absolute = path.isAbsolute(filePath) ? filePath : path.resolve(rootPath, filePath);
+        const relativeToRoot = path.relative(rootPath, absolute);
+        if (relativeToRoot.startsWith('..')) {
+          return null;
+        }
+        return absolute;
+      })
+      .filter((filePath) => filePath && fs.existsSync(filePath) && fs.statSync(filePath).isFile())
+    )];
+  }
+
+  const files = [];
+  for (const pattern of patterns) {
+    if (!pattern || pattern.trim() === '') continue;
+    try {
+      const matches = await glob(pattern.trim(), { cwd: rootPath, absolute: true, ignore: exclude });
+      files.push(...matches);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      console.warn(chalk.yellow(`⚠️  Invalid pattern: ${pattern} — ${message}`));
+    }
+  }
+  return [...new Set(files)];
+}
+
+module.exports = {
+  resolveCandidateFiles,
+};

package/src/core/analysis-generation-analyze-options.js

@@ -0,0 +1,73 @@
+/**
+ * Parse a comma-separated string into an array of trimmed, non-empty values.
+ *
+ * @param {string|null|undefined} input - Comma-separated string to parse.
+ * @returns {string[]} Array of trimmed non-empty strings; empty array if input is falsy.
+ */
+function parseCsv(input) {
+  if (!input) return [];
+  return input.split(',').map(s => s.trim()).filter(Boolean);
+}
+
+/**
+ * Determine and normalise the maximum number of files to analyse.
+ *
+ * @param {object} options - Options object.
+ * @param {number|string} [options.maxFiles] - Desired maximum; parsed as a base-10 integer.
+ * @returns {number} The validated `maxFiles` clamped to the range 1–10000; defaults to 100 when invalid.
+ */
+function parseMaxFiles(options) {
+  let maxFiles = parseInt(options.maxFiles, 10);
+  if (isNaN(maxFiles) || maxFiles < 1 || maxFiles > 10000) {
+    maxFiles = 100;
+  }
+  return Math.min(Math.max(maxFiles, 1), 10000);
+}
+
+/**
+ * Parse and return file glob patterns from an options object.
+ *
+ * If `options.patterns` is provided as a comma-separated string it is split
+ * into an array of glob patterns; otherwise a default set of common source
+ * file globs is returned.
+ *
+ * @param {Object} options - Options object that may contain a `patterns` property.
+ *   When present, `options.patterns` must be a comma-separated string of glob patterns.
+ * @returns {string[]} Array of glob patterns.
+ * @throws {TypeError} If `options.patterns` is present and is not a string.
+ */
+function parsePatterns(options) {
+  let patterns = ['**/*.ts', '**/*.tsx', '**/*.js', '**/*.jsx', '**/*.py', '**/*.go', '**/*.rs'];
+  if (options.patterns) {
+    if (typeof options.patterns !== 'string') {
+      throw new TypeError('patterns must be a string');
+    }
+    patterns = parseCsv(options.patterns);
+  }
+  return patterns;
+}
+
+/**
+ * Parse exclude glob patterns from the given options, falling back to a default set.
+ *
+ * @param {Object} options - Configuration object; may include an `exclude` property.
+ * @param {string} [options.exclude] - Comma-delimited string of glob patterns to use instead of defaults.
+ * @returns {string[]} The array of exclude glob patterns.
+ * @throws {TypeError} If `options.exclude` is provided but is not a string.
+ */
+function parseExclude(options) {
+  let exclude = ['node_modules/**', '.git/**', 'dist/**', 'build/**', '*.test.*', '*.spec.*'];
+  if (options.exclude) {
+    if (typeof options.exclude !== 'string') {
+      throw new TypeError('exclude must be a string');
+    }
+    exclude = parseCsv(options.exclude);
+  }
+  return exclude;
+}
+
+module.exports = {
+  parseMaxFiles,
+  parsePatterns,
+  parseExclude,
+};

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

@@ -0,0 +1,63 @@
+const chalk = require('chalk');
+const { parseMaxFiles, parsePatterns, parseExclude } = require('./analysis-generation-analyze-options');
+const { resolveCandidateFiles } = require('./analysis-generation-analyze-files');
+const { extractComponents } = require('./analysis-generation-analyze-components');
+const { linkDependencies } = require('./analysis-generation-analyze-dependencies');
+
+/**
+ * Orchestrates a multi-step analysis of files under a root path and returns a structured summary of the results.
+ *
+ * @param {string} rootPath - Filesystem root to analyse.
+ * @param {Object} options - Analysis options.
+ * @param {string[]} [options.includeFiles] - Explicit files to include in the analysis.
+ * @param {boolean} [options.deterministic] - If true, sort candidate files deterministically.
+ * @param {...*} [options.*] - Other options may influence patterns, exclusions and max-files.
+ * @returns {Object} Analysis result containing:
+ *  - rootPath: the analysed root path.
+ *  - components: extracted component data.
+ *  - entryPoints: discovered entry points.
+ *  - languages: detected languages metadata.
+ *  - directories: analysed directory metadata.
+ *  - totalFilesFound: total number of candidate files discovered before truncation.
+ *  - maxFilesApplied: the max-files limit that was applied.
+ */
+async function analyze(rootPath, options) {
+  const maxFiles = parseMaxFiles(options);
+  const patterns = parsePatterns(options);
+  const exclude = parseExclude(options);
+  const explicitFiles = Array.isArray(options.includeFiles) ? options.includeFiles : [];
+  let allUniqueFiles = await resolveCandidateFiles(rootPath, patterns, exclude, explicitFiles);
+
+  if (options.deterministic) {
+    allUniqueFiles = allUniqueFiles.sort();
+  }
+  const totalFilesFound = allUniqueFiles.length;
+  const uniqueFiles = allUniqueFiles.slice(0, maxFiles);
+
+  if (totalFilesFound > maxFiles) {
+    console.warn(
+      chalk.yellow(
+        `⚠️  Max-files limit reached: analyzing ${maxFiles} of ${totalFilesFound} files. Use --max-files ${Math.ceil(totalFilesFound / 100) * 100} to expand.`
+      )
+    );
+  }
+
+  const { components, entryPoints, languages, directories } = extractComponents(rootPath, uniqueFiles);
+  linkDependencies(components, rootPath);
+
+  return {
+    rootPath,
+    components,
+    entryPoints,
+    languages,
+    directories,
+    patterns,
+    exclude,
+    totalFilesFound,
+    maxFilesApplied: maxFiles,
+  };
+}
+
+module.exports = {
+  analyze,
+};

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

@@ -0,0 +1,53 @@
+const ROLE_COLOURS = Object.freeze({
+  llm: { fill: '#6d28d9', color: '#fff' },
+  agent: { fill: '#7c3aed', color: '#fff' },
+  tool: { fill: '#1d4ed8', color: '#fff' },
+  memory: { fill: '#065f46', color: '#fff' },
+  database: { fill: '#0e7490', color: '#fff' },
+  auth: { fill: '#9d174d', color: '#fff' },
+  security: { fill: '#991b1b', color: '#fff' },
+  user: { fill: '#15803d', color: '#fff' },
+  events: { fill: '#b45309', color: '#fff' },
+  integrations: { fill: '#0369a1', color: '#fff' },
+  service: { fill: '#374151', color: '#fff' },
+  general: { fill: '#374151', color: '#fff' },
+});
+Object.values(ROLE_COLOURS).forEach((entry) => Object.freeze(entry));
+
+const ROLE_ARCH_ICON = Object.freeze({
+  llm: 'cloud',
+  agent: 'server',
+  tool: 'disk',
+  memory: 'database',
+  database: 'database',
+  auth: 'server',
+  security: 'server',
+  user: 'internet',
+  events: 'server',
+  integrations: 'cloud',
+  service: 'server',
+  general: 'server',
+});
+
+const SUPPORTED_DIAGRAM_TYPES = Object.freeze([
+  'architecture',
+  'sequence',
+  'dependency',
+  'class',
+  'flow',
+  'database',
+  'erd',
+  'user',
+  'events',
+  'auth',
+  'security',
+  'agent',
+  'c4context',
+  'rag',
+]);
+
+module.exports = {
+  ROLE_COLOURS,
+  ROLE_ARCH_ICON,
+  SUPPORTED_DIAGRAM_TYPES,
+};

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

@@ -0,0 +1,105 @@
+const path = require('path');
+const { ROLE_ARCH_ICON } = require('./analysis-generation-constants');
+const {
+  normalizePath,
+  escapeMermaid,
+  sanitize,
+  mapSafeNames,
+  byNameIndex,
+} = require('./analysis-generation-utils');
+const { graphNote, architectureNote } = require('./analysis-generation-diagrams-empty');
+
+/**
+ * Build a Mermaid "architecture-beta" diagram for the provided components, optionally restricted to a focus path.
+ *
+ * The diagram groups components by directory, assigns an icon based on role tags or type, marks entry points with a star,
+ * and draws dependency edges between components. If `data` is missing or malformed, or if no components match `focus`,
+ * a text note is returned instead of the diagram.
+ *
+ * @param {Object} data - Input data object containing architecture information.
+ * @param {Array<Object>} data.components - List of component objects to include in the diagram.
+ * @param {Array<string>} [data.entryPoints] - Optional list of entry-point file paths used to mark entry nodes.
+ * @param {string} [focus] - Optional path or name to filter components; normalised before matching.
+ * @returns {string} The complete Mermaid diagram as a newline-joined string, or a note message when no data/components are available.
+ */
+function generateArchitecture(data, focus) {
+  if (!data || !Array.isArray(data.components)) {
+    return architectureNote('No data available');
+  }
+
+  const stripTrailingSlashes = (value) => (value.length > 1 ? value.replace(/\/+$/, '') : value);
+  const focusNorm = focus ? stripTrailingSlashes(normalizePath(focus)) : null;
+  const comps = focusNorm
+    ? data.components.filter((component) => {
+        const fp = stripTrailingSlashes(normalizePath(component.filePath || ''));
+        return fp === focusNorm || fp.startsWith(`${focusNorm}/`) || component.name === focusNorm;
+      })
+    : data.components;
+
+  if (comps.length === 0) {
+    return graphNote(`No components found${focus ? ` for focus: ${escapeMermaid(focus)}` : ''}`);
+  }
+
+  const iconFor = (component) => {
+    const tags = Array.isArray(component.roleTags) ? component.roleTags : [];
+    const priority = ['llm', 'agent', 'tool', 'memory', 'database', 'auth', 'user', 'events'];
+    for (const tag of priority) {
+      if (tags.includes(tag) && ROLE_ARCH_ICON[tag]) return ROLE_ARCH_ICON[tag];
+    }
+    return component.type === 'service' ? 'server' : 'disk';
+  };
+
+  const entryNames = new Set(
+    (data.entryPoints || []).map((ep) => path.basename(ep, path.extname(ep)))
+  );
+
+  const byDir = new Map();
+  for (const component of comps) {
+    const dir = component.directory === '.' ? 'root' : (component.directory || 'root');
+    if (!byDir.has(dir)) byDir.set(dir, []);
+    byDir.get(dir).push(component);
+  }
+
+  const lines = ['architecture-beta'];
+  const safeNames = mapSafeNames(comps);
+  const seenGroupIds = new Set();
+
+  for (const [dir, items] of byDir) {
+    if (items.length === 0) continue;
+    const groupId = sanitize(dir === 'root' ? 'root_group' : dir);
+    if (seenGroupIds.has(groupId)) continue;
+    seenGroupIds.add(groupId);
+    const displayDir = dir === 'root' ? 'Root' : escapeMermaid(dir);
+    lines.push(`  group ${groupId}(cloud)[${displayDir}]`);
+    for (const component of items) {
+      const safe = safeNames.get(component);
+      if (!safe) continue;
+      const icon = iconFor(component);
+      const label = `${escapeMermaid(component.originalName)}${entryNames.has(component.originalName) ? ' ⭐' : ''}`;
+      lines.push(`    service ${safe}(${icon})[${label}] in ${groupId}`);
+    }
+  }
+
+  const edges = new Set();
+  const byName = byNameIndex(comps);
+  for (const component of comps) {
+    const from = safeNames.get(component);
+    if (!from) continue;
+    for (const depName of component.dependencies || []) {
+      const dep = byName.get(depName);
+      if (!dep) continue;
+      const to = safeNames.get(dep);
+      if (!to || to === from) continue;
+      const key = `${from}->${to}`;
+      if (edges.has(key)) continue;
+      edges.add(key);
+      lines.push(`  ${from}:B --> T:${to}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  generateArchitecture,
+};

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

@@ -0,0 +1,68 @@
+const {
+  normalizePath,
+  escapeMermaid,
+  sanitize,
+  getImportPath,
+  resolveInternalImport,
+  findComponentByResolvedPath,
+  getExternalPackageName,
+} = require('./analysis-generation-utils');
+const { graphNote, noteNode } = require('./analysis-generation-diagrams-empty');
+
+/**
+ * Generate a Mermaid LR dependency graph showing component-to-component and external-package imports.
+ *
+ * Produces a `graph LR` string with edges from importing components to the components or external packages they import. External packages are rendered as distinct nodes and styled with an orange fill and white text. If `focus` is provided the graph is limited to components whose file path equals or is nested under the normalized focus path.
+ *
+ * @param {Object} data - Analysis data containing components and a rootPath used to resolve internal imports. Expected shape: `{ components: Array, rootPath?: string }`.
+ * @param {string} [focus] - Optional file or directory path to restrict the graph to a subtree; the path is normalised before matching.
+ * @returns {string} A Mermaid `graph LR` diagram as a string. If `data` is missing or `data.components` is not an array, the returned diagram is a left-to-right note stating "No data available". If no components match `focus`, the diagram contains a "No components found" note.
+ */
+function generateDependency(data, focus) {
+  if (!data || !Array.isArray(data.components)) {
+    return graphNote('No data available', 'LR');
+  }
+
+  const lines = ['graph LR'];
+  const focusNorm = focus ? normalizePath(focus) : null;
+  const comps = focusNorm ? data.components.filter((component) => {
+    const normalizedPath = normalizePath(component.filePath || '');
+    return normalizedPath === focusNorm || normalizedPath.startsWith(`${focusNorm}/`);
+  }) : data.components;
+
+  if (comps.length === 0) {
+    lines.push(noteNode('No components found'));
+    return lines.join('\n');
+  }
+
+  const external = new Set();
+  for (const component of comps) {
+    const imports = Array.isArray(component.imports) ? component.imports : [];
+    for (const importInfo of imports) {
+      const importPath = getImportPath(importInfo);
+      if (!importPath) continue;
+      if (!importPath.startsWith('.')) {
+        const pkg = getExternalPackageName(importPath);
+        if (pkg) {
+          external.add(pkg);
+          lines.push(`  ${sanitize(pkg)}["${escapeMermaid(pkg)}"] --> ${sanitize(component.name)}`);
+        }
+      } else {
+        const basePath = resolveInternalImport(component.filePath, importPath, data.rootPath);
+        if (!basePath) continue;
+        const resolved = findComponentByResolvedPath(comps, basePath);
+        if (resolved) lines.push(`  ${sanitize(component.name)} --> ${sanitize(resolved.name)}`);
+      }
+    }
+  }
+
+  for (const packageName of external) {
+    lines.push(`  style ${sanitize(packageName)} fill:#f59e0b,color:#fff`);
+  }
+
+  return lines.join('\n');
+}
+
+module.exports = {
+  generateDependency,
+};