@brainwav/diagram 1.0.8 → 1.1.0

package/src/formatters/console.js

@@ -0,0 +1,198 @@
+const chalk = require('chalk');
+
+const ExitCodes = {
+  SUCCESS: 0,
+  VALIDATION_FAILED: 1,
+  CONFIG_ERROR: 2
+};
+
+/**
+ * Detect CI environment and encoding support
+ */
+function detectEnvironment() {
+  const isCI = process.env.CI === 'true' || !process.stdout.isTTY;
+  const locale = `${process.env.LC_ALL || ''} ${process.env.LC_CTYPE || ''} ${process.env.LANG || ''}`;
+  const windowsUnicodeTerminal = Boolean(
+    process.env.WT_SESSION ||
+    process.env.TERM_PROGRAM === 'vscode' ||
+    process.env.TERM === 'xterm-256color'
+  );
+  const supportsUnicode = process.platform !== 'win32' ||
+                          windowsUnicodeTerminal ||
+                          /UTF-?8/i.test(locale);
+
+  return { isCI, supportsUnicode };
+}
+
+/**
+ * Get icons based on environment
+ */
+function getIcons(env) {
+  if (env.isCI || !env.supportsUnicode) {
+    return {
+      success: '[OK]',
+      error: '[FAIL]',
+      warning: '[WARN]',
+      skipped: '[SKIP]',
+      arrow: '->'
+    };
+  }
+  return {
+    success: '✅',
+    error: '❌',
+    warning: '⚠️',
+    skipped: '⏭️',
+    arrow: '→'
+  };
+}
+
+/**
+ * Format results for console output
+ * @param {Object} results - Validation results
+ * @param {Object} options - Output options
+ * @param {number} startTime - Start timestamp for duration calculation
+ * @returns {number} Exit code
+ */
+function formatConsole(results, options = {}, startTime = Date.now()) {
+  const env = detectEnvironment();
+  const icons = getIcons(env);
+  const { verbose } = options;
+  
+  // Validate startTime
+  if (!Number.isFinite(startTime)) {
+    startTime = Date.now();
+  }
+  const duration = Math.max(0, Date.now() - startTime);
+
+  const safeResults = results && typeof results === 'object' ? results : {};
+  const summary = safeResults.summary && typeof safeResults.summary === 'object' ? safeResults.summary : {};
+  const safeRules = Array.isArray(safeResults.rules) ? safeResults.rules : [];
+  const computed = safeRules.reduce((acc, item) => {
+    const rule = item && typeof item === 'object' ? item : {};
+    if (rule.status === 'failed') {
+      acc.failed++;
+    } else if (rule.status === 'skipped') {
+      acc.skipped++;
+    } else {
+      acc.passed++;
+    }
+    if (Array.isArray(rule.violations)) {
+      acc.violations += rule.violations.length;
+    }
+    return acc;
+  }, { total: safeRules.length, passed: 0, failed: 0, skipped: 0, violations: 0 });
+  const total = Number.isInteger(summary.total) && summary.total >= 0
+    ? Math.max(summary.total, computed.total)
+    : computed.total;
+  const passed = Number.isInteger(summary.passed) && summary.passed >= 0
+    ? Math.max(summary.passed, computed.passed)
+    : computed.passed;
+  const failed = Number.isInteger(summary.failed) && summary.failed >= 0
+    ? Math.max(summary.failed, computed.failed)
+    : computed.failed;
+  const violations = Number.isInteger(summary.violations) && summary.violations >= 0
+    ? Math.max(summary.violations, computed.violations)
+    : computed.violations;
+
+  // Configure chalk for CI
+  const c = new chalk.Instance({ level: env.isCI ? 0 : undefined });
+
+  let hasFailures = false;
+
+  for (const rule of safeRules) {
+    const currentRule = rule && typeof rule === 'object' ? rule : {};
+    const ruleIcon = currentRule.status === 'passed' ? icons.success :
+                     currentRule.status === 'skipped' ? icons.skipped :
+                     icons.error;
+
+    const statusColor = currentRule.status === 'passed' ? c.green :
+                        currentRule.status === 'skipped' ? c.yellow :
+                        c.red;
+
+    // Rule header
+    const filesChecked = Number.isInteger(currentRule.filesChecked) ? currentRule.filesChecked : 0;
+    const ruleName = typeof currentRule.name === 'string' && currentRule.name.trim() !== ''
+      ? currentRule.name
+      : 'unnamed';
+    console.log(`${ruleIcon} ${statusColor(ruleName)} ${c.gray(`(${filesChecked} files)`)}`);
+
+    if (typeof currentRule.description === 'string' && currentRule.description && verbose) {
+      console.log(c.gray(`   ${currentRule.description}`));
+    }
+
+    // Violations
+    const ruleViolations = Array.isArray(currentRule.violations) ? currentRule.violations : [];
+    if (ruleViolations.length > 0) {
+      // Only count as failure if baseline exceeded or no baseline
+      if (!currentRule.baseline || currentRule.baselineExceeded) {
+        hasFailures = true;
+      }
+
+      // Group by file for cleaner output
+      const byFile = {};
+      for (const v of ruleViolations) {
+        const fileKey = typeof v?.file === 'string' && v.file !== '' ? v.file : '<unknown file>';
+        if (!byFile[fileKey]) byFile[fileKey] = [];
+        byFile[fileKey].push(v || {});
+      }
+
+      for (const [file, violations] of Object.entries(byFile)) {
+        console.log(c.gray(`   ${file}`));
+        for (const v of violations) {
+          // Validate line number
+          let line = '';
+          if (typeof v.line === 'number' && v.line >= 0 && v.line < 1000000) {
+            line = c.cyan(`:${v.line}`);
+          }
+          const message = typeof v.message === 'string' ? v.message.slice(0, 200) : 'Unknown error';
+          console.log(`      ${icons.arrow} ${c.red(message)}${line}`);
+          if (typeof v.suggestion === 'string' && v.suggestion) {
+            console.log(c.gray(`        💡 ${v.suggestion.slice(0, 200)}`));
+          }
+        }
+      }
+    }
+
+    // Baseline warning (violations within accepted baseline)
+    if (currentRule.baselineWarning) {
+      console.log(c.yellow(`   ${icons.warning} ${currentRule.baselineWarning}`));
+    }
+
+    // Baseline exceeded
+    if (currentRule.baselineExceeded) {
+      console.log(c.red(`   ${icons.error} Baseline exceeded by ${currentRule.baselineExceeded} violation(s)`));
+    }
+
+    // Skipped message
+    if (currentRule.status === 'skipped' && currentRule.message) {
+      console.log(c.yellow(`   ${icons.warning} ${currentRule.message}`));
+    }
+
+    console.log();
+  }
+
+  // Summary
+  const skipped = Math.max(0, total - passed - failed, computed.skipped);
+
+  if (hasFailures) {
+    console.log(c.red(`${icons.error} ${failed} of ${total} rules failed (${violations} violations)`));
+  } else if (passed === total) {
+    console.log(c.green(`${icons.success} All ${total} rules passed`));
+  } else {
+    console.log(c.yellow(`${icons.warning} ${passed} passed, ${skipped} skipped`));
+  }
+
+  // Duration (only in verbose mode)
+  if (verbose) {
+    console.log(c.gray(`\nDuration: ${(duration / 1000).toFixed(3)}s`));
+  }
+
+  return hasFailures ? ExitCodes.VALIDATION_FAILED : ExitCodes.SUCCESS;
+}
+
+module.exports = {
+  formatConsole,
+  ExitCodes,
+  detectEnvironment,
+  getIcons
+};

package/src/formatters/index.js

@@ -0,0 +1,41 @@
+const { formatConsole, ExitCodes } = require('./console');
+const { formatJSON } = require('./json');
+const { formatJUnit } = require('./junit');
+
+/**
+ * Format results based on specified format
+ * @param {Object} results - Validation results
+ * @param {string} format - Output format (console, json, junit)
+ * @param {Object} options - Output options
+ * @param {number} startTime - Start timestamp for duration calculation
+ * @returns {number} Exit code
+ */
+function formatResults(results, format, options = {}, startTime = Date.now()) {
+  const normalizedFormat = typeof format === 'string' ? format.trim().toLowerCase() : 'console';
+  const validFormats = ['json', 'junit', 'console'];
+  
+  if (!validFormats.includes(normalizedFormat)) {
+    if (format && typeof format === 'string') {
+      console.warn(`Warning: Unknown format "${format}", using console`);
+    }
+    return formatConsole(results, options, startTime);
+  }
+  
+  switch (normalizedFormat) {
+    case 'json':
+      return formatJSON(results, options, startTime);
+    case 'junit':
+      return formatJUnit(results, options, startTime);
+    case 'console':
+    default:
+      return formatConsole(results, options, startTime);
+  }
+}
+
+module.exports = {
+  formatResults,
+  formatConsole,
+  formatJSON,
+  formatJUnit,
+  ExitCodes
+};

package/src/formatters/json.js

@@ -0,0 +1,113 @@
+const fs = require('fs');
+const path = require('path');
+
+const ExitCodes = {
+  SUCCESS: 0,
+  VALIDATION_FAILED: 1,
+  CONFIG_ERROR: 2
+};
+
+function buildJSONOutput(results, startTime = Date.now()) {
+  if (!Number.isFinite(startTime)) {
+    startTime = Date.now();
+  }
+  const duration = Math.max(0, Date.now() - startTime);
+  const safeResults = results && typeof results === 'object' ? results : {};
+  const summary = safeResults.summary && typeof safeResults.summary === 'object' ? safeResults.summary : {};
+  const rules = Array.isArray(safeResults.rules) ? safeResults.rules : [];
+  const computed = rules.reduce((acc, item) => {
+    const rule = item && typeof item === 'object' ? item : {};
+    if (rule.status === 'failed') {
+      acc.failed++;
+    } else if (rule.status === 'skipped') {
+      acc.skipped++;
+    } else {
+      acc.passed++;
+    }
+    if (Array.isArray(rule.violations)) {
+      acc.violations += rule.violations.length;
+    }
+    return acc;
+  }, { total: rules.length, passed: 0, failed: 0, skipped: 0, violations: 0 });
+  const total = Number.isInteger(summary.total) && summary.total >= 0
+    ? Math.max(summary.total, computed.total)
+    : computed.total;
+  const passed = Number.isInteger(summary.passed) && summary.passed >= 0
+    ? Math.max(summary.passed, computed.passed)
+    : computed.passed;
+  const failed = Number.isInteger(summary.failed) && summary.failed >= 0
+    ? Math.max(summary.failed, computed.failed)
+    : computed.failed;
+  const violations = Number.isInteger(summary.violations) && summary.violations >= 0
+    ? Math.max(summary.violations, computed.violations)
+    : computed.violations;
+  
+  return {
+    version: '1.0.0',
+    schema: 'https://diagram-cli.dev/schemas/output-v1.json',
+    summary: {
+      total,
+      passed,
+      failed,
+      skipped: Math.max(0, total - passed - failed, computed.skipped),
+      violations,
+      duration: duration / 1000, // Convert to seconds
+      exitCode: failed > 0 ? ExitCodes.VALIDATION_FAILED : ExitCodes.SUCCESS
+    },
+    rules: rules.map(rule => {
+      const safeRule = rule && typeof rule === 'object' ? rule : {};
+      return {
+        name: typeof safeRule.name === 'string' ? safeRule.name : 'unnamed',
+        description: typeof safeRule.description === 'string' ? safeRule.description : '',
+        status: typeof safeRule.status === 'string' ? safeRule.status : 'failed',
+        filesChecked: Number.isInteger(safeRule.filesChecked) ? safeRule.filesChecked : 0,
+        message: typeof safeRule.message === 'string' ? safeRule.message : undefined,
+        violations: (Array.isArray(safeRule.violations) ? safeRule.violations : []).map(v => ({
+          file: typeof v?.file === 'string' ? v.file : undefined,
+          line: Number.isInteger(v?.line) ? v.line : undefined,
+          column: Number.isInteger(v?.column) ? v.column : undefined,
+          severity: typeof v?.severity === 'string' ? v.severity : 'error',
+          message: typeof v?.message === 'string' ? v.message : 'Unknown error',
+          suggestion: typeof v?.suggestion === 'string' ? v.suggestion : undefined,
+          relatedFile: typeof v?.relatedFile === 'string' ? v.relatedFile : undefined,
+          source: typeof v?.source === 'string' ? v.source : undefined
+        }))
+      };
+    })
+  };
+}
+
+/**
+ * Format results as JSON
+ * @param {Object} results - Validation results
+ * @param {Object} options - Output options
+ * @param {number} startTime - Start timestamp for duration calculation
+ * @returns {number} Exit code
+ */
+function formatJSON(results, options = {}, startTime = Date.now()) {
+  const output = buildJSONOutput(results, startTime);
+
+  const json = JSON.stringify(output, null, 2);
+
+  if (options.output) {
+    try {
+      const outputDir = path.dirname(options.output);
+      if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true, mode: 0o755 });
+      }
+      fs.writeFileSync(options.output, json, { mode: 0o644 });
+      if (options.verbose) {
+        console.log(`Results written to ${options.output}`);
+      }
+    } catch (error) {
+      console.error(`Failed to write JSON output: ${error.message}`);
+      return ExitCodes.CONFIG_ERROR;
+    }
+  } else {
+    console.log(json);
+  }
+
+  return output.summary.exitCode;
+}
+
+module.exports = { buildJSONOutput, formatJSON, ExitCodes };

package/src/formatters/junit.js

@@ -0,0 +1,123 @@
+const fs = require('fs');
+const path = require('path');
+
+const ExitCodes = {
+  SUCCESS: 0,
+  VALIDATION_FAILED: 1,
+  CONFIG_ERROR: 2
+};
+
+/**
+ * Format results as JUnit XML
+ * @param {Object} results - Validation results
+ * @param {Object} options - Output options
+ * @param {number} startTime - Start timestamp for duration calculation
+ * @returns {number} Exit code
+ */
+function formatJUnit(results, options = {}, startTime = Date.now()) {
+  if (!Number.isFinite(startTime)) {
+    startTime = Date.now();
+  }
+  const duration = Math.max(0, (Date.now() - startTime) / 1000); // Convert to seconds
+  const safeResults = results && typeof results === 'object' ? results : {};
+  const summary = safeResults.summary && typeof safeResults.summary === 'object' ? safeResults.summary : {};
+  const rules = Array.isArray(safeResults.rules) ? safeResults.rules : [];
+  const computed = rules.reduce((acc, item) => {
+    const rule = item && typeof item === 'object' ? item : {};
+    if (rule.status === 'failed') {
+      acc.failed++;
+    } else if (rule.status === 'skipped') {
+      acc.skipped++;
+    } else {
+      acc.passed++;
+    }
+    return acc;
+  }, { total: rules.length, passed: 0, failed: 0, skipped: 0 });
+  const totalTests = Number.isInteger(summary.total) && summary.total >= 0
+    ? Math.max(summary.total, computed.total)
+    : computed.total;
+  const failures = Number.isInteger(summary.failed) && summary.failed >= 0
+    ? Math.max(summary.failed, computed.failed)
+    : computed.failed;
+  const passed = Number.isInteger(summary.passed) && summary.passed >= 0
+    ? Math.max(summary.passed, computed.passed)
+    : computed.passed;
+  const skipped = Math.max(0, totalTests - passed - failures, computed.skipped);
+  const timestamp = new Date().toISOString();
+
+  let xml = `<?xml version="1.0" encoding="UTF-8"?>\n`;
+  xml += `<testsuites name="Architecture" tests="${totalTests}" failures="${failures}" skipped="${skipped}" time="${duration.toFixed(3)}">\n`;
+  xml += `  <testsuite name="Architecture Validation" tests="${totalTests}" failures="${failures}" errors="0" skipped="${skipped}" time="${duration.toFixed(3)}" timestamp="${timestamp}">\n`;
+
+  for (const rule of rules) {
+    const safeRule = rule && typeof rule === 'object' ? rule : {};
+    const testName = escapeXml(typeof safeRule.name === 'string' ? safeRule.name : 'unnamed');
+    const violationsList = Array.isArray(safeRule.violations) ? safeRule.violations : [];
+
+    if (safeRule.status === 'failed') {
+      const violations = violationsList.map(v => {
+        let msg = `File: ${v.file || 'unknown'}`;
+        if (v.line !== undefined && v.line !== null) msg += `:${v.line}`;
+        msg += `\nMessage: ${v.message || 'No message'}`;
+        if (v.suggestion) msg += `\nSuggestion: ${v.suggestion}`;
+        return msg;
+      }).join('\n\n') || 'Rule failed with no violations payload';
+
+      xml += `    <testcase name="${testName}" time="${duration.toFixed(3)}">\n`;
+      xml += `      <failure message="${violationsList.length} violation(s)" type="ArchitectureViolation"><![CDATA[`;
+      xml += escapeCdata(violations);
+      xml += `]]></failure>\n`;
+      xml += `    </testcase>\n`;
+    } else if (safeRule.status === 'skipped') {
+      const skipMessage = escapeXml(safeRule.message || 'No files matched layer pattern');
+      xml += `    <testcase name="${testName}" time="0">\n`;
+      xml += `      <skipped message="${skipMessage}"/>\n`;
+      xml += `    </testcase>\n`;
+    } else {
+      xml += `    <testcase name="${testName}" time="0"/>\n`;
+    }
+  }
+
+  xml += `  </testsuite>\n`;
+  xml += `</testsuites>\n`;
+
+  if (options.output) {
+    try {
+      const outputDir = path.dirname(options.output);
+      if (!fs.existsSync(outputDir)) {
+        fs.mkdirSync(outputDir, { recursive: true, mode: 0o755 });
+      }
+      fs.writeFileSync(options.output, xml, { mode: 0o644 });
+      if (options.verbose) {
+        console.log(`Results written to ${options.output}`);
+      }
+    } catch (error) {
+      console.error(`Failed to write JUnit output: ${error.message}`);
+      return ExitCodes.CONFIG_ERROR;
+    }
+  } else {
+    console.log(xml);
+  }
+
+  return failures > 0 ? ExitCodes.VALIDATION_FAILED : ExitCodes.SUCCESS;
+}
+
+/**
+ * Escape XML special characters
+ */
+function escapeXml(str) {
+  if (str == null) return '';
+  return String(str)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&apos;');
+}
+
+function escapeCdata(str) {
+  if (!str) return '';
+  return str.replace(/\]\]>/g, ']]]]><![CDATA[>');
+}
+
+module.exports = { formatJUnit, ExitCodes };

package/src/graph.js

@@ -0,0 +1,159 @@
+/**
+ * ComponentGraph - Wrapper around analyze results with indexes
+ * Provides efficient lookups and reverse dependency tracking
+ */
+class ComponentGraph {
+  constructor(analyzeResult) {
+    // Validate input
+    if (!analyzeResult || typeof analyzeResult !== 'object') {
+      throw new TypeError('analyzeResult must be an object');
+    }
+    
+    this.components = Array.isArray(analyzeResult.components) ? analyzeResult.components : [];
+    this.rootPath = analyzeResult.rootPath || '';
+    this.languages = analyzeResult.languages || {};
+    this.directories = Array.isArray(analyzeResult.directories) ? analyzeResult.directories : [];
+    
+    // Validate and limit component count
+    if (this.components.length > 10000) {
+      console.warn(`Warning: Limiting to 10000 components (received ${this.components.length})`);
+      this.components = this.components.slice(0, 10000);
+    }
+    
+    // Build indexes for efficient lookups
+    this._buildIndexes();
+  }
+
+  /**
+   * Build lookup indexes
+   * @private
+   */
+  _buildIndexes() {
+    // Component name -> component
+    this._componentByName = new Map();
+    
+    // File path -> component
+    this._componentByPath = new Map();
+    
+    // Component name -> dependent component names (reverse lookup)
+    this._dependents = new Map();
+    
+    // Track duplicates
+    const seenNames = new Set();
+    
+    for (const component of this.components) {
+      // Index by name
+      if (component.name) {
+        if (seenNames.has(component.name)) {
+          console.warn(`Warning: Duplicate component name "${component.name}"`);
+        } else {
+          seenNames.add(component.name);
+          this._componentByName.set(component.name, component);
+        }
+      }
+      
+      // Index by file path
+      if (component.filePath) {
+        this._componentByPath.set(component.filePath, component);
+      }
+      
+      // Initialize dependents list
+      if (component.name) {
+        this._dependents.set(component.name, []);
+      }
+    }
+    
+    // Build reverse dependency index using Set for O(1) lookup
+    for (const component of this.components) {
+      if (Array.isArray(component.dependencies)) {
+        for (const depName of component.dependencies) {
+          if (!this._dependents.has(depName)) {
+            this._dependents.set(depName, []);
+          }
+          const dependents = this._dependents.get(depName);
+          if (!dependents.includes(component.name)) {
+            dependents.push(component.name);
+          }
+        }
+      }
+    }
+  }
+
+  /**
+   * Get component by name
+   * @param {string} name - Component name
+   * @returns {Object|undefined}
+   */
+  getComponent(name) {
+    return this._componentByName.get(name);
+  }
+
+  /**
+   * Get component by file path
+   * @param {string} filePath - File path
+   * @returns {Object|undefined}
+   */
+  getComponentByPath(filePath) {
+    return this._componentByPath.get(filePath);
+  }
+
+  /**
+   * Get direct dependencies of a component
+   * @param {string} componentName - Component name
+   * @returns {Array<Object>}
+   */
+  getDependencies(componentName) {
+    const component = this._componentByName.get(componentName);
+    if (!component || !Array.isArray(component.dependencies)) {
+      return [];
+    }
+    
+    return component.dependencies
+      .map(depName => this._componentByName.get(depName))
+      .filter(Boolean);
+  }
+
+  /**
+   * Get components that depend on a given component (reverse lookup)
+   * @param {string} componentName - Component name
+   * @returns {Array<Object>}
+   */
+  getDependents(componentName) {
+    const dependentNames = this._dependents.get(componentName) || [];
+    return dependentNames
+      .map(name => this._componentByName.get(name))
+      .filter(Boolean);
+  }
+
+  /**
+   * Get all files that match a layer pattern
+   * @param {Array<Function>} matchers - Compiled picomatch functions
+   * @returns {Array<Object>}
+   */
+  getFilesInLayer(matchers) {
+    if (!Array.isArray(matchers)) {
+      return [];
+    }
+    
+    return this.components.filter(component => {
+      if (!component || typeof component.filePath !== 'string') return false;
+      return matchers.some(matcher => {
+        try {
+          return matcher(component.filePath);
+        } catch (e) {
+          return false;
+        }
+      });
+    });
+  }
+
+  /**
+   * Get total number of components
+   * @returns {number}
+   */
+  get size() {
+    return this.components.length;
+  }
+}
+
+module.exports = { ComponentGraph };